Supported Models

Supported Models (지원 모델)

vLLM은 다양한 작업에 걸친 생성(generative) 및 풀링(pooling) 모델을 지원해요. 각 작업마다 vLLM에 구현된 모델 아키텍처를 나열하고, 각 아키텍처 옆에 이를 사용하는 인기 모델을 함께 소개해요. 이 문서는 모델 구현 방식, 모델 로딩 방법, 텍스트 전용/멀티모달/풀링 모델 목록, 그리고 모델 지원 정책을 다뤄요.

출처: 문서

본문

모델 구현

vLLM 네이티브

vLLM이 모델을 네이티브로 지원하면 구현은 vllm/model_executor/models에서 찾을 수 있어요. 이러한 모델들이 지원 텍스트 모델과 지원 멀티모달 모델 목록에 나열되는 모델이에요.

Transformers

vLLM은 Transformers에 있는 모델 구현도 지원해요. 이를 "Transformers modeling backend"라고 불러요. 이 백엔드로 로드한 모델의 성능은 전용 vLLM 모델 구현과 동일해야 해요. 현재 Transformers modeling backend는 다음에 대해 동작해요:

  • Modalities: 임베딩 모델, 언어 모델, 비전-언어 모델*, 오디오-언어 모델
  • Architectures: encoder-only, decoder-only, mixture-of-experts
  • Attention types: full attention 및/또는 sliding attention

* 비전-언어 모델은 현재 이미지 입력만 받아요. 비디오 입력 지원은 향후 릴리스에서 추가될 예정이에요.

모델이 "writing a custom model"의 모든 단계를 따르면, Transformers modeling backend와 함께 사용할 때 vLLM의 다음 기능들과 호환돼요: 호환성 매트릭스에 나열된 모든 기능, 그리고 Data/Tensor/Expert/Pipeline 병렬화의 임의 조합.

modeling backend가 Transformers인지 확인하려면:

from vllm import LLM

llm = LLM(model=...)  # Name or path of your model
llm.apply_model(lambda model: print(type(model)))

출력된 타입이 Transformers...로 시작하면 Transformers 모델 구현을 사용하는 것이에요. vLLM 구현이 있지만 Transformers 구현을 쓰고 싶다면 오프라인에서 model_impl="transformers", 온라인 서빙에서 --model-impl transformers로 설정하세요.

참고: 비전-언어 모델의 경우 dtype="auto"로 로드할 때 vLLM은 config에 dtype이 있으면 모델 전체를 그 dtype으로 로드해요. 네이티브 Transformers는 모델의 각 백본 dtype 속성을 존중해요. 이로 인해 약간의 성능 차이가 생길 수 있어요.

커스텀 모델

vLLM도 Transformers도 네이티브로 지원하지 않는 모델이라도 vLLM에서 사용할 수 있어요. 모델이 Transformers modeling backend 호환이 되려면:

  • Transformers 호환 커스텀 모델이어야 함 (모델 디렉터리가 올바른 구조, 예: config.json 존재, config.json에 auto_map.AutoModel 포함)
  • Transformers modeling backend 호환 모델이어야 함 (커스터마이즈는 base 모델에서 수행, 예: MyModelForCausalLM이 아닌 MyModel)

호환 모델이 Hugging Face Model Hub에 있으면 오프라인에서 trust_remote_code=True, 온라인 서빙에서 --trust-remote-code를 설정하면 돼요. 로컬 디렉터리에 있으면 model=<MODEL_DIR>(오프라인) 또는 vllm serve <MODEL_DIR>(온라인)로 경로를 전달하면 돼요. 이렇게 하면 Transformers나 vLLM에서 공식 지원되기 전에도 새 모델을 사용할 수 있어요.

커스텀 모델 작성

Transformers 호환 커스텀 모델을 Transformers modeling backend 호환 모델로 만들려면:

  • MyAttention은 ALL_ATTENTION_FUNCTIONS를 사용해 attention을 정확히 한 번 호출해야 해요. vLLM은 MyAttention 모듈마다 Attention 레이어를 하나씩 붙이고, MyAttention은 고유한 layer_idx를 가져야 해요 (vLLM이 이 인덱스로 KV 캐시를 키잉). scale이 head_size**-0.5가 아니면 attention 인터페이스에 scaling=을 전달하세요.
  • encoder-only 모델이면 MyAttention에 is_causal = False를 추가하세요.
  • MoE 모델이면: sparse MoE 블록이 experts라는 속성을 가져야 해요. experts(MyExperts) 클래스는 nn.ModuleList 상속(naive) 또는 3D nn.Parameters 포함(packed) 둘 중 하나여야 하고, MyExperts.forward는 hidden_states, top_k_index, top_k_weights를 받아야 해요.
