构建模型回退链：何时切换LLM及Python实现指南

大多数应用只调用单一模型。这在模型正常工作时没问题，可一旦模型过载、被弃用，或者返回了解析器无法处理的内容，整个功能就会直接宕机。如果你的接口在同一个 OpenAI 兼容的 base URL 下暴露了多个模型，那么构建一条回退链（fallback chain）就是一份廉价的保险。

真正的难点不在于那个循环本身，而在于判断哪些错误值得触发回退、哪些错误应该直接抛出并大声报错。本文将基于一个 OpenAI 兼容网关的实践，拆解一套可落地的回退链设计方案。文中示例虽使用了作者自建的扁平费率网关 APIClaw，但方案本身与具体端点无关——任何支持 Chat Completions 格式的服务商都适用。

Model Fallback Chains 原文截图

第一步：获取真实的模型 ID，不要靠猜

最常见的回退链 bug，是链条里第二或第三个模型 ID 根本从未有效过。它静静地躺在配置里好几周，偏偏在你最需要它的那一次失效。正确的做法是直接从端点拉取 ID：

from openai import OpenAI

client = OpenAI(base_url="https://your-gateway/v1", api_key="YOUR_KEY")
for m in client.models.list().data:
    print(m.id)

要原样复制打印出来的 ID。网关对模型的命名往往与原厂不同，一个点号写成了连字符这种细微偏差，换来的是 404 "model not found"，而不是什么友好的纠错提示。

更稳妥的方式是在 CI 或启动时跑一遍这个检查，如果某个配置的回退模型不在列表中，就直接拒绝启动。这只需要一次请求，却能拦截整类静默配置错误。

OpenAI 兼容接口（OpenAI-compatible API）是指遵循 OpenAI 定义的 REST API 规范的第三方服务，包括 /v1/chat/completions、/v1/models 等端点路径和请求/响应 JSON 结构。众多网关和推理服务（如 Together AI、Fireworks、本地部署的 LiteLLM 等）都采用这一规范，使得切换供应商或构建多模型路由时无需修改客户端代码。然而"兼容"并不意味着完全一致——各平台对模型 ID 的命名策略差异显著，例如 OpenAI 官方的 gpt-4o 在某些网关中可能被重命名为 openai/gpt-4o 或 gpt-4o-2024-08-06。因此通过 GET /v1/models 接口动态获取当前可用模型列表，而非在代码中硬编码模型名称，是构建健壮回退链的前提条件。

第二步：在写循环之前先对错误分类

决定回退逻辑的核心，是把失败场景分成两类。

应该回退到下一个模型的情况：

特定模型的 404 或 "model not found"（它被移除或重命名了）
正常退避重试后依然持续的 429
重试一次后仍出现的 5xx 和 529 "overloaded" 类错误
平时很快的模型出现超时
响应未通过你自己的校验（内容为空、要求 JSON 却返回非法 JSON）

不应该回退、应立即抛出的情况：

401 或 403。错误的密钥对所有模型都是错的，试三个模型只会让日志里的噪音翻三倍。
关于请求结构的 400 错误，比如非法参数或消息过长。下一个模型大概率也会拒绝它；就算没拒绝，你也等于把一个真实 bug 藏了起来。
需要人工介入审查的内容。

第二类恰恰是大多数人会跳过的部分。一条会吞掉 400 错误的回退链，会把本可一行代码修复的问题，变成一桩"为什么输出质量突然变差了"的悬案。

HTTP 状态码在 AI 网关场景中有其特定语义，理解这些语义是正确分类错误的基础。401（Unauthorized） 表示 API 密钥缺失或格式错误；403（Forbidden） 表示密钥有效但无权访问该资源——两者都是身份认证层面的失败，与具体模型无关。404（Not Found） 在模型调用场景中通常意味着指定的模型 ID 不存在或已被下线，与身份无关，属于可以尝试其他模型的信号。429（Too Many Requests） 是速率限制响应，部分网关还使用非标准的 529 表示服务过载。5xx 系列表示服务端内部错误，通常是暂时性故障。OpenAI Python SDK 将这些状态码映射为具体异常类（如 AuthenticationError、RateLimitError、InternalServerError），捕获时按类型而非数字处理，可以避免对原始 HTTP 状态码做字符串解析。

第三步：核心循环的实现

import time
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://your-gateway/v1",
    api_key="YOUR_KEY",
    timeout=60,
    max_retries=1,   # SDK 每个模型只重试一次，其余交给回退链
)

CHAIN = ["PRIMARY_MODEL_ID", "SECOND_MODEL_ID", "CHEAP_MODEL_ID"]

FALLBACK_ERRORS = (
    openai.NotFoundError,
    openai.RateLimitError,
    openai.InternalServerError,
    openai.APITimeoutError,
    openai.APIConnectionError,
)

