> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hhapi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# HHAPI 请求超时排查：推荐超时时长配置与网络诊断方法

> 解决 HHAPI 请求超时问题：了解 AI 推理接口为何需要更长超时时间，获取 Python 和 Node.js 的推荐超时配置（非流式 60s+，流式 120s+）及网络诊断建议。

AI 推理接口与普通 REST API 不同——模型生成响应需要一定的计算时间，尤其是输出内容较长或上下文较多时，单次请求耗时可能达到数十秒。如果客户端的超时配置沿用了普通接口的默认值（通常 5–10 秒），很容易在等待生成结果时触发超时中断。

## 常见超时原因

<AccordionGroup>
  <Accordion title="客户端超时设置过短">
    许多 HTTP 客户端的默认超时为 5 秒或 10 秒，这对于 AI 生成接口来说通常不够用。需要根据实际使用场景适当调大超时值。
  </Accordion>

  <Accordion title="请求内容过长">
    当 `messages` 数组包含大量历史对话记录，或单条消息包含超长文本时，模型处理输入阶段本身就需要较多时间，进一步增加了总响应时长。建议对历史消息进行截断或摘要处理，控制每次请求的 Token 总量。
  </Accordion>

  <Accordion title="网络问题或服务端高负载">
    客户端到 HHAPI 服务端之间的网络延迟、DNS 解析缓慢，或服务端在高峰期的排队等待，都可能导致请求耗时增加。可参考下方网络诊断建议进行排查。
  </Accordion>
</AccordionGroup>

## 推荐超时配置

<CodeGroup>
  ```python Python theme={null}
  import os
  import openai

  client = openai.OpenAI(
      api_key=os.environ.get("HHAPI_API_KEY"),
      base_url="<API_BASE_URL>/v1",
      # 非流式请求：建议设置 60 秒以上
      timeout=60.0
  )

  # 流式请求：建议设置 120 秒以上
  # 也可针对单次调用单独设置超时
  stream_client = openai.OpenAI(
      api_key=os.environ.get("HHAPI_API_KEY"),
      base_url="<API_BASE_URL>/v1",
      timeout=120.0
  )

  with stream_client.chat.completions.stream(
      model="<MODEL_ID>",
      messages=[{"role": "user", "content": "写一篇 1000 字的文章"}],
  ) as stream:
      for text in stream.text_stream:
          print(text, end="", flush=True)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";

  // 非流式请求：建议 60 秒以上
  const client = new OpenAI({
    apiKey: process.env.HHAPI_API_KEY,
    baseURL: "<API_BASE_URL>/v1",
    timeout: 60 * 1000, // 单位：毫秒
  });

  // 流式请求：建议 120 秒以上
  const streamClient = new OpenAI({
    apiKey: process.env.HHAPI_API_KEY,
    baseURL: "<API_BASE_URL>/v1",
    timeout: 120 * 1000,
  });

  const stream = await streamClient.chat.completions.create({
    model: "<MODEL_ID>",
    messages: [{ role: "user", content: "写一篇 1000 字的文章" }],
    stream: true,
  });

  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
  ```
</CodeGroup>

## curl 超时设置

使用 curl 测试时，可通过 `--max-time` 参数设置最大等待时间（单位：秒）：

```bash theme={null}
# 设置最大等待时间为 90 秒
curl <API_BASE_URL>/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  --max-time 90 \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

## 流式请求的特殊处理

<Note>
  流式请求（`"stream": true`）的超时语义与普通请求不同。连接建立后，服务端会持续推送数据块（SSE chunks）。客户端**不应**因为两个数据块之间的短暂间隔而触发超时断开——整体传输时长才是判断超时的依据。

  建议使用「连接超时」（connect timeout，如 10 秒）和「整体传输超时」（total timeout，如 120 秒）分开配置，而非使用同一个短超时值。
</Note>

## 网络诊断建议

若频繁出现超时，可使用以下方法诊断网络层面的问题：

```bash theme={null}
# 使用 -v 查看连接各阶段耗时（DNS 解析、TCP 握手、TLS 握手、首字节时间）
curl -v --max-time 30 \
  <API_BASE_URL>/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

```bash theme={null}
# 检查 DNS 解析是否正常
nslookup <API_BASE_URL>
# 或
dig <API_BASE_URL>
```

重点关注：

* **DNS 解析时间**：解析耗时过长可能需要更换 DNS 服务器
* **TCP/TLS 握手时间**：握手失败通常是网络连通性问题
* **首字节时间（TTFB）**：反映服务端响应延迟

<Note>
  如果在排查后仍然频繁超时，请联系 [技术支持](/support) 并提供请求时间、接口路径和错误信息，以便确认是否为服务端异常。
</Note>

***

**相关资源**

* [流式输出异常排查](/faq/streaming-issues)
* [获取技术支持](/support)