🎯 课程主题
ModelRetryMiddleware 基于指数退避算法，在模型调用失败时自动重试，与 ToolRetryMiddleware 参数体系一致，用于应对大模型 API 临时不可用的情况。
📝 核心知识点
1. ModelRetryMiddleware 概念
- 概念说明：当调用大模型 API 失败时（如网络波动、限流、模型不存在等），中间件按指数退避策略自动重试，避免程序直接崩溃。
- 关键细节：
- 参数体系与
ToolRetryMiddleware完全一致，包括max_retries、backoff_factor、initial_delay、max_delay、jitter、on_failure。 - 区别在于重试的对象：前者是模型调用，后者是工具调用。
- 同样支持
on_failure的两种模式："continue"（重试耗尽后继续执行）和"error"（重试耗尽后抛出异常）。
- 参数体系与
2. on_failure 的两种行为
| 值 | 行为 |
|---|---|
"continue" | 重试全部失败后，Agent 不抛异常，将错误信息作为 AIMessage 返回 |
"error" | 重试全部失败后，直接抛出异常终止程序 |
🏗️ 架构与工作流
用户请求 → Agent
↓
调用大模型 API
↓ (失败)
等待 delay 秒
↓
重试调用模型
↓ (失败)
... 重复至 max_retries 次
↓ (仍失败)
on_failure="continue" → 返回错误信息给用户
on_failure="error" → 抛出异常终止
💻 代码实战
示例 1：on_failure="continue"（不抛异常）
from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware
# 故意使用不存在的模型名，触发重试
model = "deepseek-v4-cat" # 不存在的模型
model_retry_middleware = ModelRetryMiddleware(
max_retries=6, # 最大重试次数（共执行 7 次）
backoff_factor=2, # 退避因子
initial_delay=1.0, # 初始延迟 1 秒
max_delay=10.0, # 最大延迟上限 10 秒
jitter=False, # 关闭抖动，便于观察
on_failure="continue" # 重试耗尽后继续执行
)
agent = create_agent(
model=model,
middleware=[model_retry_middleware]
)
result = agent.invoke({"messages": [{"role": "user", "content": "你好"}]})
print(result["messages"][-1].content)
# 输出（示例）:
# 共调用了 7 次模型均失败。支持的模型名: deepseek-v4-pro 或 deepseek-v4-flash
# 注意：程序正常结束，未抛出异常
示例 2：on_failure="error"（抛异常）
model_retry_middleware = ModelRetryMiddleware(
max_retries=6,
backoff_factor=2,
initial_delay=1.0,
max_delay=10.0,
jitter=False,
on_failure="error" # 重试耗尽后抛出异常
)
agent = create_agent(
model=model,
middleware=[model_retry_middleware]
)
result = agent.invoke({"messages": [{"role": "user", "content": "你好"}]})
# 执行约 30+ 秒后抛出异常，程序终止
⚠️ 常见问题与避坑指南
on_failure="continue"不会抛异常，但返回内容中会包含错误描述，不适合对结果可靠性要求极高的场景；此时应选择"error"让上层捕获异常并做降级处理。- 模型名写错时，即使开启重试也无法成功，建议在开发阶段先验证模型名有效性。
💡 个人总结与延伸
ModelRetryMiddleware 和 ToolRetryMiddleware 共享同一套重试策略，体现了 LangChain 中间件体系的设计一致性。在实际项目中，两者通常同时启用：模型调用失败用 ModelRetryMiddleware 兜底，工具调用失败用 ToolRetryMiddleware 兜底，形成双层容错保护。