支持的模型¶

vLLM支持跨多种任务的生成式和池化模型。

对于每项任务，我们列出了已在vLLM中实现的模型架构。每个架构旁边，我们都标注了使用该架构的一些流行模型。

模型实现¶

vLLM¶

如果vLLM原生支持某个模型，其实现可以在 vllm/model_executor/models中找到。

这些模型是我们列在supported-text-models和supported-mm-models中的。

Transformers¶

vLLM还支持Transformers中可用的模型实现。目前并非所有模型都适用，但大多数解码器语言模型和常见的视觉语言模型都已支持！视觉语言模型目前仅接受图像输入。视频输入的支持将在未来版本中添加。

要检查建模后端是否为Transformers，您可以简单地执行以下操作：

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

如果是TransformersForCausalLM或TransformersForMultimodalLM，则表示它基于Transformers！

自定义模型¶

如果某个模型既不被vLLM原生支持也不被Transformers支持，它仍然可以在vLLM中使用！

要使模型兼容vLLM的Transformers后端，必须满足以下条件：

• be a Transformers compatible custom model (see Transformers - 自定义模型):
  • 模型目录必须具有正确的结构（例如存在config.json文件）。
  • config.json 必须包含 auto_map.AutoModel。
• be a Transformers backend for vLLM compatible model (see writing-custom-models):
  • 自定义应在基础模型中完成（例如在MyModel中，而非MyModelForCausalLM中）。

如果兼容的模型是：

• 在Hugging Face模型中心，只需为离线推理设置trust_remote_code=True，或为openai兼容服务器设置--trust-remote-code。
• 在本地目录中，只需将目录路径传递给 model= 用于 离线推理，或使用 vllm serve 启动 openai兼容服务器。

这意味着，借助vLLM的Transformers后端，新模型可以在Transformers或vLLM官方支持之前就投入使用！

编写自定义模型¶

本节详细说明如何对兼容Transformers的自定义模型进行必要修改，使其适配vLLM的Transformers后端。（我们假设已创建好兼容Transformers的自定义模型，具体可参考Transformers - Customizing models）。

要使您的模型兼容Transformers后端，需要满足以下条件：

1. kwargs 参数从 MyModel 向下传递到 MyAttention 的所有模块。
2. MyAttention 必须使用 ALL_ATTENTION_FUNCTIONS 来调用注意力机制。
3. MyModel 必须包含 _supports_attention_backend = True。

from transformers import PreTrainedModel
from torch import nn

class MyAttention(nn.Module):

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

class MyModel(PreTrainedModel):
    _supports_attention_backend = True

以下是加载该模型时后台发生的情况：

1. 配置已加载。
2. MyModel Python类是从配置中的auto_map加载的，我们会检查模型是否is_backend_compatible()。
3. MyModel 被加载到 TransformersForCausalLM 或 TransformersForMultimodalLM 中（参见 vllm/model_executor/models/transformers.py），这会设置 self.config._attn_implementation = "vllm" 以便使用 vLLM 的注意力层。

就这样！

要使您的模型兼容vLLM的张量并行和/或流水线并行功能，您必须在模型的配置类中添加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 是一个 dict，它将完全限定的层名称模式映射到张量并行样式（目前仅支持 "colwise" 和 "rowwise"）。
• base_model_pp_plan is a dict that maps direct child layer names to tuples of lists of strs:
  • 您只需要对不位于所有流水线阶段的层执行此操作
  • vLLM假设只会有一个nn.ModuleList，该列表会分布在各个流水线阶段中
  • tuple第一个元素中的list包含输入参数的名称
  • tuple最后一个元素中的list包含该层在你的建模代码中输出到的变量名称

加载模型¶

Hugging Face Hub¶

默认情况下，vLLM从Hugging Face (HF) Hub加载模型。如需更改模型下载路径，可以设置HF_HOME环境变量；更多详情请参阅其官方文档。

要判断某个模型是否原生支持，您可以检查HF仓库中的config.json文件。如果"architectures"字段包含下列列出的模型架构，则该模型应该能获得原生支持。

模型不需要原生支持即可在vLLM中使用。Transformers后端允许您直接使用模型的Transformers实现（甚至Hugging Face模型中心上的远程代码）来运行模型。

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中实现您的模型。或者，您可以在GitHub上提交问题来请求vLLM支持。

下载模型¶

如果您愿意，可以使用Hugging Face CLI从模型仓库下载模型或特定文件：

# Download a model
huggingface-cli download HuggingFaceH4/zephyr-7b-beta

# Specify a custom cache directory
huggingface-cli download HuggingFaceH4/zephyr-7b-beta --cache-dir ./path/to/cache

# Download a specific file from a model repo
huggingface-cli download HuggingFaceH4/zephyr-7b-beta eval_results.json

列出已下载的模型¶

使用Hugging Face CLI来管理模型存储在本地缓存中：

