vLLM 实战：OpenAI 兼容接口参数与限制

vLLM 的 HTTP 服务实现了 OpenAI Completions API 和 Chat API；下面涉及的端点、适用范围和 extra_body 用法，都以OpenAI 兼容服务文档为准：/v1/completions 不支持 suffix，Chat API 会忽略 user，也不支持 image_url.detail。配置时要把模型类型、启动参数和请求字段一起核对，不能把“路径兼容”理解成“所有参数行为一致”。

准备环境并启动 vLLM 服务

按快速开始文档，准备 Linux 和 Python 3.10 至 3.13，并运行以下安装命令。--torch-backend=auto 会根据已安装的 CUDA 驱动选择 PyTorch 索引。

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

同一快速开始用下面的命令启动模型。服务默认监听 http://localhost:8000，可用 --host 和 --port 调整地址；一个服务进程当前只承载一个模型。

vllm serve Qwen/Qwen2.5-1.5B-Instruct

NVIDIA GPU 还需满足GPU 安装文档列出的 compute capability 7.5 或更高要求。

OpenAI 兼容接口：端点与适用范围

开头所链接的官方文档把各端点的适用模型写得很明确：

用途	路径	适用范围或限制
文本生成	/v1/completions	仅适用于文本生成模型
对话生成	/v1/chat/completions	需要 chat template
Responses	/v1/responses	提供 Responses API
向量化	/v1/embeddings	仅适用于 embedding models
语音转写	/v1/audio/transcriptions	仅适用于 ASR models
批量对话	/v1/chat/completions/batch	提供 batch Chat Completions

选择路径后，再处理请求字段。文本生成模型并不因为服务兼容 OpenAI API，就自动支持 embedding、ASR 或其他专用端点。

请求参数：扩展项与请求头

对于 OpenAI API 没有的参数，例如 top_k，可以放进 OpenAI 客户端的 extra_body：

extra_body={"top_k": 50}

直接发送 HTTP 请求时，则把扩展参数合并进 JSON payload。parallel_tool_calls=false 会把每次请求限制为零个或一个工具调用；默认值 true 允许返回多个工具调用。

需要在响应中启用 X-Request-Id 时，启动时添加 --enable-request-id-headers。X-Vllm-Priority 请求头的值必须是整数，并会覆盖 JSON 请求体中的 priority。

工具调用：自动选择需要启动能力

按工具调用文档，tool_choice 支持指定命名函数，以及 auto、required、none；其中 required 标注为从 vllm>=0.8.3 开始支持。自动工具选择必须启用 --enable-auto-tool-choice。

官方给出的 Llama 3.1 quickstart 同时配置了解析器和工具聊天模板：

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-auto-tool-choice \
  --tool-call-parser llama3_json \
  --chat-template examples/tool_chat_template_llama3.1_json.jinja

指定命名函数时，文档保证函数调用能够被正确解析，但不保证模型选择了高质量函数。

结构化输出：约束字段与后端

结构化输出文档说明，后端可以使用 xgrammar 或 guidance。通过 --structured-outputs-config.backend 选择后端，默认值是 auto；约束条件放在请求的 extra_body 中，例如：

extra_body={"structured_outputs": {"choice": ["positive", "negative"]}}

文档列出的约束类型包括 choice、regex、json、grammar 和 structural_tag。旧的 guided_* 请求字段已在 v0.12.0 移除，现有代码应改用 structured_outputs。

启动参数：资源与并行边界

这些参数决定模型执行和调度边界，准确含义以服务 CLI 参数参考为准：

参数	含义与限制
--gpu-memory-utilization	模型执行器使用的 GPU 显存比例，范围为 0 到 1，默认值为 0.92；它是每个实例的独立限制
--kv-cache-memory-bytes	直接设置每张 GPU 的 KV cache 大小；设置后会覆盖 --gpu-memory-utilization
--max-model-len	上下文总长度，包含 prompt 和 output；未设置时从模型配置推导，设为 -1 或 auto 时选择 GPU 显存能够容纳的最大长度
--max-num-seqs	单次迭代最多处理的 sequences 数量
--max-num-batched-tokens	单次迭代最多处理的 tokens 数量
--tensor-parallel-size、-tp	tensor parallel groups 数量，默认值为 1
--pipeline-parallel-size、-pp	pipeline parallel groups 数量，默认值为 1

验证与故障定位

先按快速开始提供的方法请求模型列表：

curl http://localhost:8000/v1/models

该请求用于列出可用模型。响应中没有目标模型时，先检查启动命令中的模型名称，以及 --host、--port 指定的地址。

模型列表正常但业务请求失败时，依次检查：端点是否适用于当前模型；请求中是否包含开头列出的不支持字段；工具调用是否启用自动选择；结构化输出是否仍使用已移除的 guided_*；以及是否把单模型进程当成了多模型服务。

安全边界也要单独核对：--api-key 只认证 /v1、/v2 和 /inference 前缀下的请求；同一 HTTP 服务上的其他端点不认证，/invocations 也不认证。

这些步骤依据正文所链接的官方文档整理；使用前应按当前版本复核。

资料来源

• OpenAI 兼容服务文档
• 快速开始
• GPU 安装要求
• 工具调用文档
• 结构化输出文档
• 服务 CLI 参数参考