线上服务接了大模型以后,最怕的不是模型答得不好,而是模型突然答不了:上游限流、高峰过载、模型临时下架,用户那边看到的就是一串报错。常见的补救是在业务代码里写重试和降级逻辑,但重试同一个模型往往还是失败,自己写降级又要处理一堆边界情况。Zivv 在网关层提供了请求级模型 fallback:主模型不可用时自动换备选模型,一个请求、一次往返。这篇讲它怎么用、什么时候会切换,以及怎么查清每个请求最终用了哪个模型、花了多少钱。
两层保护:先换渠道,再换模型
Zivv 对每个请求有两层容错:
- 渠道层:同一个模型通常有多个上游渠道。某个渠道限流、过载或故障时,网关会按错误类型重试或切到同模型的其它渠道,这一层不需要任何配置
- 模型层:如果这个模型的所有渠道都不可用,带了备选模型的请求会换下一个模型继续,这就是本文讲的 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 就能直接使用,不需要额外开通。