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 兼容的 Completions、Chat Completions、Responses、Embeddings 和 Audio 路由，具体支持情况取决于所提供的模型类型。通过 AISIX 使用时，Chat Completions 是主要路由；兼容的 Responses 和 Messages 请求可以使用 AISIX 中的 Chat 桥接。请为 Embedding、转录或翻译模型使用单独的别名。

AISIX 标准化的图像、视频和重排序路由不接受 byo 服务提供方值。请参阅服务提供方兼容性。

故障排除

现象	检查项
连接被拒绝或超时	从 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 兼容服务器的可复用配置和自定义定价选项。
模型别名：为别名配置路由、重试行为或成本元数据。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

准备推理服务器​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

端点覆盖范围​

故障排除​

后续步骤​