vLLM 在线服务（Online Serving）HTTP 接口全景指南：从 OpenAI 兼容 API 到开发模式端点

2026-09-07 10:34:47作者：昌雅子Ethen

本文档定位：vLLM 内置的 HTTP 推理服务不仅在 /v1 前缀下暴露了与 OpenAI 高度兼容的接口，还围绕不同模型类型、不同部署形态（离线文档、SageMaker、Scale-Out、RL 训练等）提供了一整套可选的 REST 端点。读完本文，你将掌握 vllm serve 暴露的全部 API 家族及其适用模型类型、各自的启用开关与安全注意事项，并能在实际项目中快速选出正确的端点进行集成。

vLLM 通过 vllm/entrypoints/launchers/api_server/routers.py 中的 register_api_routers 统一完成路由注册：它会根据模型的 supported_tasks（如 generate、transcription、pooling 相关任务）有条件地挂载不同 API 路由组。也就是说，并非每个端点在任意模型上都可用——这是理解下文所有接口的基础。

一、接口总览与路由注册机制

从源码看，所有在线接口的路由注册入口为 register_api_routers，其注册逻辑可归纳如下：

触发条件	注册的路由组	代表端点
始终注册	`vllm serve` 基础路由、模型列表、SageMaker	`/v1/models`、`/ping`、`/invocations`、`/version`、`/load`、`/health` 等
`supported_tasks` 含 `generate`	生成类路由、弹性专家并行、Scale-Out	`/v1/completions`、`/v1/chat/completions`、`/inference/v1/generate`、`/scale_elastic_ep`
`supported_tasks` 含 `transcription` / `realtime`	语音识别路由	`/v1/audio/transcriptions`、`/v1/audio/translations`、`/v1/realtime`
`supported_tasks` 含 pooling 类任务	池化路由	`/pooling`、`/v1/embeddings`、`/classify`、`/score`、`/rerank`
`VLLM_SERVER_DEV_MODE=1`	开发模式路由	`/reset_prefix_cache`、`/pause`、`/update_weights` 等
`enable_fault_tolerance`	容错路由	故障转移相关端点

说明：vllm.entrypoints.openai.api_server 模块已标记为 deprecated（见 api_server.py），请改用 vllm serve 命令或 vllm.entrypoints.launchers 下的新入口。

二、OpenAI 兼容接口家族（`/v1`）

vLLM 提供了与 OpenAI API 规范高度兼容的 HTTP 服务，具体支持范围如下（详见 openai_compatible_server.md）：

API	端点	适用模型
Completions API	`/v1/completions`	仅文本生成模型（`suffix` 参数不支持）
Chat Completions API	`/v1/chat/completions`	文本生成模型，且必须配置聊天模板（chat template）（`user` 参数会被忽略）
Chat Completions batch API	`/v1/chat/completions/batch`	同上
Responses API	`/v1/responses`、`/v1/responses/{response_id}`、`/v1/responses/{response_id}/cancel`	文本生成模型
Embeddings API	`/v1/embeddings`	仅 embedding 模型
Transcriptions API	`/v1/audio/transcriptions`	仅 ASR（自动语音识别）模型（见 Transcription 支持列表）
Translation API	`/v1/audio/translations`	仅 ASR 模型

启动与调用示例

使用 vllm serve 命令（完整参数见 serve_args.md）启动：

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

客户端可用官方 OpenAI Python SDK，指定 base_url="http://localhost:8000/v1"：

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)

需要特别注意的兼容性细节

parallel_tool_calls：将其设为 false 可确保 vLLM 每个请求只返回 0 或 1 个 tool call；设为 true（默认值）时允许返回多个 tool call，但不保证一定返回多个——这取决于模型本身，并非所有模型都设计为支持并行 tool call。
采样参数被模型仓库覆盖：默认情况下，若 Hugging Face 模型仓库中存在 generation_config.json，服务器会采用其中推荐的采样参数默认值；如需禁用该行为，可在启动时传 --generation-config vllm。
OpenAI 之外的扩展参数：vLLM 支持 top_k 等 OpenAI 未定义的参数，可通过客户端 extra_body 传入，如 extra_body={"top_k": 50}，也可直接合并进 HTTP JSON 请求体。
X-Request-Id 响应头：通过 --enable-request-id-headers 开启（实现见 vllm/entrypoints/serve/middleware/x_request_id.py）。
API Key 仅保护部分端点：--api-key（或 VLLM_API_KEY 环境变量）只认证 /v1、/v2、/inference 前缀下的请求；同服务上的其他端点（尤其 /invocations）不做认证，切勿单独依赖 API Key 保护服务，建议部署在反向代理之后（详见 security.md）。

三、Anthropic、Cohere 与池化 API

Anthropic Messages API

/v1/messages、/v1/messages/count_tokens：兼容 Anthropic messages 协议。实现位于 vllm/entrypoints/anthropic，其中 serving.py 中同样读取 chat_template_content_format 等配置。