from transformers import PreTrainedModel
from torch import nn


class MyAttention(nn.Module):
    is_causal = False  # Only do this for encoder-only models

    def __init__(self, config, layer_idx):
        ...
        self.config = config
        self.layer_idx = layer_idx
        self.scaling = self.head_dim**-0.5
        ...

    def forward(self, hidden_states, **kwargs):
        ...
        attention_interface = ALL_ATTENTION_FUNCTIONS.get_interface(
            self.config._attn_implementation, eager_attention_forward
        )
        attn_output, attn_weights = attention_interface(
            self, query_states, key_states, value_states,
            scaling=self.scaling, **kwargs,
        )
        ...

# Only do this for mixture-of-experts models
class MyExperts(nn.ModuleList):
    def forward(self, hidden_states, top_k_index, top_k_weights):
        ...

# Only do this for mixture-of-experts models
class MySparseMoEBlock(nn.Module):
    def __init__(self, config):
        ...
        self.experts = MyExperts(config)
        ...
    def forward(self, hidden_states: torch.Tensor):
        ...
        hidden_states = self.experts(hidden_states, top_k_index, top_k_weights)
        ...

class MyModel(PreTrainedModel):
    ...

로드 시 내부적으로 일어나는 일: config가 로드되고, config의 auto_map에서 MyModel Python 클래스가 로드되며 _can_set_attn_implementation() 여부를 확인해요. 그러고 MyModel이 vllm/model_executor/models/transformers의 Transformers modeling backend 클래스 중 하나로 로드되어 self.config._attn_implementation = "vllm"을 설정해 vLLM의 attention 레이어가 사용되게 해요.

Tensor parallel/pipeline parallel 호환을 위해 config 클래스에 base_model_tp_plan 및/또는 base_model_pp_plan을 추가할 수 있어요:

from transformers import PretrainedConfig

class MyConfig(PretrainedConfig):
    base_model_tp_plan = {
        "layers.*.self_attn.k_proj": "colwise",
        "layers.*.self_attn.v_proj": "colwise",
        "layers.*.self_attn.o_proj": "rowwise",
        "layers.*.mlp.gate_proj": "colwise",
        "layers.*.mlp.up_proj": "colwise",
        "layers.*.mlp.down_proj": "rowwise",
    }
    base_model_pp_plan = {
        "embed_tokens": (["input_ids"], ["inputs_embeds"]),
        "layers": (["hidden_states", "attention_mask"], ["hidden_states"]),
        "norm": (["hidden_states"], ["hidden_states"]),
    }
  • base_model_tp_plan은 정규화된 레이어 이름 패턴을 tensor parallel 스타일(현재 colwise, rowwise만)로 매핑하는 dict예요. vLLM은 표준 attention(q/k/v/o_proj)과 gated-MLP/experts(gate/up/down_proj) projection을 인식해 fusion할 수 있으므로 나열하지 않아도 돼요. plan은 이런 패턴을 따르지 않는 레이어에만 필요하며, fusion도 plan에도 없는 linear는 복제(replicate)돼요.
  • base_model_pp_plan은 직접 자식 레이어 이름을 (입력 인자 이름 리스트, 모델링 코드에서 레이어가 출력하는 변수 이름 리스트) 튜플 리스트로 매핑해요. 모든 pipeline stage에 없는 레이어에만 필요해요. plan이 없으면 텍스트 모델의 유일한 nn.ModuleList에서 분할을 추론해요 (파라미터 있는 모듈은 선언 순서에 따라 첫/마지막 stage에, 파라미터 없는 모듈(예: rotary embeddings)은 모든 stage에).

Plugins

일부 모델 아키텍처는 vLLM 플러그인으로 지원돼요. 예: BartForConditionalGeneration(BART, bart-plugin), Florence2ForConditionalGeneration(Florence-2, bart-plugin). 네이티브 지원되지 않는 다른 모델 아키텍처, 특히 Encoder-Decoder 모델은 플러그인 시스템을 통해 유사한 패턴으로 구현하는 것을 권장해요.

모델 로딩

Hugging Face Hub

기본적으로 vLLM은 Hugging Face(HF) Hub에서 모델을 로드해요. 다운로드 경로를 바꾸려면 HF_HOME 환경 변수를 설정하세요. 모델이 네이티브 지원되는지 확인하려면 HF 저장소의 config.json을 보세요. architectures 필드에 아래 목록의 모델 아키텍처가 있으면 네이티브 지원돼요. 모델이 네이티브일 필요는 없어요 — Transformers modeling backend로 Transformers 구현(심지어 Model Hub의 원격 코드)을 직접 실행할 수 있어요.

