Transformers 後端整合在 vLLM 中

Hugging Face Transformers 庫為龐大的模型架構生態系統提供了靈活、統一的介面。從研究到在自定義資料集上進行微調，Transformers 都是首選工具包。

但是，當涉及到大規模部署這些模型時，推理速度和效率往往成為核心關注點。vLLM 應運而生，它是一個專為高吞吐量推理而設計的庫，能夠從 Hugging Face Hub 拉取模型並對其進行最佳化，以實現生產就緒的效能。

vLLM 程式碼庫最近新增了一項功能，使其能夠利用 Transformers 作為後端來執行模型。因此，vLLM 將在現有 Transformers 架構的基礎上最佳化吞吐量/延遲。在這篇博文中，我們將探討 vLLM 如何利用 Transformers 後端，將靈活性與效率相結合，使您能夠更快、更智慧地部署最先進的模型。

更新

本節將包含自博文首次釋出（2025年4月11日）以來發生的所有更新。

支援視覺語言模型（2025年7月21日）

帶有 Transformers 後端的 vLLM 現在支援視覺語言模型。當用戶新增 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 的推理最佳化相結合，您將解鎖一個既靈活又可擴充套件的工作流程。無論您是在原型化新模型、部署自定義創作，還是擴充套件多模態應用程式，這種組合都能加速您從研究到生產的程序。