vLLM

vLLM 是一个开源推理服务器，可为你运行的模型提供 OpenAI 兼容 API。vLLM 继续提供推理服务，AISIX 则为其添加调用方身份验证、稳定的模型别名、用量报告和流量控制。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 一台已安装 vLLM，并且拥有足够算力和存储空间来运行所选模型的主机。
• 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，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 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}"'",
      "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 的密钥一致。

如果有意在不设置 --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"

为该服务提供方创建完整的声明式资源文件：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "vllm-local"
    provider: "vllm"
    adapter: "openai"
    api_key: ${VLLM_API_KEY}
    api_base: "${VLLM_API_BASE}"

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：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vllm-llama-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from vLLM."
      }
    ]
  }'

AISIX 会使用已配置的 vLLM Bearer Key，将所提供的模型名称发送到 POST /v1/chat/completions。

端点覆盖范围

当前 vLLM 在线服务器提供 OpenAI 兼容的生成、Responses、Embedding 和语音转文本 API，还提供 Anthropic 兼容的 Messages 与 Token 计数路由，以及 rerank 和 score 等池化模型 API。具体可用性仍取决于 vLLM 服务器启动时选择的模型和任务。

路由	使用本指南 vLLM 别名时的行为
/v1/chat/completions	支持使用带 Chat 模板的文本生成模型。
/v1/completions	支持文本生成模型。vLLM 不支持 OpenAI suffix 参数。
/v1/responses	通过 AISIX Responses 桥接提供支持，而不是原生 vLLM Responses API。没有对应 Chat Completions 语义的字段会被忽略。需要原生 Responses 语义时，请在 AISIX Cloud 中使用 /passthrough/byo/responses，或在开源资源文件中使用 /passthrough/vllm/responses。
/v1/messages	通过 AISIX 转换到 Chat Completions 提供支持，而不是使用原生 Anthropic 兼容 vLLM 路由。需要 vLLM 原生契约时，请在 AISIX Cloud 中使用 /passthrough/byo/messages，或在开源资源文件中使用 /passthrough/vllm/messages。
/v1/messages/count_tokens	拒绝，因为标准化路由要求使用 Anthropic 支持的模型。当前 vLLM 版本已原生实现此路由；请在相应服务提供方透传前缀后追加 /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 模型时也适用同一要求。

透传会原样发送请求体，因此应使用 vLLM 公开的模型标识符，而不是 AISIX 别名。它还会缓冲上游响应（包括 SSE），并记录零 Token 和零 Token 成本。在 AISIX Cloud 中，/passthrough/byo/* 可以选择调用方可访问的任何 byo 服务提供方模型；如果调用方可访问多个 BYO 端点，请将调用方 API Key 限定到目标 vLLM 别名。请参阅服务提供方透传。

vLLM 还提供 /pooling 和 /classify 等 Root 级 API。它们位于本指南配置的 /v1 API Base 之外，且没有标准化 AISIX 路由。要访问这些 API，需要服务提供方密钥的 Base 指向 vLLM 服务器 Root；不能假定上述基于 /v1 的密钥可以路由这些 API。

故障排除

现象	检查项
连接被拒绝或超时	从 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，并验证了模型别名。接下来可阅读以下指南：

• 自带端点：查看适用于私有 OpenAI 兼容服务器的可复用配置和自定义定价选项。
• 模型别名：为别名配置路由、重试行为或成本元数据。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。