BroadRouter
开始使用

从 OpenAI API 迁移:Python、Node 和 cURL 代码实战

BroadNet Inference 团队 · 阅读约 6 分钟 · 发布于

修改客户端的 base URL、API key 和模型 ID。对于 Chat Completions 调用,这就够了。使用 Responses API 的代码必须改写为 Chat Completions:input 变成 messages,output_text 变成 choices[0].message.content,工具定义多一层嵌套。如果新服务商没有 embeddings,就给它单独一个客户端,然后在切换流量前跑一次冒烟测试。

如果你用的是 Chat Completions,把应用从 OpenAI 迁移到 OpenAI 兼容服务商只是一处小的代码改动;如果用的是 Responses API,就得改写。本文给出 Python、Node 和 cURL 的具体代码差异,说明 Responses、工具调用、结构化输出和 embeddings 该怎么处理,并提供一个在迁移任何流量之前运行的冒烟测试。示例使用 BroadNet Inference,地址为 https://inference.broadnet.ai/v1;同样的步骤适用于任何服务商。

本文是迁移检查清单的代码篇,那篇讲的是速率限制、错误和切换规划。其他服务商的 base URL 请看 OpenAI 兼容 API base_url 汇总(已核实)。

客户端配置要改什么?

三个值:base URL、API key 和模型 ID。

Python

import os
from openai import OpenAI

# before: client = OpenAI()  # reads OPENAI_API_KEY, calls api.openai.com
client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
r = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",          # was e.g. "gpt-..."
    messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(r.choices[0].message.content)

Node

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://inference.broadnet.ai/v1",
  apiKey: process.env.BROADNET_API_KEY,
});
const r = await client.chat.completions.create({
  model: "broadnet/gemma-4-26b-a4b",
  messages: [{ role: "user", content: "Reply with one short sentence." }],
});
console.log(r.choices[0].message.content);

cURL

curl https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","messages":[{"role":"user","content":"Reply with one short sentence."}]}'

注意路径:base URL 已经以 /v1 结尾,SDK 会自动加上 /chat/completions。重复写 /v1 是最常见的第一个错误。

能不改代码就切换吗?

对于 Chat Completions 代码,可以。没有传入 base_url 时,Python SDK 会读取 OPENAI_BASE_URL;Node 客户端的 baseURL 默认值是 process.env['OPENAI_BASE_URL']。两者都会读取 OPENAI_API_KEY。设置两个环境变量,所有调用就都迁过去了。

这也正是风险所在。所有调用都会迁移,包括 embeddings、内容审核、文件上传,以及新服务商可能没有的其他任何功能。只有当你的应用只调用对话接口、别的什么都不调用时,才用环境变量切换。

如果我的代码用的是 Responses API 呢?

OpenAI 的 SDK README 现在把 Responses API 称为主要 API;Python README 把 Chat Completions 称为 “the previous standard (supported indefinitely)“(译文:上一代标准(无限期支持))。许多兼容服务商只实现了 Chat Completions。BroadNet 的文档记载的是 POST /v1/chat/completions 和 POST /v1/audio/transcriptions,所以 Responses 调用需要改写。对应关系如下:

Responses API Chat Completions
client.responses.create(...) client.chat.completions.create(...)
instructions="..." 第一条消息 {"role": "system", "content": "..."}
input="..." 或条目列表 messages=[...]
response.output_text response.choices[0].message.content
max_output_tokens max_tokens(BroadNet 文档)或 max_completion_tokens
text={"format": {...}} response_format={...}
previous_response_id、conversations 自己重新发送完整的消息历史
工具 {"type": "function", "name": ...} 工具 {"type": "function", "function": {"name": ...}}
输出条目 function_call,用 function_call_output 和 call_id 回复 message.tool_calls,用 role 为 tool 的消息和 tool_call_id 回复
内置工具(网页搜索、文件搜索) 不可用;运行你自己的工具

一个简单调用改写前后的对比:

# Before: Responses API
r = client.responses.create(model="gpt-...", instructions="Be brief.", input="What is RAG?")
text = r.output_text

# After: Chat Completions
r = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",
    messages=[{"role": "system", "content": "Be brief."},
              {"role": "user", "content": "What is RAG?"}],
)
text = r.choices[0].message.content

最大的结构变化在于状态。Responses 可以用 previous_response_id 在 OpenAI 那边保存会话状态。Chat Completions 没有服务端状态,所以由你的代码保存消息列表,并在每一轮把它全部发送出去。要为此做好预算:每次调用时,整个历史都算作输入 token。

工具调用有什么变化?

