文档 · 核心概念 · 多上游路由

多上游路由

一把 BUZZ key 后面接多个同样跑 Claude 模型的上游供应商。BUZZ 在幕后帮你把请求解析到一个健康通道,瞬时失败时重试,某一家过载时跨上游故障转移。从你的代码视角看,这一切都不可见:URL 不变、key 不变、响应形状不变。

解决什么问题

直连 Anthropic 时,你只有一个上游。Anthropic 返 529 overloaded,你只能等。某区域故障让你延迟翻倍,你还是只能等。如果你同时握着多个 Anthropic 兼容供应商的容量(Anthropic 一方、AWS Bedrock、Google Vertex、第三方分销),理论上可以绕过故障,但代价是你的应用必须知道每一家、保管每一份凭据、自己实现故障转移逻辑。

多上游路由把这套逻辑下沉到网关。你只持有一把 BUZZ key,BUZZ 持有与每家上游的关系。

模型:group 和 channel

两个概念就足够描述整个系统。

channel 是一份单独的上游凭据:一把 Anthropic key、一份 Bedrock IAM 会话、一个 Vertex 服务账户。每个 channel 携带它服务哪些模型、优先级、权重,以及哪些进阶 flag(service_tier、inference_geo、speed)被允许转发。

group 是带路由策略的 channel 集合,有名字。你的 API key 唯一绑定到一个 group。请求到达时,BUZZ 根据请求的 model、过滤出 group 内可服务该 model 的 channel,套用 group 的策略选一个。

你的 KEY (group: "production") | v +-----------------------------+ | group: production | | policy: priority + weight | | ---- | | channel A (anthropic) pri=1 weight=10 models=[opus,sonnet,haiku] | channel B (bedrock-us) pri=1 weight=5 models=[sonnet,haiku] | channel C (vertex-eu) pri=2 weight=1 models=[sonnet] +-----------------------------+ | v 被选中 = 服务该模型、优先级最高、健康的 channel

这个结构同时支持分级套餐:"free" group 只指向较慢、便宜的 channel;"pro" group 指向 Anthropic 一方;"enterprise" group 指向私有专属 channel 池。

通道选择

每次请求,BUZZ 跑一段确定性的小流程:

按 model 过滤。剔除不服务该 model 的 channel。
按健康度过滤。剔除最近失败导致冷却中的 channel。
按能力过滤。请求带通道级参数(service_tier 等)时,剔除不允许该参数的 channel。
按优先级再按权重。在最高优先级的存活集合中按权重随机抽一个。低优先级保留给故障转移。
转发。请求经选中的 channel 流式转发。

如果过滤完什么都不剩,BUZZ 返 HTTP 503 buzz_error / model_not_found。这个错误码与 Anthropic 自己的模型错误明确区分,你一眼就知道是上游可用性问题还是模型名拼错。

故障转移与重试

真实上游会失败。BUZZ 把上游响应分三类:

类别	例子	处理
客户端永久错误	400 invalid_request、401 auth、403 permission	原样回给调用方,不重试
上游瞬时错误	500、503、529 overloaded、连接 reset	该 channel 标记冷却,按下一优先级重试。每请求总预算受限
限流	429 携带 `retry-after`	该 channel 按建议时长冷却,故障转移

重试预算很小(通常 2 次),为的是延迟可控。故障转移在向你的客户端发出第一个字节之前完成;一旦流式响应已经开始,BUZZ 不会在中途偷换上游,因为那会破坏 SSE 事件流。

优先级路由

优先级是运维侧塑造成本与质量的杠杆。一种常见配置:

优先级 1:Anthropic 一方,最高保真度,完整特性面,承接大部分流量。
优先级 2:另一朵云供应商(Bedrock、Vertex)。优先级 1 冷却时启用。
优先级 3:储备容量。仅在 1、2 同时打满时启用。

同优先级内,权重决定流量分配。两个 weight 分别是 10 和 5 的优先级 1 channel,大约承接 2/3 和 1/3 的流量。

这同时是 BUZZ 暴露高级特性又不破坏兼容性的方式:把 allow_service_tier=true 的 channel 放进高级 group;客户端发 service_tier: priority 的请求会路由进去,其他人则落回标准 channel。

响应里看到什么

所选上游不会被回写进 Anthropic 标准响应形状,这是有意为之 —— 一旦回写就破坏了即插即用兼容。这条信息在两处可以无歧义获取:

BUZZ 结构化日志的 request_id 字段,可在控制台查询。
当 group 显式开启时,可选的响应头 x-buzz-channel。

大多数业务的正确答案是 "不看":路由属于运维关注点,不是应用关注点。需要看的场景(比如把账单按上游分桶),再开启 channel 头。