故障自愈与跨模型容灾降级

故障自愈与跨模型容灾降级（Auto Retries & Fallback Resilience）是 OmniCortex 保障企业 AI 生产业务连续性的核心调度底座。它通过建立同供应商局部退避瞬换与跨厂商全局容灾降级链的两级自愈体系，在主力模型服务商发生网络超时、机房宕机或 429 速率限制时，由网关内核静默完成亚毫秒级流量无感平移，结合安全围栏短路阻断与首字流式门控，消除企业大模型服务单点瘫痪风险。

---

核心机制与两级自愈架构

1. 基于模型别名机制的多供应商降级 (Alias-Driven Fallback)

在企业微服务架构中，绝不应要求业务客户端在代码中硬编码任何具体云厂商的物理模型名称或降级列表。OmniCortex 推荐的最佳实践是通过“逻辑模型别名（Model Alias）”在网关层抽象并绑定多供应商候选链路。

例如构建“官方直连云 ➔ 托管云平台 ➔ 本地私有自建算力”的三级跨云多活容灾拓扑：

🎯

客户端统一逻辑入口：model: "chat-prod"

业务端仅依赖逻辑别名发起调用，底层由网关内核按照设定优先级实现三级跨云多活调度

客户端长连接保持 · 业务 0 感知

🚀

第 1 阶梯 · 主力直连通道 (Primary)

deepseek / deepseek-chat

首选官方直连商用通道 · 原生特性与最低网络跳数

⚡ 遇到 503 机房故障 / 429 局部退避耗尽 ➔ 网关内核自动向下漂移

☁️

第 2 阶梯 · 备选通道 A (Fallback 1)

aliyun / deepseek-chat

阿里云百炼托管版 · 同规格模型跨云跨机房秒级代接

⚡ 遇到公网主干故障 / 托管云平台整体限流 ➔ 网关内核触发终极兜底

🛡️

第 3 阶梯 · 备选通道 B (Fallback 2)

vllm / deepseek-chat-local

企业自建私有化算力引擎 · 外网完全阻断时的终极兜底保障

✅ 成功获取模型流式/非流式响应，透明回传业务客户端

核心配置与流转规则

• 统一逻辑模型别名定义：在网关模型目录与路由规则中，创建一个对外的统一逻辑别名（例如 chat-prod 或场景别名 general-chat）；
• 别名绑定有序提供商链路 (Ordered Provider Candidates)：为该别名配置多个后端承接目标及优先级顺序：
  • 优先级 1 (Primary)：deepseek / deepseek-chat（首选官方商用通道，保障原生特性与最低网络跳数）；
  • 优先级 2 (Fallback 1)：aliyun / deepseek-chat（备选阿里云百炼托管通道，官方机房故障时同规格代接）；
  • 优先级 3 (Fallback 2)：vllm / deepseek-chat-local（企业内网私有算力节点，外网中断时的最终兜底）。
• 客户端透明调用：业务端请求仅需指定逻辑别名：

  {
    "model": "chat-prod",
    "messages": [{"role": "user", "content": "Hello"}]
  }

• 网关路由自动推进：
  1. 网关收到对 chat-prod 的调用后，默认投递给优先级 1 的官方通道；
  2. 若官方通道发生网络不可达、连续 5xx 宕机或局部重试耗尽，网关 Routing Engine 自动拦截错误，提取 chat-prod 别名配置的下一个候选通道（阿里云百炼），透明重写目标并派发请求；
  3. 客户端 HTTP 连接全程不断开，业务系统对底层供应商切换完全零感知。

2. 两级分层自愈体系 (Two-Tier Resilience)

面对上游大模型服务偶发的网络抖动、机房断缆或账号级配额耗尽，网关按故障严重程度分层实施自愈调度：

• 第一级：同供应商局部凭证自愈 (Local Key Rotation & Retries)
  • 凭证故障秒换：当调用遇到 401 Unauthorized（物理 Key 意外失效或被上游封禁）或额度冻结时，网关立即在同 Provider 的凭证池内瞬时轮换至其他健康 Key，避免无效等待；
  • 指数退避重试 (Full Jitter Backoff)：当遇到 429 Too Many Requests 或瞬态连接超时时，网关在当前 Provider 内部执行基于指数退避加抖动的局部重试，平滑等待上游窗口配额恢复。
• 第二级：跨厂商全局容灾降级 (Cross-Provider Fallback)
  • 当第一级局部重试达到最大阈值、当前供应商所有物理 Key 全量耗尽，或直接遇到上游 5xx 宕机错误时，网关自动触发跨供应商 Fallback；
  • 流量自动沿别名绑定的多供应商候选链（如 deepseek ➔ aliyun ➔ vllm）依次向下推进，直至获取有效响应。

3. 安全围栏短路阻断机制 (Safety Short-Circuit)

高可用降级必须建立在绝对合规与数据安全的前提之上。网关在底层构建了严格的安全短路铁律：

• 拦截短路 (AllowFallbacks = false)：当主链路因命中安全围栏插件（如 Prompt 提示词注入、越狱攻击、敏感词或违规指令拦截）被拒绝时，网关内核强制标记该请求不允许 Fallback；
• 防止违规内容扩散：系统直接向客户端返回拦截响应，严禁将存在安全风险的恶意 Payload 轮换投递到备选供应商二次尝试，切实捍卫企业安全防线。

4. 流式传输首字前容灾门控 (Stream Fallback Gate)

