🎯 课程主题

ModelFallbackMiddleware 用于在主模型不可用时自动切换到备用模型，保证系统正常运行。

📝 核心知识点

1. ModelFallbackMiddleware 概念

• 概念说明：当主模型因网络、欠费等原因无法访问时，中间件会自动将请求转发到备用模型，避免程序异常中断。
• 关键细节：
  • 第一个参数 first_model 是首选备用模型，优先尝试。
  • 第二个参数 additional_models 可传入多个额外备用模型，按顺序依次尝试。
  • 用法：ModelFallbackMiddleware(first_model="claude-sonnet", additional_models=["gpt-4o", "gemini-pro"])
  • 模型参数支持字符串（底层调用 init_chat_model）或模型实例。

2. 验证回退结果

• 概念说明：通过 response_metadata 中的 model_name 字段可确认实际调用了哪个备用模型。
• 关键细节：invoke 响应中的 response_metadata["model_name"] 记录了最终生效的模型名称。

🏗️ 架构与工作流

用户请求 → Agent
              ↓
         主模型调用
              ↓ (失败)
         first_model 尝试
              ↓ (失败)
         additional_models[0] 尝试
              ↓ (失败)
         additional_models[1] 尝试 ...
              ↓ (成功)
         返回结果

💻 代码实战

from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

# 主模型（故意写一个不存在的模型名，演示回退）
model = "deepseek-v4-cat"  # 不存在

# 备用模型列表
fallback_middleware = ModelFallbackMiddleware(
    first_model="deepseek-v4-flash",           # 首选备用
    additional_models=["deepseek-v4-pro"]      # 额外备用（可多个）
)

agent = create_agent(
    model=model,
    middleware=[fallback_middleware]
)

result = agent.invoke({"messages": [{"role": "user", "content": "你好"}]})

# 查看实际使用的模型名称
print(result["response_metadata"]["model_name"])
# 输出: deepseek-v4-flash

⚠️ 常见问题与避坑指南

• 备用模型中 first_model 优先级最高，务必把最可靠、最廉价的模型放在前面。
• 如果所有备用模型也都不可用，程序仍然会抛异常，建议配置足够数量的备用模型。

💡 个人总结与延伸

ModelFallbackMiddleware 是一个简单但实用的容灾机制，类似微服务中的熔断降级。在生产环境中可以结合成本控制策略，优先回退到免费或低成本的模型，避免因主模型欠费导致整个 Agent 链中断。