BroadRouter
开始使用

大模型 API 故障转移:在自己的代码里切换到备用服务商

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

维护一个有序的 OpenAI 兼容服务商列表,每个服务商有自己的客户端和模型 ID。在 SDK 自带的重试用完后,遇到连接错误、超时、5xx 和限流类 429 时切换。遇到 400、401、402、403、413 或 422 绝不切换。再加一个熔断器,并确认备用服务商在功能和数据条款上与主服务商一致。

每个大模型 API 都有出问题的几分钟:一个 503、一次超时、一波 429。故障转移(fallback)的意义在于,不让这几分钟变成你应用的宕机。本文介绍如何在自己的代码里,在 OpenAI 兼容的服务商之间做故障转移:哪些错误应该触发切换,熔断器如何让切换保持迅速,以及服务商之间哪些方面必须一致,才能让用户察觉不到切换。

先说明一点:BroadNet Inference 不会替你在服务商之间路由或故障转移,BroadRouter 也不会。BroadRouter 是 BroadNet 自己的网站,不是路由平台。故障转移需要你自己实现,要么像下文那样写在客户端里,要么放在 LiteLLM 这类网关中。

为什么要保留一个备用服务商?

因为大多数自助式 API 对可用性没有任何承诺。BroadNet 的条款第 7.4 条写得很直白:“self-serve has no availability commitment”(译文:自助服务没有可用性承诺),服务等级只存在于单独的书面协议中(2026 年 11 月 15 日查阅)。其他服务商承诺了什么,见大模型 API SLA 对比。如果你的功能必须保持在线,无论 SLA 怎么写,第二个服务商都是最实际的保险。

速率限制是第二个原因。BroadNet 按量付费密钥每分钟允许 30 个请求,同时最多 4 个并发。超出的流量高峰会返回 429,而在你提升容量之前,第二个服务商可以接住溢出的请求。

哪些错误应该触发故障转移?

把错误分成两类。一类是服务商的问题,换一家可能成功;另一类是你自己的问题,换到哪里都会失败。

错误 是否切换? 原因
连接错误、超时 是,重试之后 服务商或网络不可达
500、502、503、504 是,重试之后 BroadNet 的文档建议先 “retry with bounded exponential backoff”(译文:以有上限的指数退避重试)
429,速率或并发限制 是,退避之后 是这家服务商的容量问题,不是请求有误
429,消费限额 否 切换会绕过你特意设置的预算
400、422 否 请求无效,换一家也会失败
401、402 否 密钥、额度或余额问题。在 BroadNet 上,401 也包括按量付费额度已用完,切换会掩盖计费问题
403、413 否 策略或大小问题;修正请求

BroadNet 的 API 参考说明,429 表示 “a rate, concurrency, token-rate or spending limit was reached”(译文:达到了速率、并发、token 速率或消费限额),并建议 “use response details and bounded backoff”(译文:根据响应详情使用有上限的退避)。切换之前先读这些详情,这样消费限额类的 429 会终止请求,而不是把它转走。错误码指南列出了所有状态码。

先重试,再切换。OpenAI Python SDK 本身就会对连接错误、408、409、429 和 5xx 响应进行重试,“2 times by default, with a short exponential backoff”(译文:默认 2 次,使用较短的指数退避),默认超时为 10 分钟(README,2026 年 11 月 15 日查阅)。切换前等十分钟实在太久了。请为每个客户端设置 timeout。429 处理文章介绍了带抖动的退避。

用 Python 实现故障转移是什么样子?

两个客户端、一个有序列表,再加一个小熔断器。主服务商是 BroadNet 上的 GLM 5.3,备用的是 DeepInfra 上的同一个开放权重模型,其文档给出的 base URL 是 https://api.deepinfra.com/v1/openai(2026 年 11 月 15 日查阅)。

import os
import time
from openai import (OpenAI, APIConnectionError, APITimeoutError,
                    RateLimitError, InternalServerError)

