跳到主要内容

自定义端点

本指南将说明如何把 AISIX AI 网关连接到私有 OpenAI 兼容端点，例如 vLLM 或 SGLang 推理服务器、Ollama 主机，或位于自有模型前的自托管代理。

当应用需要继续使用 OpenAI 兼容 API 调用 AISIX，而 AISIX 需要将流量转发到私有或隔离网络中的模型服务时，可以使用自定义端点。该端点必须接受 OpenAI 兼容 chat completions 请求。

准备工作​

请先准备以下内容：

  • 一个 Admin 位于 :3001、代理位于 :3000 的网关。
  • 网关 config.yaml 中的 Admin Key。
  • 一个可访问的 OpenAI 兼容端点。下面示例假设 vLLM 位于 http://10.0.0.5:8000/v1，并提供 meta-llama/Llama-3.1-8B-Instruct。
  • 服务器期望的端点 base URL，例如 vLLM 的 http://host:8000/v1、SGLang 的 http://host:30000/v1，或 Ollama 的 http://host:11434/v1。

配置自有端点​

为私有端点创建服务提供方密钥、模型别名和调用方 API Key。

创建服务提供方密钥​

许多自托管推理服务器不需要 API Key。对于无需认证的端点，请在服务提供方密钥中使用非空占位值；AISIX 会把它作为 bearer token 发送，你的服务器可以忽略它。

为私有 OpenAI 兼容端点创建服务提供方密钥：

export AISIX_ADMIN_KEY="admin-local-only-change-me"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "vllm-private",
    "provider": "vllm",
    "adapter": "openai",
    "secret": "not-used-by-vllm",
    "api_base": "http://10.0.0.5:8000/v1"
  }'

服务提供方密钥 secret 的处理方式遵循服务提供方凭证中说明的凭证处理行为。

❶ provider 可以是对当前环境有意义的任意短标签。

❷ adapter 选择 OpenAI 兼容上游格式。

❸ 对于无需认证的端点，secret 是一个非空占位值。

❹ api_base 是端点 base URL。当 /v1 是服务器路由的一部分时，需要包含它。

保存返回的服务提供方密钥 ID，后续创建模型资源时使用。

创建模型​

将面向调用方的别名映射到该端点提供的上游模型 ID：

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "llama-3-private",
    "provider": "vllm",
    "model_name": "meta-llama/Llama-3.1-8B-Instruct",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'",
    "cost": {
      "input_per_1k": 0.0,
      "output_per_1k": 0.0
    }
  }'

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是端点期望的上游 ID。

❸ provider_key_id 将模型别名关联到你创建的服务提供方密钥。

❹ cost 是可选字段。对于 vLLM 和 SGLang，请使用对外提供的模型名称。对于 Ollama，请使用本地模型标签，例如 llama3.1:8b。

创建调用方 API Key​

选择应用发送给 AISIX 的明文调用方 API Key，然后为 Admin 资源计算哈希：

export AISIX_API_KEY="sk-byo-caller"

CALLER_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

创建可访问私有模型别名的 API Key 资源：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["llama-3-private"]
  }'

❶ allowed_models 必须与已创建的模型别名匹配。

价格元数据​

目录服务提供方会携带来自 models.dev 目录的价格。自定义端点不在该目录中，因此如果需要 token 成本核算，请自行设置价格元数据。

在模型上附加 cost 块，以启用按 token 的预算核算：

{
  "cost": {
    "input_per_1k": 0.10,
    "output_per_1k": 0.30
  }
}

两个值的单位都是每 1,000 个 token 的美元价格。input_per_1k 适用于 prompt token，output_per_1k 适用于 completion token。存在 cost 块时，这两个字段都必填。

自托管部署会存储这些元数据，但不会在请求时据此执行预算检查。建议在自定义端点模型上包含该信息，以便托管部署或自有用量事件消费者能够获取按 token 计价信息。参见模型别名和预算。

验证上游​

使用已创建的调用方 API Key 和模型别名，通过代理发送请求：

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3-private",
    "messages": [
      {"role": "user", "content": "Say hello from the private model."}
    ]
  }'

响应应为 OpenAI 兼容 chat completions 响应，并回显面向调用方的别名。请在端点访问日志中查看来自 AISIX 的 POST /v1/chat/completions 条目。

如果 AISIX 返回上游路由或连接错误，请检查 api_base、服务端提供的模型名称以及端点可达性。

下一步​

你已经将私有 OpenAI 兼容端点连接到 AISIX。对于其它私有 OpenAI 兼容服务器，可以按相同模式替换 provider 标签、端点 base URL、模型 ID 和可选价格元数据。