# List cached models
huggingface-cli scan-cache

# Show detailed (verbose) output
huggingface-cli scan-cache -v

# Specify a custom cache directory
huggingface-cli scan-cache --dir ~/.cache/huggingface/hub

删除缓存的模型¶

使用Hugging Face CLI交互式删除已下载的模型从缓存中：

# The `delete-cache` command requires extra dependencies to work with the TUI.
# Please run `pip install huggingface_hub[cli]` to install them.

# Launch the interactive TUI to select models to delete
$ huggingface-cli delete-cache
? Select revisions to delete: 1 revisions selected counting for 438.9M.
  ○ None of the following (if selected, nothing will be deleted).
Model BAAI/bge-base-en-v1.5 (438.9M, used 1 week ago)
❯ ◉ a5beb1e3: main # modified 1 week ago

Model BAAI/bge-large-en-v1.5 (1.3G, used 1 week ago)
  ○ d4aa6901: main # modified 1 week ago

Model BAAI/bge-reranker-base (1.1G, used 4 weeks ago)
  ○ 2cfc18c9: main # modified 4 weeks ago

Press <space> to select, <enter> to validate and <ctrl+c> to quit without modification.

# Need to confirm after selected
? Select revisions to delete: 1 revision(s) selected.
? 1 revisions selected counting for 438.9M. Confirm deletion ? Yes
Start deletion.
Done. Deleted 1 repo(s) and 0 revision(s) for a total of 438.9M.

使用代理¶

以下是一些通过代理从Hugging Face加载/下载模型的技巧：

• 为当前会话全局设置代理（或在配置文件中设置）：

export http_proxy=http://your.proxy.server:port
export https_proxy=http://your.proxy.server:port

• 仅为当前命令设置代理：

https_proxy=http://your.proxy.server:port huggingface-cli download <model_name>

# or use vllm cmd directly
https_proxy=http://your.proxy.server:port  vllm serve <model_name> --disable-log-requests

• 在Python解释器中设置代理：

import os

os.environ['http_proxy'] = 'http://your.proxy.server:port'
os.environ['https_proxy'] = 'http://your.proxy.server:port'

ModelScope¶

要使用来自ModelScope而非Hugging Face Hub的模型，请设置以下环境变量：

export VLLM_USE_MODELSCOPE=True

并使用 trust_remote_code=True。

from vllm import LLM

llm = LLM(model=..., revision=..., runner=..., trust_remote_code=True)

# For generative models (runner=generate) only
output = llm.generate("Hello, my name is")
print(output)

# For pooling models (runner=pooling) only
output = llm.encode("Hello, my name is")
print(output)

功能状态图例¶

• ✅︎ 表示该模型支持此功能。

• 🚧 表示该功能已规划但该模型尚未支持。

• ⚠️ 表示该功能可用但可能存在已知问题或限制。

纯文本语言模型列表¶

生成模型¶

查看此页面获取更多关于如何使用生成模型的信息。

文本生成¶

模型池化¶

查看此页面获取更多关于如何使用池化模型的信息。

文本嵌入¶

^C 通过 --convert embed 自动转换为嵌入模型。(details)
* 功能支持与原模型相同。

如果您的模型不在上述列表中，我们将尝试使用as_embedding_model自动转换模型。默认情况下，整个提示的嵌入向量会从与最后一个标记对应的归一化隐藏状态中提取。

奖励建模¶

^C 通过--convert reward自动转换为奖励模型。(details)
* 功能支持与原模型相同。

如果您的模型不在上述列表中，我们将尝试使用as_reward_model自动转换模型。默认情况下，我们直接返回每个token的隐藏状态。

分类¶

^C 通过--convert classify自动转换为分类模型。(details)
* 功能支持与原模型相同。

如果您的模型不在上述列表中，我们将尝试使用as_seq_cls_model自动转换模型。默认情况下，类别概率是从对应最后一个token的softmax隐藏状态中提取的。

句子对评分¶

^C 通过 --convert classify 自动转换为分类模型。(details)
* 功能支持与原模型相同。

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

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

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

多模态语言模型列表¶

根据模型的不同，支持以下模式：

• T文本
• Image
• Video
• Audio

支持由+连接的任何模态组合。

• 例如：T + I 表示该模型支持纯文本、纯图像以及图文混合输入。

另一方面，由/分隔的模态是互斥的。

• 例如：T / I 表示该模型仅支持纯文本和纯图像输入，但不支持文本与图像混合输入。

查看此页面了解如何向模型传递多模态输入。

from vllm import LLM

llm = LLM(
    model="Qwen/Qwen2-VL-7B-Instruct",
    limit_mm_per_prompt={"image": 4},
)

vllm serve Qwen/Qwen2-VL-7B-Instruct --limit-mm-per-prompt '{"image":4}'

生成模型¶

