Transformers在vLLM中部署生成模型

把 Transformers 模型部署到 vLLM，核心不是把 AutoModelForCausalLM 的推理代码原样搬到服务器，而是把 Hugging Face 模型仓库或本地目录作为模型资产交给 vllm serve，再通过 OpenAI 兼容接口提供生成服务。这样，模型加载、批处理和 HTTP 服务由 vLLM 负责，业务侧只保留请求协议和结果处理。

官方地址：https://huggingface.co/docs/transformers/；https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html

先区分 Transformers 模型和 vLLM 服务

Transformers 更像模型资产与加载接口：模型类、配置、tokenizer 和权重可以从 Hugging Face Hub 或本地目录加载。vLLM 则是面向在线推理的服务引擎，负责把同一模型包装成 HTTP 接口。部署时最重要的映射关系是：模型仓库名是输入，vLLM 是运行时，OpenAI 兼容接口是调用契约。

用 vllm serve 启动生成模型

下面把模型名放进环境变量，便于在切换模型时只改部署配置。示例模型名只是占位，实际使用时替换成与你的 Transformers 架构和显存条件匹配的模型仓库或本地目录。

# 指向 Hugging Face 模型仓库或服务器上的本地模型目录
export MODEL_ID="Qwen/Qwen2.5-1.5B-Instruct"

# 只把密钥放进环境变量，不要把真实密钥写进脚本或文章
export VLLM_API_KEY="change-me"

# 启动 OpenAI 兼容生成服务；--generation-config vllm 让服务端采样默认值更可控
vllm serve "$MODEL_ID" \
  --host 0.0.0.0 \
  --port 8000 \
  --dtype auto \
  --api-key "$VLLM_API_KEY" \
  --generation-config vllm

--dtype auto 让 vLLM 按运行环境选择数据类型；部署前仍需根据模型文档、显存和量化格式做资源决策。--generation-config vllm 用于避免模型仓库里的 generation_config.json 静默改变服务端的采样默认值。生产环境不要把调试接口直接暴露给公网，并应在反向代理或网关层补充访问控制、TLS 和限流。

如果模型所在仓库需要认证，应先在运行环境配置对应的 Hugging Face 访问凭据；不要把 token 写进 vllm serve 命令历史、文章或日志。若使用本地目录，先确认目录内的配置、tokenizer 和权重文件是一套可配对的模型资产。

用 Python 客户端调用 /v1/chat/completions

vLLM 的 OpenAI 兼容接口让业务侧不必直接依赖 Transformers 的模型类。客户端只需要把 base_url 指向服务的 /v1 前缀，把 model 与服务端加载的模型名保持一致。

from openai import OpenAI

# base_url 指向 vLLM 的 /v1 前缀，客户端会自动拼接具体接口路径
client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="change-me",
    timeout=30.0,
)

response = client.chat.completions.create(
    # 这里要与 vLLM 实际暴露的模型名保持一致
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[
        {"role": "system", "content": "你是一个简洁的技术助手。"},
        {"role": "user", "content": "用一句话解释 vLLM 的作用。"},
    ],
    temperature=0.2,
    max_tokens=128,
)

# 先取 choices，再取 message.content，避免把完整响应对象当成字符串
text = response.choices[0].message.content
print(text)

服务端返回的是 OpenAI 风格的响应对象，业务代码应只依赖自己需要的字段。若应用需要稳定输出，可以进一步约束系统提示、温度、最大输出长度和重试策略，但这些参数应作为接口契约的一部分统一管理。

chat template 是聊天接口的关键兼容点

生成模型不等于聊天模型。聊天请求需要把 system、user 等角色消息转换成模型训练时使用的输入格式，这个转换通常由 tokenizer 配置中的 Jinja chat template 完成。若模型没有可用模板，vLLM 无法正确处理聊天请求，可以通过 --chat-template 指定一个模板文件或模板字符串。

# 模型没有可用 chat template 时，显式指定模板文件
vllm serve "$MODEL_ID" \
  --chat-template ./templates/chat-template.jinja \
  --generation-config vllm

# 只需要续写而不需要角色消息时，调用方应使用 completions 语义
# 这里的注释提醒：不要把普通文本续写请求误包装成 chat 请求

排查时先确认三件事：模型是文本生成任务而不是 embedding 或 rerank 任务；tokenizer 中确实存在适配的模板；客户端发送的 messages 内容格式与模板预期一致。模板能决定角色标记、结束标记和是否生成提示词，换模板可能改变输出，即使模型权重没有变化。

参数和错误模型要一起设计

从 API 设计角度，部署成功不只意味着进程能启动，还要让调用方知道哪些错误是配置错误、哪些是请求错误、哪些是服务暂时不可用。可以把问题按下面的边界处理：

还要注意采样参数的来源。vLLM 文档说明，默认情况下服务端可能读取模型仓库中的 generation_config.json；如果希望由服务方控制默认采样值，就在启动时显式使用 --generation-config vllm，并在客户端传入业务需要的参数。不要把“模型默认值”“服务默认值”和“请求覆盖值”混在一张配置表里。

部署前用一张清单收敛兼容策略

• 模型：记录模型仓库或本地目录、任务类型、tokenizer、权重格式和访问权限。
• 服务：记录 vLLM 版本、监听地址、端口、GPU 资源、API 鉴权和是否显式指定生成配置。
• 协议：记录使用 /v1/completions 还是 /v1/chat/completions，以及客户端的模型名映射。
• 稳定性：记录超时、最大输入/输出长度、重试上限、并发上限和网关限流策略。
• 升级：模型替换时同时检查 chat template、tokenizer 和采样默认值，不要只替换一个权重目录。

这样部署出来的不是“某台机器上能跑”的临时进程，而是一份可迁移的接口契约：模型资产可以更换，vLLM 运行时可以升级，调用方仍然只依赖明确的请求和错误边界。

常见问题

Transformers 和 vLLM 是二选一吗？

不是。Transformers 提供模型资产与加载生态，vLLM 负责更适合在线服务的运行时和 HTTP 入口。你可以用 Transformers 生态中的模型标识交给 vLLM 服务。

为什么模型能启动，但 chat 请求失败？

最常见原因是 tokenizer 没有可用 chat template，或模板与消息格式不匹配。检查模板配置，必要时通过 --chat-template 显式指定。

客户端 model 写什么？

写服务端实际暴露的模型名，并让它由部署配置注入。不要凭感觉把它改成任意别名，除非你同时确认 vLLM 的模型命名配置和客户端映射。

是否可以直接把 vLLM 的 API 暴露到公网？

不建议。API key 不是完整的网络边界；生产环境还应使用反向代理、TLS、访问控制、限流和日志脱敏，并关闭不必要的开发接口。