런타임 확인 팁 — 모델이 실제로 지원되는지 가장 쉽게 확인하는 방법:

from vllm import LLM

# For generative models (runner=generate) only
llm = LLM(model=..., runner="generate")  # Name or path of your model
output = llm.generate("Hello, my name is")
print(output)

# For pooling models (runner=pooling) only
llm = LLM(model=..., runner="pooling")  # Name or path of your model
output = llm.encode("Hello, my name is")
print(output)

vLLM이 텍스트(생성 모델)나 히든 스테이트(풀링 모델)를 성공적으로 반환하면 지원되는 모델이에요. 그렇지 않으면 "Adding a New Model" 문서를 참고하거나 GitHub에 이슈를 여세요.

모델 다운로드 — Hugging Face CLI로 모델이나 특정 파일을 다운로드할 수 있어요:

# Download a model
hf download HuggingFaceH4/zephyr-7b-beta
# Specify a custom cache directory
hf download HuggingFaceH4/zephyr-7b-beta --cache-dir ./path/to/cache
# Download a specific file from a model repo
hf download HuggingFaceH4/zephyr-7b-beta eval_results.json

캐시 관리 — 로컬 캐시의 모델 나열(hf cache list -q), 상세 출력(hf cache list), 커스텀 캐시 디렉터리(hf cache list --dir ~/.cache/huggingface/hub), 캐시 삭제(hf cache rm $(hf cache list -q)).

프록시 사용 — 세션에 전역 프록시 설정(export http_proxy=..., https_proxy=...)하거나, 명령별로 https_proxy=... hf download <model> / https_proxy=... vllm serve <model>, 또는 Python에서 os.environ["http_proxy"], os.environ["https_proxy"] 설정.

MatrixHub

MatrixHub는 셀프 호스트 모델 레지스트리로, 상류 허브의 모델을 캐시하고 네트워크 내부에서 Hugging Face 호환 API로 제공해요. HF_ENDPOINT를 MatrixHub 인스턴스로 지정하면 돼요:

export HF_ENDPOINT="http://<your-matrixhub-address>"
vllm serve Qwen/Qwen3-0.6B

그러면 vLLM은 공개 HF Hub 대신 내부 네트워크의 MatrixHub에서 가중치를 다운로드해요. air-gapped 클러스터나 노드 간 반복 다운로드 회피에 유용해요. Docker/Kubersnetes 배포 예시가 포함된 end-to-end 안내는 MatrixHub guide for vLLM 참고.

ModelScope

Hugging Face Hub 대신 ModelScope 모델을 사용하려면 환경 변수를 설정하세요:

export VLLM_USE_MODELSCOPE=True

그리고 trust_remote_code=True와 함께 사용하세요.

Feature Status Legend

  • ✅︎ — 기능이 해당 모델에서 지원됨
  • 🚧 — 기능이 계획되었지만 아직 모델에서 지원되지 않음
  • ⚠️ — 기능이 제공되지만 알려진 이슈나 제한이 있을 수 있음

텍스트 전용 언어 모델 목록

생성 모델 (텍스트 생성)

이 모델들은 주로 LLM.generate API를 받아요. Chat/Instruct 모델은 추가로 LLM.chat API를 지원해요.

지원되는 아키텍처(Architecture | Models | 예시)는 매우 광범위해요. 주요 예시:

  • Llama 계열: LlamaForCausalLM (Llama 3.1/3/2/LLaMA/Yi — meta-llama/Meta-Llama-3.1-405B-Instruct 등), MistralForCausalLM (Ministral-3/Mistral), MixtralForCausalLM (Mixtral-8x7B), NemotronForCausalLM (Nemotron-3/4/Minitron), LlamaBidirectional..., MambaForCausalLM, Mamba2ForCausalLM
  • Qwen 계열: Qwen2ForCausalLM (QwQ, Qwen2), Qwen3ForCausalLM (Qwen3), Qwen2MoeForCausalLM, Qwen3MoeForCausalLM, Qwen3NextForCausalLM
  • DeepSeek 계열: DeepseekForCausalLM, DeepseekV2ForCausalLM, DeepseekV3ForCausalLM, DeepseekV32ForCausalLM, DeepseekV4ForCausalLM
  • Gemma 계열: GemmaForCausalLM, Gemma2ForCausalLM, Gemma3ForCausalLM, Gemma3nForCausalLM, Gemma4ForCausalLM
  • GLM 계열: ChatGLMModel/ChatGLMForConditionalGeneration, GlmForCausalLM(GLM-4), Glm4ForCausalLM, Glm4MoeForCausalLM, GlmMoeDsaForCausalLM(GLM-5)
  • 기타: BloomForCausalLM, CohereForCausalLM/Cohere2ForCausalLM, DbrxForCausalLM, FalconForCausalLM, FalconMambaForCausalLM, GptOssForCausalLM, GPT2LMHeadModel, GPTJForCausalLM, GPTNeoXForCausalLM, GraniteForCausalLM, GraniteMoeForCausalLM, InternLM2ForCausalLM, InternLM3ForCausalLM, JambaForCausalLM, Minitron, MiniCPMForCausalLM, Ministral, OPTForCausalLM, PhiForCausalLM, Phi3ForCausalLM, PhiMoEForCausalLM, SolarForCausalLM, StableLmForCausalLM, TeleChat2ForCausalLM, Zamba2ForCausalLM 등 다수.

