분류 사용법

분류 사용법 (Classification Usages)

분류(Classification)는 주어진 입력에 가장 잘 대응하는 미리 정의된 범주, 클래스, 또는 라벨을 예측하는 작업이에요. 문장의 감정이 긍정인지 부정인지, 이메일이 스팸인지 아닌지 같은 것들이 대표적이죠.

출처: vLLM 공식 문서 — models-pooling_models-classify

요약 (Summary)

Model Usage: (sequence) classification
Pooling Task: classify
Offline APIs:
- LLM.classify(...)
- LLM.encode(..., pooling_task="classify")
Online APIs:
- Classification API (/classify)
- Pooling API (/pooling)

(시퀀스) 분류와 토큰 분류의 핵심 차이는 출력 세분성이에요. (시퀀스) 분류는 전체 입력 시퀀스에 대해 단일 결과를 내는 반면, 토큰 분류는 시퀀스 안의 각 토큰마다 결과를 내요. 많은 분류 모델이 (시퀀스) 분류와 토큰 분류를 모두 지원하지만, 자세한 내용은 토큰 분류 페이지를 참고하세요.

분류 모델이 num_labels가 1인 출력을 낼 때만 scoring 모델로 사용되고 scoring API가 활성화될 수 있어요. 자세한 내용은 this page를 참고하세요.

전형적인 사용 사례 (Typical Use Cases)

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

지원되는 모델 (Supported Models)

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

Architecture	Models	Example HF Models	LoRA	PP
`GPT2ForSequenceClassification`	GPT2	`nie3e/sentiment-polish-gpt2-small`
`Qwen2ForSequenceClassification`	Qwen2-based	`jason9693/Qwen2.5-1.5B-apeach`
`Model`, `ForCausalLM`, etc.	Generative models	N/A	*	*

멀티모달 모델 (Multimodal Models)

참고: 멀티모달 모델 입력에 대한 자세한 내용은 지원 모델 목록을 참고하세요.

Architecture	Models	Inputs	Example HF Models	LoRA	PP
`Qwen2_5_VLForSequenceClassification`	Qwen2_5_VL-based	T + IE+ + VE+	`muziyongshixin/Qwen2.5-VL-7B-for-VideoCls`
`ForConditionalGeneration`, `ForCausalLM`, etc.	Generative models	*	N/A	*	*

참고 표기: C는 --convert classify로 자동으로 분류 모델로 변환된다는 의미이고, \*는 원래 모델과 동일한 기능 지원을 뜻해요. 모델이 위 목록에 없다면 as_seq_cls_model로 자동 변환을 시도해요. 기본적으로 마지막 토큰에 해당하는 softmax된 hidden state에서 클래스 확률을 추출합니다.

Cross-encoder 모델 (Cross-encoder Models)

Cross-encoder(일명 reranker) 모델은 두 프롬프트를 입력으로 받고 num_labels가 1인 출력을 내는 분류 모델의 부분집합이에요. 대부분의 분류 모델은 cross-encoder 모델로도 사용할 수 있어요.

텍스트 전용 Cross-encoder 모델

Architecture	Models	Example HF Models	Score template (see note)	LoRA	PP
`BertForSequenceClassification`	BERT-based	`cross-encoder/ms-marco-MiniLM-L-6-v2`, etc.	N/A
`GemmaForSequenceClassification`	Gemma-based	`BAAI/bge-reranker-v2-gemma`(see note), etc.	bge-reranker-v2-gemma.jinja	✅	✅
`GteNewForSequenceClassification`	mGTE-TRM (see note)	`Alibaba-NLP/gte-multilingual-reranker-base`, etc.	N/A
`LlamaBidirectionalForSequenceClassification`	Llama-based with bidirectional attention	`nvidia/llama-nemotron-rerank-1b-v2`, etc.	nemotron-rerank.jinja	✅	✅
`ModernBertForSequenceClassification`	ModernBERT-based	`Alibaba-NLP/gte-reranker-modernbert-base`, etc.	N/A
`Qwen2ForSequenceClassification`	Qwen2-based	`mixedbread-ai/mxbai-rerank-base-v2`(see note), etc.	mxbai_rerank_v2.jinja	✅	✅
`Qwen3ForSequenceClassification`	Qwen3-based	`tomaarsen/Qwen3-Reranker-0.6B-seq-cls`, `Qwen/Qwen3-Reranker-0.6B`(see note), etc.	qwen3_reranker.jinja	✅	✅
`RobertaForSequenceClassification`	RoBERTa-based	`cross-encoder/quora-roberta-base`, etc.	N/A
`XLMRobertaForSequenceClassification`	XLM-RoBERTa-based	`BAAI/bge-reranker-v2-m3`, etc.	N/A
`Model`, `ForCausalLM`, etc.	Generative models	N/A	N/A	*	*

참고: 일부 모델은 올바르게 동작하려면 특정 프롬프트 형식이 필요해요. 예제 HF 모델에 대응하는 score template은 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 모델

Architecture	Models	Inputs	Example HF Models	LoRA	PP
`JinaVLForSequenceClassification`	JinaVL-based	T + IE+	`jinaai/jina-reranker-m0`, etc.	✅	✅
`LlamaNemotronVLForSequenceClassification`	Llama Nemotron Reranker + SigLIP	T + IE+	`nvidia/llama-nemotron-rerank-vl-1b-v2`
`Qwen3VLForSequenceClassification`	Qwen3-VL-Reranker	T + IE+ + VE+	`Qwen/Qwen3-VL-Reranker-2B`(see note), etc.	✅	✅

참고: Qwen3-Reranker와 비슷하게, 공식 원본 Qwen3-VL-Reranker를 로드하려면 아래 --hf_overrides를 사용해야 해요. Qwen3-VL은 공식적으로 이미지 전처리에 qwen_vl_utils를 쓰지만, vLLM은 transformers의 video_processing_qwen3_vl을 사용해서 공식 Hugging Face 저장소 예제와 결과가 약간 다를 수 있어요.

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

분류 사용법