在 Chat Completions 中,工具定义把函数嵌套在 function 键下,回复则以 tool 消息的形式发回:

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_order",
        "description": "Look up an order by ID.",
        "parameters": {"type": "object",
                       "properties": {"order_id": {"type": "string"}},
                       "required": ["order_id"]},
    },
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
    messages.append(msg)                                   # keep the assistant turn
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)         # a JSON string: parse and validate it
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(lookup_order(args["order_id"]))})
    r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)

模型比结构更重要。BroadNet 的文档只为 GLM 5.3 和 Qwen3.8 27B 列出了工具调用。不要把工具循环指向文档中没有列出工具调用的模型,并且在执行任何操作前先校验参数。开源模型的工具调用给出了一个完整的带校验的循环。

结构化输出呢?

client.chat.completions.parse(..., response_format=MyPydanticModel) 和 Node 的 zodResponseFormat 都会发送带 JSON schema 的 response_format。只有当服务商在该模型上接受这种格式时,它们才能工作。BroadNet 为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出,但没有写明请求参数名。请对每个模型跑一次 JSON 模式与 json_schema 中的四步测试,而且无论服务商承诺什么,都要继续校验解析结果。

embeddings 会怎样?

如果你在一个共享客户端上修改了 base URL,而服务商没有 embeddings 端点,每次 client.embeddings.create 调用都会失败。BroadNet 不提供 embeddings。请保留两个客户端:

chat = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
embed = OpenAI(api_key=os.environ["OPENAI_API_KEY"])   # or any embeddings provider

vec = embed.embeddings.create(model="text-embedding-3-small", input=query).data[0].embedding
answer = chat.chat.completions.create(model="broadnet/glm-5.3", messages=build_prompt(query, search(vec)))

永远不要在同一个索引里混用两个 embedding 模型生成的向量。如果你同时更换 embedding 服务商,就要对整个语料库重新生成向量。embedding 费用计算器可以算出这笔费用。

其他非对话功能也是一样:图像生成、文字转语音、内容审核、Batch API 和文件存储。BroadNet 都不提供。语音转文字可以迁移:client.audio.transcriptions.create 可以调用 /v1/audio/transcriptions,支持 WAV 或 MP3,并需要 language 字段(阿拉伯语语音转文字指南)。

流式输出的代码怎么改?

Responses API 流式发送带类型的事件,比如 response.output_text.delta 和 response.completed。Chat Completions 流式发送数据块,文本位于 choices[0].delta.content。除非你主动请求,否则不会发送 usage;请求之后,它会出现在最后一个 choices 列表为空的数据块中。

// Before (Responses): for await (const e of stream) if (e.type === "response.output_text.delta") out(e.delta);
const stream = await client.chat.completions.create({
  model: "broadnet/gemma-4-26b-a4b",
  messages: [{ role: "user", content: "Count from one to three." }],
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) console.log("\ntokens:", chunk.usage.total_tokens);   // last chunk
}

切换之后,有两个习惯能让流式代码保持安全。一是对 choices[0] 做防护,因为 usage 数据块没有 choices。二是如果流在最后一行 data: [DONE] 之前就结束了,要把它当作不完整处理;BroadNet 的文档要求记录 X-Request-ID,再判断发起新请求是否安全。流式 chat completions 给出了 Python 的完整写法。

错误处理和重试要改吗?

SDK 的错误类保持不变:401 是 AuthenticationError,429 是 RateLimitError,其余是 APIStatusError。变化的是每个状态码在新服务商那里的含义。在 BroadNet 上,401 不只表示密钥错误,也可能表示按量付费额度已用完;402 表示余额不足以完成购买。这两种都不会因重试而解决。429 可能来自速率、并发、token 速率或支出限制。对 429 和 5xx 使用退避重试,其他错误则要修正。错误与重试指南有完整的表格。

SDK 默认对连接错误、408、409、429 和 5xx 重试两次。如果你加了自己的重试循环,请在客户端上设置 max_retries=0,避免两层重试叠加。

哪些参数的行为不一样?

参数 需要检查什么
max_tokens / max_completion_tokens OpenAI 已弃用 max_tokens;BroadNet 的文档使用它。在思考模型上它包含思考内容,所以值太小会返回空答案(原因)
reasoning_effort BroadNet 记载了 low;依赖其他值之前请先测试
stream_options: {"include_usage": true} BroadNet 有记载;usage 出现在最后一个数据块中
n、logprobs、seed、logit_bias BroadNet 文档中没有;请测试或删除
store、metadata OpenAI 的存储功能;删掉即可
image_url 内容块 仅限列明支持图像的模型:DeepSeek V4.1 Flash、Qwen3.8 27B、Gemma 4 VL 26B