def complete(messages, validate=None, **kwargs):
    last_err = None
    for model in CHAIN:
        start = time.monotonic()
        try:
            resp = client.chat.completions.create(
                model=model, messages=messages, **kwargs
            )
            text = resp.choices[0].message.content or ""
            if validate and not validate(text):
                raise ValueError(f"validation failed on {model}")
            log(model, "ok", time.monotonic() - start, resp.usage)
            return text, model
        except (openai.AuthenticationError,
                openai.PermissionDeniedError,
                openai.BadRequestError):
            raise
        except FALLBACK_ERRORS + (ValueError,) as e:
            log(model, type(e).__name__, time.monotonic() - start, None)
            last_err = e
            continue
    raise RuntimeError("all models in chain failed") from last_err

这段代码里有几个刻意为之的设计：

max_retries=1：SDK 默认带退避重试两次。乘以三个模型，一个坏请求能膨胀成九次调用。每个模型重试一次，足以应对瞬时抖动。
返回应答模型：函数返回了是哪个模型给出的答案。把它和输出一起存下来，当有人反馈某个诡异答案时，你能立刻知道它来自链条中的第三个模型而非第一个。
校验失败也算回退触发器，但只用于生产中你真的会拒绝的检查。"这是不是带有我需要的键的合法 JSON"是好的检查；"这个答案好不好"则不该被塞进重试循环里自动化判断。

第四步：有目的地排列链条顺序

有两种合理的排序方式，各自解决不同问题。

质量优先：最强模型 → 不同家族的同级模型 → 更便宜的模型。适用于面向用户的回答，这类场景下降级的回复也好过一个错误页。把不同家族的模型放第二位很关键：如果首次失败是某厂商全线宕机，同厂的兄弟模型往往也会一起挂掉。

便宜优先：快速廉价模型 → 仅在校验失败时升级到更强模型。这适合抽取、分类和格式化任务——廉价模型在多数情况下都正确，而你的校验器能分辨它什么时候出错。

无论哪种顺序，都要保持链条短。三个模型通常是上限。再往后，最坏路径的延迟会变得很糟：三个 60 秒超时串起来就是一个三分钟的请求。

第五步：盯住提示词，而不只是错误

不同模型对同一个提示词的遵循程度不同。几个踩过的坑：

系统提示强度：一个模型会乖乖执行的简短指令，另一个可能只当作建议。如果回退模型频繁校验失败，解法往往是更明确的提示词，而非换模型。
工具调用：工具 schema 通常能在 OpenAI 兼容端点间沿用，但各模型调用工具的积极程度和参数格式不同。要防御性地解析参数，并用你声明的同一套 schema 来校验。
Max tokens：如果你为主模型设紧了 max_tokens，更啰嗦的回退模型可能在 JSON 中途被截断。检查 finish_reason，若为 length 就当作校验失败处理。
流式输出：流式中途回退很麻烦，因为你已经展示了部分输出。对流式 UI，作者只在第一个 token 到达前回退，之后则直接可见地报错。

工具调用（Function Calling / Tool Use）是指通过在请求中声明 JSON Schema 描述的函数，让模型以结构化 JSON 格式返回函数名与参数，由调用方负责实际执行。OpenAI 于 2023 年推出该功能后，各兼容服务商相继跟进，但实现细节存在差异：部分模型倾向于将参数包裹在额外的嵌套层中，另一些则在未明确要求时会跳过工具调用直接返回自然语言。finish_reason 字段可用于判断模型是否真的触发了工具调用（值为 tool_calls）还是自行给出了文本答案（值为 stop）。在回退链中使用工具调用时，建议将 tool_choice 设为 required 或指定具体函数名，同时在校验函数中检查返回的 JSON 是否符合预期 schema，将 schema 不合规的响应视为校验失败并触发回退。

第六步：主动测试回退路径

没人演练过的回退路径，就是一条不工作的回退路径。两个廉价测试：

在测试里把一个假模型 ID 放在链首，断言调用能通过第二个模型成功。这证明 404 路径有效。
传入一个永远返回 False 的校验器，断言在恰好 len(CHAIN) 次尝试后抛出 RuntimeError。这证明你既没有无限循环，也没有吞掉最后的错误。

在生产中，统计每个模型应答的频率。如果第二个模型在应答 20% 的请求，那已经不是韧性了——那说明你的主模型选错了。

关于成本的提醒

在按 token 计费的模式下，每一次产生了输出的回退尝试都要花钱，而校验触发的回退可能悄悄让某个功能的账单翻倍。在扁平费率方案下，成本问题则变成了请求数问题，要盯住的是每个用户动作触发了多少次尝试。无论哪种计费方式，循环里那行日志都是你看清真相的依据。

小结

整套方案可以浓缩为几条原则：

从 /v1/models 拉取模型 ID，并在启动时校验。
对 404、持续 429、5xx、超时和校验失败触发回退。
对 401、403 和 400 立即抛出。
把 SDK 自身的重试次数压低，避免尝试次数成倍膨胀。
记录是哪个模型应答、链条控制在三个左右、主动测试回退路径。

大约四十行代码，就能把"模型挂了"从一次宕机变成一条日志记录。