BroadRouter

迁移到 OpenAI 兼容 API:切换服务商检查清单

BroadNet Inference 团队 · 阅读约 5 分钟 · 发布于 · 更新于

迁移到 OpenAI 兼容 API,要改三项设置(base_url、api_key 和 model),然后逐项检查差异:模型 ID、思考 token 如何计入 max_tokens、流式输出如何返回用量、哪些错误该重试、速率限制以及密钥安全。BroadNet Inference 的 base URL 是 https://inference.broadnet.ai/v1。

现在大多数大模型服务商都支持 OpenAI API 格式。这让切换看起来只需要改一行代码,如果只是想拿到第一个回答,确实如此。但要承载生产流量,请按下面的清单逐项检查。每一项都来自迁移中真实出过的问题。

0. 你的应用现在用到了什么?

改动任何东西之前,先把应用依赖的东西写下来。在代码中搜索每一处 SDK 调用并列出来。如果你调用了 OpenAI 的 Whisper API,请注意 OpenAI 已列出 whisper-1 将于 2027 年 2 月 26 日停止服务;音频部分见 Whisper API 替代方案。

功能 在哪里找 切换后测试什么
Chat completions 每一处 chat.completions.create 同样的提示词,对比回答
流式输出 stream=True 数据块正常到达,以 [DONE] 结束,带有用量
工具调用 tools= 工具调用能解析并执行
结构化输出 response_format= JSON 能通过你的 schema 校验
图像 消息中的图像部分 模型能接受
音频转写 audio.transcriptions 文本和语言正确
Embeddings、文件、批处理 其他端点 先确认服务商是否提供

最后一行很重要。“OpenAI 兼容”通常首先覆盖的是 chat completions。BroadNet Inference 的模型目录在 /v1/chat/completions 上提供聊天模型,在 /v1/audio/transcriptions 上提供语音转文字模型;如果你用到其他端点,请把它们留在现有服务商,或另找替代。

1. 要改哪三项设置?

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

base URL 这个设置在不同库里名字不同:Python SDK 和 LangChain 的 ChatOpenAI 里叫 base_url,Node.js SDK 里叫 baseURL。根据 Python SDK 的 README,它还会读取环境变量 OPENAI_BASE_URL。请检查环境中有没有残留的旧值,否则请求可能在不报错的情况下发往旧服务商。

API 密钥要放在环境变量或密钥管理服务中,绝不要写进代码。各 SDK 的配置方法:Python、Node.js、LangChain。想手动构造并测试第一个请求,可以用 API 请求构建器。想把 base URL、密钥和模型的修改应用到现有代码上,把代码粘贴到 OpenAI 迁移到 BroadNet 助手,它还会列出需要检查的事项。

2. 新的模型 ID 是什么?

每家服务商给模型的命名方式都不一样。BroadNet Inference 上:

模型 ID
DeepSeek V4.1 Flash broadnet/deepseek-v4.1-flash
GLM 5.3 broadnet/glm-5.3
Qwen3.8 27B broadnet/qwen3.8-27b
Gemma 4 VL 26B broadnet/gemma-4-26b-a4b

把模型 ID 放在配置里而不是代码里,以后切换只需要重新部署,不用改代码。每个模型的限制和价格见各自的页面:DeepSeek V4.1 Flash、GLM 5.3、Qwen3.8 27B 和 Gemma 4 VL 26B。

3. 切换后为什么返回空回答?

这是最常见的意外。DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考再回答,而且**思考 token 计入 max_tokens**。在非思考模型上够用的 256 上限,可能全部被思考用光,回答就是空的。请至少留出 1,000 个 token,或者对简单任务把 reasoning_effort 设为 low。完整说明。

4. 流式输出还会返回用量吗?

流式输出使用 Server-Sent Events,以 data: [DONE] 结束。只有你主动请求,token 用量才会出现在最后一个数据块中:

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)

不加这个参数,你的成本看板读数就是零。如果流在 [DONE] 之前就结束了,应视为不完整。参见流式输出指南。

5. 哪些错误应该重试?

状态码 含义 处理
401 密钥错误或已吊销,或按量付费额度已用完 修复,不要重试
402 余额或预算不足 充值,不要重试
403 被模型、路由或 IP 策略拒绝 修正不匹配的配置
413 请求过大 缩小请求,不要重试
429 速率、并发或支出限制 退避后重试
5xx 服务器端问题 用有上限的退避重试

