跳到主要内容

兼容 OpenAI 的 Chat Completions

采用 OpenAI Chat Completions 格式的应用可以将同样受支持的请求形态发送到 AISIX 网关的 POST /v1/chat/completions。网关会认证调用方、解析模型别名、应用网关策略，并通过所选服务提供方适配器分发请求。

这种兼容性面向客户端：上游既可以是 OpenAI，也可以是其他受支持的服务提供方。网关会返回受支持的 OpenAI 兼容响应形态，而适配器负责服务提供方协议转换。

本指南说明 Chat Completions 的代理行为。可运行的 SDK 配置请参见 OpenAI SDK。

客户端发送的内容​

客户端会发送三个面向网关的值：

  • base URL 是 AISIX 代理 API 根路径，即网关 Origin 后跟 /v1。
  • API Key 是 AISIX 调用方 API Key。
  • model 值是 AISIX 模型别名，例如 gpt-4o-prod。

请求体保持 OpenAI 兼容格式，包括 messages、tools、流式选项，以及受支持的多模态字段。服务提供方凭证、上游模型 ID、路由策略、限流、安全护栏和其它网关策略都留在 AISIX 中。有关聊天消息中的音频，请参阅使用 Chat Completions 输入和输出音频。

使用标准 Bearer Token 格式发送调用方 API Key：

Authorization: Bearer YOUR_CALLER_API_KEY

为兼容性，AISIX 也接受 x-api-key: YOUR_CALLER_API_KEY。当 OpenAI 兼容客户端支持时，建议使用 Bearer Token 格式。

导出以下示例使用的网关连接和请求值：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

发送 Chat Completions 请求​

对于兼容 OpenAI 的聊天客户端，请将 POST /v1/chat/completions 作为默认路由。

通过 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": "'"${AISIX_MODEL}"'",
    "messages": [
      {"role": "user", "content": "Hello from AISIX."}
    ]
  }'

成功响应使用兼容 OpenAI 的 Chat Completions 格式，响应中的 model 会保持为请求中面向调用方的别名。

发现可用模型​

GET /v1/models 会返回调用方 API Key 可见的每个具体模型别名，包括直接、路由、语义和合议别名。通配符别名是模式而非具体模型名称，因此不会列出。允许所有模型的 API Key 可以看到每个具体别名；受限 API Key 只能看到其允许列表许可的别名。

列出该调用方 API Key 可见的模型别名：

curl -sS "${AISIX_PROXY}/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

处理错误​

兼容 OpenAI 的 Chat Completions 路由会以 OpenAI 风格信封返回错误。需要区分调用方认证、模型访问、策略拦截、限流和上游失败时，请优先使用错误类型，再看状态码。

完整错误和响应头参考请参见响应头与错误码。

下一步​

你已经了解兼容 OpenAI 的客户端如何通过 Chat Completions 调用 AISIX。请继续阅读使用 Chat Completions 输入和输出音频、流式响应和工具调用。

如果应用需要保持 OpenAI 兼容客户端形态，但由 AISIX 调用 Anthropic 上游，请阅读 OpenAI 客户端接入 Anthropic 上游。