AI Agent SSE 流的三处契约错配
AI 总结
掘金技术分析探讨 AI Agent 流式栈完成 SSE 连接后反复出现的故障,指出应用层、框架层、运行时层与客户端库在取消、异步生成器关闭和客户端终止语义上存在不一致。文章给出断连、重试、续传、优雅关闭与访问控制的修复建议,并建议通过日志验证实际运行行为。结论基于 Starlette 0.49.1+、采用 ASGI 2.4 的 uvicorn 和 @microsoft/fetch-event-source 2.0.1。
深度见解
这份分析揭示了客户端断开后 AI Agent 仍可能持续输出并调用 LLM 的原因,并提供了可执行的诊断与修复方法。
上一版文章把断连、续传、重试、优雅关闭的修复清单列了出来。这一版不增加新条目,只做一件事:把每条修复背后的“契约假设”说清楚。因为这些问题之所以反复出现,不是因为某一行代码写错了,而是因为应用层、框架层、运行时层、客户端库,对同一件事持有不一致的假设,而没有任何一层负责仲裁。
三处错配贯穿全文:
- 服务端取消语义:Starlette 0.49+ 假设
send()在客户端断开时抛OSError,uvicorn 的send()在断开后直接return。 - 生成器关闭语义:应用层假设
aclose()是同步的、可以随时调用,Python 异步生成器在“running”状态下并发调用aclose()会抛RuntimeError,而这个RuntimeError会被except Exception捕获,掩盖关闭信号。 - 客户端终止语义:SSE 规范用 204 表示“不要重连”,
fetch-event-source的默认策略在 204 和 clean close 两个点上都与标准错位。
下面逐个展开。
一、服务端取消:Starlette 的快速路径假设了 uvicorn 不履行的契约
Starlette 0.41.2 的 StreamingResponse.__call__ 无条件运行 stream_response(send) 和 listen_for_disconnect(receive) 的 anyio task group,谁先结束谁取消对方。客户端断开时,listen_for_disconnect 读到 http.disconnect,取消 body task,CancelledError 一路传播进生成器,finally 正常执行。