Ja-ck/reranker-ko-yes24-ft

Reranker-Ko YES24 (zELO-distilled)

한국어 도서 검색 결과를 재정렬하는 크로스 인코더입니다. 검색어와 문서를 한 쌍으로 입력받아 관련도 점수 하나를 냅니다. 1차 검색기(SPLADE / dense, 가능하면 둘의 합집합)가 뽑은 top-K 후보를 이 점수로 다시 정렬하는 reranker 로 씁니다. 학습 라벨은 사람 주석이나 클릭이 아니라 LLM 페어와이즈 판정을 Bradley–Terry 로 적합한 점수(zELO) 입니다.

This is a Korean cross-encoder reranker for book search, distilled from zELO scores — pairwise LLM judgments fitted with Bradley–Terry. Trained on 49,895 (query, document) pairs over 2,510 queries. On a clean holdout it lifts dense-retrieval top-50 NDCG@10 from 0.655 to 0.819 (+0.164, relative +25%), evaluated against user clicks the model never saw.

모델 다운로드에는 Hugging Face 계정으로 접근을 요청하고 저장소 관리자의 승인을 받아야 합니다.

Model overview

항목	내용
저장소	Ja-ck/reranker-ko-yes24-ft
베이스 모델	Ja-ck/splade-ko-yes24-ft (← yjoonjang/splade-ko-v1 ← skt/A.X-Encoder-base). 절제 결과 베이스 선택은 결과에 영향 없음 (§Evaluation 4)
Backbone	ModernBERT, 22 layers, hidden 768 (~150M params)
헤드	회귀 헤드 1개 (ModernBertForSequenceClassification, num_labels=1)
입력	(검색어, 문서 텍스트) 쌍 — 문서 텍스트 형식은 §Usage 참조
출력	실수 1개. 정렬에만 쓴다 — 스케일·부호에 의미 없음(클수록 적합)
학습 길이	max_length 512
권장 서빙 길이	max_length 128 — NDCG 손실 −0.0015, 지연 4.5배 감소 (§Evaluation)
학습 라벨	zELO (kimi-k2.6 페어와이즈 판정 → Bradley–Terry), 쿼리별 z-정규화
학습 데이터	49,895 쌍 / 2,510 쿼리, 2026-01~07 검색 로그 홀드아웃
학습 완료	2026-09-11

포인트와이즈 모델입니다. 후보 N개에 forward N회 — 페어와이즈 O(N²) 가 아닙니다.

Usage

학습·검증에 쓴 버전은 Transformers 5.16.1, PyTorch 2.14 (cu130) 입니다. 4.57 에서도 동작을 확인했습니다.

pip install "transformers>=4.57" torch

검색어–문서 쌍 채점

모델 페이지에서 접근 승인을 받은 계정으로 hf auth login 을 실행한 후 다음 예제를 사용하십시오.

import re, torch
from transformers import AutoTokenizer, AutoModelForSequenceClassification

REPO = "Ja-ck/reranker-ko-yes24-ft"
tok = AutoTokenizer.from_pretrained(REPO)
model = AutoModelForSequenceClassification.from_pretrained(REPO, dtype=torch.float16).cuda().eval()

def doc_text(title, author, cat2, cat3, desc, n_desc=900):
    """학습에 쓴 문서 텍스트 형식 — 한 글자도 다르면 점수가 조용히 틀립니다."""
    desc = re.sub(r"\s+", " ", desc or "").strip()
    return f"{title or ''} | {author or ''} | {cat2 or ''} > {cat3 or ''} | {desc[:n_desc]}"

query = "면역수업"
docs = [
    doc_text("면역수업", "하기와라 기요후미", "건강/취미", "건강일반", "면역력을 높이는 생활 습관을 ..."),
    doc_text("파이썬 코딩의 기술", "브렛 슬라킨", "컴퓨터/IT", "프로그래밍", "파이썬을 효과적으로 쓰는 ..."),
]
enc = tok([query] * len(docs), docs, truncation=True, max_length=128, padding=True, return_tensors="pt").to("cuda")
with torch.no_grad():
    scores = model(**enc).logits[:, 0].float().cpu().tolist()
# 점수 내림차순이 재정렬 결과

문서 텍스트 규약 (중요)

{제목} | {저자} | {분류2} > {분류3} | {설명}