Transformers modeling backend로만 지원되는 모델(FlexOlmoForCausalLM, GPTBigCodeForCausalLM (StarCoder/SantaCoder/WizardCoder), HunYuanDenseV1ForCausalLM, HunYuanMoEV1ForCausalLM, NanbeigeForCausalLM, OlmoForCausalLM, Olmo2ForCausalLM, Olmo3ForCausalLM, SmolLM3ForCausalLM, Starcoder2ForCausalLM, VaultGemmaForCausalLM 등)도 있어요. 로그에 Transformers modeling backend가 사용된다고 나오며 fallback 경고는 없어요.

참고: 현재 ROCm 버전의 vLLM은 Mistral과 Mixtral을 컨텍스트 길이 4096까지만 지원해요.

멀티모달 언어 모델 목록

모델에 따라 지원되는 modality: Text, Image, Video, Audio. +로 결합된 조합은 전부 지원되고, /로 구분된 것은 상호 배타적이에요. 예: T + I는 텍스트 전용, 이미지 전용, 텍스트+이미지 입력 모두 지원. T / I는 텍스트 전용과 이미지 전용만 지원(텍스트+이미지는 불가).

팁: Llama-4, Step3, Mistral-3, Qwen-3.5 같은 hybrid 전용 모델은 지원되는 모든 멀티모달 modality를 0으로 설정(--language-model-only)해 텍스트 전용 모드를 켤 수 있어요. 그러면 멀티모달 모듈이 로드되지 않아 KV 캐시용 GPU 메모리를 더 확보해요.

주요 멀티모달 아키텍처:

  • 비전-언어: AriaForConditionalGeneration(Aria), Blip2ForConditionalGeneration(BLIP-2), DeepseekVLV2ForCausalLM, Gemma3ForConditionalGeneration, Gemma4ForConditionalGeneration, Gemma4UnifiedForConditionalGeneration, InternVLChatModel, Llama4ForConditionalGeneration, LlavaForConditionalGeneration(LLaVA-1.5, Pixtral), LlavaNextForConditionalGeneration, LlmNextVideoForConditionalGeneration, MiniCPMV, MiniMaxVL01ForConditionalGeneration, Mistral3ForConditionalGeneration, MolmoForCausalLM, Molmo2ForConditionalGeneration, Phi3VForCausalLM, Phi4MMForCausalLM, PixtralForConditionalGeneration, Qwen2VLForConditionalGeneration, Qwen2_5_VLForConditionalGeneration, Qwen3VLForConditionalGeneration, Qwen3VLMoeForConditionalGeneration, Qwen3_5ForConditionalGeneration, Qwen3_5MoeForConditionalGeneration, SmolVLMForConditionalGeneration, Step3VLForConditionalGeneration 등
  • 오디오-언어: AudioFlamingo3ForConditionalGeneration, KimiAudioForConditionalGeneration, MossAudioModel, Qwen2AudioForConditionalGeneration, UltravoxModel
  • 옴니(멀티모달 입력): MiniCPMO, MiMoV2OmniForCausalLM, Qwen2_5OmniThinkerForConditionalGeneration, Qwen3OmniMoeThinkerForConditionalGeneration, Gemma4ForConditionalGeneration
  • OCR: DeepseekOCRForCausalLM, GlmOcrForConditionalGeneration, PaddleOCRVLForConditionalGeneration, QianfanOCRForConditionalGeneration, UnlimitedOCRForCausalLM, HunyuanOCR

