Ja-ck/colbert-ko-yes24-ft

ColBERT-Ko YES24 Fine-tuned

한국어 도서 검색을 위해 도메인 튜닝한 ColBERT 모델입니다. 문서와 질의를 토큰 단위 벡터로 표현하고 MaxSim으로 관련도를 계산합니다. 전체 문서 컬렉션을 검색하는 retriever와 검색 후보의 순서를 조정하는 reranker로 사용할 수 있습니다.

This is a Korean multi-vector retrieval model fine-tuned on book-domain query–document supervision. It supports independent retrieval with a compatible multi-vector index and candidate reranking using late interaction.

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

Model overview

항목	내용
저장소	Ja-ck/colbert-ko-yes24-ft
베이스 모델	yjoonjang/colbert-ko-v1
베이스 revision	de14517efa38489a378a9648daf90bbd4a153909
Backbone	ModernBERT
출력	토큰당 128차원 벡터, 입력별 가변 개수
유사도	MaxSim: 질의 토큰별 최대 문서 토큰 유사도를 합산
질의 길이	32 tokens, fixed query expansion
문서 길이	최대 128 tokens
학습 도메인	한국어 도서 메타데이터 검색
최종 체크포인트	F2, epoch 3; 검증 NDCG@10으로 선택
학습 완료	2026-09-08

단일 문장 벡터 모델이 아닙니다. 토큰 벡터를 평균 pooling하거나 일반 단일 벡터 인덱스에 그대로 넣으면 아래 평가와 다른 모델 동작이 됩니다.

Usage

검증에 사용한 주요 버전은 Sentence Transformers 6.0.1, Transformers 5.16.1입니다. GPU PyTorch는 실행 장비에 맞게 먼저 설치하십시오. 학습·평가는 DGX Spark GB10의 NGC PyTorch 환경에서 수행했습니다.

pip install "sentence-transformers==6.0.1" "transformers==5.16.1"

질의와 문서의 MaxSim 점수 계산

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

from sentence_transformers import MultiVectorEncoder

model = MultiVectorEncoder(
    "Ja-ck/colbert-ko-yes24-ft",
    device="cuda",
    model_kwargs={"dtype": "float32", "attn_implementation": "sdpa"},
    config_kwargs={"reference_compile": False},
)

queries = ["초등학생 우주 과학책"]
documents = [
    "Title: 어린이를 위한 우주 이야기\n"
    "Author: 예시 저자\n"
    "Category: 어린이\n"
    "Subcategory: 과학\n"
    "GoodsType: 단행본",
    "Title: 집에서 만드는 간단한 요리\n"
    "Author: 예시 저자\n"
    "Category: 요리\n"
    "Subcategory: 생활요리\n"
    "GoodsType: 단행본",
]

query_vectors = model.encode_query(queries)
document_vectors = model.encode_document(documents)
scores = model.similarity(query_vectors, document_vectors)

print(scores)  # shape: (number of queries, number of documents)
print(scores.argsort(dim=1, descending=True))

예제 도서명과 저자는 사용 방법을 설명하기 위한 가상 데이터입니다. 출력 점수는 확률이나 0–1 관련도 라벨이 아닙니다.

저장된 query/document prompt는 각각 [Q] 와 [D] 입니다. encode_query와 encode_document가 이를 적용하므로 직접 중복해서 붙이지 마십시오. 학습 데이터에는 질의 정규화와 Kiwi 띄어쓰기 처리가 적용됐습니다. 다른 전처리를 쓰면 결과가 달라질 수 있습니다.

전체 문서 검색

위 예제는 전달한 문서 목록의 점수 계산입니다. 대규모 직접 검색에는 다음 과정이 추가로 필요합니다.

1. 문서별 token vectors를 생성합니다.
2. 호환되는 multi-vector 검색 인덱스를 구축합니다.
3. 질의 token vectors로 자체 인덱스를 검색합니다.

이번 직접 검색 평가에는 FastPlaid 1.7.0을 사용했습니다. 8-bit 인덱스에서 후보를 찾고, 원본 FP16 토큰 벡터로 MaxSim을 다시 계산했습니다. 다른 검색기가 생성한 후보에 제한된 평가는 아닙니다. 모든 ColBERT 라이브러리에서 모델 파일이 수정 없이 호환되는지는 검증하지 않았습니다.

Training

학습 데이터는 내부 도서 도메인 데이터셋 triplet-v7.1입니다.

