---
title: "迁移到 OpenAI 兼容 API：切换检查清单 | BroadRouter"
description: "改 base_url 是最简单的一步。真正容易出问题的是模型 ID、思考 token、流式输出的用量统计、错误处理、速率限制和密钥。一份附代码的检查清单。"
url: https://broadrouter.com/zh/blog/openai-compatible-api-migration-checklist/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/blog/openai-compatible-api-migration-checklist/)（2026-11-16 更新）。

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

BroadNet Inference 团队 · 阅读约 5 分钟 · 发布于 2026-11-14 · 更新于 2026-11-16

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

## 要点

-   要改的设置有三项：`base_url`、`api_key` 和 `model`。
-   切换之前，先盘点应用用到的每个端点和字段，切换后逐一测试。
-   思考模型的思考过程计入 `max_tokens`；上限太小会返回空回答。
-   在流式请求中用 `stream_options` 请求返回用量，否则成本统计会失效。
-   把生产流量切过去之前，先确定每个错误码是重试还是修复。
-   正式切换前，先让新旧服务商用真实流量并行跑一天。

**本页内容**

1.  0\. 你的应用现在用到了什么？
2.  1\. 要改哪三项设置？
3.  2\. 新的模型 ID 是什么？
4.  3\. 切换后为什么返回空回答？
5.  4\. 流式输出还会返回用量吗？
6.  5\. 哪些错误应该重试？
7.  6\. 新的速率限制是多少？
8.  7\. 你的提示词还放得下吗？
9.  8\. 密钥和数据保留怎么办？
10.  9\. 怎样安全地切换？
11.  常见的迁移错误有哪些？
12.  BroadNet Inference 的定位

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

## 0\. 你的应用现在用到了什么？

