← 返回博客

AI API 高可用:请求级模型 fallback 配置与单次对账

Zivv••10 分钟阅读
高可用模型 fallback最佳实践

线上服务接了大模型以后,最怕的不是模型答得不好,而是模型突然答不了:上游限流、高峰过载、模型临时下架,用户那边看到的就是一串报错。常见的补救是在业务代码里写重试和降级逻辑,但重试同一个模型往往还是失败,自己写降级又要处理一堆边界情况。Zivv 在网关层提供了请求级模型 fallback:主模型不可用时自动换备选模型,一个请求、一次往返。这篇讲它怎么用、什么时候会切换,以及怎么查清每个请求最终用了哪个模型、花了多少钱。

两层保护:先换渠道,再换模型

Zivv 对每个请求有两层容错:

  1. 渠道层:同一个模型通常有多个上游渠道。某个渠道限流、过载或故障时,网关会按错误类型重试或切到同模型的其它渠道,这一层不需要任何配置
  2. 模型层:如果这个模型的所有渠道都不可用,带了备选模型的请求会换下一个模型继续,这就是本文讲的 fallback

大部分偶发故障在渠道层就消化了。模型层兜的是更大的问题:某个模型整体限流、整体过载,或者被下架。

怎么配置:请求体里加 models

在请求体顶层加一个 models 数组,列出按优先级排序的备选模型(字段名与 OpenRouter 相同):

curl https://zivv.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "models": ["claude-opus-5-5", "claude-haiku-5-5"],
    "messages": [{"role": "user", "content": "Hello"}]
  }'

几条规则:

  • 支持 /v1/chat/completions、/v1/messages 和 /v1/responses(包括 Responses 的 WebSocket 模式)
  • 最多取前 3 个备选,自动去重,和 model 相同的项会被去掉
  • models 字段不会转发给上游;格式不对(不是字符串数组)会直接返回 400
  • 换到备选模型后,鉴权白名单、定价、内容审核、选路、计费都按新模型重新走一遍

什么情况会换模型

只在「换个模型可能就好了」的时候才换:

情况是否切换
模型没有可用渠道切换
全部渠道限流、过载或故障(返回 429、5xx、529)切换
模型被下架、没有定价、不在 Key 的模型白名单里切换
请求本身有问题(确定性的 4xx,比如参数错误)不切换
内容被拦截不切换
Key 的分组没有权限不切换
客户端已断开不切换
已经开始向客户端输出内容不切换

最后一条对流式请求很重要:一旦第一段内容发给了你,就不会再中途换模型,避免一个回答前半段来自 A 模型、后半段来自 B 模型。坏请求不切换也是同样的道理:参数错了换哪个模型都会错,切换只会浪费时间。

在代码里使用

OpenAI Python SDK 用 extra_body 传 models,用 with_raw_response 读响应头:

from openai import OpenAI

client = OpenAI(base_url="https://zivv.pro/v1", api_key="sk-your-key-here")

raw = client.chat.completions.with_raw_response.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "总结一下这份周报的要点"}],
    extra_body={"models": ["claude-opus-5-5", "claude-haiku-5-5"]},
)
resp = raw.parse()
print("实际模型:", raw.headers.get("x-zivv-model"))
print("请求 ID:", raw.headers.get("x-request-id"))
print(resp.choices[0].message.content)

Anthropic SDK 同样支持 extra_body:

import anthropic

client = anthropic.Anthropic(base_url="https://zivv.pro", api_key="sk-your-key-here")

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"models": ["claude-opus-5-5"]},
)

响应头 X-Zivv-Model 是实际提供服务的模型。有一种情况会没有这个头:前一次尝试期间网关为了保活已经提前发出了响应头。这时以下面的 /v1/generation 查询结果为准。

备选模型怎么挑

  • 能力相近:备选模型要能完成同样的任务。日常任务用同档或高一档,追求可用性时可以降一档兜底
  • 跨厂商更抗风险:同一厂商的模型可能同时受影响,备选里放一个其它厂商的模型更稳。各模型能力对比见 Claude 模型对比 和 国产大模型接入
  • Key 要能访问:备选模型必须在 Key 的分组里,跨分组时用智能路由 Key 勾选多个分组;分组权限不足不会触发切换
  • 协议和功能要支持:走 /v1/messages 的请求,备选模型要支持 Anthropic 协议;用到工具调用、结构化输出时,确认备选模型也支持
  • 提示词要兼容:针对某个模型精调过的提示词,换到别的模型效果可能打折,上线前用备选模型单独跑一遍

单次请求对账:/v1/generation

每个响应都带有 X-Request-ID 头。用它查询这次请求的完整情况:

curl "https://zivv.pro/v1/generation?id=<X-Request-ID>" \
  -H "Authorization: Bearer sk-your-key-here"

返回的 data 里包括:

  • model / upstream_model:最终服务的模型
  • status_code、duration_ms、ttft_ms:最终状态码、总耗时和首字延迟
  • total_cost:全部尝试加总的费用,以及 input_tokens、output_tokens、cached_tokens 等 Token 数
  • models_tried:按顺序尝试过的模型
  • attempts:每一次尝试的明细

几个注意点:只能查自己的请求,查别人的或不存在的一律返回 404,结果里不含任何渠道信息;用量是请求结束后批量写入的,刚结束的请求可能要等几秒才查得到;团队 Key 按执行成员归属。

这个接口很适合接进自己的监控:定期抽样查询,统计 fallback 触发的比例和实际成本,主模型频繁被换掉时就该调整默认模型了。

常见问题 FAQ

Q:Claude Code 能用模型 fallback 吗? A:Claude Code 不支持往请求体里加自定义字段,所以用不了 models。不过渠道层的自动切换对 Claude Code 一样生效,日常偶发的限流和过载大多在这一层就被消化了。

Q:fallback 和 SDK 自带的重试有什么区别? A:SDK 重试是把同一个请求原样再发一次,还是同一个模型;fallback 在网关内部换成另一个模型,一次往返完成,不需要客户端写任何降级逻辑。两者可以同时开。

Q:失败的尝试要付费吗? A:以 /v1/generation 返回的 total_cost 为准,它把这个请求的全部尝试加总,控制台用量页里同一个请求 ID 的多条记录也能对上。

Q:备选模型最多能写几个? A:最多生效 3 个。超过 3 个只取前 3 个,再多的话通常说明默认模型选得不合适。

写在最后

网关层的模型 fallback 让「换模型」这件事不再需要改代码:多写一行 models,主模型出问题时请求自动落到备选模型,再用 X-Zivv-Model 和 /v1/generation 把每一次切换查清楚。配合 多模型路由策略 和 429 限流排查,可以把线上 AI 功能的可用性做得更稳。注册 Zivv 就能直接使用,不需要额外开通。