api 中转站 超时时间 怎么设置

接入与开发

讲清中转站场景下连接、读取、整体三类超时该怎么分档设置,以及长请求被提前掐断时按什么顺序排查。

调用中转站时,短问答跑得好好的,一到长文生成、大段代码输出或带工具调用的任务,就开始报超时或者流断在半路。多数时候不是中转站挂了,而是超时参数没按请求形态分档,客户端、网关、上游三层各有一套默认值在互相打架。这篇给一套可落地的分档思路和排查顺序。

调用中转站时,短问答跑得好好的,一到长文生成、大段代码输出或带工具调用的任务,就开始报超时,或者流断在半路。多数时候不是中转站挂了,而是超时参数没按请求形态分档,客户端、网关、上游三层各有一套默认值在互相打架,谁先到点谁先掐线。

这篇给一套可落地的分档思路和排查顺序。核心就一句话:超时不是一个数字,而是一组按场景分档的参数。先把三层含义拆开,再按请求形态定档,最后按固定顺序排查,别一上来就无脑把所有数值拉到最大。

先分清三层超时,别把它们混成一个数

连接超时管的是握手阶段,读取超时管的是两次数据之间的间隔,整体超时管的是整个请求的生命周期,三者含义完全不同。很多人只设了其中一两个,剩下那个用默认值,结果出问题时根本不知道是哪一层先动手。

超时类型管的是什么设置原则
连接超时TCP/TLS 握手能不能建立起来设短,握手迟迟不成说明链路有问题,早失败早重试
读取超时两次数据块之间的最大间隔按模型出字节奏设,太短会在思考停顿的间隙误杀
整体超时整个请求从发出到结束的总时长最容易出事,长输出还没吐完就被它判死
握手阶段
请求刚发出、还没收到任何响应体之前的那一段
静默间隙
已经收到部分内容,模型在思考或调用工具时暂停出字的空档
阈值型中断
总是在某个固定时长附近断,八成是某一层卡了默认上限

判断自己踩的是哪一层,看中断位置就行:报错发生在请求发出后很短时间,偏连接;发生在中途、且已经收到部分内容,偏读取或整体。别把三种混在一起调,那样只会让下次更难定位。

按请求形态分档,而不是全局设一个值

把请求先粗分为三类:短问答与分类、长文与代码生成、带工具调用或多轮检索的 Agent 任务。这三类的合理超时量级差得很远,用一个全局值去套,必然是短请求太慢、长请求太紧。

  • 短问答类可以设得比较紧,快速失败反而让重试更早发生,用户体验更好
  • 长生成类要给足读取间隔和总时长,宁可贵一点也别断,断一次重来的成本更高
  • Agent 类请求的真实耗时取决于中间调了几次工具、跑了几轮检索,不能按单次模型响应的经验值估,建议单独一档并配合步数上限
  • 如果业务对响应时间有硬约束,比如前台同步接口,就不该靠拉长超时解决,应该改成异步任务加轮询或回调查询

分档之后,配置里最好按「请求类型 → 超时组」做映射,而不是散落在各处硬编码。这样以后换线路、换模型,只改一处映射就行,不用满项目找参数。

每一层该在哪里改:客户端、网关、上游

超时不是在客户端改一次就完事的,链路上每一层都有自己的默认值,任何一层先到点,都会把请求掐断。知道去哪一层改,比知道改成多少更重要。

所在层能不能改怎么处理
客户端 SDK能改连接与读取一般有独立参数,有的还支持整体超时,建议三个都显式写出
自建网关或反向代理能改注意代理层常比客户端还先动手,客户端根本收不到完整响应
上游中转站通常改不了只能通过站内目录挑线路相对稳的,固定时长附近就断多半是某层卡阈值

判断顺序:先确认是不是在固定时长附近断,是的话去核对各层默认值,看哪一层最接近;如果断点随机,优先看网络与服务端负载,而不是调超时。这条顺序能省掉大量无效尝试。

流式请求的坑:断流不等于超时

流式输出的超时判定看的是相邻数据块之间的间隔,不是总时长。所以整体超时对流式请求意义有限,读取间隔才是关键。很多人把整体超时拉得很大,结果断开照旧,因为动手的是读取间隔那一层。

  • 常见的假超时:模型在长思考或工具调用前有一段静默,超过读取间隔就被判死,实际服务端还在正常跑
  • 对策是让客户端或应用层能感知到心跳类数据,或者把读取间隔调到能覆盖最长的静默段
  • 如果上游根本不发心跳、静默期又很长,那调参数只能缓解,真正要做的是换一条转发链路更积极的线路
  • 流式请求出错时,先把收到的分片数记下来,分片数多说明已经在正常出字,问题在间隔上

什么情况不适用:如果任务本身要求即时可见的前台输出,而你用的线路静默期天然很长,那这类任务就不适合走流式,改成后台任务、完成后通知更稳妥。

超时排查的执行顺序

超时问题最怕乱试。下面这个顺序是从「先定量、再定位、后动手」来的,照着走能避免调了半天参数发现方向错了。

  1. 第一步:定量用站内测速工具先量出这条线路的延迟基线,知道正常范围长什么样,异常才好判断
  2. 第二步:定位层级看报错内容和中断位置,判断是连接、读取还是整体超时,别一上来就无脑加大所有数值
  3. 第三步:做对照同一提示词分别用短请求和长请求各跑一次,短请求正常长请求断,基本能锁定在总时长或读取间隔上
  4. 第四步:记录把每次超时的请求形态、耗时、中断位置记下来,攒几次就能看出是阈值型还是随机型
  5. 第五步:再动手确认是阈值问题再调参数,随机型问题调超时只是治标,该查的是网络和服务端负载

记录这一步最容易被跳过,但它是后面所有判断的依据。没有记录,你只能凭直觉猜,而直觉在超时问题上经常是错的。真实的延迟基线和价格档位,可以去 /price-watch 核对当时的数字,别拿旧印象当依据。

下一步先拿你手上最容易断的那个长请求做一次对照测试,把中断位置记下来,再去对应的超时层调参数。想先了解线路本身的稳定性,可以到 /sites 看各家线路的实测表现再决定从哪条下手。

常见问题

超时时间是不是设得越大越保险?

不是。设太大会让真正失败或卡死的请求迟迟不返回,占着连接和并发额度,排队越积越多。合理做法是按请求形态分档,给到刚好覆盖正常耗时且留一点余量,同时配合重试和失败快速返回。

为什么同一个模型有时正常有时超时?

常见原因是链路负载波动,不是超时参数本身。先固定请求形态和提示词长度做多次对照,如果中断点随机、时长也不固定,更像网络或服务端排队问题;如果总在某个时长附近断,才优先怀疑各层默认阈值。

带工具调用的请求老是中途失败怎么办?

这类请求耗时不取决于单次模型响应,而是取决于中间调了几次工具、跑了几轮。建议给它单独一档更宽的超时,同时设好工具调用步数上限,避免无限循环把时间耗光。如果仍频繁失败,要检查是不是某一步工具本身很慢。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。