Cohere API

Cohere Embed API（/v2/embed）：兼容 Cohere Embed 接口，支持任意 embedding 模型，含多模态模型。
Cohere Rerank API（/rerank、/v1/rerank、/v2/rerank）：同时实现并兼容 Jina AI v1 与 Cohere v1/v2 的 rerank 语义。

Pooling 类 API

Pooling 模型的相关 API 均依据模型任务类型条件注册（见 routers.py 中 POOLING_TASKS 判断分支）：

API	端点	适用模型
Pooling API	`/pooling`	所有 pooling 模型
Classification API	`/classify`	classification 模型
Embeddings API	`/v1/embeddings`	embedding 模型
Cohere Embed API	`/v2/embed`	同上
Score API	`/score`、`/v1/score`	score 模型（cross-encoder、bi-encoder、late-interaction）
Cohere Rerank API	`/rerank`、`/v1/rerank`、`/v2/rerank`	同上

更细的用法可分别参考 classify.md、embed.md、scoring.md 与 pooling 模型总览。

四、语音、自定义与生成式评分 API

Speech-to-Text API

API	端点	适用模型
Transcriptions API	`/v1/audio/transcriptions`	ASR 模型
Translation API	`/v1/audio/translations`	ASR 模型
Realtime API	`/v1/realtime`	实时语音模型

详细说明见 speech_to_text.md。

自定义（Custom）API

API	端点	适用模型
Classification API	`/classify`	classification 模型
Score API	`/score`、`/v1/score`	score 模型
Pooling API	`/pooling`	所有 pooling 模型
Generative Scoring API	`/generative_scoring`	CausalLM 文本生成模型，任务为 `generate`；为指定的 `label_token_ids` 计算 next-token 概率

Generative Scoring 的详细介绍见 generative_scoring.md。

五、Instrumentator 基础端点与指标

基础 API

/version——版本信息
/load——服务器负载指标
/v1/models——列出可用模型
/health——健康检查

实现集中在 vllm/entrypoints/serve/instrumentator（分为 basic、health、metrics、offline_docs 等子模块）。

Metrics API

/metrics——Prometheus 兼容的指标 HTTP 端点。指标体系详细设计见 design/metrics.md。

离线 API 文档（Offline Docs）

FastAPI 的 /docs 端点默认依赖外网 CDN。在离线/内网（air-gapped）环境下，使用 --enable-offline-docs 即可启用完全本地化的 Swagger UI（静态资源打包于 instrumentator/static，含 swagger-ui-bundle.js 与 swagger-ui.css）：

vllm serve NousResearch/Meta-Llama-3-8B-Instruct --enable-offline-docs

LoRA 动态加载

API 服务器原生支持 LoRA 适配器的动态加载/卸载，仅建议用于本地开发调试：

/v1/load_lora_adapter——动态加载 LoRA 适配器
/v1/unload_lora_adapter——动态卸载 LoRA 适配器

实现见 vllm/entrypoints/serve/lora/api_router.py。

Profiling API

/start_profile——启动 PyTorch profiler
/stop_profile——停止 PyTorch profiler

详细用法见 contributing/profiling.md。

SageMaker API

/ping——SageMaker 健康检查
/invocations——SageMaker 兼容端点（与 /v1 端点路由到相同的推理函数）

实现见 vllm/entrypoints/serve/sagemaker/api_router.py。

六、Scale-Out、Tokenize 与弹性专家并行 API

Scale-Out API（默认关闭）

Scale-Out 端点在 vllm serve 下默认不注册，环境变量只接受 0 或 1：

export VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1

两条特例：vllm launch render 与 vllm serve --tokens-only 这两种显式 opt-in 模式会在变量未设置时自行启用所需端点；但若显式把该变量设为 0，这两种模式会被拒绝启动。

Tokens IN ⇄ Tokens OUT：/inference/v1/generate（生成补全）；仅当同时设置 --tokens-only 时提供 /abort_requests（中止进行中的请求）。
Renderer API：/v1/completions/render、/v1/chat/completions/render——渲染 completion/chat 请求，见 renderer.md。
Derenderer API：/v1/chat/completions/derender、/v1/completions/derender——将渲染结果还原，见 derenderer.md。

Tokenize API

/tokenize——文本分词
/detokenize——token 解码
/tokenizer_info——获取完整 tokenizer 信息（含 chat template 与配置）

弹性专家并行（EEP）

/scale_elastic_ep——触发扩缩容操作
/is_scaling_elastic_ep——查询扩缩容是否进行中

（当 supported_tasks 含 generate 时注册，见 routers.py。）

七、开发模式（Server Development Mode）端点

设置 VLLM_SERVER_DEV_MODE=1 将启用一批开发端点，源码启动时会打印 SECURITY WARNING：这些端点严禁在生产环境使用。相关路由在 register_vllm_dev_api_routers 中注册，如 benchmarks 中 sweep/server.py 便依赖该模式下的 _reset_caches。

