跳到主要内容

兼容 OpenAI 的 API

兼容 OpenAI 的代理路由适合已经发送 OpenAI 风格请求，并希望由 AISIX 管理网关侧认证、模型别名、路由和策略的应用。

客户端保留受支持的 OpenAI 兼容请求和响应格式。AISIX 成为客户端调用的端点，而已配置模型别名背后的上游服务提供方可以变更。

本指南说明代理 API 行为。可运行的 SDK 配置请参见 OpenAI SDK 快速上手。

客户端发送的内容​

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

  • base URL 指向 AISIX 代理 API，例如 http://127.0.0.1:3000/v1。
  • API Key 是 AISIX 调用方 API Key。
  • model 值是 AISIX 模型别名，例如 gpt-4o-prod。

请求体保持 OpenAI 兼容格式，包括 messages、tools 和流式选项。服务提供方凭证、上游模型 ID、路由策略、限流、安全护栏和其它网关策略都留在 AISIX 中。

使用标准 bearer token 格式发送调用方 API Key：

Authorization: Bearer YOUR_CALLER_API_KEY

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

Chat Completions 请求​

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

通过 AISIX 发送 Chat Completions 请求：

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {"role": "user", "content": "Hello from AISIX."}
    ]
  }'

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

发现可用模型​

GET /v1/models 会返回该调用方 API Key 可见的单目标和集成模型别名。通配 API Key 可以看到所有单目标和集成模型；受限 API Key 只能看到显式允许的模型。

多目标别名不会列出，即使调用方可以直接使用它们。

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

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

处理错误​

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

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

下一步​

你已经了解兼容 OpenAI 的客户端如何调用 AISIX。请继续阅读流式响应、工具调用，或在应用需要保持 OpenAI 兼容客户端形态但由 AISIX 调用 Anthropic 上游时，阅读 OpenAI 客户端接入 Anthropic 上游。