版本：1.4.0

自带端点

私有模型服务器（例如 vLLM、SGLang 和 Ollama）可以从你控制的基础设施公开 OpenAI 兼容 API。AISIX 可以将模型流量路由到这些服务器，或路由到位于自有模型之前的私有代理。

如果应用需要继续通过 OpenAI 兼容 API 调用 AISIX，同时由 AISIX 将流量转发到私有或隔离网络中的模型服务，请使用 BYO 端点。该端点必须接受 OpenAI 兼容的 Chat Completions 请求。

如需使用已按各引擎文档中的 API 格式验证过的 AISIX Cloud 步骤，请参阅专门的 Ollama 或 vLLM 指南。对于 SGLang 等其他私有 OpenAI 兼容服务器，请使用本页的通用 AISIX Cloud 资源格式。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
可访问的 OpenAI 兼容端点及其提供的模型名称。示例使用提供 meta-llama/Llama-3.1-8B-Instruct 的 vLLM。
curl 和 jq。

使用 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"

使用 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-private",
    "provider": "byo",
    "adapter": "openai",
    "api_key": "not-used-by-vllm",
    "api_base": "http://10.0.0.5:8000/v1",
    "allowed_environments": ["'"$ENV_ID"'"]
  }' | jq -r '.provider_key.id')

AISIX Cloud Admin API 使用 provider: "byo"，以便用量数据区分自定义端点和目录服务提供方。对于开源 AISIX 网关，resources.yaml 中的 provider 可以是 vllm 等描述性标签。两种方式都要求 api_key 非空；仅当端点忽略身份验证时才使用占位值。

创建模型：

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": "llama-3-private",
    "model_name": "meta-llama/Llama-3.1-8B-Instruct",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

创建可访问该模型的调用方 API Key：

BYO_CALLER_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": "byo-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

在模型定价中配置 BYO 定价。AISIX Cloud 模型请求不接受开源网关使用的 cost 配置块。

使用开源 AISIX 网关配置

许多私有运行的推理服务器不需要 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。

选择应用将发送给 AISIX 的调用方 API Key：

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

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源。

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: vllm-private
    provider: vllm
    adapter: openai
    api_key: not-used-by-vllm
    api_base: http://10.0.0.5:8000/v1

models:
  - display_name: llama-3-private
    provider: vllm
    model_name: meta-llama/Llama-3.1-8B-Instruct
    provider_key: vllm-private
    cost:
      input_per_1k: 0.0
      output_per_1k: 0.0

api_keys:
  - display_name: byo-caller
    key_env: BYO_CALLER_KEY
    allowed_models: ["llama-3-private"]

provider 是适合当前环境的任意简短标签。
adapter 选择 OpenAI 兼容的上游格式。
api_key 是无需身份验证的端点所使用的非空占位值。对于需要身份验证的端点，请从环境变量引用真实凭证（例如 api_key: ${VLLM_API_KEY}），不要在文件中写入明文 Secret。
api_base 是端点根地址。如果 /v1 是服务器路由的一部分，请将其包含在内。
在模型条目中，display_name 是调用方在 model 中发送的别名。
model_name 是端点预期的上游 ID。对于 vLLM 和 SGLang，请使用所提供的模型名称；对于 Ollama，请使用本地模型标签，例如 llama3.1:8b。
provider_key 通过服务提供方密钥的 display_name 将模型别名关联到服务提供方密钥。
cost 为可选字段，用于提供下文所述的定价元数据。

调用方 Key 的 allowed_models 值必须与模型别名匹配。网关会从 BYO_CALLER_KEY 读取明文调用方 Key，并且只存储其哈希。服务提供方密钥 Secret 遵循服务提供方密钥中说明的凭证处理方式。

添加价格元数据

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

将模型条目中的零成本占位值替换为实际的每 1K 个 Token 费率：

resources.yaml（模型成本）
    cost:
      input_per_1k: 0.10
      output_per_1k: 0.30

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

开源网关会将这些元数据用于用量事件和 least_cost 路由，但不会据此执行预算限制。AISIX Cloud 不会使用 resources.yaml 中的 cost 配置块；请通过模型定价单独配置 BYO 定价。资源文件字段请参阅模型别名。

验证并加载配置

如果 AISIX 安装在本地，请在加载前验证完整文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供所引用的环境变量，再启动网关。如果这些变量已经可供本地安装的网关进程使用，请向该进程发送 SIGHUP 以重新加载文件：

kill -HUP "$(pgrep -x aisix)"

如果新增了变量或更改了变量值，请改用更新后的进程环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

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

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${BYO_CALLER_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 可以转发 Embedding 请求。其他路由有额外的服务提供方要求；请参阅服务提供方兼容性。

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

后续步骤

你已将私有 OpenAI 兼容端点连接到 AISIX。接下来可阅读以下指南：

模型别名：为别名配置路由、重试行为或成本元数据。
预算：使用定价元数据执行 AISIX Cloud 预算限制。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

使用开源 AISIX 网关配置​

添加价格元数据​

验证并加载配置​

验证服务提供方连接​

支持其他端点​

后续步骤​