Specific Model Examples

Specific Model Examples (특정 모델 예시)

이 문서는 ColBERT 계열, ColQwen3, Llama Nemotron 멀티모달, BAAI/bge-m3 같은 특수 pooling 모델들의 사용 예시를 다뤄요. 각 모델의 백본과 아키텍처 오버라이드 방법, rerank/score API, raw 토큰 임베딩 추출 등을 보여줘요.

출처: 문서

본문

ColBERT Late Interaction 모델

ColBERT(Contextualized Late Interaction over BERT)는 문서 랭킹에 per-token 임베딩과 MaxSim 스코어링을 사용하는 검색 모델이에요. 단일 벡터 임베딩 모델과 달리 토큰 수준 표현을 유지하고 late interaction으로 관련성 점수를 계산해, cross-encoder보다 효율적이면서 더 나은 정확도를 제공해요.

vLLM은 여러 인코더 백본으로 ColBERT 모델을 지원해요:

HF_ColBERT — BERT 백본: answerdotai/answerai-colbert-small-v1, colbert-ir/colbertv2.0
ColBERTModernBertModel — ModernBERT 백본: lightonai/GTE-ModernColBERT-v1
ColBERTJinaRobertaModel — Jina XLM-RoBERTa 백본: jinaai/jina-colbert-v2
ColBERTLfm2Model — LFM2 백본: LiquidAI/LFM2-ColBERT-350M

BERT 기반 ColBERT 모델은 바로 동작해요:

vllm serve answerdotai/answerai-colbert-small-v1

non-BERT 백본은 --hf-overrides로 올바른 아키텍처를 설정해야 해요:

# ModernBERT backbone
vllm serve lightonai/GTE-ModernColBERT-v1 \
    --hf-overrides '{"architectures": ["ColBERTModernBertModel"]}'

# Jina XLM-RoBERTa backbone
vllm serve jinaai/jina-colbert-v2 \
    --hf-overrides '{"architectures": ["ColBERTJinaRobertaModel"]}' \
    --trust-remote-code

# LFM2 backbone
vllm serve LiquidAI/LFM2-ColBERT-350M \
    --hf-overrides '{"architectures": ["ColBERTLfm2Model"]}'

그다음 rerank API를 사용할 수 있어요:

curl -s http://localhost:8000/rerank -H "Content-Type: application/json" -d '{
    "model": "answerdotai/answerai-colbert-small-v1",
    "query": "What is machine learning?",
    "documents": [
        "Machine learning is a subset of artificial intelligence.",
        "Python is a programming language.",
        "Deep learning uses neural networks."
    ]
}'

또는 score API:

curl -s http://localhost:8000/score -H "Content-Type: application/json" -d '{
    "model": "answerdotai/answerai-colbert-small-v1",
    "text_1": "What is machine learning?",
    "text_2": ["Machine learning is a subset of AI.", "The weather is sunny."]
}'

Pooling API에서 token_embed 작업으로 raw 토큰 임베딩도 얻을 수 있어요. 예시: examples/pooling/score/colbert_rerank_online.py.

ColQwen3 멀티모달 Late Interaction 모델

ColQwen3는 ColPali 기반으로, ColBERT의 late interaction 방식을 멀티모달 입력으로 확장해요. ColBERT가 텍스트 전용 토큰 임베딩에 동작하는 반면, ColPali/ColQwen3는 텍스트와 이미지(예: PDF 페이지, 스크린샷, 도표)를 per-token L2-정규화 벡터로 임베딩하고 MaxSim 스코어링으로 관련성을 계산해요. ColQwen3는 특히 Qwen3-VL을 비전-언어 백본으로 사용해요.

ColQwen3 — Qwen3-VL 백본: TomoroAI/tomoro-colqwen3-embed-4b, TomoroAI/tomoro-colqwen3-embed-8b
OpsColQwen3Model — Qwen3-VL: OpenSearch-AI/Ops-Colqwen3-4B, OpenSearch-AI/Ops-Colqwen3-8B
Qwen3VLNemotronEmbedModel — Qwen3-VL: nvidia/nemotron-colembed-vl-4b-v2, nvidia/nemotron-colembed-vl-8b-v2

서버 시작:

vllm serve TomoroAI/tomoro-colqwen3-embed-4b --max-model-len 4096

텍스트 전용 스코어링/리랭킹: /rerank API(query + documents)나 /score API(text_1 + text_2)를 사용해요.

멀티모달 스코어링/리랭킹 (텍스트 쿼리 × 이미지 문서): /score와 /rerank API는 멀티모달 입력을 직접 받아요. /score는 data_1/data_2, /rerank는 documents 필드에 image_url과 text 파트를 포함한 content 리스트(OpenAI chat completion API와 동일한 형식)로 이미지 문서를 전달해요. top_n도 설정할 수 있어요.

Raw 토큰 임베딩: /pooling API에 token_embed 작업으로 얻을 수 있음. 이미지 입력은 chat-style messages 필드를 사용해요:

curl -s http://localhost:8000/pooling -H "Content-Type: application/json" -d '{
    "model": "TomoroAI/tomoro-colqwen3-embed-4b",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
                {"type": "text", "text": "Describe the image."}
            ]
        }
    ]
}'

예시: examples/pooling/token_embed/colqwen3_token_embed_online.py, examples/pooling/score/colqwen3_rerank_online.py.

ColQwen3.5 멀티모달 Late Interaction 모델

ColQwen3.5는 ColPali 기반으로 ColBERT의 late interaction을 멀티모달 입력으로 확장해요. Qwen3.5 hybrid 백본(linear + full attention)을 사용하고 MaxSim 스코어링용 per-token L2-정규화 벡터를 생성해요.

