토큰 임베딩 사용법

토큰 임베딩 사용법 (Token Embedding Usages)

토큰 임베딩(token embedding)은 시퀀스 하나를 벡터 하나로 줄이는 게 아니라, 입력 안의 각 토큰마다 임베딩 벡터를 만들어내는 pooling 태스크예요. 멀티-벡터 검색이나 late-interaction 스코어링 같은 고급 검색 기법의 토대가 되죠. 시퀀스 임베딩과 어떻게 다른지부터 살펴볼게요.

출처: vLLM 공식 문서 — models/pooling_models/token_embed

한눈에 보는 요약 (Summary)

모델 사용 방식: 토큰 분류 모델
풀링 태스크: token_embed
오프라인 API:
- LLM.encode(..., pooling_task="token_embed")
온라인 API:
- Pooling API (/pooling)

(시퀀스) 임베딩 태스크와 토큰 임베딩 태스크의 차이는 이래요. 시퀀스 임베딩은 시퀀스당 하나의 임베딩을, 토큰 임베딩은 토큰당 하나의 임베딩을 출력해요.

많은 임베딩 모델이 시퀀스 임베딩과 토큰 임베딩을 동시에 지원해요. 시퀀스 임베딩에 대한 자세한 내용은 이 페이지를 참고하세요.

참고: v0.21부터 pooling 멀티태스크 지원이 제거됐어요. 기본 풀링 태스크(embed)가 원하는 값이 아니라면, 오프라인에서는 PoolerConfig(task="token_embed")로, 온라인에서는 --pooler-config.task token_embed로 직접 지정해야 해요.

주요 사용 사례 (Typical Use Cases)

멀티-벡터 검색 (Multi-Vector Retrieval)

구현 예시는 다음을 참고하세요.

오프라인: examples/pooling/token_embed/multi_vector_retrieval_offline.py
온라인: examples/pooling/token_embed/multi_vector_retrieval_online.py

Late interaction

두 입력 프롬프트 사이의 유사도 점수는 score API를 통한 late interaction으로 계산할 수 있어요. 자세한 내용은 Score API를 참고하세요.

마지막 hidden states 추출 (Extract last hidden states)

어떤 아키텍처든 --convert embed를 쓰면 임베딩 모델로 변환할 수 있어요. 그러면 토큰 임베딩을 활용해 이 모델들의 마지막 hidden states를 추출할 수 있죠.

지원되는 모델 (Supported Models)

텍스트 전용 모델 (Text-only Models)

아키텍처	모델	예시 HF 모델	LoRA	PP
`ColBERTLfm2Model`	LFM2	`LiquidAI/LFM2-ColBERT-350M`
`ColBERTModernBertModel`	ModernBERT	`lightonai/GTE-ModernColBERT-v1`
`ColBERTJinaRobertaModel`	Jina XLM-RoBERTa	`jinaai/jina-colbert-v2`
`HF_ColBERT`	BERT	`answerdotai/answerai-colbert-small-v1`, `colbert-ir/colbertv2.0`
`Model`C, `ForCausalLM`C 등	생성형 모델	N/A	*	*

멀티모달 모델 (Multimodal Models)

참고: 멀티모달 모델 입력에 대한 자세한 내용은 이 페이지를 참고하세요.

아키텍처	모델	입력	예시 HF 모델	LoRA	PP
`ColModernVBertForRetrieval`	ColModernVBERT	T / I	`ModernVBERT/colmodernvbert-merged`
`ColPaliForRetrieval`	ColPali	T / I	`vidore/colpali-v1.3-hf`
`ColQwen3`	Qwen3-VL	T / I	`TomoroAI/tomoro-colqwen3-embed-4b`, `TomoroAI/tomoro-colqwen3-embed-8b`
`ColQwen3_5`	ColQwen3.5	T + I + V	`athrael-soju/colqwen3.5-4.5B-v3`, `vultr/VultronRetrieverPrime-Qwen3.5-8B`
`OpsColQwen3Model`	Qwen3-VL	T / I	`OpenSearch-AI/Ops-Colqwen3-4B`, `OpenSearch-AI/Ops-Colqwen3-8B`
`Qwen3VLNemotronEmbedModel`	Qwen3-VL	T / I	`nvidia/nemotron-colembed-vl-4b-v2`, `nvidia/nemotron-colembed-vl-8b-v2`	✅	✅
`ForConditionalGeneration`C, `ForCausalLM`C 등	생성형 모델	*	N/A	*	*

C 표시가 붙은 모델은 --convert embed로 자동 변환돼요. * 표시는 기능 지원이 원래 모델과 동일하다는 뜻이에요.

목록에 없는 모델이라면 as_embedding_model을 이용해 자동 변환을 시도해요.

특수 모델 (Special models)

아키텍처	모델	예시 HF 모델	LoRA	PP
`JinaForRanking`	Qwen3 기반	`jinaai/jina-reranker-v3`

jina-reranker-v3는 독특한 last but not late interaction 아키텍처를 쓰는 listwise 문서 reranker예요. 자세한 내용은 examples/pooling/token_embed/jina_reranker_v3_offline.py를 참고하세요.

오프라인 추론 (Offline Inference)

풀링 파라미터 (Pooling Parameters)

다음 풀링 파라미터를 지원해요.

    use_activation: bool | None = None
    dimensions: int | None = None

`LLM.encode`

토큰 임베딩 모델에서 LLM.encode를 쓸 때는 pooling_task="token_embed"로 설정해요.

from vllm import LLM

llm = LLM(model="answerdotai/answerai-colbert-small-v1", runner="pooling")
(output,) = llm.encode("Hello, my name is", pooling_task="token_embed")

data = output.outputs.data
print(f"Data: {data!r}")

`LLM.score`

score 메서드는 문장 쌍 사이의 유사도 점수를 출력해요.

토큰 임베딩 태스크를 지원하는 모든 모델은, 두 입력 프롬프트의 late interaction을 계산해 유사도 점수를 내는 score API도 지원해요.

from vllm import LLM

llm = LLM(model="answerdotai/answerai-colbert-small-v1", runner="pooling")
(output,) = llm.score(
    "What is the capital of France?",
    "The capital of Brazil is Brasilia.",
)

score = output.outputs.score
print(f"Score: {score}")

온라인 서빙 (Online Serving)

Pooling API를 참고하고, 요청에 "task":"token_embed"를 사용하면 돼요.

더 많은 예제 (More examples)

더 많은 예제는 examples/pooling/token_embed에서 찾을 수 있어요.

지원 기능 (Supported Features)

토큰 임베딩 기능은 (시퀀스) 임베딩과 일관돼요. 자세한 내용은 이 페이지를 참고하세요.

토큰 임베딩 사용법