文生图接口超时主因是Guzzle默认超时为0，必须手动配置connect_timeout（建议3.0s）、timeout（建议15.0s）和read_timeout（建议5.0s）三层超时，否则PHP进程卡死、连接耗尽；同时需配合http_errors=>false及针对429/503的业务逻辑处理。
文生图接口超时不是“请求慢”，而是Guzzle默认不设限，必须手动配三层超时——否则PHP进程卡死、连接耗尽、监控失灵。
为什么文生图请求特别容易超时
文生图（如百度文心千帆、DeepSeek-VL、阿里万相）本质是长耗时AI推理任务：上传图片+提示词 → 服务端排队 → 模型生成 → 返回base64或URL。整个链路常达3–30秒，远超普通API的几百毫秒。而Guzzle默认timeout和connect_timeout都是0（无限等待），一旦后端卡在队列或显存不足，PHP进程就挂住不动。
- 常见错误现象：
GuzzleHttp\Exception\RequestException报错信息里带cURL error 28: Operation timed out，但没明确是连不上还是等太久 - 真实瓶颈往往不在网络，而在服务端排队或生成阶段——这时候只靠
timeout不够，得拆开控 - 别信“加个
timeout=30就行”，30秒对用户是不可接受的等待，对服务器是资源黑洞
必须配齐的三个超时参数
Guzzle的connect_timeout、timeout、read_timeout不是可选项，是文生图场景的生存配置。它们控制不同阶段，缺一不可：
-
connect_timeout：DNS解析+TCP建连时间，建议设3.0。文心千帆域名（aip.baidubce.com）在国内偶尔DNS抖动，不设这个，请求直接卡死在第一步 -
timeout：从发请求到收完响应头的总耗时上限，建议15.0。它包含建连+发数据+等响应头，必须大于connect_timeout，否则建连成功前就超时了 -
read_timeout：收到响应头后，等响应体（比如大图base64）传完的单次读取间隔，建议5.0。防止服务端已开始返回但传输断续，导致连接空挂
完整客户端初始化示例：
立即学习“PHP免费学习笔记（深入）”；
$client = new GuzzleHttp\Client([
'base_uri' => 'https://aip.baidubce.com',
'connect_timeout' => 3.0,
'timeout' => 15.0,
'read_timeout' => 5.0,
'http_errors' => false, // 关键：文生图常返400/503，别让异常中断流程
]);
如何处理400/503这类“业务超时”
文生图接口返回400 Bad Request（参数错）、429 Too Many Requests（限流）、503 Service Unavailable（后端忙）很常见——这些不是网络失败，Guzzle默认不抛异常，http_errors => false下你得自己判断：
- 先检查
$response->getStatusCode()，不是2xx就别硬解body -
429要退避重试，用指数退避（如第一次等1s，第二次2s，第三次4s），别狂刷 -
503大概率是服务端队列满，直接返回用户“正在排队，请稍后再试”，别重试 - 捕获
GuzzleHttp\Exception\ConnectException（连不上）和RequestException（超时/服务端崩）要分开处理，前者可立即重试，后者大概率要降级
示例判断逻辑：
try {
$response = $client->post('/rpc/2.0/ai_custom/v1/wenxinworkshop/image/gen', [
'headers' => ['Content-Type' => 'application/json'],
'json' => $payload,
]);
$code = $response->getStatusCode();
if ($code === 200) {
return json_decode($response->getBody(), true);
} elseif ($code === 429) {
usleep(1000000); // 等1秒
return callImageGen($payload); // 递归重试（需加最大次数限制）
} else {
throw new RuntimeException("API error: {$code}");
}
} catch (GuzzleHttp\Exception\ConnectException $e) {
// DNS或连不上，换节点或告警
Log::error('Connect failed', ['url' => $e->getRequest()->getUri()]);
} catch (GuzzleHttp\Exception\RequestException $e) {
// timeout或5xx，记录并降级
Log::warning('Request timeout or server error', ['msg' => $e->getMessage()]);
}
Laravel里用Http facade要注意什么
Laravel的Http facade底层确实是Guzzle，但它砍掉了read_timeout支持，也没法直接访问底层StreamInterface——这意味着你无法精细控制文生图这种大响应体的读取节奏。
- 如果你用
Http::timeout(15)->post(...)，它只设了Guzzle的timeout，没设read_timeout，遇到服务端缓慢吐图仍可能卡住 - 更麻烦的是，
Httpfacade的retry()机制对429/503无效，它只重试网络层失败 - 结论：文生图这种高风险调用，别图省事，老实用原生
GuzzleHttp\Client，自己控三超时+自定义重试逻辑
真要用Http facade，至少补一层保护：
// 在调用前加超时信号量（Linux only）
pcntl_alarm(20); // 强制20秒后中断
pcntl_signal(SIGALRM, function () {
throw new RuntimeException('HTTP call forced timeout');
});
$response = Http::timeout(15)->post(...);
pcntl_alarm(0); // 清除
真正难的不是配参数，是区分“服务端真忙”和“自己没配好”——很多团队把超时归咎于AI服务商，结果发现只是connect_timeout没设，DNS解析卡了8秒才连上。
