跳至内容

与Hugging Face集成

本文档介绍vLLM如何与HuggingFace库集成。我们将逐步解释运行vllm serve时底层发生的具体过程。

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

  1. model参数是Qwen/Qwen2-7B。vLLM通过检查对应的配置文件config.json来确定该模型是否存在。具体实现可参考这个代码片段。在此过程中：

    • 如果model参数对应一个现有的本地路径，vLLM将直接从该路径加载配置文件。
    • 如果model参数是由用户名和模型名称组成的HuggingFace模型ID，vLLM会首先尝试使用HuggingFace本地缓存中的配置文件，将model参数作为模型名称，--revision参数作为版本号。有关HuggingFace缓存工作原理的更多信息，请参阅他们的网站。
    • 如果 model 参数是 HuggingFace 模型 ID 但未在缓存中找到，vLLM 将从 HuggingFace 模型中心下载配置文件。具体实现请参考 此函数。输入参数包括作为模型名称的 model 参数、作为修订版本的 --revision 参数，以及用于访问模型中心的环境变量 HF_TOKEN。在本例中，vLLM 将下载 config.json 文件。

  2. 确认模型存在后，vLLM会加载其配置文件并将其转换为字典。具体实现可参考此代码片段。

  3. 接下来，vLLM 检查配置字典中的model_type字段以生成要使用的配置对象。vLLM直接支持某些model_type值；完整列表请参见此处。如果model_type不在列表中，vLLM将使用AutoConfig.from_pretrained加载配置类，参数包括model、--revision和--trust_remote_code。请注意：

    • HuggingFace 也有自己的逻辑来确定要使用的配置类。它会再次使用 model_type 字段在 transformers 库中搜索类名；支持的模型列表请参见此处。如果找不到 model_type，HuggingFace 将使用配置文件 JSON 中的 auto_map 字段来确定类名。具体来说，是 auto_map 下的 AutoConfig 字段。示例可参考DeepSeek。
    • auto_map下的AutoConfig字段指向模型仓库中的模块路径。HuggingFace会导入该模块并使用from_pretrained方法加载配置类。这通常会导致任意代码执行，因此只有在启用--trust_remote_code时才会执行。

  4. 随后，vLLM会对配置对象应用一些历史补丁。这些补丁主要与RoPE配置相关；具体实现请参见此处。

  5. 最终，vLLM能够定位到我们需要初始化的模型类。vLLM使用配置对象中的architectures字段来确定要初始化的模型类，因为它在其注册表中维护了从架构名称到模型类的映射关系。如果在注册表中找不到该架构名称，则意味着vLLM不支持该模型架构。对于Qwen/Qwen2-7B模型，其architectures字段值为["Qwen2ForCausalLM"]，对应vLLM代码中的Qwen2ForCausalLM类。该类会根据不同的配置项完成自身初始化。

除此之外，vLLM还有两个功能依赖于HuggingFace。

  1. 分词器: vLLM使用HuggingFace的分词器来处理输入文本。分词器通过AutoTokenizer.from_pretrained加载，其中model参数指定模型名称，--revision参数指定版本。也可以通过vllm serve命令中的--tokenizer参数指定使用其他模型的分词器。其他相关参数包括--tokenizer-revision和--tokenizer-mode。这些参数的具体含义请参考HuggingFace的文档。这部分逻辑可在get_tokenizer函数中找到。获取分词器后，值得注意的是vLLM会在get_cached_tokenizer中缓存分词器的一些高开销属性。

  2. 模型权重: vLLM 从 HuggingFace 模型中心下载模型权重，使用 model 参数作为模型名称，--revision 参数作为版本号。vLLM 提供了 --load-format 参数来控制从模型中心下载哪些文件。默认情况下，它会尝试加载 safetensors 格式的权重，如果该格式不可用，则回退到 PyTorch bin 格式。我们也可以传递 --load-format dummy 来跳过下载权重。

    • 建议使用safetensors格式，因为它在分布式推理加载时效率高，并且能防止任意代码执行。有关safetensors格式的更多信息，请参阅文档。这部分逻辑可以在此处找到。请注意：

这完成了vLLM与HuggingFace之间的集成。

总之，vLLM会从HuggingFace模型中心或本地目录读取配置文件config.json、分词器和模型权重。它使用来自vLLM或HuggingFace transformers的配置类，或从模型仓库加载配置类。