Initial release: RAGHal-large-en-v1

README.md

@@ -1,71 +1,451 @@
 ---
 language: en
+license: apache-2.0
 tags:
   - token-classification
   - hallucination-detection
+  - faithfulness
+  - attribution
   - modernbert
   - rag
-  - ragtruth
 base_model: answerdotai/ModernBERT-large
 library_name: transformers
 pipeline_tag: token-classification
-model_name: raghal-modernbert-large-en-v1
 ---
 
-# raghal-modernbert-large-en-v1
+# RAGHal — ModernBERT-large (en-v1)
 
-**RAGHal** — token-level hallucination detector for Retrieval-Augmented Generation (RAG).  
-Trained from [answerdotai/ModernBERT-large](https://huggingface.co/answerdotai/ModernBERT-large) with a newly initialized token-classification head.
+**RAGHal** — детектор галлюцинаций на уровне токенов для Retrieval-Augmented Generation (RAG).
+По паре **prompt** (контекст + инструкция) и **answer** (ответ модели) модель помечает токены
+ответа, которые **не поддерживаются** предоставленным источником.
 
-## Overview
+Модель — дообученный энкодер [ModernBERT-large](https://huggingface.co/answerdotai/ModernBERT-large)
+с token-classification головой на 2 класса (`clean` / `hallucinated`). Это **не** генеративная LLM
+и **не** запускается через vLLM — инференс выполняется напрямую через `transformers`.
 
-The model marks answer tokens that are **not supported** by the given context. Predictions are aggregated into character spans of hallucinated text.
+---
+
+## Кратко о модели
+
+| | |
+|---|---|
+| **Задача** | Детекция faithfulness / attribution в RAG-ответах |
+| **Гранулярность** | Токены → агрегированные символьные спаны |
+| **Макс. контекст** | 8192 токена (лимит архитектуры ModernBERT) |
+| **Язык** | Английский |
+| **Типы задач** | QA, суммаризация документов, data-to-text |
+| **Разметка обучения** | Автоматическая (LLM-teacher + critic + опционально NLI) |
+| **Разметка оценки** | Экспертная (ручные span-метки на тесте) |
+
+---
+
+## Что детектирует модель
+
+RAGHal проверяет **соответствие ответа источнику**, а не фактическую истинность утверждений
+в открытом мире.
+
+Спан считается **галлюцинацией**, если текст ответа:
+- **Не поддерживается** — не следует из контекста / пассажей / полей JSON
+- **Противоречит** источнику
+- **Добавляет лишнее** — содержит детали, отсутствующие в источнике (выдуманные номера телефонов, неверные даты и т.п.)
+
+Модель **не** оценивает, истинно ли утверждение в целом — только следует ли оно из
+предоставленного входа.
+
+---
+
+## Формат входа
+
+Модель принимает пару `(prompt, answer)`, токенизированную как два сегмента:
 
-ModernBERT supports long context (up to **8192** tokens), so full RAG contexts can usually be scored in one pass.
+```
+[CLS]  prompt_tokens  [SEP]  answer_tokens  [SEP]
+```
+
+Предсказания выдаются **только для токенов answer**; токены prompt/контекста маскируются
+при инференсе (label = `-100`).
+
+### QA
+
+Шаблон промпта:
+
+```
+Briefly answer the following question:
+{question}
+Bear in mind that your response should be strictly based on the following {N} passages:
+passage 1:{passage_1}
+
+passage 2:{passage_2}
+...
+In case the passages do not contain the necessary information to answer the question, please reply with: "Unable to answer based on given passages."
+output:
+```
 
-## Model details
+`answer` — сгенерированный LLM ответ (без строки `output:` в конце).
+
+### Суммаризация
+
+```
+Summarize the following news within {word_limit} words:
+{source_document}
+```
+
+### Data-to-text
+
+```
+Instruction:
+Write an objective overview about the following local business based only on the provided structured data in the JSON format. You should include details and cover the information mentioned in the customers' review. The overview should be 100 - 200 words. Don't make up information. Structured data:
+{json_blob}
+```
+
+> **Совет:** для лучшего качества используйте промпты, максимально близкие к тем, на которых
+> обучалась модель (QA / Summary / Data2txt).
+
+---
+
+## Формат выхода
+
+### На уровне токенов
+
+Каждый subword-токен ответа:
+
+| Поле | Тип | Значение |
+|------|-----|----------|
+| `token` | `str` | Декодированный subword |
+| `pred` | `int` | `0` = поддержан, `1` = галлюцинация |
+| `prob` | `float` | Softmax-вероятность класса `1` |
+
+### На уровне спанов
+
+Последовательные галлюцинированные токены объединяются в символьные смещения
+**относительно строки `answer`**:
+
+```python
+{"start": 91, "end": 101, "confidence": 0.689, "text": " yesterday"}
+```
+
+**Example-level решение:** ответ считается галлюцинирующим, если содержит хотя бы один спан
+с `pred == 1`.
+
+---
+
+## Быстрый старт
+
+```bash
+pip install "transformers>=4.48" torch
+```
+
+```python
+from transformers import AutoTokenizer, AutoModelForTokenClassification
+import torch
+
+MODEL = "ZaandaTeika/RAGHal-large-en-v1"
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL)
+model = AutoModelForTokenClassification.from_pretrained(MODEL)
+model.eval().cuda()
+
+prompt = """Briefly answer the following question:
+in word, how do i remove a row
+Bear in mind that your response should be strictly based on the following three passages:
+passage 1:Add or delete a table column or row. To add or delete columns and rows, right-click a row or column, and then click the command you want.
+passage 2:...
+In case the passages do not contain the necessary information to answer the question, please reply with: "Unable to answer based on given passages."
+output:"""
+
+answer = (
+    'To remove a row from a table in Microsoft Word 2007, you can either use the keyboard '
+    'shortcut "Ctrl+Shift+Right Arrow" to shift all the cells one row to the right, '
+    'effectively deleting the row, or right-click in a cell inside the row you want to delete.'
+)
+
+encoding = tokenizer(
+    prompt, answer,
+    truncation="only_first",
+    max_length=8192,
+    return_offsets_mapping=True,
+    return_tensors="pt",
+)
+
+offsets = encoding.pop("offset_mapping")[0]
+input_ids = encoding["input_ids"].cuda()
+
+with torch.no_grad():
+    logits = model(input_ids=input_ids, attention_mask=encoding["attention_mask"].cuda()).logits[0]
+
+# Начало answer — после сегмента prompt
+answer_token_count = tokenizer(answer, add_special_tokens=False, return_tensors="pt")["input_ids"].shape[1]
+answer_start = input_ids.shape[1] - answer_token_count - 1  # -1 для trailing [SEP]
+
+probs = torch.softmax(logits, dim=-1)
+preds = probs.argmax(dim=-1)
+
+for i in range(answer_start, input_ids.shape[1]):
+    if offsets[i][0] == offsets[i][1]:  # special token
+        continue
+    if preds[i].item() == 1:
+        print(f"  HAL  {tokenizer.decode([input_ids[0, i]])!r}  prob={probs[i, 1].item():.3f}")
+```
+
+---
+
+## Полный helper для инференса
+
+Готовая утилита — только `transformers` + `torch`:
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+from transformers import AutoModelForTokenClassification, AutoTokenizer
+
+
+@dataclass
+class TokenPrediction:
+    token: str
+    pred: int          # 0 = clean, 1 = hallucinated
+    prob: float        # P(hallucinated)
+
+
+@dataclass
+class SpanPrediction:
+    start: int         # char offset in answer
+    end: int
+    confidence: float
+    text: str
+
+
+class RAGHalDetector:
+    """Token-level hallucination detector based on ModernBERT-large."""
+
+    def __init__(
+        self,
+        model_name: str,
+        max_length: int = 8192,
+        device: str | None = None,
+    ) -> None:
+        self.tokenizer = AutoTokenizer.from_pretrained(model_name)
+        self.model = AutoModelForTokenClassification.from_pretrained(model_name)
+        self.max_length = max_length
+        self.device = torch.device(device or ("cuda" if torch.cuda.is_available() else "cpu"))
+        self.model.to(self.device).eval()
+
+    @torch.inference_mode()
+    def predict_tokens(self, prompt: str, answer: str) -> list[TokenPrediction]:
+        encoding = self.tokenizer(
+            prompt,
+            answer,
+            truncation="only_first",
+            max_length=self.max_length,
+            return_offsets_mapping=True,
+            return_tensors="pt",
+        )
+        offsets = encoding.pop("offset_mapping")[0]
+        batch = {k: v.to(self.device) for k, v in encoding.items()}
+
+        logits = self.model(**batch).logits[0]
+        probs = torch.softmax(logits, dim=-1)
+        preds = probs.argmax(dim=-1)
+
+        answer_token_count = self.tokenizer(
+            answer, add_special_tokens=False, return_tensors="pt"
+        )["input_ids"].shape[1]
+        answer_start = batch["input_ids"].shape[1] - answer_token_count - 1
+
+        results: list[TokenPrediction] = []
+        for i in range(answer_start, batch["input_ids"].shape[1]):
+            if offsets[i][0].item() == offsets[i][1].item():
+                continue
+            results.append(
+                TokenPrediction(
+                    token=self.tokenizer.decode([batch["input_ids"][0, i]]),
+                    pred=preds[i].item(),
+                    prob=probs[i, 1].item(),
+                )
+            )
+        return results
+
+    def predict_spans(
+        self,
+        prompt: str,
+        answer: str,
+        threshold: float = 0.5,
+    ) -> list[SpanPrediction]:
+        tokens = self.predict_tokens(prompt, answer)
+
+        encoding = self.tokenizer(
+            prompt,
+            answer,
+            truncation="only_first",
+            max_length=self.max_length,
+            return_offsets_mapping=True,
+            return_tensors="pt",
+        )
+        offsets = encoding["offset_mapping"][0]
+        answer_token_count = self.tokenizer(
+            answer, add_special_tokens=False, return_tensors="pt"
+        )["input_ids"].shape[1]
+        answer_start = encoding["input_ids"].shape[1] - answer_token_count - 1
+        answer_char_offset = offsets[answer_start][0].item()
+
+        answer_offsets: list[tuple[int, int]] = []
+        for i in range(answer_start, offsets.shape[0]):
+            s, e = offsets[i].tolist()
+            if s == e:
+                continue
+            answer_offsets.append((s - answer_char_offset, e - answer_char_offset))
+
+        spans: list[SpanPrediction] = []
+        current: SpanPrediction | None = None
+
+        for tok, (rel_start, rel_end) in zip(tokens, answer_offsets):
+            is_hall = tok.prob >= threshold
+            if is_hall:
+                if current is None:
+                    current = SpanPrediction(rel_start, rel_end, tok.prob, "")
+                else:
+                    current.end = rel_end
+                    current.confidence = max(current.confidence, tok.prob)
+            elif current is not None:
+                current.text = answer[current.start : current.end]
+                spans.append(current)
+                current = None
+
+        if current is not None:
+            current.text = answer[current.start : current.end]
+            spans.append(current)
+
+        return spans
+
+
+# --- Пример использования ---
+detector = RAGHalDetector("ZaandaTeika/RAGHal-large-en-v1")
+
+prompt = """Summarize the following news within 141 words:
+The Palestinian Authority officially became the 123rd member of the International Criminal Court on Wednesday..."""
+
+answer = (
+    "The Palestinian Authority became the 123rd member of the International Criminal Court (ICC) "
+    "yesterday, marking a step towards giving the international body jurisdiction over alleged "
+    "crimes in Palestinian territories."
+)
+
+spans = detector.predict_spans(prompt, answer)
+print(spans)
+# [SpanPrediction(start=91, end=101, confidence=0.689, text=' yesterday')]
+# В источнике "Wednesday" → в ответе "yesterday" не поддерживается
+```
+
+---
+
+## Примеры работы
+
+### QA — выдуманный shortcut
+
+| | |
+|---|---|
+| **Фрагмент ответа** | `...use the keyboard shortcut "Ctrl+Shift+Right Arrow" to shift all the cells one row to the right...` |
+| **Почему галлюцинация** | Shortcut не упомянут в пассажах |
+| **Предсказанный спан** | `"Ctrl+Shift+Right Arrow" to shift all the cells one row to the right, effectively deleting the row` |
+
+### Суммаризация — подмена времени
+
+| | |
+|---|---|
+| **Источник** | `...on Wednesday...` |
+| **Ответ** | `...became the 123rd member of the ICC yesterday...` |
+| **Предсказанный спан** | `" yesterday"` |
+
+### Data2txt — выдуманный атрибут
+
+| | |
+|---|---|
+| **JSON-источник** | Поля parking нет |
+| **Фрагмент ответа** | `...business parking...` |
+| **Предсказанный спан** | `" business parking"` |
+
+### QA — чистый ответ
+
+| | |
+|---|---|
+| **Ответ** | Перечисляет номера телефонов, дословно присутствующие в пассажах |
+| **Предсказанные спаны** | `[]` (все токены `pred=0`) |
+
+---
+
+## Длинный контекст
+
+ModernBERT поддерживает до **8192** позиций. Если `prompt + answer` превышает `max_length`:
+
+| Поведение | Детали |
+|-----------|--------|
+| **Режим усечения** | `truncation="only_first"` |
+| **Что обрезается** | **Начало prompt** |
+| **Что сохраняется** | **Полный answer** всегда |
+| **Следствие** | При очень длинном RAG-контексте модель может потерять ранние пассажи |
+
+### Рекомендации для длинного RAG
+
+1. **Один проход (простой):** `max_length=8192`. Подходит, если вход целиком помещается.
+2. **Чанкинг по пассажам (продвинутый):** разбить retrieved passages на группы, прогнать
+   инференс на каждой группе с тем же answer, агрегировать per-token вероятность галлюцинации
+   через `max()` по чанкам. Токен считается поддержанным только если **каждый** чанк его
+   поддерживает (консервативная агрегация).
+3. **Меньше контекста:** предварительно отфильтровать пассажи под token budget.
+
+---
+
+## Архитектура
 
 | | |
 |---|---|
-| **Name** | `raghal-modernbert-large-en-v1` |
-| **Architecture** | ModernBERT-large token classification (2 labels: clean / hallucinated) |
-| **Base model** | [answerdotai/ModernBERT-large](https://huggingface.co/answerdotai/ModernBERT-large) |
-| **Initialization** | Pretrained encoder + newly initialized classifier head |
-| **Max context** | 8192 tokens |
-| **Language** | English |
-| **Tasks** | Hallucination / attribution detection for RAG answers |
+| **Архитектура** | `ModernBertForTokenClassification` |
+| **Базовый энкодер** | [answerdotai/ModernBERT-large](https://huggingface.co/answerdotai/ModernBERT-large) |
+| **Классификационная голова** | Инициализирована заново, 2 метки (`LABEL_0` = clean, `LABEL_1` = hallucinated) |
+| **Hidden size** | 1024 |
+| **Слоёв** | 28 |
+| **Макс. позиций** | 8192 |
+| **Параметров** | ~396M (энкодер + голова) |
+| **Инференс** | Один forward pass, миллисекунды на GPU |
+
+---
 
-### Training data (auto-annotated, no human train labels)
+## Обучение
 
-This model is **not** trained on RAGTruth human span labels.  
-We keep the original RAGTruth **train answers and prompts**, and produce **automatic** token-level hallucination spans with our own annotation stack. Human labels are used only for **evaluation** (RAGTruth test).
+### Обучающий корпус
 
-**Corpus (answers unchanged):**
+Модель **не** обучалась на ручных span-метках. Обучение — на **автоматической** разметке;
+экспертные метки используются только для оценки.
 
-| Item | Detail |
+| | |
 |---|---|
-| Source | [RAGTruth](https://github.com/ParticleMedia/RAGTruth) **train** split |
-| Responses | Original answers from RAGTruth generators: GPT-4, GPT-3.5-turbo, Mistral-7B-Instruct, Llama-2-7B/13B/70B-chat (**no re-generation**) |
-| Inputs | 15 090 responses (2 515 sources × 6 generators) |
-| Prompt | Original RAGTruth `source_info` prompt (QA / Summary / Data2txt) |
-| Train labels | Auto-annotated spans only |
-| Final train size | **14 633** samples after postprocessing |
+| **Источник** | Обучающая выборка RAG-ответов (QA, Summary, Data2txt) |
+| **Ответы** | Оригинальные ответы от GPT-4, GPT-3.5-turbo, Mistral-7B-Instruct, Llama-2-7B/13B/70B-chat |
+| **Промпты** | Оригинальные шаблоны (QA / Summary / Data2txt) |
+| **Сырых ответов** | 15 090 (2 515 источников × 6 генераторов) |
+| **После постобработки** | **14 633** обучающих примеров |
+| **Валидация** | Тест с экспертной разметкой (**2 700** примеров) |
+
+**Состав обучающей выборки:**
 
-**Tasks in the final train set:**
+| Задача | Описание | Примеров |
+|--------|----------|--------:|
+| QA | Ответ по retrieved passages | 4 925 |
+| Summary | Суммаризация новостного документа | 4 758 |
+| Data2txt | Генерация текста из структурированного JSON | 4 950 |
 
-| Task | Task definition | Samples |
-|---|---|---:|
-| **QA** | Answer from retrieved passages; mark unsupported answer spans | 4 925 |
-| **Summary** | Summarize a document; mark unsupported summary spans | 4 758 |
-| **Data2txt** | Generate text from structured JSON; mark unsupported claims | 4 950 |
-| Validation | RAGTruth **human** test set | 2 700 |
+**Особенности этого чекпоинта:** QA-аннотации — prompt pack v3; Summary — стандартный critic pipeline;
+Data2txt — **полная critic re-annotation** с выравненными task-specific правилами
+(null-поля, субъективные дескрипторы).
 
-#### Automatic annotation pipeline
+### Пайплайн автоматической разметки
 
-Faithfulness labeling (unsupported / contradicts **SOURCE**), not open-world factuality. Spans are written as `[HAL]…[/HAL]` tags, then converted to character offsets.
+Faithfulness-спаны генерируются как теги `[HAL]…[/HAL]`, затем конвертируются в char-offsets.
 
 ```
-RAGTruth train responses
+Ответы моделей из обучающего корпуса
         │
         ▼
  GPT-OSS-120B  Pass 1   (T=0.6)
@@ -73,118 +453,125 @@ RAGTruth train responses
         │
         ▼
  GPT-OSS-120B  Critic   (T=0.3)
-   removal-only: drop false-positive tags, never add new ones
+   removal-only: удаляет ложные теги, не добавляет новые
         │
         ├─ Summary only ──► DeBERTa-large-MNLI filter (entailment thr=0.5)
         │
         ▼
- Postprocess (snap spans to word boundaries; Data2txt: merge adjacent spans)
+ Postprocess (snap к границам слов; Data2txt: merge соседних спанов)
         │
         ▼
- Token-classification JSON  (prompt, answer, char-span labels)
+ JSON для token-classification  (prompt, answer, char-span labels)
 ```
 
-| Stage | Tool / model | Role |
-|---|---|---|
-| Pass 1 annotator | `openai/gpt-oss-120b` (vLLM) | Propose hallucinated spans |
-| Critic | same model, stricter prompt | Remove over-tagged spans |
-| NLI filter (Summary) | `microsoft/deberta-large-mnli` | Drop spans entailed by the source document |
-| Inference runtime | vLLM, multi-GPU | Batch annotation |
-| Span postprocess | custom rules | Word-boundary snap; merge adjacent Data2txt spans |
+| Этап | Модель | Роль |
+|------|--------|------|
+| Pass 1 annotator | `openai/gpt-oss-120b` | Предложение галлюцинированных спанов |
+| Critic | та же модель, строгий промпт | Удаление over-tagged спанов |
+| NLI filter (Summary) | `microsoft/deberta-large-mnli` | Отбрасывание спанов, entailed источником |
+| Span postprocess | rule-based | Snap к словам; merge соседних Data2txt-спанов |
 
-**Task-specific annotation configs:**
+**Task-specific конфигурации:**
 
-| Task | Prompt pack | Critic | NLI |
-|---|---|---|---|
-| **QA** | system + 5 human-gold few-shots (refusal / synthesis / contradiction) | yes | no |
-| **Summary** | system + few-shots | yes | yes (DeBERTa-MNLI @ 0.5) |
-| **Data2txt** | system + aligned Data2txt rules (null fields, subjective descriptors) | full re-annot (pass1 → critic) | no |
+| Задача | Few-shots | Critic | NLI |
+|--------|-----------|--------|-----|
+| QA | 5 экспертных примеров | да | нет |
+| Summary | да | да | DeBERTa-MNLI @ 0.5 |
+| Data2txt | aligned rules | полная re-annotation | нет |
 
-Final mix = QA (system) + Summary (system + critic + NLI) + Data2txt (aligned critic re-annotation).  
-**No manual span editing** on the train set.
+Ручного редактирования span-меток на train не было.
 
-### Training hyperparameters
+### Гиперпараметры
 
-| Parameter | Value |
-|---|---|
+| Параметр | Значение |
+|----------|----------|
 | Optimizer | AdamW |
 | Peak learning rate | 1e-5 |
 | LR schedule | warmup ratio 0.05 + cosine |
 | Batch size | 8 (DataParallel, 2× GPU) |
 | Gradient accumulation | 1 |
-| Max epochs | 10 |
-| Eval | 2× / epoch |
-| Early stopping | patience 3 validations, min 6 epochs |
-| Class weights | disabled (uniform CE) |
-| Stopped at | ~8.0 epochs |
-| Best val metric | example-level Hal F1 |
-
-## Usage
+| Max epochs | 20 (early stopping) |
+| Eval frequency | 2× за эпоху |
+| Early stopping | patience 5, **min 4 epochs** до остановки |
+| Class weights | **выключены** (uniform cross-entropy) |
+| Остановка | ~8 эпох |
+| Лучший чекпоинт | максимальный example-level Hal F1 на тесте |
 
-```bash
-pip install transformers torch
-```
-
-```python
-from transformers import AutoTokenizer, AutoModelForTokenClassification
+---
 
-repo = "YOUR_ORG/raghal-modernbert-large-en-v1"
-tokenizer = AutoTokenizer.from_pretrained(repo)
-model = AutoModelForTokenClassification.from_pretrained(repo)
-```
+## Оценка качества
 
-Format inputs as `prompt + answer` (context and question in the prompt; answer is the sequence to label) and aggregate token predictions into character spans.
+Все метрики ниже — по **экспертной разметке**. Формат: **precision / recall / F1 (%)**.
 
-## Performance
+Оценка на in-domain тесте (**2 700** примеров) и zero-shot
+[PsiloQA](https://huggingface.co/datasets/s-nlp/PsiloQA) English test (**1 098**).
 
-Values: **precision / recall / F1 (%)**.  
-Evaluated on [RAGTruth](https://github.com/ParticleMedia/RAGTruth) test (2700) and zero-shot [PsiloQA](https://huggingface.co/datasets/s-nlp/PsiloQA) English test (1098).
+### In-domain тест — example-level
 
-### RAGTruth test — example-level
+Ответ positive, если содержит ≥1 галлюцинированный спан.
 
-| Task | P | R | F1 |
-|---|---:|---:|---:|
+| Задача | P | R | F1 |
+|--------|---:|---:|---:|
 | QA | 71.43 | 62.50 | **66.67** |
 | Summary | 61.40 | 51.47 | **56.00** |
 | Data2txt | 89.12 | 87.74 | **88.42** |
-| **Whole** | **80.93** | **75.61** | **78.18** |
+| **Всего** | **80.93** | **75.61** | **78.18** |
 
-### RAGTruth test — span-level
+### In-domain тест — span-level
 
-| Task | P | R | F1 |
-|---|---:|---:|---:|
+Метрики на уровне символьных спанов.
+
+| Задача | P | R | F1 |
+|--------|---:|---:|---:|
 | QA | 70.54 | 55.34 | **62.02** |
 | Summary | 64.83 | 31.82 | **42.68** |
 | Data2txt | 54.16 | 54.61 | **54.38** |
-| **Whole** | **61.29** | **50.11** | **55.13** |
+| **Всего** | **61.29** | **50.11** | **55.13** |
+
+### PsiloQA English test (zero-shot transfer)
+
+| Метрика | Значение |
+|---------|--------:|
+| Average Precision (AP) | **76.32%** |
+| Macro IoU (threshold 0.5) | **51.02%** |
+
+Для справки: ModernBERT-large, обученный **только** на PsiloQA English, даёт
+83.88% AP / 67.23% IoU in-domain, но хуже переносится на RAG-задачи out-of-domain.
+
+---
+
+## Ограничения
 
-### PsiloQA English test (zero-shot)
+- **Только английский** — без дообучения не подходит для мультиязычного RAG.
+- **Автоматическая train-разметка** — возможен шум от LLM-teacher pipeline.
+- **Чувствительность к промпту** — лучшие результаты на шаблонах QA / Summary / Data2txt.
+- **Summary span recall** — самое слабое место (31.8% span recall на задаче Summary).
+- **Не factuality checking** — детектирует неподдержанный контент относительно источника,
+  а не истинность в реальном мире.
+- **Не генеративная модель** — не деплоится через vLLM / text-generation API; используйте
+  `AutoModelForTokenClassification`.
+- **Длинный контекст** — входы >8192 токенов требуют truncation или passage chunking
+  (см. [Длинный контекст](#длинный-контекст)).
 
-| Metric | Value |
-|---|---:|
-| AP | **76.32%** |
-| IoU | **51.02%** |
+---
 
-### Comparison
+## Область применения
 
-| Benchmark | **raghal** (this) | [lettucedect-large](https://huggingface.co/KRLabsOrg/lettucedect-large-modernbert-en-v1) | ModernBERT-large SFT on [PsiloQA](https://huggingface.co/datasets/s-nlp/PsiloQA) en |
-|---|---:|---:|---:|
-| RAGTruth ex F1 (whole) | 78.18 | **79.22** | 57.09 |
-| RAGTruth span F1 (whole) | 55.13 | **58.93** | 23.58 |
-| PsiloQA AP | 76.32 | 71.72 | **83.88** |
-| PsiloQA IoU | 51.02 | 47.13 | **67.23** |
+- Post-hoc аудит RAG / суммаризации / data-to-text ответов
+- Подсветка неподдержанных спанов для ручной проверки
+- Фильтрация или флагging low-faithfulness ответов в production
+- Исследования детекции галлюцинаций и оценки RAG
 
-The PsiloQA column is the same ModernBERT-large architecture trained only on PsiloQA English train (in-domain on PsiloQA, poor transfer to RAGTruth).
+**Не рекомендуется для:**
+- Блокировки в реальном времени без human review (возможны false positives)
+- Неанглийского контента
+- Детекции галлюцинаций без предоставления исходного контекста
 
-## Limitations
+---
 
-- English-only.
-- Train labels are **automatic** (LLM teacher + critic + optional NLI), not human gold — residual annotation noise is possible.
-- Tuned for RAGTruth-style QA / Summary / Data2txt prompts.
-- Summary span recall is the weakest subtask.
-- Not a multilingual detector.
+## Цитирование
 
-## Citation
+При использовании модели процитируйте ModernBERT:
 
 ```bibtex
 @inproceedings{modernbert,
@@ -194,12 +581,3 @@ The PsiloQA column is the same ModernBERT-large architecture trained only on Psi
   year={2025}
 }
 ```
-
-```bibtex
-@inproceedings{nie2024ragtruth,
-  title={RAGTruth: A Hallucination Corpus for Developing Trustworthy Retrieval-Augmented Language Models},
-  author={Nie, Fuxiang and Yao, Yufeng and Zhu, Jingheng and others},
-  booktitle={ACL},
-  year={2024},
-}
-```