vLLM官方中文教程：使用vLLM的两种方式(离线推理和vllm server)

最新推荐文章于 2025-10-14 20:33:46 发布

原创

最新推荐文章于 2025-10-14 20:33:46 发布 · 1.4w 阅读

75 ·

CC 4.0 BY-SA版权

文章标签：

#vllm #大模型推理 #推理框架

英文原文链接：https://docs.vllm.ai/en/stable/serving/env_vars.html

在这里插入图片描述

离线推理

您可以在自己的代码中根据提示列表运行 vLLM。

离线 API 基于 LLM 类。要初始化 vLLM 引擎，请创建一个新的 LLM 实例并指定要运行的模型。

例如，以下代码从 HuggingFace 下载 facebook/opt-125m 模型，并使用默认配置在 vLLM 中运行。

llm = LLM(model="facebook/opt-125m")

初始化 LLM 实例后，可以使用各种 API 执行模型推理。可用的 API 取决于正在运行的模型类型：

生成模型会输出 logprobs，通过对 logprobs 进行采样，获得最终输出文本。
池化模型直接输出其隐藏状态。

有关每个 API 的详细信息，请参阅上述页面。和参见接口文档： API Reference

配置选项

本节列出了运行 vLLM 引擎的最常用选项。如需完整列表，请参阅 “引擎参数 ”页面。

模型解析

vLLM 通过检查模型资源库 config.json 中的architectures字段，找到已注册到 vLLM 的相应实现，从而加载与 HuggingFace 兼容的模型。不过，我们的模型解析可能会因为以下原因而失败：

模型资源库的 config.json 缺少architectures字段。
非官方资源库使用 vLLM 未记录的其他名称来引用模型。
多个模型使用了相同的架构名称，这就造成了应加载哪个模型的模糊性。

要解决这个问题，可以通过向 hf_overrides 选项传递 config.json overrides 来明确指定模型架构。例如：

model = LLM(
    model="cerebras/Cerebras-GPT-1.3B",
    hf_overrides={
   
   "architectures": ["GPT2LMHeadModel"]},  # GPT-2
)

我们的支持模型列表显示了 vLLM 可识别的模型架构。

减少内存使用量

大型模型可能会导致机器内存不足（OOM）。以下是一些有助于缓解这一问题的选项。

张量并行

张量并行（tensor_parallel_size 选项）可用于在多个 GPU 上分割模型。

下面的代码将模型分割到 2 个 GPU 上。

llm = LLM(model="ibm-granite/granite-3.1-8b-instruct",
          tensor_parallel_size=2)

为确保 vLLM 能正确初始化 CUDA，应避免在初始化 vLLM 之前调用相关函数（如 torch.cuda.set_device()）。否则，你可能会遇到类似 RuntimeError： Cannot re-initialize CUDA in forked subcess.

要控制使用哪些设备，请设置 CUDA_VISIBLE_DEVICES 环境变量。

量化

量化模型占用内存较少，但精度较低。

静态量化模型可从 HF Hub 下载（Neural Magic 提供了一些常用模型）并直接使用，无需额外配置。

量化选项还支持动态量化quantization，详情请点击此处。

上下文长度和批量大小

通过限制模型的上下文长度（max_model_len 选项）和最大批量大小（max_num_seqs 选项），可以进一步减少内存使用量。

llm = LLM(model="adept/fuyu-8b",
          max_model_len=2048,
          max_num_seqs=2)

上下文长度（max_model_len）：
这个参数定义了模型能够处理的单次输入的最大长度。对于语言模型来说，它通常指的是可以一次性处理的最大文本长度（例如，单词或字符的数量）。上下文长度决定了模型在生成下一个词或者理解当前输入时能考虑的前文信息量。较长的上下文长度允许模型捕捉到更长距离的依赖关系，但同时也会增加计算复杂度和所需的内存。
最大批量大小（max_num_seqs）：
批量大小是指在更新模型权重之前，一次处理的数据样本数量。在自然语言处理任务中，这通常意味着有多少个序列（如句子或文档）会被一起输入到模型中进行处理。增大批量大小可以在一定程度上提高训练效率和模型稳定性，因为这样可以提供更多的信息用于每次权重更新。然而，较大的批量大小也会消耗更多的内存资源。

性能优化和调整

您可以通过微调各种选项来提高 vLLM 的性能。详情请参考本指南。

兼容 OpenAI 的服务

vLLM 提供了一个 HTTP 服务器，可实现 OpenAI 的 Completions API、Chat API 等功能！

您可以通过 vllm serve 命令或 Docker 启动服务器：

vllm serve NousResearch/Meta-Llama-3-8B-Instruct --dtype auto --api-key token-abc123

要调用服务器，可以使用 OpenAI 官方 Python 客户端或任何其他 HTTP 客户端。

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-abc123",
)

completion = client.chat.completions.create(
  model="NousResearch/Meta-Llama-3-8B-Instruct",
  messages=[
    {
   
   "role": "user", "content": "Hello!"}
  ]
)