• 결측은 빈 문자열. 설명은 연속 공백을 하나로 합치고 양끝을 지운 뒤 앞 900자.
• 구분자 | 세 개와 > 한 개, 순서 고정.
• 서빙에서 max_length=128 이면 설명은 사실상 잘려 나가지만 그래도 같은 형식으로 만들어 넣어야 합니다 — 절단은 토크나이저가 합니다.

판본(edition) 처리 — 권장 후처리

같은 책의 여러 판(판본·제본판·세트)은 텍스트가 같아 이 모델이 구별하지 못합니다. 검증에서 top-50 의 20% 가 판본 중복이었습니다. 판본 클러스터로 묶고 대표를 점수 + 0.2·log1p(이전 기간 클릭수) 로 고르면 사용자가 실제로 누르는 판을 95.7% 맞춥니다(리랭커 점수만으로는 82.1%). 클러스터 매핑과 인기도 피처는 이 저장소에 포함되지 않습니다.

Training

1. 판정 수집 (zELO Step 1) — 쿼리당 후보 20개(클릭 10 + SPLADE 미클릭 4 + dense 미클릭 4 + 랜덤 2)에 랜덤 해밀턴 사이클 6개(간선 120개)를 겹쳐 kimi-k2.6 에게 "두 문서 중 어느 쪽이 더 적합한가" 를 물었습니다. 출력은 A|B|T 한 글자 + 첫 토큰 logprobs 로 소프트 점수. 172 쿼리(직접) + 1,998 쿼리(아래 학생 모델로).

2. Bradley–Terry 적합 — 페어 승패를 쿼리별로 적합해 문서당 연속 점수(zELO). zbench 의 calculate_elos 이식.

3. 2단계 증류 — (a) kimi 판정 → Qwen3-0.6B LoRA 페어와이즈 학생(교사와 통계적으로 구별 불가), 이 학생으로 1,998 쿼리를 게이트웨이 없이 판정. (b) 그 zELO 로 이 모델(포인트와이즈)을 학습.

항목	값
손실	MSE, 타깃 = 쿼리별 z-정규화 zELO
옵티마이저	AdamW, lr 2e-5, weight decay 0.01, OneCycle
에폭 / 배치	3 / 16
장비	DGX Spark GB10, fp32 (4겹 CV 7.3시간, 배포본은 전체 쌍으로 단일 학습)

Evaluation

모든 평가는 클릭 기준 NDCG@10 입니다. zELO 라벨 기준으로 재면 자기참조라 쓰지 않았습니다. 리랭커가 학습하지 않은 쿼리에서만 잽니다.

1. 4겹 교차검증 (후보 20개 안 재정렬, 홀드아웃 2,510 쿼리)

점수	NDCG@10
zELO 라벨 (상한)	0.7749
이 모델	0.7795
dense	0.6588
SPLADE	0.6380

짝지은 차이: vs SPLADE +0.1415 [0.133, 0.150], vs dense +0.1207. 학습 데이터를 2,632 → 10,164 → 49,895 쌍으로 늘리며 +0.079 → +0.109 → +0.142 로 올랐습니다.

2. 실전 형태 — dense 전체 인덱스(290만) → top-50 → 재정렬 (홀드아웃 300 쿼리)

	NDCG@10
dense 단독	0.6546
재정렬 후	0.8188
차이	+0.1642 [0.128, 0.200]

좋아진 쿼리 135 · 나빠진 38 · 동일 65. 나빠진 쿼리의 손실 합(−6.0)은 좋아진 쿼리의 이득 합(+45.1)의 1/7.5 입니다. top-50 에 클릭 문서가 하나도 없는 쿼리 21% 는 재정렬 대상이 아닙니다. 그 원인을 가르면 61% 는 평가용 dense 인덱스가 2026-01-20 스냅숏이라 그 뒤 신간이 없는 오프라인 인공물이고(인덱스에 있는 문서만 보면 recall@50 = 90.8%), 진짜 검색기 실패는 8% 입니다. 그 절반은 저자명·정확 제목 검색 — dense 가 희귀 고유명사에 약한 것이므로 SPLADE/BM25 후보를 dense 후보와 합쳐 이 모델에 넘기는 hybrid 구성을 권장합니다.

3. 입력 길이 트레이드오프 (238 쿼리)

max_length	NDCG@10	차이	지연 (GB10 fp16, 후보 50)
512 (기준)	0.8188	—	515 ms
384	0.8166	−0.0022	—
256	0.8144	−0.0044	258 ms
128	0.8173	−0.0015	115 ms

설명문 토큰이 순위에 거의 기여하지 않습니다. 제목·저자·분류(약 40 토큰)가 신호를 다 담습니다.

