AI Agent / 系统课时

配置节点重试与超时边界

配置节点重试与超时边界

外部模型、HTTP 服务和工具调用会遇到短暂抖动,也会遇到不可恢复的业务错误。本篇把“是否重试、等多久、最多几次、单次最长多久”放到节点策略里,避免一个不稳定节点无限占用整张图。

学习目标

  • 用 RetryPolicy 只重试暂时性异常,并配置退避、抖动与最大尝试次数
  • 为异步节点设置单次执行超时,让卡住的调用及时失败
  • 区分可重试故障、永久错误与具有副作用的节点边界

先划分哪些失败值得重试

重试不是“捕获所有异常再试一次”。网络断连、限流、临时上游错误通常具有瞬时性;参数校验失败、权限拒绝、业务规则冲突则往往重复执行也不会改变结果。RetryPolicy.retry_on 可以接收异常类型、异常类型序列或判断函数,因此最稳妥的做法是把可恢复错误显式列入白名单。当前 API 中 max_attempts 统计总尝试次数,包含第一次执行。 ([LangChain 参考文档][2])

退避用于避免故障期间立即形成请求风暴。initial_interval 决定首次重试前等待多久,backoff_factor 让后续间隔逐步放大,max_interval 限制最长等待;jitter 可打散大量并发实例同时重试的时间点。

重试与超时如何组合

超时解决“单次尝试卡太久”,重试解决“失败后是否再给机会”。在当前 Python Graph API 中,add_node 可同时设置 retry_policy 与 timeout;超时会产生 NodeTimeoutError,随后仍由重试策略判断是否重试。节点超时只支持可取消的异步节点,同步阻塞函数不能依赖这一机制安全中断。 ([LangChain 参考文档][3])

节点重试、退避与超时决策流程

把超时设得极短会把正常慢请求误判为故障,把重试次数设得过高则会放大下游压力。两者必须结合服务的正常延迟分布和调用成本设置,而不是统一套一个全局数字。

完整示例

下面模拟一个前两次失败、第三次成功的异步远程调用。策略只对白名单中的 TransientError 和 NodeTimeoutError 重试,并把每次尝试的硬超时设为 0.2 秒。

python
import asyncio

from typing_extensions import TypedDict
from langgraph.errors import NodeTimeoutError
from langgraph.graph import END, START, StateGraph
from langgraph.types import RetryPolicy

class State(TypedDict, total=False):
    result: str

class TransientError(RuntimeError):
    pass

attempts = 0

def retry_if_transient(exc: Exception) -> bool:
    return isinstance(exc, (TransientError, NodeTimeoutError))

async def fetch_remote(state: State) -> dict:
    global attempts
    attempts += 1
    print(f"attempt={attempts}")

    # 模拟一次可取消的异步网络等待。
    await asyncio.sleep(0.05)
    if attempts < 3:
        raise TransientError("temporary upstream failure")
    return {"result": "ok"}

builder = StateGraph(State)
builder.add_node(
    "fetch_remote",
    fetch_remote,
    retry_policy=RetryPolicy(
        initial_interval=0.05,
        backoff_factor=2.0,
        max_interval=0.2,
        max_attempts=3,
        jitter=False,
        retry_on=retry_if_transient,
    ),
    timeout=0.2,
)
builder.add_edge(START, "fetch_remote")
builder.add_edge("fetch_remote", END)
graph = builder.compile()

async def main() -> None:
    result = await graph.ainvoke({})
    print(result)

asyncio.run(main())

预期输出

text
attempt=1
attempt=2
attempt=3
{'result': 'ok'}

如果把节点中的等待时间改成大于 0.2 秒,每次尝试会先触发 NodeTimeoutError;因为判断函数把该异常列为可重试,仍会按同一退避策略再次尝试,直到成功或耗尽 max_attempts。

生产边界

模型推理、网络请求和只读工具通常适合有限重试;扣款、发消息、创建工单等有外部副作用的节点必须先设计幂等键或去重机制,否则一次“超时但服务端实际成功”的请求可能在重试时重复生效。

不要用重试掩盖确定性错误。参数错误、鉴权失败或不可满足的业务条件应尽快失败并交给错误处理分支。对于长时间但持续有进展的异步任务,可以进一步使用 TimeoutPolicy 区分硬运行上限与空闲超时;当前 API 支持 run_timeout、idle_timeout 以及进度刷新策略。 ([LangChain 参考文档][4])

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置节点重试与超时边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通