Embedding Usages

Embedding Usages (임베딩 사용법)

Embedding 모델은 텍스트, 이미지, 오디오 같은 비정형 데이터를 임베딩이라는 구조화된 수치 표현으로 변환하도록 설계된 머신러닝 모델 클래스예요. vLLM에서는 embed pooling task로 구현되며, 오프라인으로 LLM.embed(...), LLM.encode(..., pooling_task="embed"), LLM.score(...)를, 온라인으로 Cohere Embed API(/v2/embed), OpenAI 호환 Embeddings API(/v1/embeddings), Pooling API(/pooling)를 제공해요.

출처: 문서

본문

요약

Model Usage: (시퀀스) 임베딩
Pooling Task: embed
오프라인 API: LLM.embed(...), LLM.encode(..., pooling_task="embed"), LLM.score(...)
온라인 API: Cohere Embed API(/v2/embed), OpenAI 호환 Embeddings API(/v1/embeddings), Pooling API(/pooling)

(시퀀스) 임베딩과 토큰 임베딩의 핵심 차이는 출력 세분성이에요. (시퀀스) 임베딩은 전체 입력 시퀀스에 대해 단일 임베딩 벡터를 생성하고, 토큰 임베딩은 시퀀스 내 각 토큰에 대한 임베딩을 생성해요. 많은 임베딩 모델이 둘 다 지원해요.

전형적인 사용 사례

Embedding

임베딩 모델의 가장 기본적인 사용 사례는 RAG처럼 입력을 임베딩하는 것이에요.

Pairwise Similarity

Score API를 사용해 pairwise 유사도 점수를 계산해 유사도 매트릭스를 만들 수 있어요.

지원 모델

텍스트 전용 모델

Architecture	Models	Example HF Models	LoRA	PP
BertModel	BERT 기반	BAAI/bge-base-en-v1.5, Snowflake/snowflake-arctic-embed-xs 등
BertSpladeSparseEmbeddingModel	SPLADE	naver/splade-v3
BgeM3EmbeddingModel	BGE-M3	BAAI/bge-m3
Gemma2Model^C	Gemma 2 기반	BAAI/bge-multilingual-gemma2 등	✅	✅
Gemma3TextModel^C	Gemma 3 기반	google/embeddinggemma-300m 등	✅	✅
GteModel	Arctic-Embed-2.0-M	Snowflake/snowflake-arctic-embed-m-v2.0
GteNewModel	mGTE-TRM	Alibaba-NLP/gte-multilingual-base 등
JinaEmbeddingsV5Model^C	Qwen3-decoder 또는 EuroBERT-encoder 백본	jinaai/jina-embeddings-v5-text-small 등	✅	✅
LlamaBidirectionalModel^C	Llama 기반 양방향 어텐션	nvidia/llama-nemotron-embed-1b-v2 등	✅	✅
LlamaModel^C, LlamaForCausalLM^C, MistralModel^C 등	Llama 기반	intfloat/e5-mistral-7b-instruct 등	✅	✅
ModernBertModel	ModernBERT 기반	Alibaba-NLP/gte-modernbert-base 등	✅
NomicBertModel	Nomic BERT	nomic-ai/nomic-embed-text-v1 등
Qwen2Model^C, Qwen2ForCausalLM^C	Qwen2 기반	ssmits/Qwen2-7B-Instruct-embed-base, Alibaba-NLP/gte-Qwen2-7B-instruct 등	✅	✅
Qwen3Model^C, Qwen3ForCausalLM^C	Qwen3 기반	Qwen/Qwen3-Embedding-0.6B 등	✅	✅
RobertaModel, RobertaForMaskedLM	RoBERTa 기반	sentence-transformers/all-roberta-large-v1 등
VoyageQwen3BidirectionalEmbedModel^C	Voyage Qwen3 기반 양방향 어텐션	voyageai/voyage-4-nano 등	✅	✅
XLMRobertaModel	XLM-RoBERTa 기반	BAAI/bge-m3, intfloat/multilingual-e5-base, jinaai/jina-embeddings-v3 등
Model^C, ForCausalLM^C 등	생성 모델	N/A	*	*

^C: --convert embed로 임베딩 모델로 자동 변환됨. * 기능 지원은 원본 모델과 동일.

