PHP 调用 AI 接口时的超时处理实践

文章目录

问题从哪里来

PHP 调用 AI 接口时,超时通常不是单一原因。一次请求会经过 DNS 解析、TCP 连接、TLS 握手、发送请求、等待模型生成、接收响应等阶段;如果使用流式输出,还要持续读取分块数据。AI 接口的响应时间往往比普通查询接口更长,输出长度、排队情况和网络抖动都会影响耗时。

因此,不能只设置一个很大的超时,也不能把 PHP 的脚本执行时间当成网络超时。更稳妥的做法是把超时拆成几层:连接超时、总请求超时、流式读取的低速超时、PHP 执行超时,以及 Nginx、PHP-FPM、负载均衡等外层超时。内层超时应短于外层超时,让 PHP 有机会返回可读的错误,而不是让网关直接断开连接。

先区分几类超时

  • 连接超时:DNS、TCP 或 TLS 阶段没有及时建立连接。它适合设置得较短,避免请求卡在不可达地址上。
  • 总请求超时:从发起请求到接收完响应的总时长,适合非流式请求。
  • 读空闲或低速超时:流式响应已经建立,但长时间没有新数据,或传输速度过低。
  • 应用执行超时:PHP 的 max_execution_time、PHP-FPM 的 request_terminate_timeout 等限制。
  • 网关超时:Nginx 的代理读取超时、负载均衡的空闲超时等。它们通常比 PHP 内部超时更靠外。

下面的数字只是示例,不是推荐值。实际值应结合接口 SLA、最大输出长度、用户可接受等待时间和网关配置来确定。

用 cURL 设置非流式请求

非流式请求适合设置明确的连接超时和总超时。示例中把连接超时设为 3 秒,总超时设为 60 秒,仅用于说明配置方式。

function requestAi(string $url, array $payload, string $apiKey): array
{
    $body = json_encode($payload, JSON_UNESCAPED_UNICODE);
    if ($body === false) {
        throw new RuntimeException('JSON 编码失败');
    }

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $apiKey,
        ],
        CURLOPT_POSTFIELDS => $body,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT_MS => 3000,
        CURLOPT_TIMEOUT_MS => 60000,
        CURLOPT_NOSIGNAL => true,
    ]);

    $raw = curl_exec($ch);
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($errno === CURLE_OPERATION_TIMEDOUT) {
        throw new RuntimeException('AI 接口超时:' . $error);
    }
    if ($errno !== 0 || $raw === false) {
        throw new RuntimeException('网络错误:' . $error);
    }

    return [$status, $raw];
}

调用方应根据 HTTP 状态码和响应体区分错误。例如 400 多半是参数问题,401 是鉴权问题,429 表示限流,5xx 表示服务端异常。不要把所有非 200 都当成网络超时。

流式响应要单独处理

流式响应通常使用 Server-Sent Events 或分块传输。此时总超时的含义会变化:如果总超时太短,长回答会被中途切断;如果完全不设限制,连接又可能长期挂起。可以考虑设置连接超时、较长的总超时,并配合低速限制检测停滞。

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey,
        'Accept: text/event-stream',
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => false,
    CURLOPT_CONNECTTIMEOUT_MS => 3000,
    CURLOPT_TIMEOUT_MS => 180000,
    CURLOPT_LOW_SPEED_LIMIT => 1,
    CURLOPT_LOW_SPEED_TIME => 30,
    CURLOPT_NOSIGNAL => true,
    CURLOPT_WRITEFUNCTION => function ($ch, string $chunk): int {
        echo $chunk;
        if (ob_get_level() > 0) {
            @ob_flush();
        }
        flush();
        return strlen($chunk);
    },
]);

$ok = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
curl_close($ch);

输出缓冲、压缩和代理缓冲可能让流式内容无法及时到达浏览器。实际项目中要检查输出缓冲设置,并避免中间层缓存整个响应。如果业务允许,也可以把流式响应的总超时设为略大于最大生成时间,而不是无限等待。

重试与错误分类

超时后是否重试,要看请求是否幂等。查询类请求通常可以重试;AI 生成请求往往是 POST,服务端可能已经收到并处理,只是响应没有及时返回。盲目重试可能造成重复计费、重复生成或数据重复写入。

可以按以下顺序处理:

  1. 连接失败、DNS 失败、明确未建立连接的请求,可有限次重试。
  2. 429 和部分 5xx 可按退避策略重试,但要设置最大次数和总时间预算。
  3. 参数错误、鉴权错误不要重试。
  4. 已经等待很久的生成请求,重试前先确认业务是否允许重复处理;如果接口支持请求标识或幂等键,应优先使用。
  5. 重试要有上限,并在日志中记录请求标识、状态码、耗时和错误类型,便于排查。

退避可以采用指数退避加随机抖动,避免大量客户端同时重试。重试预算应小于用户可接受等待时间,不能因为重试让请求无限延长。

常见错误

  • 只设置 CURLOPT_TIMEOUT_MS,不设置 CURLOPT_CONNECTTIMEOUT_MS,连接阶段可能长时间卡住。
  • PHP 超时设置得比 Nginx 或负载均衡更长,用户先收到网关错误,PHP 仍在后台执行。
  • 把 max_execution_time 当作网络超时。它主要限制脚本执行,不等同于 cURL 的网络超时。
  • 对 AI 生成请求无脑重试,造成重复调用或重复计费。
  • 流式请求使用过短的总超时,回答被中途截断;或者完全不设低速限制,连接长期挂起。
  • 超时后不记录响应体和状态码,无法判断是限流、参数错误还是服务端异常。
  • 忽略 JSON 编码失败、请求体过大、输出长度过长等应用层问题,把它们误判为网络超时。

适用边界

超时设置只能控制客户端等待多久,不能保证服务端停止处理。请求超时后,AI 服务可能仍在生成内容,因此需要结合业务幂等、请求标识和结果补偿来设计。不同接口的超时语义也可能不同,流式接口尤其要阅读其文档。

没有一组通用超时值适合所有场景。较短的超时能更快释放资源,但会增加失败率;较长的超时能容忍慢响应,但会占用 PHP 进程和连接。建议先明确用户等待上限,再让连接超时、总超时、PHP 执行超时和网关超时形成由内到外的合理层级,并通过日志持续观察超时分布,而不是只依赖一个固定数字。