阶段三 · 集成与实践
可靠性 —— 失败了怎么办
网络会抖、服务会限流、配额会用完。可靠的 Agent 不是"不出错",而是把错误变成一条可预期的数据流。Pi 的思路是:先分类,再决定重试;退避要有上限;取消要能立刻生效。这一章还纠正两个常见误传:重试其实分两层,以及"错误脱敏"是课程主张而不是 Pi 的现状。
具体回答三个问题:哪些失败该重试?等多久?取消和重试怎么配合?
学习目标
- 理解为什么"该不该重试"不能只看状态码。
- 知道 Pi 的重试分两层,默认只有一层开着。
- 掌握指数退避的写法与上限的意义。
- 分清四个不同的问题:重试、取消、流式错误、上下文溢出。
一、失败是常态,不是异常
Agent 的每一次模型调用都依赖网络和第三方服务。过载、限流、超时、配额耗尽——失败是常态。关键不是"会不会失败",而是失败发生时程序的行为可预期:该重试的重试,该停的停,该报告的报告。
二、先分类,再重试
不是所有失败都该重试。 只看状态码不够:同一个 429,可能只是"你太快了,慢点再来"(可重试),也可能是"这个月额度用完了"(重试只会继续消耗额度)。
Pi 在"每次模型调用"这一层,是按错误文本匹配两张表:
| 分类 | 典型文案(节选) | 重试? |
|---|---|---|
| 可重试 | 过载、限流、429/500/502/503/504、服务暂时不可用 | 是 |
| 不可重试 | 额度不足、超出预算、账单问题、用量上限 | 否 |
先查不可重试那张表,命中就直接失败——顺序很重要,因为配额类文案里常常也带"限流"字样,反过来查就会误判成可重试。
为什么集中维护两张表?因为新增服务商的报错写法不同,改一处就够了;分类策略和具体调用代码解耦。
三、重试分两层,别混为一谈
这是最容易讲错的地方。Pi 的重试其实有两层:
| 层 | 管什么 | 默认 | 怎么判 |
|---|---|---|---|
| 外层(每次模型调用) | 这次调用失败要不要再来一遍 | 开,默认 3 次 | 按错误文本匹配上面两张表 |
| 内层(单个请求) | 这一条 HTTP 请求失败要不要重发 | 关,要显式开 | 按状态码与响应头 |
为什么要分开?因为两层想解决的问题不同:外层解决"这一轮模型调用没成功",内层解决"这一条网络请求失败"。外层更保守(默认开但次数少),内层更激进(会读服务端给的等待时间、会加随机抖动),所以默认关着——让上层先有机会做更聪明的决定。
这里有个非常常见的误传:"重试会看服务端给的 Retry-After"。默认配置下不会——只有内层开着才会读它。如果服务端说"60 秒后再来",而你的退避只等 2 秒,那就是白白重试。
四、退避与取消
退避是纯指数:第一次等一个基数,之后每次翻倍,并且有单次等待上限。上限的意义是防止"一次长时间故障把调用挂死"。
取消和重试不是对手,而是搭档:
- 已经被取消的调用永远不重试。
- 正在退避等待时收到取消,会立刻中断等待,并把结果归一化成"已取消"的一条回复——调用方不需要关心取消发生在哪一步。
这个"归一化"很关键:取消可能发生在发起前、等待中、流式返回中,如果每种情况都吐不同形状的结果,调用方就得写一堆分支。统一成一种,代码立刻清爽。
五、四个不同的问题
| 问题 | 手段 |
|---|---|
| 重试 | 分类 + 指数退避 + 上限 |
| 取消 | 取消信号沿调用链传下去 |
| 流式错误 | 把已经收到的部分和错误一起处理 |
| 上下文溢出 | 压缩之后再试,不是重试 |
第四行最容易混。上下文溢出(请求太长)不是"抖动",重发一百次还是太长。Pi 的处理是"压缩后再发"——先让请求变短,再试。所以它属于压缩机制,不属于重试机制。
六、脱敏:课程主张,不是 Pi 现状
很多教材会说"重试失败后只保留异常类型和次数,不把敏感文本传出去"。这是好的设计主张,但要说清楚:Pi 目前不做这个过滤。它把原始错误文本放进重试事件(还给界面显示),最终失败时也带着原始错误。
这不是说 Pi 错了——错误原文对诊断很有价值,界面上用户也需要看到"到底哪儿出错了"。真正该做的是在你的宿主程序里决定:日志要不要脱敏、哪些字段不能进模型上下文。把"默认不脱敏"当成事实讲,比把它包装成"已实现"更有用。
当前 Pi 行为
- 外层重试默认开启,默认 3 次,退避从 2 秒起翻倍,单次等待上限 60 秒。
- 内层请求重试默认关闭;开启后会读服务端给的等待时间(两种头部都支持),并加约 25% 随机抖动、更短的单次上限(8 秒);服务端要求的等待超过 60 秒时直接失败,不空等。
- 外层按错误文本分类,先判不可重试;内层按状态码与响应头判断。
- 重试过程对用户可见:有"重试开始"和"重试结束"两个事件,前者带次数、上限、等待时长与错误文案,后者带成功与否、最终错误。
- 被取消的调用不重试;退避期间取消会立即中断并归一化成已取消的回复。
- 流式请求失败不抛未捕获异常,而是变成一条"出错"的助手回复,走正常结束路径。
- 上下文溢出单独处理:压缩后再试。
- 协议模式下,队列可以清空,重试也可以远程设置与中止。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 外层重试 | retryAssistantCall |
| 分类函数 | isRetryableAssistantError |
| 退避计算 | retryDelayMs |
| 内层请求重试 | packages/ai/src/utils/provider-retry.ts |
| 重试事件 | auto_retry_start / auto_retry_end |
| 溢出处理 | packages/ai/src/utils/overflow.ts |
| 配置项 | retry.maxRetries / baseDelayMs / maxAgentDelayMs |
源码位置
packages/ai/src/utils/retry.ts:两张模式表、分类、退避、重试循环。packages/ai/src/utils/provider-retry.ts:内层请求重试。packages/coding-agent/docs/settings.md:重试相关配置的说明。
失败与边界实验
lab reliability 与对应测试覆盖的重试矩阵:
| 失败类型 | 分类 | 策略 | 为什么 |
|---|---|---|---|
| 429 限流 | 可重试 | 指数退避 + 上限 | 服务端明确说"稍后再来" |
| 5xx | 可重试 | 指数退避 + 上限 | 瞬时故障概率高 |
| 401 / 403 | 不可重试 | 立即失败并提示配认证 | 重试只是刷错误日志 |
| 400 参数错误 | 不可重试 | 立即失败 | 同样的错误参数再发一次还是错 |
| 上下文溢出 | 不可重试,但有专门处理 | 压缩后再试 | 请求太长,重发没用 |
| 流中途断开 | 视情况 | 已产出的部分按截断处理 | 不能重复计费整轮 |
关键不变量:重试发生在"一次模型调用"的边界内。工具已经产生的副作用不会因为重试而消失——所以有副作用的工具必须自己幂等,重试机制救不了它。
python3 -m learn_pi_lab lab reliability
python3 -m unittest tests.test_09_reliability -v
在 Pi 里怎么操作
- 重试大多自动发生,不需要手动操作。
- 网络不通或额度用完时,先看登录状态与账户额度,而不是反复重跑。
- 终端里出现重试提示时,可以按取消键中止,不必等它耗尽次数。
Python 实验
reliability.py 用注入的 sleep 实现可测试的指数退避:
for current_attempt in range(1, attempts + 1):
try:
return RetryResult(operation(), current_attempt, tuple(delays))
except Exception as error:
if current_attempt == attempts:
raise RetryExhausted(current_attempt, type(error).__name__) from error
delay = float(base_delay) * (2 ** (current_attempt - 1)) # 1, 2, 4, ...
delays.append(delay)
if sleep is not None:
sleep(delay)
三个教学点:
- sleep 是参数,不是 import:测试传一个"记录等待时长"的假函数,生产传真正的 sleep。同一个函数,测试里零等待、可断言——离线可验证就是靠这种依赖注入实现的。
- 异常只带类型名:
RetryExhausted只保留"OSError"这样的类型名,不保留原始错误文本。这是课程主张的"脱敏"落地方式(注意:Pi 本身不做这一步,见上一节)。 - 分类不在这里:这个函数对一切异常一视同仁地退避。调用方要先按上一节的矩阵过滤——401 之类的根本不该进来。
result = retry(operation, attempts=3, base_delay=0.25)
# 成功 → RetryResult(值, 实际尝试次数, 每次等待时长)
# 耗尽 → RetryExhausted(尝试次数, 错误类型名)
Tau 的 tau_ai/retry.py 提供了同样的退避函数,外加可取消的等待——按很短的片轮询,随时响应取消。这正是把"取消是重试的搭档"落到实现层的样子。
python3 -m learn_pi_lab lab reliability # 打印重试元数据,不真睡
这一模块的核心代码在核心代码导览 · 重试与退避有逐段解读。
验证方式
python3 -m unittest tests.test_09_reliability -v
边界与安全
- 重试只适合幂等或可安全重放的操作;写文件、支付、外部部署需要幂等键、人工确认或补偿机制。
- 不要把异常文本无界地传播到日志或模型上下文——Pi 默认会带原文,需要你在宿主层过滤。
- 指数退避必须有上限,否则一次长时间故障会把瞬时问题放大成自我 DDoS。
自测三问
- 同样是 429,什么情况下不该重试?判断依据在哪一层?
- 默认配置下,服务端说"60 秒后再来",Pi 会等 60 秒吗?
- 上下文溢出为什么不算"失败重试",而要单独处理?
回顾
- 先分类再重试:外层按文本匹配,先判不可重试;内层按状态码,默认关闭。
- 两个约束:退避必封顶;取消要能立刻打断退避。
- 四个问题:重试 / 取消 / 流式错误 / 上下文溢出——溢出走压缩,不走重试。
- 脱敏是主张:Pi 默认保留错误原文,过滤是宿主程序的职责。
Agent 不只是人用的——它还要被程序用。下一章协议与集成讲 SDK、协议与分帧。