항목	수량 / 설정
원본 triplet	574,950행
완전 중복 제거	7행
실제 학습	574,943행 전체, 449,911개 고유 정규화 질의
충돌 negative 처리	1,620행의 explicit negative만 비활성화; query–positive 학습 유지
문서 텍스트	Title / Author / Category / Subcategory / GoodsType
Loss	CachedMultiVectorMultipleNegativesRankingLoss, scale 1.0
최종 실행 학습률	1e-5
비교 실행 학습률	3e-6
Batch / mini-batch	64 / 8
Optimizer	AdamW, weight decay 0.01
Schedule	Linear decay, 5% warmup
Precision	FP32 parameters, BF16 autocast
Gradient clipping	1.0
Seed	42
Epochs	실행별 3
학습량	실행별 26,955 steps / 1,724,829회 논리적 행 노출

두 실행은 같은 공개 베이스에서 각각 시작했고, backbone과 token projection을 모두 학습했습니다. 최종 모델은 lr=1e-5 실행의 3 epoch입니다. 매 epoch에 모든 학습 행을 정확히 한 번 사용했는지 자동 검사했습니다. 초기 약 5만 질의 파일럿과 전체 학습은 별개이며, 최종 모델은 파일럿의 가중치를 이어 학습한 모델이 아닙니다.

이번 본 학습은 대조학습이며 Cross-Encoder soft-score 증류는 사용하지 않았습니다. 추가 수작업 관련도 라벨링 없이 기존 감독 데이터와 행동 기반 평가 신호를 사용했습니다.

Evaluation

검증 질의 3,605개로 학습률과 체크포인트를 선택하고, 최종 모델을 고정한 후 테스트 질의 8,629개를 평가했습니다. ColBERT 학습 질의와 dev/test는 정규화 query key 기준으로 분리했습니다. 시간 기반 holdout이나 도서 ID 전체 분리를 의미하지는 않습니다.

아래 점수는 내부 도서 검색 벤치마크의 결과이며 다른 데이터셋의 지표 절댓값과 직접 비교해서는 안 됩니다.

1. 전체 문서 직접 검색

모든 모델이 동일한 3,396,913개 문서와 동일한 텍스트·테스트 질의·관련도 정보를 사용했습니다.

모델	NDCG@10	MRR@10*	Recall@100	Recall@200
도메인 Dense (bge-m3-yes24-ft)	0.1775	0.1977	0.2619	0.2858
도메인 Sparse (splade-ko-yes24-ft)	0.1719	0.1824	0.2747	0.3008
이 모델	0.2629	0.2959	0.3435	0.3643
Dense + Sparse RRF	0.2008	0.2190	0.2956	0.3175
Dense + Sparse + 이 모델 RRF	0.2347	0.2562	0.3337	0.3551

RRF는 k=60, 동일 가중치이며 테스트 점수에 맞춰 튜닝하지 않았습니다. 이번 결과에서는 이 모델 단독이 동일 가중치 결합보다 우수했습니다.

이 모델의 NDCG@10 차이에 대한 질의별 paired bootstrap 3,000회, 95% 신뢰구간:

비교	절대 차이	95% CI
이 모델 − Dense	+0.08544	[+0.08148, +0.08933]
이 모델 − Sparse	+0.09099	[+0.08716, +0.09483]
이 모델 − Dense+Sparse RRF	+0.06207	[+0.05886, +0.06544]

Dense/Sparse의 과거 학습 데이터 버전·학습량은 이 모델과 다르며, 실제 split이 없어 테스트 질의의 학습 노출 여부를 확인하지 못했습니다. 이는 배포 후보 모델 비교이지 모델 구조만의 통제 실험은 아닙니다. 공개 베이스 ColBERT의 직접 검색 평가는 이 표에 포함하지 않았습니다.

2. 베이스 대비 고정 후보 재정렬

같은 테스트 질의 8,629개에 대해 기존 Qwen 검색기가 3,372,402문서에서 찾은 Top-200 후보를 정렬했습니다.

모델	NDCG@10	MRR@10*	Recall@100
yjoonjang/colbert-ko-v1	0.1711	0.1886	0.2634
이 모델	0.2442	0.2779	0.2810

NDCG@10 절대 개선은 +0.07312, 95% CI는 [+0.06969, +0.07666]입니다. 이 비교는 같은 후보에서의 튜닝 효과를 측정합니다. 직접 검색 표와 corpus·후보 제약이 달라 두 표의 차이를 튜닝만의 효과로 해석하면 안 됩니다.