PROVIDERS = [
    {"name": "broadnet", "model": "broadnet/glm-5.3",
     "client": OpenAI(base_url="https://inference.broadnet.ai/v1",
                      api_key=os.environ["BROADNET_API_KEY"],
                      max_retries=2, timeout=60)},
    {"name": "deepinfra", "model": "zai-org/GLM-5.3",
     "client": OpenAI(base_url="https://api.deepinfra.com/v1/openai",
                      api_key=os.environ["DEEPINFRA_API_KEY"],
                      max_retries=2, timeout=60)},
]

# Provider-side failures only. 400, 401, 402, 403 and 422 raise straight through.
FAILOVER_ON = (APIConnectionError, APITimeoutError, RateLimitError, InternalServerError)
TRIP_AFTER = 3     # consecutive failures before the breaker opens
COOLDOWN = 30      # seconds to skip a provider once its breaker is open
state = {p["name"]: {"fails": 0, "open_until": 0.0} for p in PROVIDERS}


def chat(messages, **kwargs):
    last_error = None
    for p in PROVIDERS:
        s = state[p["name"]]
        if time.monotonic() < s["open_until"]:
            continue  # breaker open: don't wait on a provider that is down
        try:
            reply = p["client"].chat.completions.create(
                model=p["model"], messages=messages, **kwargs)
            s["fails"] = 0
            return p["name"], reply
        except FAILOVER_ON as err:
            last_error = err
            s["fails"] += 1
            if s["fails"] >= TRIP_AFTER:
                s["open_until"] = time.monotonic() + COOLDOWN
    raise RuntimeError("every provider failed") from last_error


served_by, reply = chat([{"role": "user", "content": "Reply with one short sentence."}],
                        max_tokens=1000)
print(served_by, reply.model, reply.choices[0].message.content)

有四个细节很重要:

  1. **异常类。**SDK 对 429 抛出 RateLimitError,对 500 及以上抛出 InternalServerError,无法连接时抛出 APIConnectionError(APITimeoutError 是它的子类)。其他异常故意不捕获。要把消费限额类的 429 排除在外,请在继续之前检查 err.response。
  2. **熔断器。**没有它,主服务商宕机时每个请求都要等满超时才会转走。连续失败三次后,主服务商会被跳过 30 秒。之后的下一个请求会再次试探它。
  3. **记录由谁响应。**返回服务商名称,并保留 reply.model。质量出现变化时,你需要知道是哪家服务商给出的回答。
  4. **思考预算。**GLM 5.3 会先思考再回答。BroadNet 的文档说明思考 token 计入 max_tokens,所以在每个服务商上都要留出 1,000 或以上。

如何在服务商之间映射模型 ID?

同一个开放权重模型在每家托管方都有不同的 ID,各家列明的功能也可能不同。以下是 2026 年 11 月 15 日的 GLM 5.3:

BroadNet Inference DeepInfra Fireworks AI
模型 ID broadnet/glm-5.3 zai-org/GLM-5.3 accounts/fireworks/models/glm-5p3
上下文 1,048,576 token 1,048,576 token “1040k” token
工具 有文档说明 列有 “Function” 支持
结构化输出 有文档说明 列有 “JSON” 未核查

由此得出两条规则。第一,把映射放在配置里,不要散落在代码各处。第二,备用方案要匹配你的请求实际用到的功能。在 BroadNet 上,只有 GLM 5.3 和 Qwen3.8 27B 有工具和结构化输出的文档说明。一个调用工具的智能体可以从 GLM 5.3 切换到别家的 GLM 5.3,但不能安全地切换到没有工具文档说明的模型。如果备用方案的上下文窗口更小,就裁剪提示词,或者长请求跳过这个备用方案。14 家服务商的 base URL 见 base URL 参考。

切换之后如何让回答保持可比?

