自定义端点

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

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

前提条件

请先准备以下内容：

一个运行中的 AISIX 网关，Admin API 和代理 API 可用。命令使用快速开始监听地址，如有需要请替换。
网关 config.yaml 中的 Admin Key。
一个可访问的 OpenAI 兼容端点及其提供的模型名称。下面示例使用提供 meta-llama/Llama-3.1-8B-Instruct 的 vLLM。

配置自有端点

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

创建服务提供方密钥

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

请使用服务器要求的端点根地址，例如 vLLM 的 http://host:8000/v1、SGLang 的 http://host:30000/v1，或 Ollama 的 http://host:11434/v1。下面示例使用 http://10.0.0.5:8000/v1。

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

# 请替换为实际值
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"

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" \
  --data-binary @- <<EOF
  {
    "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
    }
  }
EOF

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

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

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

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

添加价格元数据

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

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

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

两个值的单位都是每 1,000 个 Token 的美元价格。input_per_1k 适用于提示词 Token，output_per_1k 适用于补全 Token。存在 cost 块时，这两个字段都必填。

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

创建调用方 API Key

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

# 请替换为实际值
export AISIX_API_KEY="YOUR_CALLER_API_KEY"

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" \
  --data-binary @- <<EOF
  {
    "key_hash": "${CALLER_KEY_HASH}",
    "allowed_models": ["llama-3-private"]
  }
EOF

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

验证服务提供方连接

使用已创建的调用方 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、服务端提供的模型名称以及端点可达性。

支持其它端点

私有端点必须为应用通过 AISIX 调用的每个 OpenAI 兼容路由提供实现。当端点提供兼容的 Embeddings 路由时，AISIX 可以转发 Embeddings 请求。其他路由还需要满足额外的服务提供方要求，详见服务提供方兼容性。

对于请求或响应格式的细微差异，请在服务提供方密钥上配置服务提供方专用覆盖项。

下一步

你现在已将一个私有 OpenAI 兼容端点连接到 AISIX。接下来可继续阅读：

模型别名：为别名配置路由、健康检查行为或额外的成本元数据。
预算：使用价格元数据实施托管预算控制。
服务提供方兼容性：查看受支持的代理端点和服务提供方专用边界。

前提条件​

配置自有端点​

创建服务提供方密钥​

创建模型​

添加价格元数据​

创建调用方 API Key​

验证服务提供方连接​

支持其它端点​

下一步​