Transformers 建模后端在 vLLM 中的集成

2025年4月11日6 分钟阅读

Hugging Face 团队

Hugging Face Transformers 库提供了一个灵活、统一的接口，涵盖了广泛的模型架构生态系统。从研究到在自定义数据集上进行微调，Transformers 是大家的首选工具包。

但是，当涉及到大规模部署这些模型时，推理速度和效率往往占据核心地位。这时就需要 vLLM，这是一个专为高吞吐推理而设计的库，它从 Hugging Face Hub 获取模型并对其进行优化，以实现生产级的性能。

vLLM 代码库最近的一项新增功能使其能够利用 Transformers 作为模型实现的后端。因此，vLLM 将在现有的 Transformers 架构之上优化吞吐量/延迟。在这篇文章中，我们将探讨 vLLM 如何利用 Transformers 建模后端将灵活性与效率相结合，使您能够更快、更智能地部署最先进的模型。

更新

本节将包含自博客文章首次发布（2025年4月11日）以来发生的所有更新。

对视觉语言模型（VLM）的支持（2025年7月21日）

带有 Transformers 建模后端的 vLLM 现在支持视觉语言模型（Vision Language Models）。当用户添加 model_impl="transformers" 时，系统会自动推断并加载适用于纯文本或多模态任务的正确类。

以下是如何使用 Transformers 建模后端来服务多模态模型的方法。

vllm serve llava-hf/llava-onevision-qwen2-0.5b-ov-hf \
--model_impl transformers \

要调用该模型，可以使用 openai API，如下所示

from openai import OpenAI
openai_api_key = "EMPTY"
openai_api_base = "https://:8000/v1"
client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)
chat_response = client.chat.completions.create(
    model="llava-hf/llava-onevision-qwen2-0.5b-ov-hf",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "http://images.cocodataset.org/val2017/000000039769.jpg",
                },
            },
        ],
    }],
)
print("Chat response:", chat_response)

您也可以直接使用 LLM API 初始化 vLLM 引擎。以下是使用 LLM API 服务同一个模型的示例。

from vllm import LLM, SamplingParams
from PIL import Image
import requests
from transformers import AutoProcessor
 
model_id = "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
hf_processor = AutoProcessor.from_pretrained(model_id) # required to dynamically update the chat template
 
messages = [
    {
      "role": "user",
      "content": [
          {"type": "image", "url": "dummy_image.jpg"},
          {"type": "text", "text": "What is the content of this image?"},
        ],
    },
]
prompt = hf_processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
image = Image.open(
    requests.get(
        "http://images.cocodataset.org/val2017/000000039769.jpg", stream=True
    ).raw
)
 
# initialize the vlm using the `model_impl="transformers"`
vlm = LLM(
    model="llava-hf/llava-onevision-qwen2-0.5b-ov-hf",
    model_impl="transformers",
)
 
outputs = vlm.generate(
    {
        "prompt": prompt,
        "multi_modal_data": {"image": image},
    },
    sampling_params=SamplingParams(max_tokens=100)
)
 
for o in outputs:
    generated_text = o.outputs[0].text
    print(generated_text)
 
# OUTPUTS:
# In the tranquil setting of this image, two feline companions are enjoying a peaceful slumber on a
# cozy pink couch. The couch, adorned with a plush red fabric across the seating area, serves as their perfect resting place.
#
# On the left side of the couch, a gray tabby cat is curled up at rest, its body relaxed in a display
# of feline serenity. One paw playfully stretches out, perhaps in mid-jump or simply exploring its surroundings.

Transformers 与 vLLM：实际推理应用

让我们先从一个简单的文本生成任务开始，使用 meta-llama/Llama-3.2-1B 模型来看看这两个库的表现如何。

使用 Transformers 进行推理

transformers 库的优势在于其简洁性和多功能性。使用其 pipeline API，推理变得轻而易举

from transformers import pipeline
 
pipe = pipeline("text-generation", model="meta-llama/Llama-3.2-1B")
result = pipe("The future of AI is")
 
print(result[0]["generated_text"])

这种方法非常适合原型设计或小规模任务，但它并未针对高容量推理或低延迟部署进行优化。

