在避免重复输出的前提下路由模型

逻辑模型与物理模型

Router 向 Agent 暴露一个逻辑 ModelRef，并在多个命名物理 Route 中选择。服务商拓扑 变化时，Prompt、Tool、RunContext 与下游可观测性仍保持稳定。

路由不代表模型在行为上可以互换。同一逻辑池中的每条 Route 都必须单独验证输出质量与 能力支持。

构建 Router

use std::{sync::Arc, time::Duration};
use runifold::{
    Agent, CircuitBreakerConfig, ModelFallbackPolicy, ModelRef,
    ModelRouter,
};
 
let logical = ModelRef::new("router", "assistant");
let router = ModelRouter::builder(logical.clone())
    .route(
        "primary",
        primary_model,
        ModelRef::new("openai", "gpt-5"),
    )
    .route(
        "backup",
        backup_model,
        ModelRef::new("anthropic", "claude-sonnet"),
    )
    .fallback_policy(ModelFallbackPolicy::safe_only())
    .circuit_breaker(CircuitBreakerConfig::new(
        3,
        Duration::from_secs(30),
    )?)
    .build()?;
 
let agent = Agent::builder("assistant", Arc::new(router), logical)
    .build()?;

Route 名称应稳定，用于指标与运营。不要包含凭证、租户 ID 或临时主机名。

重试与 Fallback 安全

Retry 会重复同一物理 Route；Fallback 会选择另一 Route。如果服务商可能已经接受第一 个请求，两者都可能产生重复成本。

默认 Fallback Policy 只接受明确标记为 Retry-safe 的错误。允许安全性 Unknown 的错误 类型，等于显式接受再次计费风险。同时遵守服务商 Retry-After、调用 Deadline 和共享 Run Budget。

取消永远不会触发 Retry 或 Fallback。

流式锁定

第一个规范化流事件可见后，Runifold 会锁定所选 Route。输出一部分后切换服务商，可能 重复文本、工具调用或推理，Consumer 无法可靠合并。

因此流中途失败会如实返回失败，不会被另一模型的新答案掩盖。界面应保留部分进度， 同时明确展示最终状态。

运行 Router

熔断器按物理 Route 独立计数。达到阈值后，该 Route 会跳过一个 Cooldown，随后恰好 一个 Half-open 请求探测恢复。

把 route_health() 导出到 Readiness 诊断与运营面板。按 Route 监控选择次数、失败 分类、Retry 次数、熔断状态、延迟、Token 与质量。

路由检查清单：

• 同一逻辑池只放满足同一产品契约的模型；
• 显式设置 Retry 与 Fallback Policy；
• 测试限流、发送前断网、响应丢失与流中断；
• 非幂等 Tool 使用 Effect，Router 无法让写操作变安全；
• 增加或提升 Backup Model 前运行质量评估门禁。