如果你用的是 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 需要先充值。