官方 Python SDK 本身已经会重试部分错误:它的 README 说,连接错误以及 408、409、429 和 5xx 响应默认会以较短的指数退避重试两次。请显式设置 max_retries,让这个行为成为你的决定,而不是默认值。记录每个响应的请求 ID,方便技术支持追查问题。全部错误码。

6. 新的速率限制是多少?

在流量到来之前就要清楚新的限制。BroadNet 的按量付费密钥允许每分钟 30 个请求,同时最多 4 个请求。不限量套餐每个会话同一时间运行一个请求。按此调整你的工作进程池,否则第一天就会遇到 429;速率限制计算器可以帮你算规模。参见为并行智能体规划容量。

7. 你的提示词还放得下吗?

检查上下文窗口:DeepSeek V4.1 Flash 和 GLM 5.3 为 1,048,576 token,Qwen3.8 27B 为 262,144,Gemma 4 VL 26B 为 32,768。在旧模型上放得下的提示词,换到更小的窗口未必放得下;可以用上下文窗口计算器检查。把稳定不变的提示词内容放在最前面,以享受缓存输入价格。

8. 密钥和数据保留怎么办?

用 IP 白名单把生产密钥锁定到你服务器的 IP。问清楚新服务商会保留哪些数据;参见 ZDR 检查清单。

9. 怎样安全地切换?

  1. 把一天的真实请求复制一份,同时发给两家服务商。
  2. 抽样对比回答,以及延迟、错误和每个请求的成本。
  3. 先切 10% 的流量,观察一天,再切剩下的。
  4. 把旧服务商保留为备用,配置保留一周。

如果你运行着很多服务,可以用 LiteLLM 这样的代理,在一个地方切换服务商,而不用在每个应用里改。

常见的迁移错误有哪些?

  • **base URL 缺少 /v1。**请求返回 404。请使用完整的 URL。
  • **配置里还是旧的模型名。**新服务商不认识它们。
  • **请求中留着服务商专有的字段。**只有旧服务商认识的字段可能被拒绝或忽略。在通用客户端中把它们去掉。
  • **只测一个提示词。**按第 0 步的清单逐个功能测试。
  • **周五切换。**留出时间观察一整天的真实流量。

BroadNet Inference 的定位

对于通过 OpenAI SDK 使用 chat completions 和音频转写的应用,BroadNet Inference 可以直接替换:改三项设置,再按上面的清单逐项检查。它的模型目录只有聊天和语音转文字模型,所以如果你依赖其他端点,例如 embeddings 或文件存储,请把这些继续留在其他服务商。新账户有 $5 的初始额度。聊天模型中只有 Gemma 4 VL 26B 可以用它(它也可用于两个 Transcribe 模型),所以要在 DeepSeek、GLM 或 Qwen 上做影子测试需要先充值。

常见问题

需要换一个 SDK 吗?

不需要。官方的 OpenAI Python 和 Node.js SDK 都支持自定义 base URL。基于它们构建的框架也支持,例如 LangChain 的 ChatOpenAI。

OpenAI SDK 里怎么修改 base URL?

在 Python 中给客户端传入 base_url,在 Node.js 中传入 baseURL,或者设置环境变量 OPENAI_BASE_URL。BroadNet Inference 的值是 https://inference.broadnet.ai/v1,密钥填在 api_key 中。

切换后为什么返回空回答?

DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 这类思考模型会先思考再回答,思考部分计入 max_tokens。把 max_tokens 提高到 1,000 或以上,或把 reasoning_effort 设为 low。

切换后为什么报 404 或 model not found?

通常是模型 ID 还用着旧服务商的名称,或者 base URL 缺少 /v1 路径。请使用新服务商的准确模型 ID 和完整的 base URL。

哪些错误应该重试?

429 和 5xx 用有上限的指数退避重试。401、402 和 413 要先修复再重试。本站的错误指南列出了所有错误码。

OpenAI 兼容等于完全相同吗?

不等于。请求和响应的结构一致,但模型 ID、支持的参数、限制、用量字段和错误细节都可能不同。应用用到的每个功能都要测试。

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