大模型接口超时频发？手把手教你调整超时配置

调用大模型API时，如果出现 ReadTimeout、Request timed out 或网关返回 504，多数情况不是模型本身不可用，而是请求链路中某一层等待时间超过了默认限制。
这篇教程从最常见的超时位置讲起，给出 Python 代码、Nginx 反向代理两处的具体配置方法，并说明改完之后怎么验证。
适用于自建或调用第三方大模型接口的开发者，尤其适合刚接触 API 调用的零基础用户。

先判断超时发生在哪一层

大模型请求通常经过三层：客户端（你的代码）→ 反向代理（如 Nginx）→ 模型服务。
任何一层的超时时间小于实际响应时间，都会报错。

排查时先看报错信息里的关键词：

• 客户端报 Read timed out 或 ConnectTimeout：优先检查代码里的 timeout 参数。
• Nginx 返回 504 Gateway Time-out：检查 proxy_read_timeout 等代理配置。
• 模型服务自身日志显示请求处理过久：考虑模型推理耗时或资源不足。

下面按从客户端到服务端的顺序，逐个说明配置方法。

客户端：Python 请求超时设置

使用 OpenAI SDK

OpenAI Python SDK 默认超时时间较短，长文本生成容易触发。
可以在初始化客户端时统一设置：

from openai import OpenAI

client = OpenAI(
    api_key="你的API密钥",
    base_url="https://你的接口地址/v1",
    timeout=120.0,  # 单位秒，根据实际生成时长调整
    max_retries=2
)

如果只想针对单次请求调整，也可以在调用时传入：

response = client.chat.completions.create(
    model="你的模型名",
    messages=[{"role": "user", "content": "写一段200字的产品介绍"}],
    timeout=180.0
)

注意：timeout 设置的是单次请求的总等待时间，不是 token 生成速度。
如果你的模型输出较长（如超过 1000 tokens），建议先设 120 秒以上，再根据实际耗时微调。

使用 requests 库

如果直接调用 HTTP 接口，requests 默认没有超时限制，但部分网关会主动断开，表现为 ConnectionError。
显式设置超时更稳妥：

import requests

resp = requests.post(
    "https://你的接口地址/v1/chat/completions",
    headers={"Authorization": "Bearer 你的API密钥"},
    json={"model": "你的模型名", "messages": [{"role": "user", "content": "你好"}]},
    timeout=(10, 180)  # (连接超时, 读取超时)
)

元组形式中第一个值是建立连接的超时，第二个是等待响应的超时。
读取超时建议给足，因为大模型生成耗时波动较大。

反向代理：Nginx 超时调整

如果你通过 Nginx 转发到大模型服务，默认的 proxy_read_timeout 是 60 秒，长响应会被切断并返回 504。

在对应的 server 或 location 块中调整：

location /v1/ {
    proxy_pass http://127.0.0.1:8000;
    proxy_connect_timeout 10s;
    proxy_send_timeout 180s;
    proxy_read_timeout 180s;
    send_timeout 180s;
}

关键参数说明：

• proxy_connect_timeout：与后端建立连接的超时，一般 5–10 秒足够。
• proxy_read_timeout：等待后端响应的超时，大模型场景需要调大。
• proxy_send_timeout：向后端发送请求的超时，通常与读取超时保持一致。

修改后执行 nginx -t 检查语法，再 systemctl reload nginx（或宝塔面板中重载配置）使配置生效。

如果使用宝塔面板，路径为：网站 → 设置 → 配置文件，在对应 location 中追加上述参数后保存，面板会自动重载。

改完配置后如何验证

不要只看代码不报错就认为成功，建议做一次带计时的验证：

curl -w "time_total: %{time_total}s\n" -o /dev/null -s \
  -X POST https://你的接口地址/v1/chat/completions \
  -H "Authorization: Bearer 你的API密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型名","messages":[{"role":"user","content":"生成一段300字的说明"}]}'

观察 time_total 是否小于你设置的超时时间。
如果接近或超过，说明还需要继续调大，或者检查模型服务端的处理耗时。

另外，在客户端代码中捕获超时异常并打印耗时，能更快定位问题：

import time
start = time.time()
try:
    response = client.chat.completions.create(...)
except Exception as e:
    print(f"请求失败，耗时 {time.time() - start:.2f}s，错误：{e}")

常见坑与注意事项

• 只改了一处：客户端超时调大了，但 Nginx 还是 60 秒，结果仍然 504。三层要一起检查。
• 超时设得过长：设置 600 秒以上会占用连接资源，如果并发高，可能拖垮服务。建议根据实际 P95 耗时加 20% 余量。
• 忽略重试：超时后自动重试可能造成重复计费或重复生成，建议在业务层控制重试次数，并确认接口是否支持幂等。
• 流式响应场景：如果使用 stream 模式，超时判断的是两次数据块之间的间隔，不是总时长，配置时需单独考虑。

几个常见疑问

问：超时时间设置多少合适？
没有统一值。先统计正常请求的耗时分布，取 P95 耗时再加 20–30 秒缓冲。例如多数请求 40 秒完成，可设 60–70 秒。

问：改了 Nginx 超时还是 504 怎么办？
检查 Nginx 是否真的重载成功（nginx -t 输出 syntax is ok），以及请求是否经过了其他网关或负载均衡，那些层也可能有独立超时。

问：客户端和 Nginx 超时哪个优先？
以先到达的那个为准。客户端超时 30 秒、Nginx 超时 120 秒，实际 30 秒就会断开。所以客户端超时应大于等于 Nginx 超时，避免客户端提前放弃。

整体思路就是：先定位超时层级，再分别调整客户端和代理的超时参数，最后用计时请求验证。
如果环境里有多个代理或网关，逐层排查，不要只改一处就收工。