모델

API로 제공하는 모델은 아래 네 개입니다. 다른 KURE 패밀리 모델은 Hugging Face에서 받아 직접 실행할 수 있습니다 (모델 비교).

모델 ID (별칭)	스냅샷	엔드포인트	용도
`kure-v3`	`kure-v3-20261016`	`/embeddings`	Dense 임베딩 (의미 검색)
`kure-sparse-nano`	`kure-sparse-nano-20261016`	`/sparse-embeddings`	희소 임베딩 (역색인·하이브리드 검색)
`kure-sparse-base`	`kure-sparse-base-20261016`	`/sparse-embeddings`	희소 임베딩 (nano보다 정확, 어휘가 큼)
`kure-reranker-nano`	`kure-reranker-nano-20261016`	`/rerank`	재정렬 (cross-encoder)

모델을 다른 엔드포인트에 보내면 404와 함께 맞는 엔드포인트를 알려 줍니다.

모델 ID와 버전

모델 ID는 스냅샷과 별칭 두 가지입니다.

종류	예	가리키는 것
스냅샷	`kure-v3-20261016`	그 날짜에 배포한 가중치. 바뀌지 않습니다
별칭	`kure-v3-latest`	그 모델의 최신 스냅샷
별칭	`kure-v3`	`kure-v3-latest`와 같음

응답의 model에는 실제로 처리한 스냅샷 ID가 들어갑니다. 별칭이 지금 어느 스냅샷을 가리키는지는 GET /models의 alias_for로 확인할 수 있습니다.
가중치를 고치면 새 날짜의 스냅샷을 추가하고 별칭을 옮깁니다. 별칭을 옮기기 전에 공지합니다.
벡터를 저장해 두고 검색하는 서비스라면 스냅샷 ID를 쓰세요. 별칭이 옮겨 가면 같은 문장이라도 벡터가 달라져, 저장해 둔 문서 벡터와 새 질의 벡터를 비교할 수 없게 됩니다. 스냅샷을 쓰면 직접 바꾸기 전까지 결과가 그대로입니다.
리랭커·희소 임베딩 모델도 같은 규칙입니다 (kure-reranker-nano-20261016, kure-sparse-nano-latest, kure-sparse-base 등).

KURE-v3

항목	값
모델 ID	`kure-v3-20261016` (별칭 `kure-v3`, `kure-v3-latest`)
종류	Dense 단일 벡터 임베딩
파라미터	1.1B
출력 차원	2048 (MRL: 256, 512, 768, 1024, 2048)
최대 입력 길이	8,192 토큰
정규화	L2 정규화 (내적 = 코사인 유사도)
언어	한국어 중심, 한↔영 교차 검색

질의와 문서 구분 (`input_type`)

KURE-v3는 질의와 문서 앞에 서로 다른 접두어를 붙여 학습했습니다. input_type을 주면 서버가 알맞은 접두어를 붙여 줍니다.

`input_type`	붙는 접두어	언제
`query`	`query:`	사용자가 입력한 검색어·질문
`document`	`passage:`	검색 대상 문서, 문단, 청크
생략	없음	텍스트를 그대로 임베딩

검색에서는 질의와 문서를 반드시 구분하세요. 같은 문장 두 개의 유사도를 비교하는 경우(중복 탐지, 클러스터링)에는 양쪽 모두 같은 input_type을 쓰면 됩니다.

접두어를 직접 붙인 텍스트에 input_type까지 주면 접두어가 두 번 붙습니다. 둘 중 하나만 쓰세요.

MRL 차원 줄이기

KURE-v3는 Matryoshka Representation Learning(MRL)으로 학습해 벡터 앞부분만 잘라 써도 성능이 크게 떨어지지 않습니다. dimensions를 주면 서버가 앞에서부터 자른 뒤 다시 정규화해서 돌려줍니다.

`dimensions`	float32 벡터 하나의 크기	2048 대비 저장 공간
2048 (기본)	8 KB	100%
1024	4 KB	50%
768	3 KB	38%
512	2 KB	25%
256	1 KB	13%

문서와 질의는 같은 차원으로 임베딩해야 비교할 수 있습니다.
2048 차원 벡터를 저장해 두었다면 API를 다시 부르지 않고 앞부분을 잘라 다시 정규화해도 같은 결과입니다.
차원별 순위 변화는 플레이그라운드에서 직접 비교해 볼 수 있습니다.

긴 문서

텍스트 하나는 최대 8,192 토큰이며, 넘으면 400 context_length_exceeded를 돌려줍니다. 일반적인 한국어 문장은 1,000자에 600 토큰 안팎이라 8,192 토큰은 대략 1만 3천 자입니다. 텍스트마다 다르므로 긴 문서는 문단 단위로 나누어 넣는 것을 권장합니다. 실제 토큰 수는 응답의 usage.prompt_tokens로 확인할 수 있습니다.

KURE-Sparse

항목	`kure-sparse-nano`	`kure-sparse-base`
종류	학습형 희소 벡터 (SPLADE 계열)	학습형 희소 벡터 (영어 어휘 + 다국어 어휘)
파라미터	149M	593M
어휘 크기 (`dimension`)	36,282	280,524
최대 입력 길이	8,192 토큰 (넘으면 잘라서 인코딩)	8,192 토큰
MTEB(kor) Retrieval nDCG@10	0.7716	0.7984
Hugging Face	KURE-Sparse-nano	KURE-Sparse-base

질의와 문서를 다르게 인코딩하므로 input_type이 필수입니다. 사용법은 Sparse Embeddings API를 보세요.

KURE-Reranker-nano

항목	값
종류	Cross-encoder 리랭커
파라미터	149M
최대 입력 길이	질의 + 문서 8,192 토큰 (넘으면 긴 쪽부터 잘라서 채점)
리랭킹 nDCG@10 (한국어 9개 벤치마크, BM25 상위 50개)	0.8757 (1.7B base는 0.8800)
점수	관련 확률 0~1 (`relevance_score`)
Hugging Face	KURE-Reranker-nano

사용법은 Rerank API를 보세요.

모델 수명 주기

GPU 자원이 한정되어 있어 새 모델을 내놓으면 이전 모델은 일정 기간 뒤 서빙을 종료합니다. 종료는 아래 단계로 진행하며, 공지부터 종료까지 최소 30일을 둡니다.

상태	서빙	API에서 보이는 것
`active`	O	평소와 같음
`deprecated`	O	응답 헤더 `Deprecation`, `Sunset`(종료 예정일). `GET /models`의 `status`, `sunset`, `replacement`
retired	X	`410 model_retired`, 메시지에 대체 모델

최근 30일 안에 deprecated 모델을 쓴 계정은 대시보드 상단에 안내가 표시됩니다. 계정 이메일을 알 수 있으면 메일로도 알려 드립니다.
수명 주기는 스냅샷 단위입니다. 별칭은 종료할 스냅샷을 가리키지 않도록 먼저 옮깁니다.
스냅샷이 바뀌면 벡터끼리 비교할 수 없으므로 저장해 둔 문서 벡터를 새 스냅샷으로 모두 다시 만들어야 합니다.
코드에서 Sunset 헤더나 GET /models의 status를 확인해 경고를 남겨 두면 공지를 놓치지 않습니다.

웨이트 공개

KURE-v3 웨이트는 Hugging Face에 공개되어 있습니다. kure-v3-20261016은 nlpai-lab/KURE-v3의 revision 9e799c2와 같은 가중치라, sentence-transformers로 직접 만든 벡터와 API 벡터를 섞어 쓸 수 있습니다.

모델