참고: 2세대 GTE 모델(mGTE-TRM)은 NewModel로 이름이 지어졌어요. NewModel이라는 이름은 너무 일반적이므로 --hf-overrides '{"architectures": ["GteNewModel"]}'로 GteNewModel 아키텍처를 지정해야 해요. 참고: ssmits/Qwen2-7B-Instruct-embed-base는 잘못 정의된 Sentence Transformers config를 가져요. --pooler-config '{"pooling_type": "MEAN"}'로 mean pooling을 직접 설정해야 해요. 참고: Alibaba-NLP/gte-Qwen2-*는 올바른 tokenizer를 로드하려면 --trust-remote-code를 활성화해야 해요. 참고: BAAI/bge-m3는 sparse/colbert 임베딩용 추가 가중치가 함께 오는데, 관련 페이지를 참고하세요. 참고: jinaai/jina-embeddings-v3는 LoRA를 통해 여러 작업을 지원하지만, vLLM은 현재 LoRA 가중치를 병합해 text-matching 작업만 지원해요. 참고: jinaai/jina-embeddings-v5-text-small(Qwen3 decoder)과 -text-nano(양방향 EuroBERT encoder)는 네 개의 작업별 LoRA 어댑터(retrieval, text-matching, classification, clustering)와 함께 제공돼요. vLLM은 로드 시 선택된 어댑터를 기본 가중치에 병합해요. 작업 선택은 --hf-overrides '{"jina_task": "<task>"}'로 하며 기본은 retrieval이에요.

멀티모달 모델

Architecture	Models	Inputs	Example HF Models	LoRA	PP
CLIPModel	CLIP	T / I	openai/clip-vit-base-patch32 등
LlamaNemotronVLModel	Llama Nemotron Embedding + SigLIP	T + I	nvidia/llama-nemotron-embed-vl-1b-v2
LlavaNextForConditionalGeneration^C	LLaVA-NeXT 기반	T / I	royokong/e5-v	✅
Phi3VForCausalLM^C	Phi-3-Vision 기반	T + I	TIGER-Lab/VLM2Vec-Full	✅
Qwen3VLForConditionalGeneration^C	Qwen3-VL	T + I + V	Qwen/Qwen3-VL-Embedding-2B 등	✅	✅
SiglipModel	SigLIP, SigLIP2	T / I	google/siglip-base-patch16-224 등
ForConditionalGeneration^C, ForCausalLM^C 등	생성 모델	*	N/A	*	*

모델이 위 목록에 없으면 as_embedding_model로 자동 변환을 시도해요. 기본적으로 전체 프롬프트의 임베딩을 마지막 토큰에 해당하는 정규화된 히든 스테이트에서 추출해요.

참고: --convert embed로 어떤 아키텍처의 모델도 임베딩 모델로 자동 변환할 수 있지만, 최상의 결과를 얻으려면 임베딩 모델로 특별히 학습된 pooling 모델을 사용해야 해요.

오프라인 추론

Pooling 파라미터

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

LLM.embed

embed 메서드는 각 프롬프트에 대한 임베딩 벡터를 출력해요:

from vllm import LLM

llm = LLM(model="intfloat/e5-small", runner="pooling")
(output,) = llm.embed("Hello, my name is")
embeds = output.outputs.embedding
print(f"Embeddings: {embeds!r} (size={len(embeds)})")

코드 예시: examples/basic/offline_inference/embed.py

LLM.encode

LLM.encode를 임베딩 모델에 쓸 때는 pooling_task="embed"를 설정하세요. output.outputs.data에서 데이터를 얻을 수 있어요.

LLM.score

score 메서드는 문장 쌍 간 유사도 점수를 출력해요. embedding 작업을 지원하는 모든 모델은 두 입력 프롬프트 임베딩의 cosine 유사도를 계산해 score API로 유사도 점수를 계산할 수 있어요:

from vllm import LLM

llm = LLM(model="intfloat/e5-small", 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}")

온라인 서빙

OpenAI 호환 Embeddings API

Embeddings API는 OpenAI의 Embeddings API와 호환되며, 공식 OpenAI Python 클라이언트로 상호작용할 수 있어요. 코드 예시: examples/pooling/embed/openai_embedding_client.py.

Completion 파라미터 — model, user, input, encoding_format(기본 "float"), dimensions. 추가 파라미터는 classify와 유사하며 truncate_prompt_tokens, padding, truncation_side, request_id, priority, mm_processor_kwargs, cache_salt, add_special_tokens, embed_dtype(기본 "float32"), endianness(기본 "native"), use_activation을 지원해요.

모델에 채팅 템플릿이 있으면 입력을 messages 리스트(Chat API와 같은 스키마)로 바꿔 모델의 단일 프롬프트로 취급할 수 있어요.

Embedding Usages