查看此页面获取更多关于如何使用生成模型的信息。

文本生成¶

部分模型仅通过Transformers后端获得支持。下表旨在列出我们官方以这种方式支持的模型。日志会显示正在使用Transformers后端，且不会提示这是回退行为。这意味着，如果您在使用以下列出的任何模型时遇到问题，请提交问题，我们将尽力修复！

^{^} 你需要通过--hf-overrides设置架构名称以匹配vLLM中的架构。    • 例如，要使用DeepSeek-VL2系列模型：      --hf-overrides '{"architectures": ["DeepseekVLV2ForCausalLM"]}' ^E 该模态可以输入预计算的嵌入向量。 ⁺ 该模态每个文本提示可以输入多个项目。

# Core vLLM-compatible dependencies with Molmo accuracy setup (tested on L40)
torch==2.5.1
torchvision==0.20.1
transformers==4.48.1
tokenizers==0.21.0
tiktoken==0.7.0
vllm==0.7.0

# Optional but recommended for improved performance and stability
triton==3.1.0
xformers==0.0.28.post3
uvloop==0.21.0
protobuf==5.29.3
openai==1.60.2
opencv-python-headless==4.11.0.86
pillow==10.4.0

# Installed FlashAttention (for float16 only)
flash-attn>=2.5.6  # Not used in float32, but should be documented

转录¶

专门为自动语音识别训练的Speech2Text模型。

模型池化¶

查看此页面获取更多关于如何使用池化模型的信息。

文本嵌入¶

下表列出了在vLLM中经过测试的项目。

^C 通过 --convert embed 自动转换为嵌入模型。(details)
* 功能支持与原模型相同。

评分¶

^C 通过 --convert classify 自动转换为分类模型。(details)
* 功能支持与原模型相同。

模型支持政策¶

在vLLM，我们致力于促进第三方模型在我们生态系统中的集成与支持。我们的方法旨在平衡对稳健性的需求与支持广泛模型的实际限制。以下是我们管理第三方模型支持的方式：

1. 社区驱动的支持: 我们鼓励社区贡献来添加新模型。当用户请求支持新模型时，我们欢迎社区提交拉取请求(PRs)。这些贡献主要根据其生成输出的合理性进行评估，而非严格遵循现有实现(如transformers中的实现)。贡献号召： 来自模型供应商的直接PRs将特别受欢迎！

2. 尽力保持一致性: 虽然我们致力于维持vLLM中实现的模型与其他框架(如transformers)之间的一致性水平，但完全对齐并不总是可行的。加速技术和低精度计算的使用等因素可能会引入差异。我们的承诺是确保所实现的模型功能正常并产生合理的结果。

   提示

   当比较Hugging Face Transformers的model.generate输出与vLLM的llm.generate输出时，请注意前者会读取模型的生成配置文件(即generation_config.json)并应用默认生成参数，而后者仅使用传递给函数的参数。在比较输出时，请确保所有采样参数完全相同。

3. 问题解决与模型更新: 我们鼓励用户报告在使用第三方模型时遇到的任何错误或问题。建议的修复方案应通过PR提交，并附上对问题及解决方案背后原理的清晰说明。如果某个模型的修复会影响其他模型，我们依赖社区来发现并解决这些跨模型依赖关系。注意：对于错误修复的PR，通知原作者并征求他们的反馈是一种良好的礼仪。

4. 监控与更新: 对特定模型感兴趣的用户应监控这些模型的提交历史（例如通过跟踪main/vllm/model_executor/models目录中的变更）。这种主动方式有助于用户及时了解可能影响其所用模型的更新和变更。

5. 选择性聚焦: 我们的资源主要投向具有重大用户关注度和影响力的模型。使用频率较低的模型可能获得的关注较少，我们依赖社区在其维护和改进方面发挥更积极的作用。

通过这种方式，vLLM 营造了一个协作环境，让核心开发团队和更广泛的社区共同为我们生态系统中支持的第三方模型提供稳健性和多样性。

请注意，作为推理引擎，vLLM本身并不引入新模型。因此，从这个角度来看，vLLM支持的所有模型都属于第三方模型。

我们对模型有以下几级测试：

1. 严格一致性：我们将模型的输出与HuggingFace Transformers库中模型在贪婪解码下的输出进行比较。这是最严格的测试。请参考models tests查看已通过此测试的模型。
2. 输出合理性: 我们通过测量输出的困惑度并检查是否存在明显错误，来验证模型的输出是否合理且连贯。这是一个较为宽松的测试。
3. 运行时功能: 我们检查模型是否能无错误地加载和运行。这是最宽松的测试。请参考功能测试和示例查看已通过此测试的模型。
4. 社区反馈: 我们依赖社区提供关于模型的反馈。如果某个模型出现问题或未按预期工作，我们鼓励用户提交问题报告或发起拉取请求进行修复。其余模型属于此类别。