跳到主要内容
版本：1.6.0

兼容 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_URL"
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 会保持为请求中面向调用方的别名。

消息角色​

每条消息的 role 必须是小写的 system、developer、user、assistant 或 tool。其他取值，包括大小写不同的 Developer，都会在请求到达服务提供方之前以 400 invalid_request_error 拒绝。

developer 消息承载应用指令。OpenAI 的推理模型用它代替 system 消息，编码 Agent 等客户端会向这些模型发送它。只有 OpenAI API 会以这个角色收到该消息；其他上游都会在各自存放系统指令的位置收到它：

上游上游收到的内容
provider 为 openai 的服务提供方密钥原样的 developer 消息，适用于所有模型，与密钥的 api_base 无关。
使用 openai 适配器的其他服务提供方（例如 DeepSeek 或 Google AI Studio），以及 Azure OpenAI位置不变的 system 消息。
Vertex AI 上兼容 OpenAI 的模型和合作伙伴模型（例如 Llama 或 Mistral）位置不变的 system 消息。
Anthropic，以及 Vertex AI 上的 Claude顶层 system 字段，与开头的 system 消息合并。developer 消息无论出现在会话的哪个位置，都会被移到这里，而不只是开头的那些。
Vertex AI 上的 Gemini顶层 systemInstruction。
Amazon Bedrock系统指令：Converse 的 system 块；非流式 Claude 请求使用 Anthropic 请求体，则放入其顶层 system 字段。

安全护栏对 developer 消息的处理与 system 消息相同。参见选择输入消息窗口。

发现可用模型​

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 上游。