vLLM
vLLM 是一个开源推理服务器，可为你运行的模型提供 OpenAI 和 Anthropic 兼容 API。vLLM 继续提供推理服务，AISIX 则为其添加调用方身份认证、稳定的模型别名、用量报告和流量控制。
准备工作
开始前，请准备以下内容：
- 一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
- 一 台已安装 vLLM 0.10.0 或更高版本，并且拥有足够算力和存储空间来运行所选模型的主机。该版本开始提供本指南使用的原生 Responses 路由。
- AISIX 网关与 vLLM 之间网络连通。
curl和jq。
准备推理服务器
启动官方示例模型，并启用 API Key 检查：
vllm serve NousResearch/Meta-Llama-3-8B-Instruct \
--dtype auto \
--api-key token-abc123
导出上游密钥，以及可从 AISIX 网关访问的 API 根地址：
export VLLM_API_KEY="token-abc123"
export VLLM_API_BASE="http://vllm.internal:8000/v1"
请将 vllm.internal 替换为可解析的主机名或服务名称。如果使用 Docker Desktop 且 vLLM 位于主机上，通常可使用 http://host.docker.internal:8000/v1。如果两个服务共享 Docker 或 Kubernetes 网络，请使用 vLLM 服务的 DNS 名称。
vLLM 文档说明，--api-key 保护的是其 OpenAI 兼容 API 路由，而不是服务器可能公开的所有端点。请将 vLLM 服务保留在私有网络中；如果管理或诊断路由需要保护，请应用网络策略或带身份验证的反向代理。
使用 AISIX Cloud 配置
导出 AISIX Cloud 连接信息：
# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
vLLM 是私有端点，而不是 AISIX 目录服务提供方。请使用 byo 服务提供方值进行配置，并显式选择 openai 适配器。
创建服务提供方密钥
PROVIDER_KEY_ID=$(
curl -sS -X POST "$AISIX_CP/provider_keys" \
-H "Authorization: Bearer $AISIX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "vllm-local",
"provider": "byo",
"adapter": "openai",
"api_key": "'"${VLLM_API_KEY}"'",
"api_base": "'"${VLLM_API_BASE}"'",
"apis": {
"responses": {}
},
"allowed_environments": ["'"${ENV_ID}"'"]
}' | jq -er '.provider_key.id'
)
echo "$PROVIDER_KEY_ID"
BYO 密钥要求提供 provider: "byo"、非空的 api_key 和 api_base。本指南显式设置 adapter: "openai"；省略时，AISIX 会默认让 BYO 密钥使用 OpenAI 兼容适配器。AISIX 将 VLLM_API_KEY 作为 Authorization: Bearer <key> 发送，与传给 vllm serve 的密钥一致。
apis.responses 声明会把 Responses 请求发送至 vLLM 原生端点，而不是通过 Chat Completions 转换。
如果有意在不设置 --api-key 的情况下运行 vLLM，AISIX 的服务提供方密钥 schema 仍要求提供非空占位值。只要流量可能来自严格受控的本地网络之外，就应优先使用需要身份验证的 vLLM 端点。
创建模型
使用 vLLM 提供的模型名称：
MODEL_ID=$(
curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
-H "Authorization: Bearer $AISIX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "vllm-llama-prod",
"model_name": "NousResearch/Meta-Llama-3-8B-Instruct",
"provider_key_id": "'"${PROVIDER_KEY_ID}"'"
}' | jq -er '.model.id'
)
echo "$MODEL_ID"
model_name 必须与 vLLM 从 /v1/models 公开的名称匹配。如果启动 vLLM 时覆盖了所提供的模型名称，请使用该覆盖值，而不是模型仓库路径。
创建调用方 API Key
AISIX_API_KEY=$(
curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
-H "Authorization: Bearer $AISIX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "vllm-caller",
"allowed_models": ["'"${MODEL_ID}"'"]
}' | jq -er '.plaintext'
)
echo "$AISIX_API_KEY"
使用开源 AISIX 网关配置
导出上游凭证，并选择应用将发送给网关的调用方 API Key：
export VLLM_API_KEY="token-abc123"
export VLLM_API_BASE="http://vllm.internal:8000/v1"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"
对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：
_format_version: "1"
provider_keys:
- display_name: "vllm-local"
provider: "vllm"
adapter: "openai"
api_key: ${VLLM_API_KEY}
api_base: "${VLLM_API_BASE}"
apis:
responses: {}
models:
- display_name: "vllm-llama-prod"
provider: "vllm"
model_name: "NousResearch/Meta-Llama-3-8B-Instruct"
provider_key: "vllm-local"
api_keys:
- display_name: "vllm-caller"
key_env: CALLER_API_KEY
allowed_models:
- "vllm-llama-prod"
如果 AISIX 安装在本地，请在加载前验证文件：
aisix validate --resources resources.yaml
验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。
如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：
export AISIX_API_KEY="$CALLER_API_KEY"
验证服务提供方连接
导出 AISIX 网关 Origin：
# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
通过 AISIX 代理发送 Responses 请求：
curl -sS -X POST "$AISIX_PROXY/v1/responses" \
-H "Authorization: Bearer $AISIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "vllm-llama-prod",
"input": "Say hello from vLLM."
}'
AISIX 会使用已配置的 vLLM Bearer Key，将所提供的模型名称发送到 vLLM 原生 POST /v1/responses 端点，然后在响应中恢复 AISIX 别名。
通过透传使用原生 Messages
当前 vLLM 版本提供 Anthropic 兼容的 /v1/messages 和 /v1/messages/count_tokens 路由。本指南配置的已认证服务器要求 Bearer 身份认证，而 AISIX 会在声明的原生 Messages 协议面上发送 x-api-key。不要向此服务提供方密钥添加 apis.messages。
配置一条透传路由，然后调用 /passthrough/byo/messages 或 /passthrough/vllm/messages 访问原生 Messages。将 /messages/count_tokens 追加到同一路由前缀即可访问 Count Tokens。透传会保留配置的 Bearer 凭证以及 vLLM 请求和响应协议。
端点覆盖范围
当前 vLLM 在线服务器提供 OpenAI 兼容的生成、Responses、Embedding 和语音转文本 API，以及 rerank 和 score 等池化模型 API。具体可用性仍取决于 vLLM 服务器启动时选择的模型和任务。
| 路由 | 使用本指南 vLLM 别名时的行为 |
|---|---|
/v1/chat/completions | 支持使用带 Chat 模板的文本生成模型。 |
/v1/completions | 支持文本生成模型。vLLM 不支持 OpenAI suffix 参数。 |
/v1/responses | 由于本指南声明了 apis.responses，请求会发送至 vLLM 原生 Responses API。对于低于 0.10.0 的服务器，请省略此声明，让 AISIX 使用 Responses 桥接。 |
/v1/messages | 通过 AISIX 转换到 Chat Completions 提供支持，而不是使用原生 Anthropic 兼容 vLLM 路由。需要 vLLM 原生契约时，请使用 /passthrough/byo/messages 或 /passthrough/vllm/messages。 |
/v1/messages/count_tokens | 配置的服务提供方密钥未声明 Messages 协议面，因此 AISIX 会拒绝此规范化路由。当前 vLLM 版本实现了 Count Tokens；请在透传路由前缀后追加 /messages/count_tokens。 |
/v1/embeddings | 当别名指向运行 Embedding 模型的 vLLM 服务器时受支持。 |
/v1/audio/transcriptions、/v1/audio/translations | 当别名指向运 行兼容自动语音识别模型且安装了 vLLM 音频依赖的服务器时受支持。翻译支持取决于模型。 |
/v1/audio/speech | 不支持，因为 vLLM 未提供 OpenAI 兼容的文本转语音路由。 |
/v1/realtime | 当 vLLM 提供支持 Realtime 的自动语音识别模型且安装了音频依赖时受支持。AISIX 会通过标准化 Realtime 路由中继 OpenAI 形态的 vLLM WebSocket 协议。vLLM 当前支持流式语音转文本，而不是部分 OpenAI Realtime 模型提供的双向语音生成。 |
/v1/rerank | 拒绝，因为 byo 和 vllm 都不在标准化路由的服务提供方允许列表中。运行评分模型的 vLLM 服务器会提供 /v1/rerank；请通过 /passthrough/byo/rerank 或 /passthrough/vllm/rerank 访问。 |
/v1/chat/completions/batch、/v1/score | AISIX 没有对应的标准化路由。请在你的透传路由前缀后追加 /chat/completions/batch 或 /score。 |
/v1/models | 返回调用方可访问的 AISIX 别名，而不是 vLLM 提供的模型。请通过 /passthrough/byo/models 或 /passthrough/vllm/models 获取 vLLM 原生列表。 |
/v1/images/generations、/v1/videos | 拒绝，因为这两个服务提供方值均不在对应标准化路由允许列表中。vLLM 也未提供匹配的生成 API。 |
每个生成、Embedding 或语音转文本模型都应使用单独的模型别名，通常还应使用单独的服务提供方密钥和服务进程。通过透传路由访问 Rerank 模型时也适用同一要求。
上述 /passthrough/byo 和 /passthrough/vllm 前缀假定一条透传路由认领该前缀，target_url 设为 vLLM 服务器根地址；在调用方 Key 的 allowed_routes 上授予路由名称。透传路由会原样中继请求体，因此应使用 vLLM 公开的模型标识符，而不是 AISIX 别名。它会增量中继包括 SSE 在内的上游响应。哪些请求形态会记录 Token 用量，参见信封识别与用量。一条路由绑定一个固定 target_url，因此请为每台 vLLM 服务器各建一条路由，而不是依赖模型访问权限挑选端点。
vLLM 还提供 /pooling 和 /classify 等 Root 级 API。它们位于本指南配置的 /v1 API Base 之外，且没有标准化 AISIX 路由。要通过透传路由访问这些 API，需要 target_url 指向 vLLM 服务器 Root；不能假定以上述 /v1 Base 为目标的路由可以到达它们。
故障排除
| 现象 | 检查项 |
|---|---|
| 连接被拒绝或超时 | 从 AISIX 网关容器中解析并调用 VLLM_API_BASE。 |
上游返回 401 | 为 --api-key 和 AISIX 服务提供方密钥的 api_key 使用相同的值。 |
| 找不到模型 | 将 model_name 与 GET $VLLM_API_BASE/models 的结果进行比较。 |
| Chat 模板错误 | 提供具有有效 Chat 模板的 Chat 模型，或在 vLLM 中配置模板。 |
创建服务提供方密钥时返回 400 | 请包含 provider: "byo"、adapter: "openai"、非空的 api_key 和 api_base。 |
后续步骤
你已将 AISIX 连接到 vLLM，并验证了模型别名。接下来可阅读以下指南：