Transformers modeling backend로만 지원: Emu3ForConditionalGeneration, HunYuanVLForConditionalGeneration, VibeVoiceAsrForConditionalGeneration.

특정 모델 참고 사항: MiniCPM-V-2는 공식이 동작하지 않아 포크(2HwwwH/MiniCPM-V-2 0)를 사용. Gemma3n은 V1에서만 지원(공유 KV 캐싱 + timm>=1.0.17 필요). DiffusiveGemma, Moondream3, MuseGlimmer, Nemotron Nano 등은 각각의 주의 사항이 있어요.

변환(transcription) 모델 — 자동 음성 인식 전용 학습 모델: CohereAsrForConditionalGeneration(Cohere-Transcribe), FunASRForConditionalGeneration, GlmAsrForConditionalGeneration(GLM-ASR), GraniteSpeechForConditionalGeneration, Qwen3ASRForConditionalGeneration, VoxtralForConditionalGeneration, WhisperForConditionalGeneration 등.

Realtime 변환 — /v1/realtime WebSocket 엔드포인트로 스트리밍 변환을 지원하는 음성 모델: VoxtralRealtimeGeneration, Qwen3ASRRealtimeGeneration. Voxtral은 mistral-common[audio] 설치 필요 + --tokenizer-mode mistral. Qwen3ASRRealtimeGeneration은 config.json에서 자동 감지되지 않으므로 서빙 시 --hf-overrides '{"architectures":["Qwen3ASRRealtimeGeneration"]}'를 전달해야 해요.

Pooling 모델

pooling 모델 사용법은 관련 문서를 참고하세요. 일부 모델 아키텍처가 생성과 풀링 작업을 모두 지원하므로, 생성 모드 대신 pooling 모드로 사용하려면 --runner pooling을 명시하세요. 지원되는 특정 pooling 작업별 모델은 다음을 참고: Classification, Embedding, Reward, Token Classification, Token Embedding, Scoring, Specific Model Examples.

모델 지원 정책

vLLM은 생태계 내 타사 모델의 통합과 지원을 촉진하는 데 전념해요. 접근 방식은 견고성의 필요성과 광범위한 모델 지원의 실질적 제약 사이의 균형을 목표로 해요:

  • 커뮤니티 주도 지원: 새 모델 추가를 위한 커뮤니티 기여를 장려해요. PR은 생성된 출력의 타당성(센스)을 주로 평가하며, transformers 같은 기존 구현과의 엄격한 일관성보다는 실용적 정합성에 초점을 둬요. 모델 벤더에서 직접 온 PR을 특히 환영해요.
  • Best-Effort 일관성: transformers 같은 다른 프레임워크와 완전한 정렬이 항상 가능한 것은 아니에요. 가속 기법, 저정밀 연산 등이 불일치를 만들 수 있어요. 구현된 모델이 기능하고 타당한 결과를 내는 것이 핵심 약속이에요. (팁: HF Transformers의 model.generate와 vLLM의 llm.generate 출력을 비교할 때 전자는 generation_config.json의 기본 파라미터를 적용하지만 후자는 전달된 파라미터만 사용하므로, 비교 시 모든 샘플링 파라미터를 동일하게 맞추세요.)
  • 이슈 해결과 모델 업데이트: 버그는 PR로 수정하며, 문제 설명과 해결 근거를 명확히 제시해야 해요. 한 모델의 수정이 다른 모델에 영향을 주면 커뮤니티가 이를 지적해 주길 기대해요. 버그픽 PR은 원작자에게 알리는 것이 예의예요.
  • 모니터링과 업데이트: 관심 모델의 커밋 히스토리를 모니터링(예: main/vllm/model_executor/models 디렉터리의 변화 추적)해 업데이트를 파악하세요.
  • 선택적 집중: 자원은 사용자 관심과 영향력이 큰 모델에 주로 투입돼요. 덜 쓰이는 모델은 유지보수에서 커뮤니티의 적극적 역할에 의존해요.

vLLM은 추론 엔진으로서 새 모델을 소개하지 않으므로, 지원되는 모든 모델은 이 관점에서 타사 모델이에요. 모델 테스트 수준:

  1. Strict Consistency: greedy 디코딩에서 HF Transformers의 모델 출력과 비교 — 가장 엄격한 테스트
  2. Output Sensibility: 출력의 혼란도(perplexity) 측정과 명백한 오류 확인 — 덜 엄격
  3. Runtime Functionality: 모델이 오류 없이 로드·실행되는지 — 가장 덜 엄격
  4. Community Feedback: 커뮤니티 피드백에 의존 — 나머지 모델은 이 범주

더 알아보기 (Learn more)