阶段三 · 集成与实践

可靠性 —— 失败了怎么办

网络会抖、服务会限流、配额会用完。可靠的 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、协议与分帧。