排查模型 API 超时,先确认完成状态
指南强调客户端超时不能证明服务端未处理请求,建议记录 HTTP 状态、请求 ID 和最后收到的 Responses API 事件。未收到明确完成事件时,应保留不完整或未知状态,避免自动重放 POST。
AI 深度解读
OpenAI API 超时,能确定的是客户端停止等待,服务端可能仍在处理请求。Tokenhot 团队这篇排障指南的核心结论是:流式请求要分别记录 HTTP 状态、完整接收的事件和业务结果,不能看到超时就判失败,也不能看到 HTTP 200 就判成功。
它适合正在接入 AI 对话、流式生成或工具调用的开发者。不过,原文给出的 Python 脚本在关键位置被截断,作者也明确表示没有调用真实 API 验证。值得带走的是诊断方法,代码则需要补全后才能使用。
超时到底能证明哪一步出了问题
一次请求超时,描述的是某个等待期限到了,不是服务端执行结果。
尤其是 POST 可能已经发出时,客户端断开连接,并不能证明 OpenAI 没收到请求、没接受请求,或者没完成生成。没有足够证据,就应把结果保留为「未知」,而不是补成一个确定的失败。
作者要求区分三类证据:配置的等待上限、实际观测到的时间,以及收到的状态和事件。原文在这里没有完整展开三类清单,但后续代码和说明给出了具体含义。
以 aiohttp 为例:
connect包括建立连接,以及等待连接池中出现可用连接的时间。sock_connect限制新建对端连接的等待时间。sock_read限制两段数据之间的等待时间,不是整个回答的生成时间。
因此,配置 connect=5.0,不能据此声称「建连实际用了 5 秒」。要分析连接池、DNS、TLS 或写入阶段,得使用 TraceConfig 或传输层提供的观测钩子。
原文用下面这段代码配置传输层等待上限:
timeout = aiohttp.ClientTimeout(
total=None,
connect=CONNECT_LIMIT_SECONDS,
sock_connect=SOCKET_CONNECT_LIMIT_SECONDS,
sock_read=sock_read_seconds,
)
要看的是 total=None:这里没有设置 aiohttp 的总超时,总期限交给外层的 asyncio.timeout(total_seconds) 控制。脚本默认连接等待和新连接等待各为 5.0 秒,读取空闲等待为 30.0 秒,应用总期限为 90.0 秒。
即使持续有数据到达、没有触发读取空闲超时,请求仍可能碰到应用总期限。排障记录如果只写一句「请求超时」,就丢掉了最有用的区别。
HTTP 200 为什么还不能代表回答完成
Responses API 的流式输出采用服务端发送事件(SSE)。HTTP 200 说明响应成功开始,回答是否完成,还要继续看事件。
作者把几种情况分得很清楚:
| 观测结果 | 应如何记录 |
|---|---|
| 没收到响应头 | 没有可确认的状态码和响应请求 ID;若 POST 可能已发出,结果未知 |
| 收到非 2xx 响应头 | 保存状态码与请求 ID,按 HTTP 拒绝处理 |
收到 2xx,随后收到 response.completed |
API 已报告完成 |
收到 response.incomplete、response.failed 或 error |
保存明确的事件类型,不计为完成 |
| 没有终态事件便遇到 EOF 或传输异常 | 保留部分输出,业务结果记为不完整或未知 |
这里还有一个容易漏掉的边界:response.completed 如果已经被完整接收,后续本地清理或连接关闭报错,不会抹掉此前的完成证据。应该同时记录「已完成」和「随后发生本地异常」。
业务完成与连接正常关闭,是两件需要分别记录的事。
SSE 的帧边界也不能省略。一个事件要等到空行分隔符到达,才算可以分发。如果只收到一行 data:,连接就在空行之前结束,即使内容看起来像完成事件,也不能把它算作已经观察到的 response.completed。
作者依据 SSE 处理规则,要求在 EOF 时丢弃待完成帧,并单独记录 unterminated_sse_frame。这个标记描述传输尾部是否残缺,不应覆盖之前已经完整分发的事件。
同样,脚本把 [DONE] 映射成 sse_done_marker,但不能拿这个名称代替 Responses API 文档里的完成事件。
对业务层而言,收到文字片段后直接断流,仍不足以确认整个响应完成。原文因此提醒:不要解析尚未完成的 JSON,也不要从未完成响应中触发工具调用。
一次受控复现,需要留下哪些证据
作者建议先做一次边界清楚的复现:直接请求 api.openai.com 的 /v1/responses,只发送一次 POST,关闭重定向,不做重试,并且只记录事件名,不记录生成正文。
它要求 Python 3.11 或更高版本,并固定使用原文指定的 aiohttp 版本:
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install 'aiohttp==3.13.5'
这里应保留 aiohttp==3.13.5 的精确版本,避免排查过程中混入客户端版本差异。不过,作者称这是脚本验证所用的版本,同时又声明没有进行真实 API 调用;不能把它理解为已经完成线上验证。
运行前,需要通过安全环境注入设置 OPENAI_API_KEY,并把 OPENAI_MODEL 设为账号实际可用的精确模型 ID,再执行 python timeout_probe.py。请求启用 stream: True,提示模型只回复单词 OK。运行会联系 OpenAI,并可能产生费用。
但当前提供的正文,代码停在 async for line_bytes,缺少循环体和后续收尾逻辑。虽然文章描述了按行输出 JSON 的日志格式,以及最终记录如何处理残缺 SSE 帧,这份输入中的脚本仍不是可直接运行的完整实现。
它的记录思路可以直接采用:保存 UTC 开始时间、响应头时间、状态码、x-request-id、首个事件时间、最后事件类型、终态事件、结束原因和异常类型链。代码使用 time.monotonic() 计算耗时,异常链只保留类名,最多追踪 5 层,不输出异常文本或响应头。
事故记录还应包含客户端精确版本、模型或路由 ID、各层重试情况,以及 connect、sock_connect、sock_read 和总期限。部分输出可以放在应用受保护的状态中,但普通日志不要附带 Authorization、完整提示词、生成文本或未经脱敏的错误正文。
兼容 OpenAI 的网关也不能直接照搬。它的超时控制、请求 ID 和事件协议,需要查自己的文档;这份脚本只针对 OpenAI 直连端点。
我的判断
我认同这篇文章对「证据边界」的坚持。AI 流式接口最容易混淆的,就是网络状态、协议状态和业务状态。把三者拆开,才能解释为什么用户已经看见文字,系统却仍不能确认任务完成。
它对重试的提醒也有价值。POST 可能已经被接受时,断流后重新提交,可能重复执行工作。原文建议先检查端点是否提供幂等或请求对账机制,但没有给出具体可用机制,也没有证明携带某个参数就能安全重试。不能替它补上这个承诺。
不过,「不要自动重放 POST」仍需结合业务理解。只生成一段文字,与生成后还会触发工具操作,重复执行的后果不同。比较合理的做法,是先判断操作能否安全重复,再决定重试策略;原文自己也把这一判断作为前提。
和单纯拉长总超时相比,这套方法能提供更清楚的诊断证据。但文章没有延迟分布、故障复现结果或策略对照数据,无法证明 5.0、30.0、90.0 秒适合一般团队。它们是示例配置,不是通用最优值。
这是一份排障方法指南,不是一份性能优化实验报告。它能帮助判断「目前究竟知道什么」,不能单凭这些记录定位所有慢请求的根因。
能拿来做什么
- 给前端流式界面区分「正在接收」「已完成」「明确未完成」和「结果未知」,由后端依据完整终态事件确认完成;断流时保留已显示内容,并明确当前状态。
- 在 Node 服务接入同类接口时,分别记录 HTTP 状态、请求 ID、最后完整事件和结束原因,并检查所用客户端对连接等待、读取空闲和总期限的具体定义。
- 为 AI 编程中的结构化输出和工具调用设置完成门槛,不从残缺 JSON 或未完成响应里提取参数执行操作;重试前先确认重复提交是否安全。
- 沿用原文的事故记录字段整理一次真实故障,先补齐版本、时间、事件和异常类型,再判断是调整等待期限、检查连接链路,还是携带脱敏证据联系服务方。