企业官网建设流程全解析

GoModel 是一个用 Go 编写的开源 AI 网关（AI Gateway / AI 控制平面），它统一提供 OpenAI 兼容与 Anthropic 兼容的 API，将 OpenAI、Anthropic、Gemini、Groq、xAI、Ollama、vLLM 等上游模型服务收拢到一个入口后面。本文聚焦它的故障转移（Failover）与弹性（Resilience）设计：内置的指数退避自动重试、按 Provider 隔离的熔断器（Circuit Breaker）、以及基于虚拟模型（Virtual Model）的跨模型故障转移链——三层保护让 Provider 报错、限流、超时时请求被自动接管，无需人工干预。

为什么 AI 网关需要故障转移：三类常见的上游故障

AI 网关位于你的应用和多个模型供应商之间，而上游不稳定是常态而非例外：

更棘手的是最后一种："还活着"的慢 Provider 永远不会报错，传统错误检测对它无效。GoModel 的弹性设计正是针对这四类场景逐层设防。

GoModel 弹性架构：三层保护一览

GoModel 为每一次上游 Provider 调用包裹了多层弹性机制，由内到外：

1. 自动重试（Retry）—— 对同一 Provider 指数退避重试。默认即覆盖429、502、503、504、522、524等瞬时状态码。
2. 熔断器（Circuit Breaker）—— 按 Provider（或按模型）统计连续失败，达到阈值后快速失败并定时探测，直到自动恢复。
3. 跨模型故障转移（Failover）—— 前两层救不回来时，沿虚拟模型定义的故障转移链，按声明顺序自动尝试备用目标。

前两层解决"同一个 Provider 怎么重试、什么时候放弃"；第三层回答"什么时候换一家模型"。三者默认参数分别定义在 config/resilience.go 与 config/failover_policy.go 中。

第一层 | 指数退避自动重试：零配置即可用

默认参数已经按"生产安全"调过，大多数部署无需改动：

两个值得注意的细节：

• 流式请求一旦开始发送就不再重试——部分数据可能已经发给客户端，透明重放会破坏回答。但 GoModel 会在首个字节到达前做故障转移判定，空流会被当作502处理。
• Idempotency-Key会原样转发给 Provider 及每一次重试，支持按 key 去重的供应商可以识别重放请求。

第二层 | 熔断器：对坏掉的 Provider 快速失败

重试解决的是"偶发抖动"，而一个持续出错的 Provider 需要被暂时隔离——这就是熔断器的职责。默认行为：

熔断打开期间，请求不再排队苦等超时，而是立即收到一条可触发故障转移的503（circuit breaker is open - provider <name> temporarily unavailable），随即进入第三层保护。每经过timeout，放行一个探测请求试探上游，连续success_threshold次成功即自动恢复，全程无需重启。

🐌对付"慢而不断"：把slow_call_threshold设为你健康请求的慢上限（如60s），连续慢调用同样会触发熔断——这是 GoModel 区别于多数网关的能力。注意此时建议配合scope: model，避免同一 Provider 上快的模型不断重置慢模型的计数。

熔断器状态是内存态、按网关进程独立，重启即重置；开启 Prometheus 指标后还会导出gomodel_circuit_breaker_state指标（0=闭合，1=半开，2=打开）。

第三层 | 跨模型故障转移：用虚拟模型搭建保护链

当某个目标的重试耗尽（或熔断打开）后，GoModel 会沿着虚拟模型的故障转移链自动切换。只需声明一个failover策略的虚拟模型，把目标按优先级排好：

virtual_models: - source: resilient-chat strategy: failover targets: - { model: openai/gpt-4o } - { model: anthropic/claude-sonnet-4-6 } - { model: ollama/qwen3:8b }

客户端请求model: resilient-chat，GoModel 总是优先打向第一目标；失败后按声明顺序尝试后续目标，首个成功即返回。也可以在 Dashboard 的 Models 页面直接为某个真实模型添加回退目标（策略默认即 Failover），无需改动客户端代码：

哪些失败会触发故障转移？

• 5xx服务端错误（含隐藏错误的502）
• 429限流——被限满的目标会被跳过，把流量让给有容量的目标
• "模型不存在 / 已下线 / 被禁用"类错误（model not found、model deprecated等短语匹配，与状态码无关）
• 聚合类 Provider 用4xx转发的上游失败（如400 "Upstream request failed"）
• 200但choices为空的响应，按502处理

被禁用的目标、当前 API Key 无权使用的目标会被静默跳过，不计入尝试次数。每次尝试都会写入请求日志，响应按实际应答的模型计费，审计轨迹里能清楚看到故障转移发生过。

实战组合：先重试 Cloudflare 超时，再自动换模型

对非流式请求，三层机制可以叠加使用：同一模型上先重试 Cloudflare522/524，彻底失败后再切到备用模型。合并以下配置到你的config.yaml：

providers: cloudflare: resilience: retry: max_retries: 2 retry_on_statuses: [429, 502, 503, 504, 522, 524] circuit_breaker: scope: model # 一个模型熔断不牵连同 Provider 的其他模型 failure_threshold: 5 virtual_models: - source: resilient-chat strategy: failover targets: - { model: cloudflare/model1 } - { model: cloudflare/model2 }

效果：model1返回524时最多重试 2 次；3 次全部失败后自动请求model2（它拥有自己独立的重试预算）；model1熔断打开期间直接跳过，不再阻塞model2。

Dashboard 监控：熔断器状态与每次尝试一目了然

弹性机制不是黑盒。Dashboard 的 Providers 页面把每个 Provider 的健康状况摊开给你看：状态药丸（Healthy / Degraded / Circuit Open / Recovering）、最近 10 分钟请求成败统计、Breaker State芯片，以及生效的重试与熔断器参数（3 retries, 1s initial, 30s max, factor 2, jitter 0.1这样的人类可读格式）：

熔断打开时状态药丸变为Circuit Open，恢复中显示Recovering；Provider 掉线时模型列表会自动隐藏其模型（全部 Provider 同时故障则保留旧库存，避免把"上游报错"变成"模型不存在"），快检循环每 60 秒重探一次，上游恢复后通常一分钟内流量回归。

配合审计日志，每一次重试、每一次故障转移都有据可查——日志按会话分组，右侧面板可回看完整的请求交互：

故障转移与熔断器实现在哪里

想深入源码或完整文档，可以从这些入口开始：

• 重试与熔断器默认配置：config/resilience.go
• 故障转移触发状态与错误短语清单：config/failover_policy.go
• 客户端侧重试 / 熔断实现：internal/llmclient/
• 网关编排（重试与故障转移的衔接）：internal/gateway/
• Provider 健康状态 API：internal/admin/handler_providers.go
• 官方文档：Resilience（弹性与熔断器调优）、Failover（故障转移链）、Virtual Models（虚拟模型）、Provider Failure Modes（各类故障的处理契约）

一句话总结：GoModel 把"重试 → 熔断 → 跨模型故障转移"做成默认开启的三层保护，绝大多数部署零配置即可获得生产级稳定性；而需要精细调优时，每一层的阈值都能通过 YAML 或环境变量独立控制。