Pipecat 修复工具进度回调误取消超时
Pipecat 原先收到异步工具的进度回调就会取消超时计时,工具随后卡住也无法触发超时。已合并的修复保留计时,直到收到最终结果。
AI 深度解读
一个工具先回了句「处理中」,随后卡住,原本负责兜底的超时却再也没触发。Pipecat 的 PR #5760 修的就是这个问题。按作者的记录,补丁于 2026 年 9 月 15 日合并,关闭了 issue #5481。
这次改动把进度和完成区分开了。中间结果可以照常上报,超时仍从调用开始算,最终结果才会清除计时任务。对接过流式输出或异步工具的开发者,可以借这个例子检查自己的超时到底管到了哪一步。
为什么工具报了进度,超时反而失效了
Pipecat 优先使用单个工具配置的 timeout_secs,工具没单独配置时就用全局的 function_call_timeout_secs。处理函数每上报一次结果,服务都会进入 function_call_result_callback。旧逻辑在这里取消超时任务,即使结果被标记为 FunctionCallResultProperties(is_final=False),也会照样取消。
这个标记表示工具还在执行。用户可能已经看到一条「处理中」,但工具如果接下来卡住,框架原本用来收尾的计时任务已经没了。问题出在回调对两种结果执行了同一个清理动作。
最终结果清除计时,中间结果沿用原截止时间
修复落在 src/pipecat/services/llm_service.py。取消超时任务的代码被移进 is_final 分支。最终结果会将调用标记为已完成,并取消仍在运行的超时任务。中间结果到达时,计时任务继续运行,截止时间也保持原样。
如果工具超过截止时间,处理函数会收到 asyncio.CancelledError,调用以取消状态收尾,随后触发模型推理,让模型有机会告诉用户这次操作没完成。作者也更新了 register_function 和 register_direct_function 的文档,把这套行为写清楚。
两条测试分别验证了什么
第一条测试 test_intermediate_result_does_not_disarm_the_deadline 让工具先回 working,带上 is_final=False,再睡到超过 timeout_secs。断言覆盖了三个层面。工具后续的副作用没有执行,处理函数收到了 CancelledError,框架依次发出 FunctionCallsStartedFrame、FunctionCallInProgressFrame、非最终的 FunctionCallResultFrame 和 FunctionCallCancelFrame。最后一帧还设置了 run_llm。
对照测试 test_a_hanging_async_tool_times_out_without_any_update 让工具直接睡过去。它原本会在睡醒后返回最终结果,但在此之前就被取消了。帧序列只有开始、进行中和取消。这个用例守住了原来就应该正常工作的路径。
两条用例位于 tests/test_llm_service.py 的 TestFunctionCallTimeout 类。PR 给出的命令是 uv run pytest tests/test_llm_service.py::TestFunctionCallTimeout。合并记录显示一共改了 3 个文件,其中包括 changelog/5760.fixed.md。作者写文章时依据的是已合并的改动,没有为文章重跑测试。
我的判断
这次修复和 Pipecat 的超时语义一致。如果配置项管的是整次执行,从调用开始计时就能给工具占用这一轮对话的时间设上限。另一种常见做法是空闲超时,每收到一次进度就续期,适合检测工具多久没动静。产品如果同时关心总耗时和长时间无进展,就需要分别定义两种超时。
测试里「后续副作用没执行」也有范围。它验证的是这个测试处理函数在等待期间被取消后,没有走到后面的代码。原文没有测真实外部服务的取消效果,也没有给出线上延迟或成功率的对照数据。把这个结果推广到已经发出的请求或已经提交的写入,证据还不够。
能拿来做什么
- 给 Node 工具或前端流式界面约定明确的进度、完成和取消事件,只在进入终态时清理本次调用的超时计时器。
- 写回归测试时覆盖两条路径。让工具先报进度再卡住,以及从头卡到超时。除了断言取消信号,还检查调用有没有收尾,界面是否退出等待状态。
- 如果 Node 工具用
Promise.race做超时,检查底层请求是否也接到了取消信号。对于支持AbortSignal的请求,把信号传到实际发请求的那一层。