지표 정의

• NDCG: 행동 기반 관련도 등급 1/2/3에 대해 gain = 2^relevance - 1을 사용하고, 이상적인 순위로 정규화한 질의별 점수를 평균합니다.
• MRR@10*: 질의별 최고 관련도 등급 문서의 첫 등장 순위 역수입니다. 모든 관련 문서 중 첫 번째를 사용하는 일반적인 binary MRR와 정의가 다릅니다.
• Recall: 상위 k개에서 찾은 qrels 문서 수를 질의별 전체 qrels 수로 나눈 뒤 평균합니다.

테스트에는 67,293개의 질의–도서 정답 관계가 있고 corpus에 누락된 정답 관계는 0개입니다. 행동에 관측되지 않은 관련 도서는 정답 목록에 없을 수 있습니다. NDCG 0.2629는 정확도 26.29%를 의미하지 않습니다.

Retrieval configuration and cost

직접 검색의 ColBERT 설정은 다음과 같습니다.

항목	값
인덱스	FastPlaid, 8-bit
IVF probes	512
Full-score candidates	65,536
원본 MaxSim 재점수화 후보	4,096
ANN 보정	dev 16질의, 전체 corpus 정확 MaxSim과 비교
Top-100 ID 평균 일치율	96.94%

ANN 설정은 dev로 보정했습니다. 위 일치율은 테스트 전체의 ANN recall을 의미하지 않습니다.

모델	검색용 파일 크기	8,629개 질의 배치 검색	질의당 환산
Dense	12.96 GiB	197.1초	22.8ms
Sparse	1.95 GiB	415.8초	48.2ms
이 모델	53.45 GiB	9,642.7초	1,117.5ms

이 표는 온라인 응답 시간 벤치마크가 아닙니다. 질의 벡터가 미리 만들어진 배치 검색이며 질의 인코딩·네트워크·대기 시간은 제외합니다. Dense는 GPU 전수 내적, Sparse는 CPU CSR 전수 연산, ColBERT는 GPU ANN 및 원본 재점수화를 사용해 구현과 병렬 처리 방식이 다릅니다. 모델 고유의 속도 차이나 SLA로 일반화하지 마십시오.

ColBERT 파일 크기에는 인덱스와 검색에 필요한 원본 FP16 token vectors를 합산했습니다. 53.45 GiB는 모델 가중치 크기가 아니라 이 corpus의 검색 저장 공간입니다. corpus 인덱스는 모델 가중치와 별도로 구축해야 합니다.

Intended use and limitations

• 한국어 도서 메타데이터 검색, 후보 재정렬, 도서 탐색 RAG의 검색 구성요소로 평가할 수 있습니다.
• 이 모델은 답변 생성 모델이 아니며, RAG 답변 정확도나 근거 충실성을 직접 검증하지 않았습니다.
• 도서 본문, 법률·의료 등 다른 도메인, 다른 언어에서 동일한 성능을 보장하지 않습니다.
• 긴 질의는 32토큰에서 잘릴 수 있습니다. 긴 대화 전체를 검색 질의로 그대로 넣지 말고 필요한 내용을 보존하는 별도 질의 구성 방식을 검증하십시오.
• 문서도 128토큰 제한이 있습니다. 학습에 사용한 메타데이터보다 긴 본문에는 별도 chunking 및 평가가 필요합니다.
• seed를 바꾼 반복 실험은 수행하지 않았습니다. 작은 체크포인트 간 차이의 재현성은 미확인입니다.
• 학습 데이터와 평가 corpus는 내부 데이터이며, 이 모델 카드가 데이터셋의 공개 배포를 뜻하지 않습니다.

Provenance

이 모델은 위에 명시한 yjoonjang/colbert-ko-v1 체크포인트를 기반으로 도메인 튜닝했습니다.

최종 backbone model.safetensors SHA-256:

97d37dec8c2e708fb1fc92494e0fe4ba404cdb040a75c80e9ed4ea013249e450

이 해시는 backbone 파일만의 해시입니다. 실제 사용에는 128차원 projection, masking/normalization 모듈 설정, tokenizer 및 prompt 설정도 함께 필요합니다.

References

• Base model: yjoonjang/colbert-ko-v1
• Sentence Transformers multi-vector encoders
• ColBERT
• FastPlaid