与 Hugging Face 的集成

本文档介绍了 vLLM 如何与 Hugging Face 库集成。我们会一步步讲解当你运行 vllm serve 时，底层发生了什么。

假设我们要通过运行 vllm serve Qwen/Qwen2-7B 来部署热门的 Qwen 模型。

1. model 参数是 Qwen/Qwen2-7B。vLLM 会检查是否存在对应的配置文件 config.json。实现见 代码片段。流程如下：

   • 如果 model 参数是本地路径，vLLM 会直接从该路径加载配置文件。
   • 如果 model 参数是 Hugging Face 的模型 ID（即用户名+模型名），vLLM 会优先尝试从 Hugging Face 的本地缓存读取配置文件，此时 model 作为模型名，--revision 作为版本号。关于 Hugging Face 缓存机制，请参考 官网说明。
   • 如果 model 参数是 Hugging Face 的模型 ID，但在缓存中找不到，vLLM 会从 Hugging Face 模型库下载配置文件。实现见 此函数。输入参数包括 model（模型名）、--revision（版本）、环境变量 HF_TOKEN（访问模型库的 token）。在本例中，vLLM 会下载 config.json。

2. 确认模型存在后，vLLM 加载其配置文件并转为字典。实现见 代码片段。

3. 接下来，vLLM 会检查配置字典中的 model_type 字段，并据此生成要使用的 config 对象。部分 model_type vLLM 直接支持，详见 支持列表。如果 model_type 不在列表中，vLLM 会调用 AutoConfig.from_pretrained 加载 config 类，参数包括 model、--revision 和 --trust_remote_code。注意：

   • Hugging Face 也有自己的逻辑决定 config 类，依然会用 model_type 在 transformers 库中查找类名，支持的模型见 这里。如找不到则用 config.json 中的 auto_map 字段确定类名，具体是 auto_map 下的 AutoConfig 字段。可参考 DeepSeek。
   • auto_map 下的 AutoConfig 指向模型仓库内的某个模块路径。Hugging Face 会导入该模块，并用 from_pretrained 方法加载 config 类。此操作可能导致任意代码执行，因此仅在启用 --trust_remote_code 时执行。

4. 随后 vLLM 会对 config 对象应用一些历史补丁（多与 RoPE 配置相关），实现见 代码片段。

5. 最后，vLLM 会定位到要初始化的模型类。vLLM 使用 config 对象中的 architectures 字段确定要初始化的模型类，并在其注册表中查找架构名到模型类的映射。如果未在注册表中找到，则说明 vLLM 不支持该模型架构。对于 Qwen/Qwen2-7B，architectures 字段为 ["Qwen2ForCausalLM"]，对应 vLLM 代码中的 Qwen2ForCausalLM 类。此类会根据各种配置初始化自身。

除此之外，vLLM 还依赖 Hugging Face 的两项内容：

1. 分词器（Tokenizer）：vLLM 使用 Hugging Face 的分词器对输入文本分词。分词器通过 AutoTokenizer.from_pretrained 加载，参数为 model（模型名）和 --revision（版本）。你也可以通过 vllm serve 的 --tokenizer 参数指定用其它模型的分词器，相关参数还有 --tokenizer-revision 和 --tokenizer-mode。具体含义请查阅 Hugging Face 文档。该逻辑见 get_tokenizer 函数。分词器获取后，vLLM 会在 get_cached_tokenizer 内缓存一些代价较大的属性。

2. 模型权重：vLLM 从 Hugging Face 模型库下载模型权重，参数为 model（模型名）和 --revision（版本）。vLLM 提供 --load-format 参数控制下载文件类型。默认优先加载 safetensors 格式权重，若无则回退到 PyTorch bin 格式。你也可以用 --load-format dummy 跳过权重下载。

   • 推荐使用 safetensors 格式，其在分布式推理中高效且不涉及任意代码执行。详见 safetensors 格式文档。实现见 相关代码。注意：

至此 vLLM 与 Hugging Face 的集成过程结束。

总结：vLLM 会从 Hugging Face 模型库或本地目录读取 config.json 配置文件、分词器和模型权重。它使用来自 vLLM、Hugging Face transformers，或模型仓库的 config 类进行配置加载和模型初始化。

原文地址：https://docs.vllm.ai/en/latest/design/huggingface_integration.html
当前更新时间：2025-10-08