vLLM接口调用与生成参数配置
用 vllm 启动 OpenAI 兼容服务，并通过 extra_body 配置 top_k 等生成参数、请求头鉴权和返回模型检查。
完成后，你会得到一个本机可调用的 OpenAI 兼容 HTTP 服务，能使用 /v1/completions、/v1/chat/completions，通过 extra_body 传入扩展生成参数，并清楚 --api-key 只保护 /v1、/v2、/inference；这些接口、传参和鉴权边界见 vLLM 的 OpenAI-Compatible Server 文档。开始前需要 vLLM 快速开始文档列出的 Linux、Python 3.10 至 3.13；若走 NVIDIA GPU 路线，vLLM GPU 安装文档要求 compute capability 为 7.5 或更高。下面用 vllm 的官方安装和启动流程，把生成请求、返回结果与鉴权边界接起来。
准备条件
先准备 Linux 命令行环境，并确保有可用的 uv。本文沿用快速开始文档中的 Qwen/Qwen2.5-1.5B-Instruct，但不据此推断其他模型也能使用相同硬件条件。
官方建议使用全新环境。如果当前 CUDA 版本不同，或者需要沿用已有 PyTorch 安装，应从源码构建，并准备 GCC/G++ 11.3 或更高版本。vLLM 不原生支持 Windows，文档给出的运行方式是在 WSL 中使用兼容的 Linux 发行版。
操作步骤：用 vllm 启动并调用
1. 创建环境并安装
按前述快速开始文档创建 Python 3.12 环境：
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
这会在 .venv 中创建环境并安装 vLLM；--torch-backend=auto 会检查已安装的 CUDA driver，以选择对应的 PyTorch index。
2. 启动模型服务
使用快速开始文档中的模型启动服务：
vllm serve Qwen/Qwen2.5-1.5B-Instruct
服务默认监听 http://localhost:8000，可用 --host 和 --port 修改地址；当前一个服务进程一次托管一个模型。
3. 选择兼容接口
文本生成和聊天请求分别使用以下 endpoint：
/v1/completions
/v1/chat/completions
/v1/completions 只适用于 text generation models，且不支持 suffix 参数；/v1/chat/completions 会忽略 user 参数。
4. 配置生成参数
使用 OpenAI client 时，在请求的 extra_body 位置传入 vLLM 扩展参数：
extra_body={"top_k": 50}
vLLM 服务端参数参考列出的额外 sampling parameters 包括 top_k、min_p 和 repetition_penalty。
直接使用 HTTP 请求时，把额外参数合并进原有 JSON payload：
{"top_k": 50}
这个代码块只是待合并的 JSON 片段，不是完整请求；请求 endpoint、model、messages 和返回结构应按当前 Chat API 文档填写。
5. 配置请求头鉴权
如果要启用 API key 检查，先把真实值保存在环境变量中：
export VLLM_API_KEY=YOUR_VALUE
VLLM_API_KEY 会让服务检查请求头中的 API key，真实值不要写入代码、仓库或示例命令。
在同一个 shell 中启动服务：
vllm serve Qwen/Qwen2.5-1.5B-Instruct
也可以使用 --api-key 启用检查；该参数后可以放置多个 key，服务会接受其中任意一个，适合 key rotation，但本文采用环境变量避免把真实值直接写入启动命令。
怎么确认成功
先在没有 API key 的本机实例上执行快速开始文档给出的命令：
curl http://localhost:8000/v1/models
正确结果是返回可用模型列表，其中应包含当前实例加载的模型。如果从启动起就设置了 VLLM_API_KEY，上面的裸 curl 不再适合作为鉴权检查，因为 /v1/models 位于受保护的 /v1 前缀下；此时应按当前官方请求头示例传入同一个 key，不要猜测 header 格式。
如果你配置了多个 --served-model-name，vllm serve 命令行参考说明请求可以使用其中任一名称，而响应 model 字段会返回列表中的第一个名称。完整 Chat 响应不要按固定文案验收，应按当前版本的 Chat API 文档核对返回结构，再检查实际生成内容。
常见出错点
聊天请求为什么全部报错
服务默认使用 tokenizer 中预定义的 chat template；没有 chat template 时，服务器无法处理聊天请求。vLLM 在线服务文档说明，--chat-template 可以接收模板文件路径或模板字符串；如果消息 content 格式的自动识别不符合预期，还可用 --chat-template-content-format 覆盖识别结果。
接口兼容是否代表所有字段都兼容
不代表。开头所引的官方文档明确列出了差异：Completions API 不支持 suffix，Chat API 忽略 user，Chat API 也不支持 image_url.detail；接入现有 OpenAI 代码时，应先移除这些字段，而不是期待服务端按原样处理。
为什么配置 API key 后仍有路径未鉴权
--api-key 和 VLLM_API_KEY 只检查 /v1、/v2、/inference 前缀下的请求，同一 HTTP server 上的其他 endpoint 不受这枚 key 保护。因此不要把它当作整台服务的统一鉴权层，也不要仅凭该参数判断所有路径都已受到保护。
这些步骤按正文所链接的官方文档整理，未在本站机器上运行或测量；部署前请按当前 vLLM 版本复核命令、参数和响应结构。