在流式输出（SSE / Server-Sent Events）场景下，降级策略与文本传输时序紧密相关：

• 首字延迟 (TTFT) 前容灾：在首个 Data Chunk 尚未推送到客户端连接前，若上游发生超时或握手失败，网关安全切断当前通道并静默重试备用链路，保障客户端首字正常吐出；
• 首字输出后通道锁定：一旦首个 Chunk 已写入客户端连接，网关立即锁定当前通信通道，禁止发生模型中途漂移，彻底避免多模型回复内容相互撕裂与文本错乱拼接。

5. 主动健康心跳探测与亚健康摘除

为防止流量持续打入已知异常的供应商，网关后台维护独立的健康巡检协程：

• 故障端点动态隔离：当某个供应商或特定端点连续返回错误达到失败阈值，网关主动将其移入亚健康隔离区，后续请求直接越过该节点执行 Fallback，消除无谓的网络超时开销；
• 无人值守探测自愈：后台心跳协程持续向被隔离节点发送健康探测，确认端点网络恢复稳定后自动将其重新纳入活跃轮询池。

---

控制台配置与全链路可观测

管理入口：模型与治理 ➔ 供应商管理 ➔ 网络配置，以及 可观测性 ➔ LLM 全量日志。

1. 供应商网络重试与退避配置

在供应商高级配置抽屉的「网络」选项卡中，调整局部重试与退避参数。

📸 截图替换指引（图 1：供应商网络重试与退避配置抽屉）

• 需截图内容：在「供应商管理」中点击右上角「配置」按钮，滑出 720px 高级抽屉，切换至「网络 Network」Tab。
• 关键画面要素：
  1. 重试参数输入区：最大重试次数（max_retries，如设为 3）；
  2. 指数退避时间滑块：初始退避毫秒数（retry_backoff_initial，如 500ms）与最大退避毫秒数（retry_backoff_max，如 5000ms）；
  3. 超时与连接池控制：默认请求超时（default_request_timeout_in_seconds）与流式空闲超时。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/resilience/zh/retry-config.png
  • 英文版：Documentation/docs/public/images/resilience/en/retry-config.png

2. LLM 运行日志中的 Fallback 命中追溯

进入可观测日志面板，可按 routingEngine=fallback 快速检索发生过容灾降级的请求详情。

📸 截图替换指引（图 2：LLM 运行日志中的 Fallback 命中追溯详情）

• 需截图内容：进入「可观测性」→「LLM 运行日志」（/observability/llm-logs），在检索栏筛选 routing_engine=fallback，点击一条发生过容灾降级的请求查看详情弹窗。
• 关键画面要素：
  1. 顶部状态标签：高亮展示 Routing Engine: Fallback 与 Status: 200 OK；
  2. 主备链路执行轨迹：清晰呈现 Primary 模型（如 openai/gpt-4o 失败标签）与 Actual 承接模型（如 anthropic/claude-3-5-sonnet 成功标签）；
  3. 自愈耗时统计：显示局部重试次数（Retries: 2）、Fallback 索引（Fallback Index: 1）及降级总耗时。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/resilience/zh/fallback-chain-log.png
  • 英文版：Documentation/docs/public/images/resilience/en/fallback-chain-log.png

核心配置规格参数表

配置参数 / 字段	数据类型	默认值 / 约束	语义作用与工程建议
max_retries	整数	默认 0 (生产建议 2~3)	网络超时或 429 时的同供应商内部最大重试次数。
retry_backoff_initial	整数 (毫秒)	默认 500	首次重试前的初始等待时间基数。
retry_backoff_max	整数 (毫秒)	默认 5000	退避上限时长，防止指数退避时间过长阻塞客户端连接。
stream_idle_timeout_in_seconds	整数 (秒)	默认 30	流式首字前等待上游的最长阈值，超限触发链路切换。

---

常见异常排查与故障处理

聚焦与容灾链路流转、跨云备选与流式截断深度绑定的异常。

现象 / 错误码	根因排查方向	推荐处理方案
502 All Fallbacks Exhausted	主模型及 fallbacks 链中声明的所有备用模型均发生连接超时、429 配额耗尽或未配置有效物理凭证。	1. 检查备选链中各供应商的物理 Key 状态与上游余额； 2. 核对各备选 Provider 是否已在控制台中完成纳管； 3. 验证备选链路的出向网络连通性。
400 Safety Policy Violation (未触发 Fallback)	请求被安全围栏阻断（命中 Prompt 注入或违规敏感词），网关按安全策略强制终止降级。	1. 此为系统预期的合规防御行为（底层触发 AllowFallbacks=false 短路机制）； 2. 前往「安全拦截日志」查看威胁取证详情，优化客户端 Prompt。
400 Context Length Exceeded (降级后报错)	备选模型的最大上下文窗口（context_window）小于主模型，降级后当前会话 Prompt 超出备选模型承载上限。	1. 规划备选链路时，优先挑选相同或更大上下文规格的同梯队模型； 2. 在「模型目录」中核对备选模型的上下文规格，必要时在业务侧执行前置上下文修剪。
流式传输中途断开未自动降级	首个 SSE Chunk 已经输出给客户端后，上游才发生连接异常或网络中断。	1. 此为保障数据一致性的防御机制（首字后锁定通道，防止上下文拼装错乱）； 2. 在网络抽屉中调大 stream_idle_timeout； 3. 建议客户端针对非首字断连实现轻量级断点重试。