《AI Agent 技术原理与架构·运行时、协议与系统架构》5.2 校验、幂等与重试

重试不是重复调用,它要回答隔多久、试几次、哪些错误值得试。实验给出指数退避序列、封顶与抖动,量化重试的成功率收益,并演示全抖动如何把峰值集中摊开。结论是退避要指数、要有上限、要加抖动,成功率随重试次数收敛到 1,但永久错误重试没有意义。重试策略要与幂等键配合,防止重试放大副作用。

以下退避序列、失败率、抖动种子均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。seed=7 的全抖动序列是讲解用的确定性演示,真实系统用随机种子,但"退避要有上限、抖动压低峰值"这一条不变。

5.1 讲了工具契约:schema、错误分类、版本。错误分类告诉我们"哪些失败值得重试"。这一节回答重试本身的三件事:隔多久、试几次、怎么试才不把服务打崩。

重试最常见的错是"失败了就立刻再来一次"。立刻重试有两个问题:服务还没恢复,重试大概率再失败;所有客户端同时立刻重试,形成重试风暴。重试的正确姿势是指数退避 + 上限 + 抖动。

重试的三要素

要素回答的问题规则
退避隔多久指数退避:1, 2, 4, 8…
上限退避到多大封顶 cap,防止无限增长
抖动是否同时撞打散到区间,压低峰值

指数退避拉开两次尝试的间隔:第一次失败后等 1 个单位,第二次 2,第三次 4,翻倍上去。上限防止退避无限增长——等了 64 个单位还不够,就固定在 cap(比如 8)。抖动把延迟打散到区间(比如 [0.5d, d]),避免所有客户端在同一时刻重试。

重试的成功率模型

固定失败率 p 下,重试 r 次的累计成功率是 1 − p^(r+1):只要一次成功就成功,全部失败才失败。

失败率重试 3 次成功率含义
p=0.50.9375一次成功率 0.5,三次后 0.9375
p=0.20.9984三次重试几乎必然成功

成功率随重试次数收敛到 1——这是"值得重试"的量化:对瞬时故障,重试把成功率推高;对永久错误,p=1,重试多少次都是 0。 这也呼应 5.1 的分类:先分类,再决定是否重试。

最小实验:退避、抖动与成功率

实验生成退避序列、抖动序列,量化重试成功率,并比较抖动前后的峰值。

# file: agp_lab/tool_retry.py | write
# tier: 3
# verify: python3 -m unittest tests.test_tool_retry
"""校验、幂等与重试:退避、上限与抖动。

重试不是重复调用:它要回答"隔多久、试几次、哪些错误值得试"。
指数退避拉开两次尝试的间隔,上限防止退避无限增长,
全抖动把峰值集中打在某一刻的请求摊开到时间轴上。

本模块给出退避序列、重试成功率模型,并演示抖动如何压低峰值。
"""
from __future__ import annotations

import random
from typing import Any


def backoff_sequence(base: float = 1.0, factor: float = 2.0, cap: float = 8.0, count: int = 5) -> list[float]:
    """指数退避序列,封顶 cap。"""
    delays: list[float] = []
    value = base
    for _ in range(count):
        delays.append(value)
        value = min(value * factor, cap)
    return delays


def retry_success(failure_prob: float, retries: int) -> float:
    """固定失败率下重试 retries 次的累计成功率 = 1 - p^(retries+1)。"""
    return 1.0 - failure_prob ** (retries + 1)


def total_wait(delays: list[float], retries: int) -> float:
    """前 retries 次退避的累计等待时间。"""
    return sum(delays[:retries])


def jittered(delays: list[float], seed: int = 7) -> list[float]:
    """全抖动:把每个延迟打散到 [0.5*d, d] 区间(固定 seed 保证确定性)。"""
    rng = random.Random(seed)
    return [round(d * (0.5 + 0.5 * rng.random()), 3) for d in delays]


def demo() -> dict[str, Any]:
    delays = backoff_sequence()
    jitter = jittered(delays)
    return {
        "backoff": delays,
        "jittered": jitter,
        "retry_success_p05_r3": retry_success(0.5, 3),
        "retry_success_p02_r3": retry_success(0.2, 3),
        "total_wait_3": total_wait(delays, 3),
        "peak_before": max(delays),
        "peak_after": max(jitter),
    }


