Classification Usages

Classification Usages (분류 사용법)

Classification은 주어진 입력에 가장 잘 대응하는 사전 정의된 카테고리, 클래스, 또는 라벨을 예측하는 작업이에요. vLLM에서는 classify pooling task로 구현되며, 오프라인으로 LLM.classify(...) 또는 LLM.encode(..., pooling_task="classify"), 온라인으로 Classification API(/classify)와 Pooling API(/pooling)를 제공해요.

출처: 문서

본문

요약

Model Usage: (시퀀스) 분류
Pooling Task: classify
오프라인 API: LLM.classify(...), LLM.encode(..., pooling_task="classify")
온라인 API: Classification API(/classify), Pooling API(/pooling)

(시퀀스) 분류와 토큰 분류의 핵심 차이는 출력 세분성(granularity)이에요. (시퀀스) 분류는 전체 입력 시퀀스에 대해 단일 결과를 생성하는 반면, 토큰 분류는 시퀀스 내 각 토큰에 대한 결과를 생성해요. 많은 분류 모델이 두 가지를 모두 지원해요. 분류 모델이 num_labels == 1을 출력할 때만 스코어링 모델로 사용할 수 있고 scoring API가 활성화돼요.

전형적인 사용 사례

분류 모델의 가장 근본적인 응용은 입력 데이터를 사전 정의된 클래스로 분류하는 것이에요.

지원 모델

텍스트 전용 모델

Architecture	Models	Example HF Models	LoRA	PP
GPT2ForSequenceClassification	GPT2	nie3e/sentiment-polish-gpt2-small
Qwen2ForSequenceClassification^C	Qwen2 기반	jason9693/Qwen2.5-1.5B-apeach
Model^C, ForCausalLM^C 등	생성 모델	N/A	*	*

^C: --convert classify로 분류 모델로 자동 변환됨. * 기능 지원은 원본 모델과 동일.

멀티모달 모델

Architecture	Models	Inputs	Example HF Models	LoRA	PP
Qwen2_5_VLForSequenceClassification^C	Qwen2_5_VL 기반	T + I + V	muziyongshixin/Qwen2.5-VL-7B-for-VideoCls	*	*
ForConditionalGeneration^C, ForCausalLM^C 등	생성 모델	*	N/A	*	*

모델이 위 목록에 없으면 as_seq_cls_model로 자동 변환을 시도해요. 기본적으로 마지막 토큰에 해당하는 softmax된 히든 스테이트에서 클래스 확률을 추출해요.

Cross-encoder 모델

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

텍스트 전용 모델 — 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) 등.

참고: 일부 모델은 올바르게 동작하기 위해 특정 프롬프트 형식이 필요해요. Example HF Models에 대응하는 score 템플릿은 examples/pooling/score/template/에서 찾을 수 있어요. 예시: examples/pooling/score/using_template_offline.py, examples/pooling/score/using_template_online.py.

공식 원본 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) 등.

참고: Qwen3-Reranker와 유사하게 공식 원본 Qwen3-VL-Reranker를 로드하려면 다음 --hf_overrides가 필요해요:

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

Reward 모델

(시퀀스) 분류 모델을 리워드 모델로 사용하는 방식이에요. 지원 아키텍처: Jamba(ai21labs/Jamba-tiny-reward-dev), Qwen3 기반(Skywork/Skywork-Reward-V2-Qwen3-0.6B), Llama 기반(Skywork/Skywork-Reward-V2-Llama-3.2-1B) 등. 이들 모두 LoRA ✅, PP ✅.

오프라인 추론

Pooling 파라미터

지원되는 pooling 파라미터:

use_activation: bool | None = None

LLM.classify

classify 메서드는 각 프롬프트에 대한 확률 벡터를 출력해요:

from vllm import LLM

llm = LLM(model="jason9693/Qwen2.5-1.5B-apeach", runner="pooling")
(output,) = llm.classify("Hello, my name is")
probs = output.outputs.probs
print(f"Class Probabilities: {probs!r} (size={len(probs)})")

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

LLM.encode

encode 메서드는 vLLM의 모든 pooling 모델에서 사용 가능해요. 분류 모델에 LLM.encode를 쓸 때는 pooling_task="classify"를 설정하세요:

from vllm import LLM

llm = LLM(model="jason9693/Qwen2.5-1.5B-apeach", runner="pooling")
(output,) = llm.encode("Hello, my name is", pooling_task="classify")
data = output.outputs.data
print(f"Data: {data!r}")

온라인 서빙

Classification API

온라인 /classify API는 LLM.classify와 유사해요.

Completion 파라미터 — model, user, input. 다음 추가 파라미터를 지원해요:

truncate_prompt_tokens (int >= -1) — 프롬프트를 잘라낼 토큰 수
padding ("max_length" | "do_not_pad") — Transformers tokenizer와 같은 이름. 고정 시퀀스 길이로 학습되고 attention mask가 없는 모델(예: SigLIP)은 임베딩을 비교 가능하게 하려면 max_length가 필요해요.
truncation_side ("left" | "right") — truncation 방향 (right는 앞 N개, left는 뒤 N개 토큰 유지)
request_id — 요청 ID (지정하지 않으면 random_uuid 생성)
priority (default 0) — 요청 우선순위 (낮을수록 먼저 처리)
mm_processor_kwargs — HF processor에 전달할 추가 kwargs
cache_salt (default None, length 1~1024) — multi-user 환경에서 공격자가 프롬프트를 추측하는 것을 막도록 prefix cache를 소금질
add_special_tokens (default True) — 특수 토큰(BOS 등)을 프롬프트에 추가할지
use_activation — pooler 출력에 활성화를 적용할지. None이면 pooler 기본값(대부분 True)

Chat 파라미터 — messages를 전달하면 채팅 형식 입력을 지원하고, 위 추가 파라미터에 더해 add_generation_prompt, continue_final_message, chat_template, chat_template_kwargs, media_io_kwargs 등을 지원해요.

예시 요청: 여러 텍스트 분류 (코드 예시: examples/pooling/classify/classification_online.py):

curl -v "http://127.0.0.1:8000/classify" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "jason9693/Qwen2.5-1.5B-apeach",
      "input": [
        "Loved the new café—coffee was great.",
        "This update broke everything. Frustrating."
      ]
  }'

응답의 data 배열에는 각 항목마다 index, label, probs, num_classes가 포함돼요. input 필드에 문자열을 직접 전달할 수도 있어요.

Classification Usages