改动任何东西之前，先把应用依赖的东西写下来。在代码中搜索每一处 SDK 调用并列出来。如果你调用了 OpenAI 的 Whisper API，请注意 OpenAI 已列出 `whisper-1` 将于 2027 年 2 月 26 日停止服务；音频部分见 [Whisper API 替代方案](https://broadrouter.com/zh/blog/whisper-api-alternative/)。

| 功能 | 在哪里找 | 切换后测试什么 |
| --- | --- | --- |
| 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\. 要改哪三项设置？

```python
from openai import OpenAI
import os

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

[base URL](https://broadrouter.com/zh/glossary/base-url/) 这个设置在不同库里名字不同：Python SDK 和 LangChain 的 ChatOpenAI 里叫 `base_url`，Node.js SDK 里叫 `baseURL`。根据 Python SDK 的 [README](https://github.com/openai/openai-python)，它还会读取环境变量 `OPENAI_BASE_URL`。请检查环境中有没有残留的旧值，否则请求可能在不报错的情况下发往旧服务商。

[API 密钥](https://broadrouter.com/zh/glossary/api-key/)要放在环境变量或密钥管理服务中，绝不要写进代码。各 SDK 的配置方法：[Python](https://broadrouter.com/zh/guides/openai-python-sdk/)、[Node.js](https://broadrouter.com/zh/guides/openai-node-sdk/)、[LangChain](https://broadrouter.com/zh/guides/langchain-openai-base-url/)。想手动构造并测试第一个请求，可以用 [API 请求构建器](https://broadrouter.com/tools/api-request-builder/)。想把 base URL、密钥和模型的修改应用到现有代码上，把代码粘贴到 [OpenAI 迁移到 BroadNet 助手](https://broadrouter.com/tools/openai-to-broadnet-migration/)，它还会列出需要检查的事项。

## 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](https://broadrouter.com/zh/models/deepseek-v4.1-flash/)、[GLM 5.3](https://broadrouter.com/zh/models/glm-5.3/)、[Qwen3.8 27B](https://broadrouter.com/zh/models/qwen3.8-27b/) 和 [Gemma 4 VL 26B](https://broadrouter.com/zh/models/gemma-4-vl-26b/)。

## 3\. 切换后为什么返回空回答？

这是最常见的意外。DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考再回答，而且\*\*[思考 token](https://broadrouter.com/zh/glossary/reasoning-tokens/) 计入 [`max_tokens`](https://broadrouter.com/zh/glossary/max-tokens/)\*\*。在非思考模型上够用的 256 上限，可能全部被思考用光，回答就是空的。请至少留出 1,000 个 token，或者对简单任务把 `reasoning_effort` 设为 `low`。[完整说明](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)。

## 4\. 流式输出还会返回用量吗？

[流式输出](https://broadrouter.com/zh/glossary/streaming/)使用 Server-Sent Events，以 `data: [DONE]` 结束。只有你主动请求，token 用量才会出现在最后一个数据块中：

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

不加这个参数，你的成本看板读数就是零。如果流在 `[DONE]` 之前就结束了，应视为不完整。参见[流式输出指南](https://broadrouter.com/zh/guides/streaming-chat-completions/)。

## 5\. 哪些错误应该重试？

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

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

## 6\. 新的速率限制是多少？

在流量到来之前就要清楚新的限制。BroadNet 的按量付费密钥允许每分钟 30 个请求，同时最多 4 个请求。不限量套餐每个会话同一时间运行一个请求。按此调整你的工作进程池，否则第一天就会遇到 429；[速率限制计算器](https://broadrouter.com/tools/llm-rate-limit-calculator/)可以帮你算规模。参见[为并行智能体规划容量](https://broadrouter.com/zh/blog/run-parallel-coding-agents-flat-rate/)。

## 7\. 你的提示词还放得下吗？

检查上下文窗口：DeepSeek V4.1 Flash 和 GLM 5.3 为 1,048,576 token，Qwen3.8 27B 为 262,144，Gemma 4 VL 26B 为 32,768。在旧模型上放得下的提示词，换到更小的窗口未必放得下；可以用[上下文窗口计算器](https://broadrouter.com/tools/context-window-calculator/)检查。把稳定不变的提示词内容放在最前面，以享受[缓存输入价格](https://broadrouter.com/zh/blog/cached-input-tokens-explained/)。

## 8\. 密钥和数据保留怎么办？

用 [IP 白名单](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/)把生产密钥锁定到你服务器的 IP。问清楚新服务商会保留哪些数据；参见 [ZDR 检查清单](https://broadrouter.com/zh/blog/zero-data-retention-llm-api-checklist/)。

## 9\. 怎样安全地切换？

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

如果你运行着很多服务，可以用 [LiteLLM](https://broadrouter.com/zh/guides/litellm-proxy-custom-provider/) 这样的代理，在一个地方切换服务商，而不用在每个应用里改。

## 常见的迁移错误有哪些？

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

## BroadNet Inference 的定位

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

相关免费工具（英文）

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[免费工具（英文）](https://broadrouter.com/tools/)

## 本文涉及的术语

[嵌入向量（embeddings）](https://broadrouter.com/zh/glossary/embeddings/)

嵌入向量（embeddings）是模型为一段文本、一张图片或其他输入生成的浮点数列表（向量）。意思相近的输入会得到彼此接近的向量，因此可以用向量之间的距离来给搜索结果排序、对文档聚类或查找相关条目。

[Base URL（base\_url）](https://broadrouter.com/zh/glossary/base-url/)

base URL 是 API 固定的根地址，例如 https://api.example.com/v1，客户端会把它加在每个端点路径（例如 /chat/completions）前面。在 OpenAI 兼容 SDK 中，修改 base URL，再配合 API 密钥和模型 ID，就能让同一份代码改用另一家服务商。

[工具调用（tool calling / function calling）](https://broadrouter.com/zh/glossary/tool-calling/)

工具调用（也叫函数调用，function calling）是大模型 API 的一项功能：模型返回一个结构化请求，要求执行开发者定义的某个函数，并附上 JSON 参数。应用执行该函数并把结果发回；模型自己从不执行代码。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

[速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/)

速率限制是 API 对客户端在一个时间窗口内的使用量设定的上限，例如每分钟请求数或每分钟 token 数。超出限制的请求会被拒绝，通常返回 HTTP 429 Too Many Requests，直到用量回落到限制以下。

[指数退避（exponential backoff）](https://broadrouter.com/zh/glossary/exponential-backoff/)

指数退避（exponential backoff）是一种重试策略：客户端每失败一次，就等待更长时间再重试，通常把延迟翻倍，直到达到上限。在每次等待中加入随机抖动（jitter），可以把众多客户端的重试错开，避免它们在同一时刻打到服务器上。

[Chat Completions API（对话补全接口）](https://broadrouter.com/zh/glossary/chat-completions-api/)

Chat Completions API 是 OpenAI 的 HTTP 端点 POST /v1/chat/completions，它接收模型名称和一组带角色标记的消息，返回模型的下一条消息。它的请求与响应结构已成为 OpenAI 兼容服务商和各类 SDK 通用的格式。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

## 常见问题

### 需要换一个 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、支持的参数、限制、用量字段和错误细节都可能不同。应用用到的每个功能都要测试。

## 继续阅读

-   [OpenAI 兼容 API 的 base\_url 汇总：14 家服务商逐一核对](https://broadrouter.com/zh/blog/openai-compatible-api-base-urls/)
-   [AI 智能体用 OpenRouter 还是固定价格套餐：哪个更省钱？](https://broadrouter.com/zh/blog/openrouter-alternative-flat-rate/)
-   [百万 token 上下文窗口什么时候值得用（什么时候不值得）](https://broadrouter.com/zh/blog/million-token-context-window-guide/)
-   [零数据保留大模型 API：10 个问题的核对清单](https://broadrouter.com/zh/blog/zero-data-retention-llm-api-checklist/)
-   [BroadNet 的 GPU 硬件与推理部署方式（据 BroadNet 自述）](https://broadrouter.com/zh/blog/broadnet-gpu-fleet-and-serving/)
-   [缓存大模型 API 响应以降低成本：用 Python 实现精确匹配缓存](https://broadrouter.com/zh/blog/cache-llm-responses-cut-cost/)
-   [指南：用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)
-   [指南：用 OpenAI Node.js SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-node-sdk/)
-   [指南：在 LangChain 中调用 BroadNet Inference](https://broadrouter.com/zh/guides/langchain-openai-base-url/)
-   [指南：BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)
-   [指南：对话补全的流式输出，以及连接中断的处理](https://broadrouter.com/zh/guides/streaming-chat-completions/)
-   [指南：推理模型为什么返回空回答](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)
-   [指南：用 LiteLLM 路由到 BroadNet Inference（SDK 与代理）](https://broadrouter.com/zh/guides/litellm-proxy-custom-provider/)

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-openai-compatible-api-migration-checklist&utm_content=page-cta) ·

**来源**

-   [BroadNet Inference API 参考（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-blog-openai-compatible-api-migration-checklist&utm_content=sources)
-   [OpenAI Python SDK README（base\_url、OPENAI\_BASE\_URL、重试；2026-11-14 核实）](https://github.com/openai/openai-python)
