问题:一次调用可能卡在几个不同阶段
调用 AI 接口和调用普通业务接口的差别在于时间分布很不稳定。普通接口常在几十毫秒内返回,而 AI 接口需要排队、推理、逐段输出,单次耗时可以从一秒到几十秒不等。一次请求可能卡在以下几个阶段:DNS 解析、TCP 建连、TLS 握手、服务端排队等待、模型生成、网络回传。
如果客户端不设超时,很多 HTTP 库的默认行为是长时间等待甚至无限等待。后果是连接池被占满、请求线程堆积、上游已经开始限流而本地仍在持续发起请求。
另一个方向的错误同样常见:超时设得比上游网关还长,请求早已在网关侧断开,客户端还在等;或者一旦超时就立刻重试,把一次慢请求放大成多次,既加重限流,也可能造成重复计费。
因此,超时和重试需要放在一起设计:超时决定「什么时候放弃」,重试决定「放弃之后是否再来一次」,两者必须共享同一个时间预算。
先分清三种时间,而不是一个数字
- 连接超时:建立 TCP 连接与 TLS 握手的时间。这一段通常应设得较短,避免网络异常时长时间挂起。
- 读超时:等待响应数据的时间。对非流式请求,它近似等于整个生成耗时;对输出较长的任务,需要留出足够余量。
- 总预算:从发起第一次请求到最终放弃的总时间,包含所有重试和退避等待。
很多库只接受一个 timeout 参数,会把连接超时和读超时混在一起。例如 Python 的 requests 支持 (connect, read) 元组;httpx 支持分别设置 connect、read、write、pool;Go 的 http.Client.Timeout 控制整体时长,建连时间则由 Transport 的 DialContext 控制。使用前应查清所用库的语义,不要假设单个数字能覆盖全部阶段。
重试必须共享总预算。若每次超时 30 秒、最多重试 3 次,实际最坏等待会超过 90 秒,很容易超过上游网关或用户可接受的范围。
流式输出:用空闲超时而非总超时
流式场景下,总时长可能很长,但服务一直在持续返回数据,这不属于故障。此时真正需要检测的是「两个数据块之间停了多久」,也就是读超时(socket 级空闲时间)。同时,外层仍应有一个总上限,防止服务挂死后进程永不退出。
如果客户端库的读超时正好按「两次收到数据之间的最大间隔」计算,可以直接使用;如果不支持,可以在读循环中自行计时,超过阈值就中断连接。
重试之前先判断可重试性
重试不是越多越好,关键是把错误分成三类:
- 可重试:建连失败、连接被重置、未收到任何内容的读超时、HTTP 429、500、502、503、504。
- 不可重试:400、401、403、404、413、422 等。请求本身有问题,重试只会重复失败并浪费配额。
- 需谨慎:流式内容已经开始输出后中断。此时重试会造成重复内容和重复计费,更适合提示用户重新生成或从断点继续。
退避策略建议采用指数退避加随机抖动,并设置上限;如果服务端返回 Retry-After,应优先遵守。最大尝试次数和总时间预算两者取先到者。
可操作的封装步骤
- 把 AI 调用收敛到一个客户端封装层,不要让超时参数散落在业务代码里。
- 为每类调用定义总预算:先看上游网关或调用方的超时限制,再给客户端留出余量,保证客户端总预算小于上游限制。
- 分别配置连接超时、读超时和连接池等待超时。连接超时取较短值,读超时按任务类型分档。
- 实现错误分类函数和退避函数,限制最大尝试次数。
- 每次尝试生成唯一请求 ID 并写入日志,记录尝试序号、状态码和耗时。
- 对流式接口单独实现空闲超时,不要复用非流式配置。
下面是一段示意代码,数值仅用于说明结构,实际值需结合网络质量、输出长度和上游限制调整:
import random
import time
import httpx
RETRYABLE_STATUS = {429, 500, 502, 503, 504}
def new_request_id():
return str(time.time_ns())
def backoff(attempt):
base = min(8.0, 0.5 * 2 ** (attempt - 1))
return base * (0.5 + random.random())
def call_ai(url, payload, deadline=45.0, max_attempts=3):
start = time.monotonic()
for attempt in range(1, max_attempts + 1):
remaining = deadline - (time.monotonic() - start)
if remaining <= 0:
raise TimeoutError('总时间预算已耗尽')
timeout = httpx.Timeout(
connect=min(5.0, remaining),
read=min(30.0, remaining),
write=min(10.0, remaining),
pool=min(5.0, remaining),
)
try:
with httpx.Client(timeout=timeout) as client:
resp = client.post(url, json=payload,
headers={'X-Request-Id': new_request_id()})
except (httpx.ConnectError, httpx.ReadTimeout,
httpx.RemoteProtocolError):
if attempt == max_attempts:
raise
time.sleep(min(backoff(attempt), max(0.0, remaining - 0.1)))
continue
if resp.status_code in RETRYABLE_STATUS and attempt < max_attempts:
time.sleep(min(backoff(attempt), max(0.0, remaining - 0.1)))
continue
resp.raise_for_status()
return resp.json()流式请求的读取逻辑可以简化为:
timeout = httpx.Timeout(connect=5.0, read=20.0, write=10.0, pool=5.0)
with httpx.Client(timeout=timeout) as client:
with client.stream('POST', url, json=payload) as resp:
resp.raise_for_status()
for chunk in resp.iter_bytes():
handle(chunk)这里的 read 表示两次收到数据之间允许的最长间隔,而不是整个回答的总时长。
常见错误
- 只写一个
timeout=30:建连慢时会挤占生成时间,且无法区分故障阶段。 - 重试循环放在总预算之外:实际最长等待远超预期。
- 重试时重新生成随机参数:结果无法对比,排查困难。
- 对创建类接口无幂等键就重试:可能产生重复记录或重复扣费。
- 忽略
Retry-After:按自己的节奏继续请求,触发更严格的限流。 - 客户端超时短于服务端典型处理时间:每次都超时,每次都重试。
- 流式接口只设总超时:正常的长回答被误杀;只设空闲超时又可能导致服务异常时永不退出。
- 日志缺少请求 ID 和尝试序号:无法判断失败来自超时、限流还是参数错误。
适用边界
本文讨论的是 HTTP 同步调用。异步任务型 API 通常采用「提交任务 + 轮询结果」的模式,超时和重试应放在轮询层,提交动作本身要保持幂等,避免重复创建任务。
超时和重试的具体数值没有通用最优解,需要结合模型输出长度、网络状况和上游网关配置确定。本文不给出所谓最佳值,也不宣称任何参数组合能适配所有场景。
重试不能解决容量问题。持续出现 429 说明配额或并发已经不足,应当限流、排队或降级,而不是增加重试次数。对于已开始输出内容的流式请求,重试需要在 UI 层处理重复内容,这属于产品设计问题,而不仅是客户端配置问题。