4. 베이스 모델 절제 — 도메인 SPLADE 튜닝은 필요하지 않았습니다

같은 데이터(132 쿼리, 2,632 쌍)·seed·4겹 분할에서 베이스만 바꿔 학습했습니다.

베이스	무엇	NDCG@10	vs SPLADE
skt/A.X-Encoder-base	한국어 ModernBERT 원본 (MLM 만)	0.7337	+0.070 [+0.034, +0.108]
yjoonjang/splade-ko-v1	일반 도메인 SPLADE	0.7425	+0.079 [+0.044, +0.116]
Ja-ck/splade-ko-yes24-ft (이 모델의 베이스)	도서 도메인 SPLADE	0.7353	+0.072 [+0.035, +0.108]

짝지은 차이는 세 쌍 모두 신뢰구간이 0 을 포함합니다(spladev1−ax +0.009 [−0.016, +0.035] · yes24ft−ax +0.002 [−0.021, +0.024] · yes24ft−spladev1 −0.007 [−0.027, +0.013]). 같은 seed 로 다시 돌려도 실행 간 잡음이 약 0.007 이라 베이스 차이는 그 안에 있습니다.

원본 ModernBERT 에서 바로 시작해도 같은 리랭커가 나옵니다. 도메인 적응은 zELO 라벨 파인튜닝이 다 합니다. 다른 도메인에서 이 레시피를 재현할 때 SPLADE 도메인 튜닝 단계는 건너뛰어도 됩니다 — 필요한 것은 top-K 후보를 주는 1차 검색기와, 쿼리 선정·평가에 쓸 행동 로그(또는 그 대체재)입니다.

지표 정의

NDCG@10 의 관련성 = 해당 검색어로 그 문서를 클릭한 고유 사용자 수(2026-01~07 홀드아웃, 24시간 backward attribution). 신뢰구간은 쿼리 단위 부트스트랩 4,000회.

Serving configuration

권장: GPU fp16 · max_length 128 · 후보 50. fp16 은 골든 회귀(피어슨 0.999998, NDCG −0.0024)를 통과했습니다. 정적 int8(MinMax 캘리브레이션)은 모델을 파괴했습니다(NDCG 0.14) — 쓰지 마십시오. 사후 점수 혼합(α·dense + (1−α)·reranker)이나 dense top-1 고정 게이트는 실측에서 효과가 없거나 유의하게 나빴습니다 — 순수 리랭커 점수로 정렬하십시오.

Intended use and limitations

• 용도: YES24 도서 카탈로그의 검색 후보 재정렬. 다른 도메인·다른 카탈로그에서의 성능은 검증되지 않았습니다.
• 판본: 같은 책의 여러 판을 구별하지 못합니다. 위 후처리 없이는 대표 판 적중률이 82% 입니다.
• 라벨 편향: 평가 기준인 클릭은 노출 위치·인기도 편향을 상속합니다. 오프라인 +0.164 가 온라인 이득을 보장하지 않습니다.
• 판정자 1종: 라벨의 교사가 kimi-k2.6 하나입니다. 그 모델의 체계적 오류가 있다면 이 리랭커에 들어가 있습니다. deepseek-v4-pro 는 위치 편향(뒤에 놓인 문서를 3.3배 선호)으로 제외했습니다.
• dense 가 이미 잘하는 쿼리(NDCG ≥ 0.8)에서 36% 확률로 조금 나빠집니다. 평균 이득이 훨씬 크지만 개별 쿼리 보장은 없습니다.

Provenance

항목	내용
베이스	Ja-ck/splade-ko-yes24-ft 의 ModernBERT 본체(MLM 헤드 제거)
판정 모델	kimi-k2.6 (사내 게이트웨이), thinking=false, logprobs
페어와이즈 학생	Qwen3-0.6B LoRA (별도 배포 없음)
데이터	YES24 MAKI 검색·클릭·주문 로그 2026-01-0107-31 (기존 모델 미학습 구간), 인기도 피처는 2025-0712
코드	사내 zelo-book-rank 저장소 — serving/reference.py 가 입력 계약
토크나이저	Ja-ck/splade-ko-yes24-ft 와 동일

References

• Sun et al., zELO: ELO-inspired Training Method for Rerankers and Embedding Models, arXiv:2509.12541
• zeroentropy-ai/zbench — 사이클 표집·Bradley–Terry 레퍼런스 구현
• yjoonjang/splade-ko-v1 — 베이스의 베이스