if __name__ == "__main__":
    result = demo()
    print(f"backoff={result['backoff']}")
    print(f"jittered={result['jittered']}")
    print(f"retry_success(p=0.5, r=3)={result['retry_success_p05_r3']:.4f}")
    print(f"retry_success(p=0.2, r=3)={result['retry_success_p02_r3']:.4f}")
    print(f"total_wait(3)={result['total_wait_3']}")
    print(f"peak {result['peak_before']} -> jittered {result['peak_after']}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.tool_retry

输出:

backoff=[1.0, 2.0, 4.0, 8.0, 8.0]
jittered=[0.662, 1.151, 3.302, 4.29, 6.144]
retry_success(p=0.5, r=3)=0.9375
retry_success(p=0.2, r=3)=0.9984
total_wait(3)=7.0
peak 8.0 -> jittered 6.144

六行输出对应重试的四个面:

  1. backoff=[1, 2, 4, 8, 8]:指数退避到 8 后封顶——第 4、5 次都是 8,不再无限翻倍。这就是"上限":退避是 1→2→4→8→8,不是 1→2→4→8→16。
  2. jittered=[0.662, 1.151, 3.302, 4.29, 6.144]:同样的序列加全抖动,每个值落在 [0.5d, d] 区间。注意 8.0 被抖成 4.29 和 6.144,8.0 不再原样出现——峰值被打散。
  3. 成功率:p=0.5 时三次重试成功率 0.9375;p=0.2 时 0.9984。失败率越低,重试收益越显著。
  4. 峰值对比:peak 8.0 -> jittered 6.144。抖动把最大的同时重试负载从 8.0 压到 6.144——这就是防"重试风暴"的直接证据:所有客户端一起在 8.0 时刻重试,会被摊开到不同的时刻。

一个值得点破的细节:total_wait(3)=7.0(前三次退避 1+2+4)。这意味着一次重试序列最多等待 7 个单位就完成三次尝试。重试不是无限等,是有预算的:预算到了还没成功,就放弃并走补偿或对账(见 2.3、5.3)。

重试策略的落地,通常要配套幂等键才完整(见 2.2)。单靠"指数退避 + 抖动"解决的是"什么时候重试",没解决"重试会不会重复副作用"。Agent 的工具调用里,很多动作天然不幂等——发通知、扣款、创建资源。这些动作的重试必须配合幂等键去重,否则重试越多,副作用越多。

工具动作是否幂等重试前需要
读文件是无
写固定 key是无
发通知否幂等键 + 去重
扣款否幂等键 + 事务

还有一个容易踩的坑:退避与超时打架。重试的等待时间如果超过了请求的总超时,重试根本不会发生。比如总超时 10s、退避序列 1+2+4=7s,还剩 3s 只能做一次尝试;如果退避 1+2+4+8=15s 超过超时,后面的重试都是摆设。设计退避时要把总超时预算算进去,让重试序列在超时窗口内完成得完。

配置值说明
总超时10s请求级预算
退避序列1,2,43 次尝试,共 7s
剩余预算3s最后一次尝试窗口
若退避过长重试被超时吞掉配置失效

抖动还有一个现实收益:它天然打散了"整点风暴"。没有抖动时,所有客户端在同一时刻重试形成负载尖峰;有抖动后,即使大家都用同一套退避参数,各自的延迟也不同,峰值被平摊。这正是 5.2 实验里 8.0→6.144 那个数字的现实意义。

重试的边界是熔断。 指数退避假定"重试可能成功";当上游持续故障时,无限重试只会加重雪崩。熔断器把"重试"变成"阶段性的重试":连续失败超过阈值就打开熔断,请求直接快速失败,过一段时间再半开试探,成功则关闭、失败则继续打开。

熔断状态请求处理转换条件
关闭正常重试失败率超阈值 → 打开
打开快速失败冷却时间到 → 半开
半开少量放行试探成功 → 关闭;失败 → 打开

重试、幂等、熔断是三层配合,不是各自独立。 重试决定"什么时候再试",幂等保证"再试不重复副作用",熔断决定"还要不要试"。只有重试没有熔断,故障期靠重试放大负载;只有重试没有幂等,重试放大副作用。三层合起来,才算一个完整的可靠调用策略。

还有一个运维细节:重试统计要有独立的指标。 单独看调用成功率看不出重试的代价——一次失败被重试三次,成功率是 100%,但负载是 3 倍。跟踪"首次失败率"与"重试次数分布",才能看到重试策略是否在掩盖问题而不是解决问题。

幂等键的生成要放在"作用源头"而非"消费端"。 幂等键应该由发起请求的一方生成并随请求传递(如 request_id),而不是由工具自己生成——工具内部生成的话,同一逻辑请求在重试时会拿到两个不同幂等键,去重失效。幂等键的生命周期贯穿"重试的同一逻辑请求",这是它能去重的根本。

幂等键生成位置重试时是否去重
请求方(正确)同一逻辑请求同一键是
工具内部(错误)每次不同键否,副作用重复

校验失败的错误信息要足够 Agent 侧自愈。 Agent 收到"参数不合法",如果只有裸报错,它不知道改什么重试;给到字段级的原因(哪个字段、为什么不行、期望值是什么),Agent 才能修正后重试。校验的目的不是拒绝,是让拒绝可被修复。 这与工具契约(5.1)的错误码设计一脉相承。

错误粒度Agent 能做什么反馈
“参数不合法”猜重复失败
“field x 应为数字”修正 x 重试一次通过

校验的边界也要想清楚:谁负责校验。 Agent 侧校验(调用前按 schema 自查)能减少无效调用,工具侧校验(入口处强校验)是最终防线。双侧校验不是浪费——Agent 自查拦下大部分坏参数,工具侧强校验兜住"Agent 没检查的边界"。校验要放在"信任的边界"上:只要调用方不完全可信,工具就必须自校验,不能假定上游已过滤。

校验位置作用局限
Agent 侧减少无效调用不是防线,是效率
网关/适配层统一强校验需定义统一 schema
工具侧最终防线必须存在

校验规则与 schema 版本绑定:schema 升级后校验规则跟着变,旧规则校验旧事件、新规则校验新事件——这与 6.3 的版本兼容呼应。校验不是一套规则通吃,而是按 schema 版本分派。 校验器与解析器(6.3 的 parse_event)要共享同一套 schema 描述,避免"解析按新 schema、校验按旧规则"的错位。

重试的归因:区分"可重试"与"不可重试"是调度器的事吗? 不是——归因在错误发生处。工具的错误要带"可重试性"标记(5.1 的错误 schema),Agent 侧按标记决策:可重试的走退避重试,不可重试的直接放弃或改方案。重试决策如果靠猜(失败就重试),会把不可重试的错误也重试 N 次,白白放大延迟。

错误类型标记重试动作
网络/超时retryable退避重试
参数非法non-retryable改参数
资源冲突retryable-after等冲突解除

重试与任务超时的关系也要明确:重试序列的总时长不能超过任务允许的总时间(见实验的"退避与超时打架")。一个交互任务 10 秒超时,退避序列 1+2+4+8=15 秒,重试根本没机会执行完。重试预算是任务超时的子集——退避序列设计时,把"还剩多少时间给最后一次尝试"算清楚,别让重试变成任务超时的隐形放大器。

架构判据

重试实现是否合格,用五条判据检查:

判据合格的样子不合格的样子
指数退避间隔翻倍固定间隔或立刻重试
有上限退避封顶,不会无限增长退避无限翻倍
有抖动峰值被打散所有客户端同一时刻重试
只重试可恢复错误永久错误直接放弃永久错误反复重试
有预算尝试次数/等待有上限无限重试

判据第四条呼应 5.1:先分类再重试。 判据第五条是止损:重试要有预算,预算到就放弃并走补偿,不然"重试"本身变成一种拖垮系统的循环。

小结

  • 重试三要素:指数退避、上限、抖动;立刻重试会放大失败并形成重试风暴。
  • 成功率模型 1 − p^(r+1) 量化收益:对瞬时故障重试把成功率推到接近 1,永久错误重试无效。
  • 抖动把峰值打散:8.0 → 6.144,同一时刻的重试负载被摊开。
  • 重试要有预算,预算到就放弃并走补偿/对账,不能无限重试。

阅读导航:上一节:5.1 工具契约:schema、错误与版本 · 下一节:5.3 补偿、回滚与 Saga 。

常见错误与边界

  1. 失败立刻重试。 服务没恢复,重试大概率再失败,还放大负载;要退避。
  2. 退避无上限。 无限翻倍会让等待无限长;要封顶。
  3. 无抖动。 所有客户端同时重试形成风暴;全抖动把峰值摊开。
  4. 永久错误也重试。 p=1 时重试多少次成功率都是 0;先分类(5.1)再决定。
  5. 重试无预算。 无限重试等于拖垮系统;预算到就放弃,走补偿或对账。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图