同一份权重在两家托管方仍可能给出不同的回答,因为托管方可能使用不同的精度、对话模板或默认参数。换成另一个模型,回答肯定会不同。

  • 用你的评测集测试列表中的每一项,而不只是主服务商。
  • 每个请求都固定 temperature、max_tokens 和系统提示词,避免服务商的默认值改变输出。
  • 在每条路径上用同样的方式校验结构化输出。修复无效 JSON介绍了修复加重试的循环。
  • 宁可用别家的同一个模型,也不要用同一家的另一个模型。比起几秒的延迟,用户更容易察觉到风格的变化。

流式输出和工具调用怎么办?

流式输出可能中途失败。BroadNet 的文档说明,在 data: [DONE] 之前结束的流应视为不完整:记录 X-Request-ID,再判断你的应用能否安全地发送新请求。

  • **第一个 token 之前:**可以放心切换。用户什么都还没看到。
  • **已经显示了 token 之后:**在备用服务商上重新开始并替换不完整的回答,或者显示错误并提供重试按钮。把两家服务商各一半的回答拼在一起,读起来很糟糕。
  • **有副作用的工具调用:**绝不能仅仅因为模型调用失败,就重新执行发邮件、扣款或写数据库的步骤。为每个操作分配一个幂等键。长时间运行的智能体介绍了检查点。

SSE 流式输出详解说明了如何检测提前结束的流。

故障转移要付出什么成本?

  • **重复工作。**你这边超时,并不能证明服务商停止了处理。在按 token 计费时,每次重试都是一次新的推理,所以要预料到部分请求会付两次钱。
  • **价格不同。**备用服务商按自己的价格计费。DeepInfra 在 2026 年 11 月 15 日为 GLM-5.3 列出的是促销价,做预算之前请重新核对。BroadNet 每百万 token 收取输入 $0.78、缓存输入 $0.173、输出 $3.46。
  • **缓存是冷的。**缓存输入不会在服务商之间转移。备用服务商上的头几个请求,对于在主服务商上已缓存的前缀,要付全额输入价。参见缓存输入 token。
  • **对冲请求。**每个请求同时发给两家服务商、取先返回的回答,可以降低尾延迟,但账单大约翻倍。只在延迟值得这个代价的地方使用。

备用服务商符合同样的数据条款吗?

备用服务商是另一个接收相同提示词的处理方。如果你向客户就其数据做过承诺,这个承诺必须在列表中的每一项上都成立。

BroadNet 的隐私声明写道:“We do not retain prompts, audio, images, answers or transcripts”(译文:我们不保留提示词、音频、图像、回答或转写文本)。推理内容不会被保留;必要的账户、计费和安全元数据按该声明所述保留。声明还说,推理数据不会用于训练、微调或评估模型。该声明称,托管模型 “run on BroadNet-owned or leased hardware in the United States, with partner capacity as backup”(译文:运行在 BroadNet 自有或租用的美国硬件上,并以合作方容量作为备份);DeepSeek V4.1 Flash 由合作方托管。对于有驻留要求的数据,条款(第 7.3a 条)要求在发送之前约定处理地点。请对备用服务商检查同样几点:数据保留、训练用途、地点和子处理方。如果它达不到要求,就让敏感请求不走备用路径,失败时直接拒绝(fail closed)。零数据保留检查清单列出了要问的问题。

要不要改用 LiteLLM 这样的网关?

如果多个服务需要同样的故障转移规则,就用网关。LiteLLM 代理接受一个按顺序尝试的 fallbacks 列表。num_retries 会在回退之前重试某个模型组。allowed_fails 和 cooldown_time 会把出错的部署暂时下线,起到熔断器的作用。另有 context_window_fallbacks 和 content_policy_fallbacks 分别处理这两类错误(LiteLLM 文档,2026 年 11 月 15 日查阅):

model_list:
  - model_name: glm
    litellm_params:
      model: openai/broadnet/glm-5.3
      api_base: https://inference.broadnet.ai/v1
      api_key: os.environ/BROADNET_API_KEY
  - model_name: glm-backup
    litellm_params:
      model: openai/zai-org/GLM-5.3
      api_base: https://api.deepinfra.com/v1/openai
      api_key: os.environ/DEEPINFRA_API_KEY

