Scoring Usages

Scoring Usages (스코어링 사용법)

스코어링 모델은 두 입력 프롬프트 간의 유사도 점수를 계산하도록 설계됐어요. 세 가지 모델 타입(일명 score_type)을 지원해요: cross-encoder, late-interaction, bi-encoder. 오프라인으로 LLM.score, 온라인으로 Score API(/score, /v1/score)와 Cohere Rerank API(/rerank, /v1/rerank, /v2/rerank)를 제공해요.

출처: 문서

본문

참고: vLLM은 RAG 파이프라인의 모델 추론 부분(임베딩 생성, 리랭킹 등)만 처리해요. 더 상위 레벨의 RAG 오케스트레이션은 LangChain 같은 통합 프레임워크를 활용하세요.

요약

  • Model Usage: Scoring
  • Pooling Task: score_type에 따라 다름
    • cross-encoder → classify (linear classifier)
    • late-interaction → token_embed (late interaction / MaxSim)
    • bi-encoder → embed (cosine similarity)
  • 오프라인 API: LLM.score
  • 온라인 API: Score API(/score, /v1/score), Cohere Rerank API(/rerank, /v1/rerank, /v2/rerank)

참고: 분류 모델이 num_labels == 1을 출력할 때만 스코어링 모델로 사용할 수 있고 scoring API가 활성화돼요.

Score 타입

세 가지 지원 스코어링 함수는 cross-encoder(linear classifier), late-interaction(MaxSim), bi-encoder(cosine similarity)예요.

지원 모델

Cross-encoder 모델

Cross-encoder(리랭커) 모델은 두 개의 프롬프트를 입력으로 받고 num_labels == 1을 출력하는 분류 모델의 하위 집합이에요.

텍스트 전용 — BERT 기반(cross-encoder/ms-marco-MiniLM-L-6-v2), Gemma 기반(BAAI/bge-reranker-v2-gemma, bge-reranker-v2-gemma.jinja), mGTE-TRM(Alibaba-NLP/gte-multilingual-reranker-base), Llama 양방향 어텐션 기반(nvidia/llama-nemotron-rerank-1b-v2, nemotron-rerank.jinja), ModernBERT 기반(Alibaba-NLP/gte-reranker-modernbert-base), Qwen2 기반(mixedbread-ai/mxbai-rerank-base-v2, mxbai_rerank_v2.jinja), Qwen3 기반(Qwen/Qwen3-Reranker-0.6B, qwen3_reranker.jinja), RoBERTa 기반(cross-encoder/quora-roberta-base), XLM-RoBERTa 기반(BAAI/bge-reranker-v2-m3) 등. 일부 모델은 특정 프롬프트 형식이 필요해요 — score 템플릿은 examples/pooling/score/template/에서 확인하세요.

공식 원본 BAAI/bge-reranker-v2-gemma 로드:

vllm serve BAAI/bge-reranker-v2-gemma \
    --hf_overrides '{"architectures": ["GemmaForSequenceClassification"],"classifier_from_token": ["Yes"],"method": "no_post_processing"}'

공식 원본 mxbai-rerank-v2 로드:

vllm serve mixedbread-ai/mxbai-rerank-base-v2 \
    --hf_overrides '{"architectures": ["Qwen2ForSequenceClassification"],"classifier_from_token": ["0", "1"], "method": "from_2_way_softmax"}'

공식 원본 Qwen3 Reranker 로드:

vllm serve Qwen/Qwen3-Reranker-0.6B \
    --hf_overrides '{"architectures": ["Qwen3ForSequenceClassification"],"classifier_from_token": ["no", "yes"],"is_original_qwen3_reranker": true}'

멀티모달 cross-encoder — JinaVL 기반(jinaai/jina-reranker-m0, T + I), Llama Nemotron Reranker + SigLIP(nvidia/llama-nemotron-rerank-vl-1b-v2), Qwen3-VL-Reranker(Qwen/Qwen3-VL-Reranker-2B, --hf_overrides 필요) 등. Qwen3-VL은 공식적으로 qwen_vl_utils로 이미지 전처리를 하고 vLLM은 transformers의 video_processing_qwen3_vl을 사용해 공식 HF 예시와 약간 다른 결과를 낼 수 있어요.

Late-interaction 모델

토큰 임베딩 작업을 지원하는 모든 모델은 두 입력 프롬프트의 late interaction을 계산해 score API로 유사도 점수를 계산할 수 있어요.

텍스트 전용: LFM2(LiquidAI/LFM2-ColBERT-350M), ModernBERT(lightonai/GTE-ModernColBERT-v1), Jina XLM-RoBERTa(jinaai/jina-colbert-v2), BERT(answerdotai/answerai-colbert-small-v1, colbert-ir/colbertv2.0) 등.

멀티모달: ColModernVBERT(ModernVBERT/colmodernvbert-merged), ColPali(vidore/colpali-v1.3-hf), ColQwen3(TomoroAI/tomoro-colqwen3-embed-4b 등), ColQwen3_5(athrael-soju/colqwen3.5-4.5B-v3 등), OpsColQwen3(OpenSearch-AI/Ops-Colqwen3-4B 등), Qwen3-VL Nemotron Embed(nvidia/nemotron-colembed-vl-4b-v2 등).

