调用 AI 接口时的超时与重试:分层设置与可重试性判断

文章目录

问题:一次调用可能卡在几个不同阶段

调用 AI 接口和调用普通业务接口的差别在于时间分布很不稳定。普通接口常在几十毫秒内返回,而 AI 接口需要排队、推理、逐段输出,单次耗时可以从一秒到几十秒不等。一次请求可能卡在以下几个阶段:DNS 解析、TCP 建连、TLS 握手、服务端排队等待、模型生成、网络回传。

如果客户端不设超时,很多 HTTP 库的默认行为是长时间等待甚至无限等待。后果是连接池被占满、请求线程堆积、上游已经开始限流而本地仍在持续发起请求。

另一个方向的错误同样常见:超时设得比上游网关还长,请求早已在网关侧断开,客户端还在等;或者一旦超时就立刻重试,把一次慢请求放大成多次,既加重限流,也可能造成重复计费。

因此,超时和重试需要放在一起设计:超时决定「什么时候放弃」,重试决定「放弃之后是否再来一次」,两者必须共享同一个时间预算。

先分清三种时间,而不是一个数字

  1. 连接超时:建立 TCP 连接与 TLS 握手的时间。这一段通常应设得较短,避免网络异常时长时间挂起。
  2. 读超时:等待响应数据的时间。对非流式请求,它近似等于整个生成耗时;对输出较长的任务,需要留出足够余量。
  3. 总预算:从发起第一次请求到最终放弃的总时间,包含所有重试和退避等待。

很多库只接受一个 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,应优先遵守。最大尝试次数和总时间预算两者取先到者。

可操作的封装步骤

  1. 把 AI 调用收敛到一个客户端封装层,不要让超时参数散落在业务代码里。
  2. 为每类调用定义总预算:先看上游网关或调用方的超时限制,再给客户端留出余量,保证客户端总预算小于上游限制。
  3. 分别配置连接超时、读超时和连接池等待超时。连接超时取较短值,读超时按任务类型分档。
  4. 实现错误分类函数和退避函数,限制最大尝试次数。
  5. 每次尝试生成唯一请求 ID 并写入日志,记录尝试序号、状态码和耗时。
  6. 对流式接口单独实现空闲超时,不要复用非流式配置。

下面是一段示意代码,数值仅用于说明结构,实际值需结合网络质量、输出长度和上游限制调整:

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 层处理重复内容,这属于产品设计问题,而不仅是客户端配置问题。