缓存管理 API

/reset_prefix_cache——重置 prefix cache（可能中断服务）
/reset_mm_cache——重置多模态缓存（可能中断服务）
/reset_encoder_cache——重置 encoder 缓存（可能中断服务）

权重传输 API（RL 训练用）

面向 RLHF/RL 训练的权重更新流程，详细介绍见 training/weight_transfer/README.md：

端点	作用	风险
`/pause`	暂停生成	造成拒绝服务
`/resume`	恢复生成	—
`/is_paused`	查询是否暂停	—
`/abort_requests`	中止所有（或指定 `request_ids` 的）在途请求，不停调度器	—
`/init_weight_transfer_engine`	初始化 RLHF 权重传输引擎	—
`/start_weight_update`	为权重更新准备推理引擎	—
`/update_weights`	更新模型权重	可能改变模型行为
`/finish_weight_update`	完成权重更新	—
`/update_weight_version`	仅切换权重版本、不更新模型权重	—
`/weight_info`	获取最新已提交的权重版本	—
`/get_world_size`	获取分布式 world size	—

其他开发端点

/collective_rpc——在引擎上执行任意 RPC 方法（极其危险）
/server_info——获取详细服务器配置
Sleep Mode API：/sleep（使引擎休眠，造成拒绝服务）、/wake_up（唤醒引擎）、/is_sleeping（查询休眠状态），详见 sleep_mode.md。

八、Chat Template（聊天模板）

要让语言模型支持 chat 协议，vLLM 要求模型的 tokenizer 配置中带有一个 chat template——一个 Jinja2 模板，用来规定角色（role）、消息及聊天专用 token 如何编码进输入。

若模型缺少 chat template（即使经过指令/对话微调也可能没有），可用 --chat-template 显式指定模板文件路径或模板字符串：

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

没有 chat template 时，服务器将无法处理 chat 请求并报错。

vLLM 社区为常见模型维护了一批开箱即用的模板，位于仓库根目录 examples（如 tool_chat_template_deepseekr1.jinja、tool_chat_template_deepseekv3.jinja、tool_chat_template_qwen3coder.jinja、tool_chat_template_llama4_pythonic.jinja 等，文件名与模型/工具风格一一对应，可直接作为 --chat-template 的取值）。

多模态消息与 content 格式检测

OpenAI 规范为多模态 chat API 引入了同时含 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 的 chat template 期望 content 是字符串，但部分较新模型（如 meta-llama/Llama-Guard-3-1B）期望 content 按 OpenAI schema 中的列表格式组织。vLLM 提供 best-effort 的自动检测：启动日志会打印类似 "Detected the chat template content format to be..." 的信息，并在内部把请求转换为检测到的格式。可能取值：

"string"：字符串，例如 "Hello world"
"openai"：OpenAI 风格的字典列表，例如 [{"type": "text", "text": "Hello world!"}]

如果自动检测结果不符合预期，可用 CLI 参数 --chat-template-content-format 强制覆盖使用哪种格式（该参数在 app_state.py 中传递至 chat 与 embedding 各服务实现）。

九、Ray Serve LLM：把 vLLM 引擎做成生产级服务

Ray Serve LLM 提供 vLLM 引擎的可扩展、生产级托管方案，与 vLLM 深度集成，并额外提供自动扩缩容（auto-scaling）、负载均衡（load balancing）与背压控制（back-pressure）能力。关键能力包括：

暴露 OpenAI 兼容的 HTTP API 与 Pythonic API；
无需改代码即可从单 GPU 扩展到多节点集群；
通过 Ray dashboard 与指标提供可观测性和自动扩缩容策略。

仓库中的可直接参考的端到端示例：使用 Ray Serve LLM 部署 DeepSeek R1 大模型的脚本见 examples/ray_serving/ray_serve_deepseek.py。其余可组合编排的分布式示例（弹性专家并行、批量 LLM 推理、多节点服务脚本）位于 examples/ray_serving 目录。

十、总结与选型速查

生产文本生成：优先使用 OpenAI 兼容的 /v1/completions、/v1/chat/completions 与 Responses API，同时注意 chat template 与 generation_config.json 对采样默认值的影响；
Embedding/重排/打分：依据模型类型选择 /v1/embeddings、/v2/embed、/rerank、/classify、/score、/pooling 等 pooling 族端点；
语音模型：/v1/audio/transcriptions、/v1/audio/translations、/v1/realtime；
运维监控：/health、/metrics、/load、/version；离线环境记得加 --enable-offline-docs；
内网环境接口可见性：所有端点均由 routers.py 按 supported_tasks 与环境变量条件注册，接口是“按需暴露”而非“全量开放”，配置前请先确认自己的模型任务类型与所需开关（VLLM_ENABLE_SCALE_OUT_ENDPOINTS、VLLM_SERVER_DEV_MODE 等）。