怎么测试这次切换?

在迁移任何流量之前,先对新服务商跑一个简短的冒烟测试。下面这个测试检查普通对话、流式输出的 usage、思考预算和身份验证。如果你用到工具,再加一个工具调用的用例。

import os, openai
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
FAST, REASONING = "broadnet/gemma-4-26b-a4b", "broadnet/qwen3.8-27b"
msg = [{"role": "user", "content": "Reply with the word ok."}]

# 1. Plain chat returns text and usage
r = client.chat.completions.create(model=FAST, messages=msg)
assert r.choices[0].message.content and r.usage.prompt_tokens > 0

# 2. Streaming reports usage in the last chunk
chunks = list(client.chat.completions.create(model=FAST, messages=msg, stream=True,
                                             stream_options={"include_usage": True}))
assert chunks[-1].usage is not None

# 3. A reasoning model needs room: a tiny budget can come back empty
r = client.chat.completions.create(model=REASONING, messages=msg, max_tokens=2000)
assert r.choices[0].finish_reason == "stop" and r.choices[0].message.content

# 4. A bad key raises AuthenticationError (401), which you should not retry
bad = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key="invalid", max_retries=0)
try:
    bad.chat.completions.create(model=FAST, messages=msg)
    raise AssertionError("expected 401")
except openai.AuthenticationError:
    pass
print("smoke test passed")

然后比较质量,而不仅仅是格式。在两个服务商上重放一批真实提示词,并给回答打分;切换前如何评估大模型介绍了做法。OpenAI 到 BroadNet 迁移工具可以帮你改写代码片段,并列出其中用到的功能。

最常出问题的是什么?

  • 全局 base URL,连 embeddings 和文件调用也一起迁走了。
  • Responses 专用的辅助属性,比如 output_text,残留在已经改用 Chat Completions 的代码里。
  • 模型 ID。gpt-... 这样的名称在别处不存在。在 BroadNet 上,模型 ID 形如 broadnet/glm-5.3。
  • 空回复,来自 max_tokens 设得太小的思考模型。
  • **速率限制。**BroadNet 按量付费密钥每分钟允许 30 个请求,同时 4 个。批量任务需要队列(429 处理)。

BroadNet Inference 适合什么场景

BroadNet Inference 适合那些对 OpenAI 的使用以对话和转写为主的应用:助手、信息提取、摘要、翻译和阿拉伯语语音。它也适合想为智能体使用固定价格 DeepSeek V4.1 Flash 套餐的应用。如果你依赖 Responses API 的服务端状态、内置工具、embeddings、图像生成、文字转语音、实时语音或 Batch API,它就不是合适的目标。请把这些功能迁到提供它们的服务商,或者留在 OpenAI 上,只迁移对话调用。Gemma 4 VL 26B 和两个转写模型可以用 $5 初始额度调用;GLM 5.3、Qwen3.8 27B 和 DeepSeek V4.1 Flash 需要先充值。

常见问题

使用 OpenAI 兼容 API,需要换一个 SDK 吗?

不需要。继续用官方 openai 包,传入不同的 base_url(Python)或 baseURL(Node),再加上新服务商的密钥。对于服务商支持的端点,请求和响应对象保持不变。

OpenAI 兼容 API 支持 Responses API 吗?

有些支持,很多只支持 Chat Completions。请查看服务商的端点列表。BroadNet Inference 的文档记载了 /v1/chat/completions 和 /v1/audio/transcriptions,所以 Responses 代码必须改写为 Chat Completions。

切换后,我的 embeddings 会怎样?

如果新服务商没有 embeddings 端点,而你又全局修改了 base URL,它们就会失败。BroadNet 不提供 embeddings,所以请保留一个指向你的 embeddings 服务商的客户端。永远不要在同一个索引里混用两个 embedding 模型生成的向量。

应该传 max_tokens 还是 max_completion_tokens?

OpenAI 已将 max_tokens 标为弃用,改用 max_completion_tokens。许多兼容服务商的文档写的是 max_tokens,BroadNet 的文档也用 max_tokens。按服务商文档来传,并在冒烟测试中确认上限确实生效。

OpenAI 的结构化输出辅助函数还能用吗?

只有当服务商在你使用的模型上接受带 json_schema 的 response_format 时才能用。BroadNet 为 GLM 5.3 和 Qwen3.8 27B 列出了结构化输出,但没有写明请求参数名,所以请先测试,并继续校验解析结果。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity