跳到主要内容
版本：1.2.0

OpenAI SDK

本指南会把官方 OpenAI SDK 指向 AISIX AI 网关，而不是直接向上游服务提供方发送请求。这种方式适合已经使用兼容 OpenAI Chat Completions 格式、并希望尽量少改客户端代码的应用。

示例会使用调用方 API Key 向 AISIX 认证，把请求发送到 AISIX 代理 API 根路径，使用 AISIX 模型别名，并接收兼容 OpenAI 的 Chat Completions 响应。只要配置的模型别名和服务提供方支持对应请求格式，上游服务提供方仍可在网关后切换。

准备工作​

  • 应用可以访问的、正在运行的 AISIX 网关。
  • 已配置且接受兼容 OpenAI Chat Completions 请求的模型别名。
  • 允许使用该模型别名的调用方 API Key。
  • 安装带有 npm 的 Node.js 20 LTS 或更新版本。

如果你的组织已部署 AISIX，请向负责管理的团队获取网关 URL、模型别名和调用方 API Key。否则，请按照开源 AISIX 网关快速入门或 AISIX Cloud 快速入门操作；如需使用 Hybrid Cloud，请联系 API7。

配置 SDK​

创建一个小型 Node.js 项目，安装 SDK，并将其指向 AISIX 代理 API 根路径。

安装 SDK​

创建一个小型演示项目：

mkdir aisix-openai-demo && cd aisix-openai-demo
npm init -y

在演示项目中安装 OpenAI SDK：

npm install openai

设置调用方 API Key、模型别名和网关 base URL：

# AISIX_BASE_URL 以 /v1 结尾，末尾不带斜杠
# 本地快速入门使用 http://127.0.0.1:3000/v1
export AISIX_BASE_URL="YOUR_AISIX_GATEWAY_URL/v1"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"

创建聊天示例​

使用 .mjs 扩展名，这样 Node 无需额外配置即可把顶层 await 和 import 当作 ES 模块处理。

openai-sdk-example.mjs
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AISIX_API_KEY,
  baseURL: process.env.AISIX_BASE_URL,
});

const response = await client.chat.completions.create({
  model: process.env.AISIX_MODEL ?? "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello from AISIX." }],
});

console.log(response.choices[0]?.message.content);

运行示例​

在演示项目中运行聊天示例：

node openai-sdk-example.mjs

你应该会看到一段简短的助手回复。具体文本取决于上游模型。

当网关能够解析 gpt-4o-mini 且上游服务提供方可访问时，SDK 会返回包含助手消息的标准 OpenAI Chat Completions 对象。AISIX 会解析模型别名，并在调用上游服务提供方前注入已保存的服务提供方凭证。

流式响应​

同一个 baseURL 也适用于流式响应。

openai-sdk-streaming.mjs
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AISIX_API_KEY,
  baseURL: process.env.AISIX_BASE_URL,
  maxRetries: 0,
});

const stream = await client.chat.completions.create({
  model: process.env.AISIX_MODEL ?? "gpt-4o-mini",
  messages: [{ role: "user", content: "Stream a short greeting." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

在演示项目中运行流式响应示例：

node openai-sdk-streaming.mjs

你应该会看到终端中持续打印流式文本。

生产环境配置模式​

在大多数部署中，应用代码只需要网关 base URL、调用方 API Key 和 AISIX 模型别名。上游凭证、服务提供方 base URL、上游模型 ID、路由策略、限流、安全护栏和可观测性挂钩都保留在网关后。

这种解耦让你可以轮换服务提供方凭证、变更上游模型 ID，或新增网关策略，而无需修改 SDK 调用点。

如果 SDK 请求失败​

先使用直接请求检查调用方 API Key、网关 base URL 和 AISIX 模型别名，再在 SDK 中使用相同的值。

如果 SDK 仍然把流量直接发送到 OpenAI，请检查 baseURL。它必须指向 AISIX 代理 API 根路径，而不是上游 OpenAI API URL。

如果 AISIX 返回 404，说明请求的模型别名未配置。如果 AISIX 返回 403，说明调用方 API Key 已存在，但没有权限使用该别名。

下一步​

你现在已经通过 OpenAI SDK 客户端调用了 AISIX。接下来可阅读兼容 OpenAI 的 API了解代理行为。关于 SSE 响应和工具定义，请参阅流式响应和工具调用。如果应用需要 Claude 风格请求，请继续阅读 Anthropic SDK。