问题从哪里来
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,服务端可能已经收到并处理,只是响应没有及时返回。盲目重试可能造成重复计费、重复生成或数据重复写入。
可以按以下顺序处理:
- 连接失败、DNS 失败、明确未建立连接的请求,可有限次重试。
- 429 和部分 5xx 可按退避策略重试,但要设置最大次数和总时间预算。
- 参数错误、鉴权错误不要重试。
- 已经等待很久的生成请求,重试前先确认业务是否允许重复处理;如果接口支持请求标识或幂等键,应优先使用。
- 重试要有上限,并在日志中记录请求标识、状态码、耗时和错误类型,便于排查。
退避可以采用指数退避加随机抖动,避免大量客户端同时重试。重试预算应小于用户可接受等待时间,不能因为重试让请求无限延长。
常见错误
- 只设置
CURLOPT_TIMEOUT_MS,不设置CURLOPT_CONNECTTIMEOUT_MS,连接阶段可能长时间卡住。 - PHP 超时设置得比 Nginx 或负载均衡更长,用户先收到网关错误,PHP 仍在后台执行。
- 把
max_execution_time当作网络超时。它主要限制脚本执行,不等同于 cURL 的网络超时。 - 对 AI 生成请求无脑重试,造成重复调用或重复计费。
- 流式请求使用过短的总超时,回答被中途截断;或者完全不设低速限制,连接长期挂起。
- 超时后不记录响应体和状态码,无法判断是限流、参数错误还是服务端异常。
- 忽略 JSON 编码失败、请求体过大、输出长度过长等应用层问题,把它们误判为网络超时。
适用边界
超时设置只能控制客户端等待多久,不能保证服务端停止处理。请求超时后,AI 服务可能仍在生成内容,因此需要结合业务幂等、请求标识和结果补偿来设计。不同接口的超时语义也可能不同,流式接口尤其要阅读其文档。
没有一组通用超时值适合所有场景。较短的超时能更快释放资源,但会增加失败率;较长的超时能容忍慢响应,但会占用 PHP 进程和连接。建议先明确用户等待上限,再让连接超时、总超时、PHP 执行超时和网关超时形成由内到外的合理层级,并通过日志持续观察超时分布,而不是只依赖一个固定数字。