특수 모델: JinaForRanking(Qwen3 기반, jinaai/jina-reranker-v3) — listwise 문서 리랭커로, novel한 "last but not late interaction" 아키텍처를 사용해요. examples/pooling/token_embed/jina_reranker_v3_offline.py 참고.

Bi-encoder

embedding 작업을 지원하는 모든 모델은 두 입력 프롬프트 임베딩의 cosine 유사도를 계산해 score API로 유사도 점수를 낼 수 있어요. 지원 아키텍처는 embed 페이지와 동일해요 (BERT, SPLADE, BGE-M3, Gemma 2/3, Llama 기반, ModernBERT, Nomic BERT, Qwen2/3 기반, RoBERTa, XLM-RoBERTa, CLIP, SigLIP 등).

오프라인 추론

Pooling 파라미터

다음 pooling 파라미터는 cross-encoder 모델에서만 지원되고 late-interaction·bi-encoder 모델에서는 동작하지 않아요:

use_activation: bool | None = None

LLM.score

score 메서드는 문장 쌍 간 유사도 점수를 출력해요:

from vllm import LLM

llm = LLM(model="BAAI/bge-reranker-v2-m3", 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}")

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

온라인 서빙

Score API

Score API(/score, /v1/score)는 LLM.score와 유사하게 두 입력 프롬프트 간 유사도 점수를 계산해요.

파라미터: model, user, queries, documents, truncate_prompt_tokens, padding, truncation_side, request_id, priority, mm_processor_kwargs, cache_salt, use_activation, max_tokens_per_query(기본 0, 쿼리당 최대 토큰 수, 초과 시 잘림), max_tokens_per_doc(기본 0, 문서당 최대 토큰 수), instruction(채팅 템플릿을 통해 각 점수 쌍 앞에 붙는 작업 지시, chat_template_kwargs={'instruction': ...}과 동일), chat_template_kwargs.

queries와 documents에 모두 문자열을 전달하면 단일 문장 쌍을 형성해요:

curl -X 'POST' 'http://127.0.0.1:8000/score' \
  -H 'accept: application/json' -H 'Content-Type: application/json' \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "encoding_format": "float",
    "queries": "What is the capital of France?",
    "documents": "The capital of France is Paris."
  }'

queries에 문자열, documents에 리스트를 전달하면 len(documents)개의 쌍을 형성해요. 둘 다 리스트를 전달하면 zip()처럼 대응 문자열로 쌍을 만듭니다 (쌍 수는 len(documents)).

멀티모달 입력 — 스코어링 모델에 이미지 등의 멀티모달 입력을 전달할 수 있어요. 전체 예시: examples/pooling/score/vision_score_api_online.py, examples/pooling/score/vision_rerank_api_online.py.

Cohere Rerank API

/rerank, /v1/rerank, /v2/rerank API는 Jina AI의 rerank API 인터페이스와 Cohere의 rerank API 인터페이스 모두와 호환돼요. 코드 예시: examples/pooling/score/rerank_api_online.py.

파라미터는 Score API와 유사하며 query(ScoreInput)와 documents(ScoreInput | list[ScoreInput]), top_n(기본 0)을 사용해요. top_n은 선택 사항이며 기본적으로 documents 필드의 길이예요. 결과 문서는 관련성 순으로 정렬되고, index 속성으로 원래 순서를 알 수 있어요.

curl -X 'POST' 'http://127.0.0.1:8000/v1/rerank' \
  -H 'accept: application/json' -H 'Content-Type: application/json' \
  -d '{
    "model": "BAAI/bge-reranker-base",
    "query": "What is the capital of France?",
    "documents": [
      "The capital of Brazil is Brasilia.",
      "The capital of France is Paris.",
      "Horses and cows are both animals"
    ]
  }'

추가 예시

examples/pooling/score에서 더 많은 예시를 찾을 수 있어요.

지원 기능

Cross-encoder 모델은 두 개의 프롬프트를 입력으로 받고 num_labels == 1을 출력하는 분류 모델의 하위 집합이므로, cross-encoder 기능은 (시퀀스) 분류와 일관돼요.

Score Template

Score 템플릿은 cross-encoder 모델에서만 지원돼요. 임베딩 모델로 스코어링할 때는 score 템플릿이 적용되지 않아요. 일부 스코어링 모델은 특정 프롬프트 형식이 필요하며, --chat-template 파라미터로 커스텀 score 템플릿을 지정할 수 있어요. score 템플릿은 messages 리스트를 받고, 각 메시지는 role 속성("query" 또는 "document")을 가져요. 일반적인 point-wise cross-encoder는 정확히 두 메시지(하나의 query, 하나의 document)를 기대해요. Jinja의 selectattr 필터로 접근할 수 있어요:

  • Query: {{ (messages | selectattr("role", "eq", "query") | first).content }}
  • Document: {{ (messages | selectattr("role", "eq", "document") | first).content }}

이 방식은 messages[0], messages[1] 같은 인덱스 접근보다 견고해요. 예시 템플릿: examples/pooling/score/template/nemotron-rerank.jinja.

활성화 토글

use_activation으로 활성화를 켜거나 끌 수 있는데, cross-encoder 모델에서만 동작해요.

더 알아보기 (Learn more)