timeout 到底设几秒：连接、读取与整体超时的分档清单

跑得好好的脚本突然一堆请求失败，日志里却是超时，不是 4xx 也不是 5xx；或者流式输出到一半断掉，重试又重复计费。多数时候不是接口坏了，而是几层超时的时间没配成套。这篇按调用类型给一张分档清单，讲清连接、读取、整体三个超时分别管什么，以及客户端比服务端先掐断时会出现哪些特征现象，最后给一个由外到内的排查顺序。

脚本昨天还跑得好好的，今天一堆请求失败，翻日志发现全是超时，既不是 4xx 也不是 5xx；流式输出到一半突然断掉，重试一次又多扣一份用量。遇到这种情况，多数人第一反应是接口挂了或者中转站掉包，其实更常见的原因是几层超时的时间没配成套：连接、读取、整体各设各的，谁也不管谁。

这篇不讲概念史，只做两件事：把超时按调用类型分成四档给你一张对照表，再讲清客户端比服务端先掐断时会看到哪些特征现象，最后给一个由外到内的排查顺序。具体填几秒不给死数字，因为端点和时段都会变，去站内页面看你自己的实测数字再定。

先把三个超时拆开：连接、读取、整体各管什么

连接超时

管的是 TCP 握手和建连，走中转或跨地域时值得单独调大；建连都过不去，说明问题在网络或域名层面，不是模型慢。

读取超时

管的是「两个数据块之间等了多久」，不是整个请求的总时长。流式场景下它才是决定会不会被误判的那一层。

整体超时

兜底用的，防止连接虽活但永远不返回。它必须大于读取超时，否则读取超时形同虚设。

空闲超时

流式专用，衡量「多久没收到任何字符就判死」，和整体超时分开设置。

三层的关系是：连接超时最先触发，读取超时看间隔，整体超时最后兜底。很多人把三件事塞进一个 timeout 参数里，结果就是短请求被拖太久、长请求又被提前掐死。正确做法是超时值一律写成配置项，散落在代码各处的硬编码迟早会漏改。定值之前先去 /tools/speed-test 量一次你到目标端点的延迟基线，没有基线就谈秒数都是拍脑袋。

按调用类型分档：先定档位，再谈具体秒数

分档的核心是先归位再填数：同一个项目里四类调用可能同时存在，全局一个数字必然错。相对口径比绝对值靠谱，比如「正常 P95 的两三倍」，因为它跟着你的实际环境和时段走。至于具体填几秒，随端点和时段变化，到 /tools/speed-test 看当时的实测，再到 /ai-status 核对服务状态，两边都对上了再回填配置。

• 短问答和长文生成不要共用一套超时值，输出长度差一个量级。
• 流式优先改读取超时的口径，别直接加大整体超时。
• Agent 场景把整体超时按轮数粗算，算完再留一档余量。
• 超时值写进配置文件并跟调用类型走，不要全局一个数字。
• 改完配置先跑一轮长耗时用例验证，别只看短请求通不通。

客户端超时比服务端短，会看到什么现象

这是最常见的坑，现象也最好认：你会看到大量超时失败，但服务端侧可能显示请求正常完成并已计费。钱花了、结果没拿到，这是最典型的特征。更麻烦的是重试会放大问题——客户端以为失败就重发，服务端其实还在跑，于是同一份输入被算两三次，非流式长文生成上尤其容易踩。

反过来，客户端设得远长于服务端也不安全：连接早已被对端关闭，你还在傻等，白占连接池、拖慢整批任务。还有一种情况要排除——网络本身在丢包。这时候超时只是表象，先去 /tools/speed-test 看链路质量，再回头看配置。什么情况下不适用这套判断？如果你的请求本来就该秒回却大量超时，那多半不是超时值的问题，而是端点或网络异常。

配置与排查清单：照这个顺序走一遍

1. 归位列出所有调用点，按四档归位，给每一档写明连接、读取、空闲、整体四个值，写进配置文件而不是散在代码里。
2. 重试策略重试只针对超时和 5xx，必须带退避和次数上限；幂等性没保证的写操作不要自动重试。
3. 确认计费重试前先确认上一次是否真的没产生计费，这点在长文生成和 Agent 场景里尤其重要，可结合用量记录核对。
4. 日志留痕日志至少记下调用类型、四个超时值、实际耗时、是否重试、最终结果，方便回溯是不是超时的锅。
5. 排查顺序先量延迟基线，再核对四档配置，再看失败是否集中在长耗时请求，最后才怀疑渠道质量。顺序反了会白折腾。