OriginCoder

什么是 OpenAI 兼容 API：切换提供商只改两项设置，以及常见差异与排错

发布于 2026-11-11

「OpenAI 兼容 API」指的是：某个服务（模型厂商、网关或自建推理服务）接收和返回的数据格式，和 OpenAI 的接口保持一致，所以为 OpenAI 写的客户端和 SDK 不用改代码就能连上它。实际操作里，通常只需要换两项设置：Base URL（请求发到哪里）和 API Key（用谁的身份）。本文讲清这件事怎么用、哪里会有差异，以及出问题时按什么顺序排查。

利益声明：我们运营 OriginCoder，一个 OpenAI 兼容的 AI 网关，所以示例里用的是我们的地址，我们对这条路线有立场。示例换成其他兼容服务的地址和密钥同样适用。内容截至 2026 年 11 月，各家实现的细节会变，请以对应服务的官方文档为准。

两项设置就够了

设置 作用 示例
Base URL 请求的基础地址，SDK 会在后面拼接 /chat/completions 等路径 https://origincoder.com/v1
API Key 放进 Authorization: Bearer 请求头的密钥 sk-xxxx

另外还有第三项经常被忘记：模型名。不同提供商的模型名不同，换提供商时模型名也要一起换。

在 Python、Node.js 和 curl 里切换

最好的做法是把这三项放进环境变量，切换提供商时只改环境变量，不动代码。

export LLM_BASE_URL="https://origincoder.com/v1"
export LLM_API_KEY="sk-xxxx"
export LLM_MODEL="your-model-name"

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["LLM_BASE_URL"],
    api_key=os.environ["LLM_API_KEY"],
)

resp = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[{"role": "user", "content": "用一句话介绍你自己。"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: process.env.LLM_MODEL,
  messages: [{ role: "user", content: "用一句话介绍你自己。" }],
});
console.log(resp.choices[0].message.content);

curl "$LLM_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$LLM_MODEL\", \"messages\": [{\"role\": \"user\", \"content\": \"用一句话介绍你自己。\"}]}"

在一个通过 OpenAI 兼容格式提供多家模型的网关上，切换模型厂商甚至只需要改模型名。具体例子见 DeepSeek API 示例和 Gemini API 示例，模型名以模型价格页为准。

「兼容」不等于「完全一样」

兼容通常覆盖最常用的部分，边缘部分各家不同。下面这些是最常见的差异点，是否支持请以对应服务的文档和你自己的实测为准：

  • 接口范围。 大多数服务支持 /chat/completions；/embeddings、图片、语音、/responses 等接口不一定都有。
  • 流式输出。 设置 stream: true 后以服务器推送（SSE）逐块返回。数据块里的字段、结束标记和是否带 usage 统计，各家略有差异。
  • 工具调用（function calling）。 请求里的 tools 和响应里的 tool_calls 格式通常一致，但是否支持并行调用、tool_choice 的取值范围、参数 JSON 的严格程度可能不同。
  • 参数支持。 temperature、max_tokens、response_format、reasoning 类参数，有的会被忽略，有的会报错。
  • 推理模型的字段。 部分模型会把推理过程和最终答案分开返回，字段名各家不统一。
  • 错误体。 错误的 HTTP 状态码通常符合预期，但错误消息的文字和 error.type 不一定一致，所以不要按消息文本写判断逻辑。
  • 限额与计费。 速率限制、上下文长度、token 统计口径由各提供商决定。

建议：换提供商后先用一个最小请求测通，再依次测流式、工具调用，最后再跑你的真实流程。

常见问题排查

按下面的顺序检查，大部分问题能在前三步解决。

现象 可能原因 处理
401 或「API Key 无效」 Key 写错、被禁用，或把 A 提供商的 Key 用在了 B 的地址上；请求头多了空格或引号 重新复制 Key，确认 Key 与 Base URL 属于同一个服务
404 Base URL 多写或少写了 /v1；SDK 已经会拼 /chat/completions，你又写了一遍 看服务文档的 Base URL 写法；用 curl 手动拼完整路径验证
「模型不存在」或 403 模型名拼错，或这个 Key 所在分组不提供该模型 从服务提供的模型列表复制名字，不要凭记忆写
400 某个参数该服务不支持，或消息格式不合法 去掉可选参数，用最小请求复现
429 触发速率限制 带退避重试，并检查该 Key 的限额
流式输出一次性全部返回，不是逐字 中间的反向代理或 CDN 缓冲了响应 见下一节
连接被断开、长请求超时 中间层的读超时或空闲超时太短 调大代理超时，或改用流式让连接保持有数据

如果你自己在服务前面放了 Nginx 之类的反向代理，流式被缓冲是最常见的原因：需要对该路径关闭代理缓冲（如 Nginx 的 proxy_buffering off），并确认没有被 CDN 压缩或缓存。具体配置请查你所用代理的官方文档。

用 /models 自查

多数兼容服务提供 GET /models，返回该 Key 能用的模型列表，可以同时验证 Key、Base URL 和模型名三件事：

curl "$LLM_BASE_URL/models" -H "Authorization: Bearer $LLM_API_KEY"

这个接口返回的内容是否完整因服务而异，拿不准时仍以控制台或文档为准。

什么时候该用网关

如果你只对接一个提供商，直接用它的官方 API 最简单。如果你想在多个厂商之间切换、集中账单和用量记录，或者想让只会 OpenAI 格式的工具用上别家模型，可以考虑网关。判断标准和取舍见 AI 网关是什么，不同方案的对比见 LLM 网关对比。要使用 OriginCoder，可先注册账号，并阅读服务条款了解数据如何处理。

全部教程

更多教程