ko-hallucheck-v1: Korean faithfulness cross-encoder (bge-reranker-v2-m3 ft)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,84 @@
+---
+language:
+- ko
+license: apache-2.0
+base_model: BAAI/bge-reranker-v2-m3
+pipeline_tag: text-classification
+tags:
+- hallucination-detection
+- faithfulness
+- korean
+- cross-encoder
+- rag
+---
+
+# ko-hallucheck-v1 — 한국어 환각(충실성) 판별기
+
+**(context, answer) 쌍을 입력받아 답변이 문맥에 충실한지(SUPPORTED) 환각인지(HALLUCINATED) 판별하는 한국어 전용 cross-encoder입니다.**
+RAG 파이프라인의 출력 게이트, LLM 납품 인수검증, 생성 콘텐츠 품질 게이트 용도로 설계되었습니다.
+
+영어권에는 vectara/hallucination_evaluation_model, MiniCheck, LettuceDetect 등 성숙한 판별기가 있지만,
+한국어 전용 공개 판별기는 없어 그 공백을 채우기 위해 만들었습니다.
+
+- **Base**: BAAI/bge-reranker-v2-m3 (568M, Apache-2.0) → 2-label seq-classification 파인튜닝
+- **Labels**: `0 = HALLUCINATED`, `1 = SUPPORTED`
+- **Max length**: 512 (context+answer, longest_first truncation)
+
+## 성능
+
+| 평가셋 | acc | AUROC | 환각탐지 recall (intrinsic / extrinsic) |
+|---|---|---|---|
+| in-dist test (위키 기반 문장형, n=1002) | 0.938 | 0.980 | 0.83 / 1.00 |
+| span형 held-out (KorQuAD 위키, n=688) | 0.988 | 0.997 | 0.99 / 1.00 |
+| **cross-source OOD (KLUE-MRC 뉴스 span, n=1500)** | **0.966** | 0.979 | 0.99 / 0.99 |
+
+- OOD는 학습에 쓰지 않은 소스(뉴스 도메인)이며, 기본 임계값 0.5에서 위 성능이 나옵니다(별도 캘리브레이션 불필요).
+- v1 대비 핵심 개선: 문장형 데이터만으로 학습하면 span형 입력에서 판별이 붕괴(포맷 shortcut)하는 문제를
+  다포맷(문장형+span형) 학습으로 해결했습니다.
+
+## 정직한 한계 (읽고 쓰세요)
+
+1. **negative(환각) 샘플이 LLM 생성 + 룰 변형(숫자/개체 치환, 타문서 이식)으로 만들어졌습니다.**
+   OOD 평가의 환각도 같은 룰 패밀리로 생성되어, 실환경 LLM 환각과 분포가 다를 수 있습니다.
+   사람 라벨 기반 독립 벤치마크(Ko-FaithBench)를 준비 중이며 공개 시 여기에 결과를 추가합니다.
+2. 미묘한 1글자 수준 변형(intrinsic)의 in-dist recall은 0.83으로, 극히 미세한 왜곡은 놓칠 수 있습니다.
+3. context 512 토큰 초과분은 잘립니다. 긴 문서는 청크 단위로 나눠 판별하세요.
+4. 사실성 판별이 아니라 **주어진 context에 대한 충실성** 판별입니다. context 자체가 틀리면 잡지 못합니다.
+5. 의료·법률 등 고위험 용도에는 사람 검토 없이 단독 사용하지 마세요.
+
+## 사용법
+
+```python
+import torch
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+
+repo = "jismsy/ko-hallucheck-v1"
+tok = AutoTokenizer.from_pretrained(repo)
+model = AutoModelForSequenceClassification.from_pretrained(repo).eval()
+
+context = "농심의 첫 회사명은 롯데공업사였다. 1978년 사명을 농심으로 변경했다."
+answer = "농심은 1965년 삼양식품으로 창립되었다."
+
+enc = tok(context, answer, truncation="longest_first", max_length=512, return_tensors="pt")
+with torch.no_grad():
+    prob_supported = torch.softmax(model(**enc).logits, -1)[0, 1].item()
+print(f"SUPPORTED 확률: {prob_supported:.3f}")  # 0.5 미만 → 환각 판정
+```
+
+## 학습 데이터
+
+- 한국어 위키피디아 기반 문장형 (context, answer) ~18k쌍: LLM 생성 supported/intrinsic/extrinsic, 샘플 수동 검수(라벨 정확도 ~90%)
+- KorQuAD v1 기반 span형 ~5.3k쌍: 룰 기반 생성
+- 문서(article) 그룹 단위 train/val/test 분할로 누수 차단
+- 데이터 원문 라이선스: Korean Wikipedia(CC BY-SA), KorQuAD v1(CC BY-ND) — 데이터셋 자체는 재배포하지 않습니다.
+
+## Citation
+
+```
+@misc{ko-hallucheck-2026,
+  title={ko-hallucheck: Korean Faithfulness / Hallucination Detection Cross-Encoder},
+  author={ianwoo},
+  year={2026},
+  url={https://huggingface.co/jismsy/ko-hallucheck-v1}
+}
+```

config.json

@@ -0,0 +1,39 @@
+{
+  "add_cross_attention": false,
+  "architectures": [
+    "XLMRobertaForSequenceClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": 0,
+  "classifier_dropout": null,
+  "dtype": "float32",
+  "eos_token_id": 2,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 1024,
+  "initializer_range": 0.02,
+  "intermediate_size": 4096,
+  "is_decoder": false,
+  "layer_norm_eps": 1e-05,
+  "max_position_embeddings": 8194,
+  "model_type": "xlm-roberta",
+  "num_attention_heads": 16,
+  "num_hidden_layers": 24,
+  "output_past": true,
+  "pad_token_id": 1,
+  "position_embedding_type": "absolute",
+  "problem_type": "single_label_classification",
+  "tie_word_embeddings": true,
+  "transformers_version": "5.5.0",
+  "type_vocab_size": 1,
+  "use_cache": false,
+  "vocab_size": 250002,
+  "id2label": {
+    "0": "HALLUCINATED",
+    "1": "SUPPORTED"
+  },
+  "label2id": {
+    "HALLUCINATED": 0,
+    "SUPPORTED": 1
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d99aae172f2ac96f8fe96f2b01b1b0dc9ce85d6fe22b69a85e303784cae7f4a
+size 2271075904

tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f4ef3f81caf54d51dbbba684cfab52a71ba630b5329b24f2393a074f551539b
+size 17098183

tokenizer_config.json

@@ -0,0 +1,16 @@
+{
+  "add_prefix_space": true,
+  "backend": "tokenizers",
+  "bos_token": "<s>",
+  "clean_up_tokenization_spaces": true,
+  "cls_token": "<s>",
+  "eos_token": "</s>",
+  "is_local": false,
+  "mask_token": "<mask>",
+  "model_max_length": 8192,
+  "pad_token": "<pad>",
+  "sep_token": "</s>",
+  "sp_model_kwargs": {},
+  "tokenizer_class": "XLMRobertaTokenizer",
+  "unk_token": "<unk>"
+}