router_settings:
  fallbacks: [{"glm": ["glm-backup"]}]
  allowed_fails: 3
  cooldown_time: 30

litellm_settings:
  num_retries: 2
  request_timeout: 60

LiteLLM 代理指南给出了完整的 BroadNet 配置项。两个配置项都使用 LiteLLM 通用的 openai/ 前缀加 api_base,与指南中的写法相同。网关会多一跳,也多一个需要维护运行的组件。对单个应用来说,像上面那样在客户端里写大约 40 行代码就够了。

如何在真正需要之前测试故障转移?

  1. 在测试配置中把主服务商指向一个不可达的主机,检查请求是否落到了备用服务商上。
  2. 故意发送一个无效请求,检查它不会触发切换。
  3. 使用无效的主服务商密钥,检查 401 会作为错误暴露出来,而不是悄悄切换。
  4. 观察熔断器:失败三次之后,主服务商应被跳过,而不必等待超时。
  5. 当备用服务商承担的流量超过一小部分时发出告警。悄无声息的故障转移可能会把主服务商的故障掩盖好几天。

在直接测试中,LiteLLM 的 Router 接受 mock_testing_fallbacks=True 来强制触发回退。

BroadNet Inference 适合什么场景

BroadRouter 是 BroadNet 的网站,而 BroadNet Inference 可以作为你列表中的任意一项。作为主服务商,它在同一个 base URL 上提供有工具和结构化输出文档说明的 GLM 5.3 和 Qwen3.8 27B,以及 Gemma 4 VL 26B 和 DeepSeek V4.1 Flash,且不保留任何内容。作为备用,它是你可以加入列表的又一个 OpenAI 兼容端点。无论哪种方式,故障转移逻辑都由你负责:BroadNet 不在服务商之间路由,自助服务也没有 SLA。如果你需要合同约定的服务等级,只能通过单独的书面协议获得。比较各模型,或者创建账户,用 $5 初始额度在 Gemma 4 VL 26B 上测试你的切换链路。GLM 5.3 和 Qwen3.8 27B 需要充值后使用。

常见问题

哪些错误应该触发大模型 API 切换到备用服务商?

在 SDK 自带的重试之后,遇到连接错误、超时、5xx 和限流类 429 时切换。遇到 400、401、402、403、413 或 422 不要切换:这说明请求或账户有问题,下一家服务商会同样失败,或者掩盖计费问题。

BroadNet 会自动切换到其他服务商吗?

不会。BroadNet Inference 不会在模型或服务商之间路由请求;本站 BroadRouter 是 BroadNet 的信息网站,不是路由平台。故障转移需要你在客户端或 LiteLLM 这类网关中自己实现。

能在所有服务商上用同一个模型 ID 吗?

不能。同一个开放权重模型,各服务商的命名都不同。GLM 5.3 在 BroadNet 上是 `broadnet/glm-5.3`,在 DeepInfra 上是 `zai-org/GLM-5.3`,在 Fireworks 上是 `accounts/fireworks/models/glm-5p3`(2026 年 11 月 15 日查阅)。请为每个服务商维护一份映射。

失败的尝试要花钱吗?

可能要。你这边超时,并不能证明服务商停止了处理;在按 token 计费时,每次重试都是一次新的推理。请为部分请求被重复计费留出预算,并限制每个请求的尝试次数。

备用服务商需要有相同的隐私条款吗?

需要。备用服务商是另一个会看到相同提示词的处理方。加入之前请检查它的数据保留、训练用途和处理地点条款,否则你的隐私承诺只在主服务商正常时才成立。

BroadNet 有 SLA 吗?

自助服务没有。BroadNet 的条款(第 7.4 条)说明自助服务没有可用性承诺;服务等级只存在于单独的书面协议中。

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