以下退避序列、失败率、抖动种子均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。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.5 | 0.9375 | 一次成功率 0.5,三次后 0.9375 |
| p=0.2 | 0.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
六行输出对应重试的四个面:
- backoff=[1, 2, 4, 8, 8]:指数退避到 8 后封顶——第 4、5 次都是 8,不再无限翻倍。这就是"上限":退避是 1→2→4→8→8,不是 1→2→4→8→16。
- jittered=[0.662, 1.151, 3.302, 4.29, 6.144]:同样的序列加全抖动,每个值落在 [0.5d, d] 区间。注意 8.0 被抖成 4.29 和 6.144,8.0 不再原样出现——峰值被打散。
- 成功率:p=0.5 时三次重试成功率 0.9375;p=0.2 时 0.9984。失败率越低,重试收益越显著。
- 峰值对比:
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,4 | 3 次尝试,共 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 。
常见错误与边界
- 失败立刻重试。 服务没恢复,重试大概率再失败,还放大负载;要退避。
- 退避无上限。 无限翻倍会让等待无限长;要封顶。
- 无抖动。 所有客户端同时重试形成风暴;全抖动把峰值摊开。
- 永久错误也重试。 p=1 时重试多少次成功率都是 0;先分类(5.1)再决定。
- 重试无预算。 无限重试等于拖垮系统;预算到就放弃,走补偿或对账。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。