其他 OpenAI 兼容服务提供方

许多公开模型服务提供方都提供 OpenAI 兼容 API。当服务提供方接受通过 Bearer Token 认证的 OpenAI Chat Completions 请求并已列入 AISIX 服务提供方目录时，AISIX Cloud 可以连接到它。开源 AISIX 网关可在操作人员选择的服务提供方标签下使用任何具有相同协议和认证结构的可访问端点。

如果某个服务提供方在服务提供方上游中已有专用配置，请按照对应页面操作。以下配置是适用于其他公开服务提供方的参数化模板；AISIX Cloud 路径假定该服务提供方已列入其目录。

对于私有或客户自行运营的服务器，请使用专用的 Ollama、vLLM 或自定义端点指南。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
OpenAI 兼容服务提供方的 API Key。对于 AISIX Cloud，该服务提供方必须列入 AISIX 服务提供方目录；开源资源工作流不使用该目录进行准入。
curl 和 jq。

选择服务提供方值

对于 AISIX Cloud，请选择 AISIX 服务提供方目录中显示的准确 ID。对于开源资源文件，请选择稳定的服务提供方标签，例如服务提供方的小写名称。然后从服务提供方官方 API 参考中复制 API 根地址和模型 ID：

export PROVIDER_ID="YOUR_PROVIDER_ID"
export PROVIDER_API_KEY="YOUR_PROVIDER_API_KEY"
export PROVIDER_API_BASE="https://api.provider.example/v1"
export UPSTREAM_MODEL_ID="publisher/model-id"
export MODEL_ALIAS="provider-model-prod"

以上地址和 ID 均为虚构占位符。运行配置前，请替换所有值。

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

为由该服务提供方支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

AISIX 通过 openai 适配器连接，并使用服务提供方的 API 根地址作为 api_base。请为服务提供方密钥设置说明性标签，以便运维人员之后识别上游。

创建服务提供方密钥

PROVIDER_KEY_RESPONSE=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "display_name": "community-provider-prod",
  "provider": "${PROVIDER_ID}",
  "api_key": "${PROVIDER_API_KEY}",
  "api_base": "${PROVIDER_API_BASE}",
  "allowed_environments": ["${ENV_ID}"]
}
EOF
)

PROVIDER_KEY_ID=$(printf '%s' "$PROVIDER_KEY_RESPONSE" | jq -er '.provider_key.id')
echo "$PROVIDER_KEY_ID"

provider 必须与 AISIX 目录中的 ID 完全一致。AISIX Cloud Admin API 会为社区目录服务提供方派生 openai 适配器和 Bearer 认证。不要发送 adapter 字段；仅当 provider 为 byo 时才接受该字段。

没有专用配置页面的服务提供方是从已同步的公开目录接入，而不是来自网关内置服务提供方列表。如果创建操作返回提及目录的 400 INVALID_REQUEST，表示控制平面的当前目录中没有该服务提供方。联网部署会在启动时以及每 24 小时同步；打包的 On-Premises 部署默认使用内置快照，不会刷新。请在在线同步后重试、查看 On-Premises 定价目录设置，或改用自定义端点配置上游。

AISIX 会将端点路径追加到 api_base。如果官方端点要求 /v1、/openai 或 /openai/v1 等服务提供方专属前缀，请将其包含在内。显式设置根地址还可避免依赖最近一次目录同步所缓存的 API 基础地址。

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

创建模型

将面向调用方的别名映射到服务提供方的准确模型 ID：

MODEL_RESPONSE=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- <<EOF
{
  "display_name": "${MODEL_ALIAS}",
  "model_name": "${UPSTREAM_MODEL_ID}",
  "provider_key_id": "${PROVIDER_KEY_ID}"
}
EOF
)

MODEL_ID=$(printf '%s' "$MODEL_RESPONSE" | jq -er '.model.id')
echo "$MODEL_ID"

display_name 是调用方在 model 中发送的别名。model_name 会原样发送到上游，因此请保留发布方命名空间、大小写、标点和版本后缀。

如需为预算核算或用量报告配置成本元数据，请参阅模型别名。

创建调用方 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": "community-provider-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

明文仅在创建调用方密钥时返回。请妥善保存。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export PROVIDER_ID="YOUR_PROVIDER_ID"
export PROVIDER_API_BASE="YOUR_PROVIDER_API_BASE"
export UPSTREAM_MODEL_ID="YOUR_UPSTREAM_MODEL_ID"
export MODEL_ALIAS="YOUR_MODEL_ALIAS"
export PROVIDER_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

开源网关会验证服务提供方标签的格式，但不要求它出现在 AISIX Cloud 目录中。请在服务提供方密钥和模型上使用同一标签。该标签还会在遥测数据和 /passthrough/example-provider/* 等透传路径中标识上游。

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "community-provider-prod"
    provider: "${PROVIDER_ID}"
    adapter: "openai"
    api_key: ${PROVIDER_API_KEY}
    api_base: "${PROVIDER_API_BASE}"

models:
  - display_name: "${MODEL_ALIAS}"
    provider: "${PROVIDER_ID}"
    model_name: "${UPSTREAM_MODEL_ID}"
    provider_key: "community-provider-prod"

api_keys:
  - display_name: "community-provider-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "${MODEL_ALIAS}"

如果 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" \
  --data-binary @- <<EOF
{
  "model": "${MODEL_ALIAS}",
  "messages": [
    {
      "role": "user",
      "content": "Say hello through the configured provider."
    }
  ]
}
EOF

响应应与 OpenAI 兼容，并包含面向调用方的别名。如果服务提供方提供请求日志或用量页面，请用其确认请求已到达预期的上游账号和模型。

如果网关返回上游认证错误，请检查服务提供方密钥的 api_key。如果返回上游路由错误，请检查 api_base 和 UPSTREAM_MODEL_ID。

支持服务提供方专属行为

服务提供方必须接受 OpenAI Chat Completions 请求。使用不同请求格式的服务提供方需要原生适配器协议族或兼容端点。

openai 适配器不会让每个规范化 AISIX 端点对所有服务提供方标签都可用：

/v1/completions、/v1/embeddings、/v1/audio/*、/v1/files、/v1/batches 和 /v1/fine_tuning/jobs 可通过此适配器分派，但只有上游实现对应 OpenAI 路由和字段时才可用。
对社区服务提供方标签，/v1/responses 会通过 Chat 使用 Responses 桥接。/v1/messages 同样会通过 Chat 转换请求和响应，而不是使用服务提供方原生 Messages 路由。
/v1/images/generations、/v1/rerank 和 /v1/videos 实施服务提供方允许列表。即使上游提供同名路由，也可能拒绝社区服务提供方标签。

应用需要服务提供方原生路由或协议时，请使用服务提供方透传。透传不会重写模型别名，且流式传输和用量核算行为不同，因此采用前请查看其限制。规范化路由矩阵请参阅服务提供方兼容性。

AISIX 会保留 reasoning_content，并将 reasoning 标准化到该规范字段。如果服务提供方从不同的 delta 路径流式输出推理内容，请在服务提供方密钥上使用 response.reasoning_field 覆盖项。

后续步骤

模型别名：为别名配置路由、重试行为或成本元数据。
服务提供方兼容性：查看受支持的代理端点和服务提供方专属边界。

准备工作​

选择服务提供方值​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

支持服务提供方专属行为​

后续步骤​