使用 vLLM 进行推理

vLLM 采取了不同的路径，通过 PagedAttention（一种内存高效的注意力机制）和动态批处理等功能优先考虑效率。以下是使用 vLLM 执行相同任务的方法

from vllm import LLM, SamplingParams
 
llm = LLM(model="meta-llama/Llama-3.2-1B")
params = SamplingParams(max_tokens=20)
outputs = llm.generate("The future of AI is", sampling_params=params)
print(f"Generated text: {outputs[0].outputs[0].text}")

vLLM 的推理速度明显更快，资源利用率也更高，特别是在负载情况下。例如，它可以在较低的 GPU 内存占用下每秒处理数千个请求。

vLLM 的部署超能力：OpenAI 兼容性

除了卓越的性能外，vLLM 还提供与 OpenAI 兼容的 API，使其成为外部服务的直接替代品。启动服务器：

vllm serve meta-llama/Llama-3.2-1B

然后使用 curl 进行查询：

curl https://:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "meta-llama/Llama-3.2-1B", "prompt": "San Francisco is a", "max_tokens": 7, "temperature": 0}'

或者使用 Python 的 OpenAI 客户端：

from openai import OpenAI
 
client = OpenAI(api_key="EMPTY", base_url="https://:8000/v1")
completion = client.completions.create(
    model="meta-llama/Llama-3.2-1B",
    prompt="San Francisco is a",
    max_tokens=7,
    temperature=0
)
print("Completion result:", completion.choices[0].text)

这种兼容性降低了成本并增强了控制力，让您可以利用 vLLM 的优化在本地扩展推理。

为什么我们需要 Transformers 建模后端？

Transformers 库针对社区贡献和添加新模型进行了优化。另一方面，在 vLLM 中添加新模型则稍微复杂一些。

在理想世界中，一旦新模型被添加到 Transformers 中，我们就能立即在 vLLM 中使用它。随着 Transformers 建模后端的集成，我们向这个理想世界迈进了一步。

这是关于如何使您的 Transformers 模型与 vLLM 兼容以启用集成的官方文档。我们遵循了该指南，并使 modeling_gpt2.py 兼容了此次集成！您可以在此 Transformers 合并请求中跟踪这些变更。

对于已经在 Transformers 中（且与 vLLM 兼容）的模型，我们需要进行如下设置：

llm = LLM(model="new-transformers-model", model_impl="transformers")

注意：添加 model_impl 参数并非强制要求。如果模型未被 vLLM 原生支持，vLLM 会自动切换到 Transformers 实现。

或者针对来自 Hugging Face Hub 的自定义模型：

llm = LLM(model="custom-hub-model", model_impl="transformers", trust_remote_code=True)

此后端充当了一座桥梁，将 Transformers 的即插即用灵活性与 vLLM 的推理能力结合起来。您将获得两全其美的优势：使用 Transformers 进行快速原型设计，以及使用 vLLM 进行优化部署。

案例研究：Helium

Kyutai 团队的 Helium 尚未被 vLLM 原生支持。您可能希望使用 vLLM 在该模型上运行优化后的推理，而这正是 Transformers 建模后端大放异彩的地方。

让我们来看看它的实际应用：

vllm serve kyutai/helium-1-preview-2b --model-impl transformers

使用 OpenAI API 进行查询：

from openai import OpenAI
 
openai_api_key = "EMPTY"
openai_api_base = "https://:8000/v1"
 
client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)
 
completion = client.completions.create(model="kyutai/helium-1-preview-2b", prompt="What is AI?")
print("Completion result:", completion)

在这里，vLLM 高效地处理输入，利用 Transformers 建模后端无缝加载 kyutai/helium-1-preview-2b。与在 Transformers 中原生运行相比，vLLM 提供了更低的延迟和更好的资源利用率。

通过将 Transformers 的模型生态系统与 vLLM 的推理优化配对，您可以开启一个既灵活又可扩展的工作流。无论您是在进行新模型原型设计、部署自定义模型，还是扩展多模态应用，这种组合都将加速您从研究到生产的进程。