超时问题

请求超时是指客户端在指定时间内未收到服务器的响应。这通常与网络状况、模型响应速度或超时配置有关。

常见超时错误

错误信息	说明
`ETIMEDOUT`	连接超时，无法在规定时间内建立连接
`ESOCKETTIMEDOUT`	Socket 超时，连接已建立但数据传输超时
`ReadTimeoutError`	读取超时，服务器未在规定时间内返回响应
`Gateway Timeout (504)`	网关超时，上游模型服务响应超时

原因分析

网络延迟

客户端与服务器之间的网络延迟过高
跨地域访问导致延迟增大
网络带宽不足

模型响应慢

复杂的 prompt 导致模型推理时间过长
max_tokens 设置过大，生成时间变长
上游模型服务负载高，排队等待时间长
使用了推理能力更强的模型（如 o1、deepseek-reasoner），响应时间天然较长

超时设置过短

客户端的超时设置默认值太小
SDK 的默认超时不适用于大模型场景
网关的超时配置限制

排查步骤

1. 测试网络延迟

# 测试到服务器的延迟
ping api.example.com

# 测试 TCP 连接时间
curl -o /dev/null -s -w "TCP Connect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY"

2. 检查超时配置

# Python requests 默认无超时，需手动设置
import requests

# 错误：没有设置超时
response = requests.post(url, headers=headers, json=data)

# 正确：设置合理的超时
response = requests.post(url, headers=headers, json=data, timeout=60)

// JavaScript fetch 需要使用 AbortController
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 60000);

try {
    const response = await fetch(url, {
        method: "POST",
        headers: headers,
        body: JSON.stringify(data),
        signal: controller.signal,
    });
    clearTimeout(timeoutId);
} catch (error) {
    console.error("Request timed out:", error);
}

3. 测试简单请求

发送一个最小请求，观察是否仍然超时：

curl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}], "max_tokens": 5}' \
  --max-time 60

如果最小请求也超时，说明问题可能出在网络或服务端；如果只有大请求超时，说明是模型推理时间过长。

解决方案

增加超时时间

根据模型和请求复杂度，设置合理的超时值：

场景	建议超时时间
简单对话（max_tokens < 100）	30 秒
普通对话（max_tokens < 1000）	60 秒
长文本生成（max_tokens > 4000）	120 秒
推理模型（o1、deepseek-reasoner）	180 秒以上

# Python OpenAI SDK
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.example.com/v1",
    timeout=120.0,  # 设置超时为 120 秒
)

// JavaScript OpenAI SDK
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "sk-your-api-key",
    baseURL: "https://api.example.com/v1",
    timeout: 120000,  // 设置超时为 120 秒（毫秒）
});

使用流式响应

流式响应可以在模型开始生成后立即返回数据，避免等待整个响应完成：

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一篇长文章"}],
    stream=True,  # 启用流式响应
)

for chunk in response:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

# cURL 流式请求
curl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

检查网络环境

确认网络连接稳定
如果使用 VPN 或代理，检查是否影响连接
尝试切换网络环境（如从 WiFi 切换到有线网络）
如果在中国大陆访问海外服务，确认网络链路是否通畅

优化请求参数

减小 max_tokens 参数，避免生成长文本
精简 prompt，减少输入 token 数量
使用响应更快的模型（如 gpt-4o-mini 替代 gpt-4o）