OpenAI API 国内接入教程：SDK 迁移、Base URL 与错误排查

结论先说： 已使用 OpenAI SDK 的项目，通常可以通过替换 Base URL、API Key 和模型 ID 迁移到 AI快站。迁移前先确认项目使用的是 Chat Completions 还是 Responses API；“兼容 OpenAI”不代表所有端点和高级参数都完全一致。

迁移前先找出三个配置

建议先在测试环境迁移，不要直接替换生产配置。为不同项目创建独立 Key，设置可控额度，发生泄露或停止使用时可以单独撤销。

第一步：确认模型与基础链路

export AIFAST_API_KEY="你的_API_Key"

curl --fail-with-body --silent --show-error \
  https://www.aifast.club/v1/models \
  -H "Authorization: Bearer $AIFAST_API_KEY"

成功返回包含 data 数组的模型列表响应，说明域名、HTTPS 和 Bearer 认证链路基本正常。随后从响应中复制真实模型 ID：

export MODEL_ID="从模型列表复制的真实_ID"

第二步：迁移 Python 项目

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIFAST_API_KEY"],
    base_url="https://www.aifast.club/v1",
)

response = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[
        {"role": "system", "content": "回答必须简洁。"},
        {"role": "user", "content": "列出 API 迁移前的三项检查。"},
    ],
)

print(response.choices[0].message.content)

如果原项目使用 OPENAI_API_KEY，不要同时保留多个来源不明的 Key。明确环境变量优先级，避免程序读取到 OpenAI 官方 Key，而请求却发送到第三方 Base URL，或反过来。

第三步：迁移 Node.js 项目

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AIFAST_API_KEY,
  baseURL: "https://www.aifast.club/v1",
});

const response = await client.chat.completions.create({
  model: process.env.MODEL_ID,
  messages: [
    { role: "user", content: "只回复 OPENAI_COMPATIBLE_READY" },
  ],
  temperature: 0,
});

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

先完成非流式短请求，再增加流式、工具调用、图像输入或结构化输出。一次加入过多参数，会让错误来源难以定位。

Chat Completions 与 Responses 怎么选

查看大模型 API 兼容性矩阵可以快速确认需要验证的端点边界。

五分钟验收清单

1. /v1/models 返回可解析 JSON，而不是 HTML。
2. 最小请求返回预期结构，并保存 model、usage 和请求 ID。
3. 错误 Key 返回明确 401/403，不泄露敏感信息。
4. 流式请求能持续读取 SSE，而不是等待完整响应后一次性输出。
5. 账单变化能与模型、Token、Key 和请求时间对应。

若要比较现有接口，可使用免费模型检测检查协议、模型声明、Token、SSE 和工具调用。检测结果不是底层厂商认证，应结合多时段样本和真实业务题集判断。

常见问题

为什么出现 /v1/v1？

客户端与配置各追加了一次 /v1。若日志显示 /v1/v1/chat/completions，根据客户端规则把 Base URL 改为域名根地址，或关闭自动追加路径。

为什么返回 401？

检查 Key 来源、环境变量优先级、Bearer 请求头和前后空格。不要把 Key 放进浏览器前端、公开仓库或截图。

为什么返回 429？

429 通常与额度、并发或速率限制有关。读取错误正文和 Retry-After，使用指数退避与随机抖动，不要无限立即重试。

为什么接口返回 200，业务仍失败？

HTTP 200 只能说明请求被正常处理。仍需验证输出约束、工具参数、Token、流式结束事件和业务题集通过率。

下一步

继续阅读OpenAI Compatible 快速接入、401、429、502 错误排查和生产上线检查清单，再进行灰度迁移与回滚演练。