print(completion.choices[0].message)

支持的API接口

我们目前支持以下 OpenAI API：

Completions API (/v1/completions)

只能用于 text generation models 模型 (--task generate).
注意: suffix 参数是不支持的

Chat Completions API (/v1/chat/completions)

只能用于 text generation models 模型 (--task generate)，使用一个 chat template.
注意: parallel_tool_calls 和 user 参数是不支持的

Embeddings API (/v1/embeddings)

只能用于 embedding models (--task embed).

Transcriptions API (/v1/audio/transcriptions)

仅适用于自动语音识别 (ASR) 模型 (OpenAI Whisper) (--task generate).

聊天模板

为了让语言模型支持聊天协议，vLLM 要求模型在其tokenizer配置中包含一个聊天模板。聊天模板是一个 Jinja2 模板，用于指定输入中的角色、信息和其他chat-specific标记的编码方式。

NousResearch/Meta-Llama-3-8B-Instruct 的聊天模板示例可在此处找到

有些模型即使进行了指令/聊天微调，也不会提供聊天模板。对于这些模型，您可以在 --chat-template 参数中手动指定它们的聊天模板，并提供聊天模板的文件路径或字符串形式的模板。如果没有聊天模板，服务器将无法处理聊天，所有聊天请求都会出错。

vllm serve <model> --chat-template ./path-to-chat-template.jinja

vLLM 社区为常用模型提供了一套聊天模板。您可以在 examples 目录下找到它们。

在这里插入图片描述

随着多模态聊天应用程序接口的加入，OpenAI 规范现在可以接受新格式的聊天信息，这种格式同时指定了一个type和一个text字段。下面提供了一个示例：

completion = client.chat.completions.create(
  model="NousResearch/Meta-Llama-3-8B-Instruct",
  messages=[
    {
   
   "role": "user", "content": [{
   
   "type": "text", "text": "Classify this sentiment: vLLM is wonderful!"}]}
  ]
)

大多数 LLM 聊天模板都希望content字段是字符串，但也有一些较新的模式（如 meta-llama/Llama-Guard-3-1B）希望内容按照请求中的 OpenAI 模式格式化。

vLLM 会尽力支持自动检测，并将其记录为类似 “检测到聊天模板内容格式为… ”的字符串，并在内部将传入请求转换为与检测到的格式相匹配的格式，这些格式可以是以下格式之一：

“string”: A string.

Example: “Hello world”

“openai”: 词典列表，类似于 OpenAI 模式。

Example: [{“type”: “text”, “text”: “Hello world!”}]

如果结果与你预期的不同，你可以设置 CLI 参数 --chat-template-content-format 来覆盖要使用的格式。

额外的参数

vLLM 支持一组不属于 OpenAI API 的参数。要使用这些参数，可以在 OpenAI 客户端中将它们作为额外参数传递。如果您直接使用 HTTP 调用，也可以将它们直接合并到 JSON 有效负载中。

completion = client.chat.completions.create(
  model="NousResearch/Meta-Llama-3-8B-Instruct",
  messages=[
    {
   
   "role": "user", "content": "Classify this sentiment: vLLM is wonderful!"}
  ],
  extra_body={
   
   
    "guided_choice": ["positive", "negative"]
  }
)

额外的请求头

目前只支持 X-Request-Id HTTP 请求头。可以使用 --enable-request-id-headers 启用它。

请注意，启用请求头会对高 QPS 速率下的性能产生重大影响。因此，我们建议在路由器层（例如通过 Istio）而不是在 vLLM 层实施 HTTP 标头。有关详细信息，请参见本 PR。

completion = client.chat.completions.create(
  model="NousResearch/Meta-Llama-3-8B-Instruct",
  messages=[
    {
   
   "role": "user", "content": "Classify this sentiment: vLLM is wonderful!"}
  ],
  extra_headers={
   
   
    "x-request-id": "sentiment-classification-00001",
  }
)
print(completion._request_id)

completion = client.completions.create(
  model="NousResearch/Meta-Llama-3-8B-Instruct",
  prompt="A robot may not injure a human being",
  extra_headers={
   
   
    "x-request-id": "completion-test",
  }
)
print(completion._request_id)

CLI参数

vllm serve 命令用于启动与 OpenAI 兼容的服务器。

usage: vllm serve [-h] [--host HOST] [--port PORT]
                  [--uvicorn-log-level {
   
   debug,info,warning,error,critical,trace}]
                  [--allow-credentials] [--allowed-origins ALLOWED_ORIGINS]
                  [--allowed-methods ALLOWED_METHODS]
                  [--allowed-headers ALLOWED_HEADERS] [--api-key API_KEY]
                  [--lora-modules LORA_MODULES [LORA_MODULES ...]]
                  [--prompt-adapters PROMPT_ADAPTERS [PROMPT_ADAPTERS ...]]
                  [--chat-template CHAT_TEMPLATE]