ColQwen3_5 — Qwen3.5 백본: athrael-soju/colqwen3.5-4.5B

vllm serve athrael-soju/colqwen3.5-4.5B --max-model-len 4096

그다음 /rerank(query + documents), /score(text_1 + text_2) 엔드포인트를 사용할 수 있어요. 예시: examples/pooling/score/colqwen3_5_rerank_online.py.

Llama Nemotron 멀티모달

임베딩 모델

Llama Nemotron VL Embedding 모델은 양방향 Llama 임베딩 백본(nvidia/llama-nemotron-embed-1b-v2)에 SigLIP을 비전 인코더로 결합해 텍스트와/또는 이미지에서 단일 벡터 임베딩을 생성해요.

LlamaNemotronVLModel — Bidirectional Llama + SigLIP: nvidia/llama-nemotron-embed-vl-1b-v2

vllm serve nvidia/llama-nemotron-embed-vl-1b-v2 \
    --trust-remote-code \
    --chat-template examples/pooling/embed/template/nemotron_embed_vl.jinja

참고: 이 모델 tokenizer에 번들된 채팅 템플릿은 embeddings API에 적합하지 않아요. messages 기반(chats-style) embeddings API로 서빙할 때는 위의 override 템플릿을 사용하세요. override 템플릿은 메시지 role로 적절한 프리픽스를 자동 붙여요: query(→ query:) 또는 document(→ passage:) role, 그 외 role은 프리픽스 없음.

텍스트 쿼리 임베딩 (/v1/embeddings, role: query), 이미지 임베딩(messages의 role: document + image_url)으로 사용할 수 있어요.

리랭커 모델

Llama Nemotron VL reranker 모델은 같은 양방향 Llama + SigLIP 백본에 시퀀스 분류 헤드를 결합해 cross-encoder 스코어링/리랭킹을 해요.

LlamaNemotronVLForSequenceClassification — Bidirectional Llama + SigLIP: nvidia/llama-nemotron-rerank-vl-1b-v2

vllm serve nvidia/llama-nemotron-rerank-vl-1b-v2 \
    --runner pooling \
    --trust-remote-code \
    --chat-template examples/pooling/score/template/nemotron-vl-rerank.jinja

참고: 이 체크포인트 tokenizer의 채팅 템플릿은 Score/Rerank API에 적합하지 않아요. 위 override 템플릿을 사용하세요.

/score(data_1 + data_2) 및 /rerank(query + documents)로 텍스트 쿼리를 이미지 문서와 스코어링/리랭킹할 수 있어요.

BAAI/bge-m3

BAAI/bge-m3는 dense 검색, 어휘 매칭(lexical matching), ColBERT 스타일 multi-vector 검색을 지원해요. config.json이 XLMRobertaModel로 선언되어 있어, vLLM은 추가 sparse/ColBERT 가중치 없이 vanilla RoBERTa 모델로 로드해요. 그래서 아래 예시는 아키텍처를 BgeM3EmbeddingModel로 override해요.

세 가지 검색 모드는 구체적인 pooling task로 매핑돼요:

Retrieval mode	Pooling task	Output
Dense	embed	입력당 임베딩 벡터 1개
Lexical/sparse	token_classify	non-special 토큰당 스칼라 가중치 1개
ColBERT multi-vector	token_embed	non-special 토큰당 임베딩 벡터 1개

로드 시 task를 선택해 하나의 구체적인 모드를 서빙해요:

vllm serve BAAI/bge-m3 \
  --runner pooling \
  --hf-overrides '{"architectures": ["BgeM3EmbeddingModel"]}' \
  --pooler-config.task <task>

dense 임베딩: <task>를 embed로 바꾸고 Embeddings API(/v1/embeddings) 사용
어휘(lexical) 가중치: <task>를 token_classify로 바꾸고 Pooling API(/pooling) 사용. 출력 스키마 제한으로 각 입력에 대한 토큰 점수 리스트로 나오므로, 토큰 ID와 점수를 짝지으려면 /tokenize도 호출해야 해요. test_bge_m3.py는 반복 토큰 ID 결합까지 포함한 완전한 예시예요.
ColBERT 벡터: <task>를 token_embed로 바꾸고 Pooling API 사용

IO processor 플러그인을 통한 dense·sparse 출력

소스 트리에는 dense 임베딩, sparse 토큰 가중치 또는 둘 다를 하나의 응답으로 포맷하는 참조용 BGE-M3 IO processor 플러그인이 포함돼 있어요. 소스 체크아웃에서:

uv pip install ./tests/plugins/bge_m3_sparse_plugin
vllm serve BAAI/bge-m3 \
  --runner pooling \
  --hf-overrides '{"architectures": ["BgeM3EmbeddingModel"]}' \
  --io-processor-plugin bge_m3_sparse_plugin

플러그인은 내부적으로 embed & token_classify 작업을 선택해 dense·lexical 출력을 함께 계산해요. 공개 요청은 task를 plugin으로 설정하고 플러그인별 필드를 data에 넣어야 해요:

curl -s http://localhost:8000/pooling -H "Content-Type: application/json" -d '{
  "model": "BAAI/bge-m3",
  "task": "plugin",
  "data": {
    "input": ["What is BGE M3?", "Definition of BM25"],
    "embed_task": "dense&sparse",
    "return_tokens": true
  }
}'

embed_task는 dense, sparse, dense&sparse를 받아요. 결합된 embed & token_classify 작업은 이 플러그인의 내부 실행 계약이지 일반 Pooling API 응답 형식이 아니에요. 플러그인 없이 위의 세 가지 구체적 작업 중 하나를 선택하세요.

Specific Model Examples