APIMart API 超时怎么排查和处理？
简答：APIMart API 超时，先不要直接增加等待时间或重复提交：先用最小请求确认 API 地址、Key、模型名和响应状态，再区分连接建立超时、读取超时、代理超时与模型处理慢。同步聊天请求可以配置客户端 timeout，流式请求要持续消费响应，图像或视频等长任务则应优先采用接口支持的异步任务和 task_id 轮询；具体模型、接口状态与账户配置以 APIMart 当前文档和控制台为准。
定义：APIMart API 超时，是客户端在规定时间内没有完成连接、收到响应头或读完响应数据而主动中止请求的现象，不等同于 APIMart 一定发生故障。
先试这一步：用最小请求确认是不是基础连接问题
本文是面向 APIMart 用户的第三方接入指南，不是 APIMart 官方页面。APIMart 公开文档示例使用 https://api.apimart.ai/v1 作为 Base URL，并通过 Authorization: Bearer 发送 API Key；但模型名称和可用接口可能随当前账户与文档变化，下面统一使用环境变量 APIMART_MODEL，不要直接复制过时模型名。来源可参考 APIMart Gemini CLI 接入文档。
- 先在当前终端安全设置临时变量：
export APIMART_API_KEY='你的Key'、export APIMART_MODEL='从当前模型列表核对的模型名'。Windows PowerShell 可使用$env:APIMART_API_KEY='你的Key'和$env:APIMART_MODEL='模型名'。 - 用 curl 区分连接阶段和整体请求阶段：
curl --connect-timeout 10 --max-time 60 -sS -o response.json -w 'status=%{http_code} connect=%{time_connect} start=%{time_starttransfer} total=%{time_total}\n' https://api.apimart.ai/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer $APIMART_API_KEY" -d '{"model":"'"$APIMART_MODEL"'","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'。 - 只判断结果，不要把 Key 打印到日志：
test -n "$APIMART_API_KEY" && echo 'key_present=true' || echo 'key_present=false'。curl 的--connect-timeout只限制 DNS、TCP、TLS 等连接阶段，--max-time限制整个传输过程，具体含义见 curl 官方手册。
如果 DNS、TLS 或连接都失败，优先查域名解析、本机网络、防火墙和代理；如果能返回 HTTP 状态码，说明请求至少到达了某个 HTTP 服务，下一步应查看状态码、响应体和请求参数，而不是继续盲目加大 timeout。
按现象定位：连接超时、读取超时、504 和模型处理慢
| 现象 | 更可能的层级 | 先做什么 |
|---|---|---|
| DNS 解析失败、TLS 握手失败、curl 一直连不上 | 本地网络、DNS、代理或连接阶段 | 检查域名、代理变量、证书链，并用 --connect-timeout 单独测连接 |
| 连接成功但长时间没有响应头 | 网关等待、上游排队或模型处理阶段 | 记录 time_connect、time_starttransfer，核对模型和请求体大小 |
| HTTP 504 | 某一层网关或上游等待超过限制 | 记录状态码、响应体、时间戳和 request ID；不要据此断言 APIMart 固定存在某个超时秒数 |
| 收到部分流式内容后中断 | 读取超时、连接被关闭或客户端未持续消费 | 检查流式读取循环、代理缓冲和客户端 read timeout |
| 客户端报 timeout，但服务端可能已经开始生成 | 客户端主动取消或读取窗口过短 | 谨慎重试；对生成类请求先确认是否有 task_id、request ID 或控制台记录 |
APIMart 公开资料没有核实出统一适用于所有模型和接口的网关超时数值，因此不要把 10 秒、60 秒或其他示例值写成 APIMart 的 SLA。排查时应把客户端日志与控制台可见的请求记录关联起来；公开接入文档提到可查看请求日志、调用统计和使用情况，但具体菜单以当前版本为准。
按客户端设置 timeout：Python、Node.js、Java 和 curl
Python OpenAI SDK
如果使用当前 OpenAI Python SDK 兼容方式，客户端可以设置整体 timeout，也可以通过 HTTPX 风格对象分别设置 connect、read 和 write。SDK 文档说明 timeout 会抛出 APITimeoutError，并且默认会对部分连接错误、408、429 和 500 以上错误进行有限重试；生产环境应明确设置自己的重试预算。参考 openai-python 官方 README。
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["APIMART_API_KEY"],
base_url="https://api.apimart.ai/v1",
timeout=60.0,
max_retries=0,
)
response = client.chat.completions.create(
model=os.environ["APIMART_MODEL"],
messages=[{"role":"user","content":"ping"}],
max_tokens=16,
)
print(response.choices[0].message.content)
这里的 60 秒只是示例上限，不是 APIMart 官方推荐值。若需要更细的连接和读取边界，可使用 SDK 支持的 timeout 对象；流式消费时不要只设置“等待首字节”的思路，还要保证读取循环持续运行。
Node.js fetch 与 axios
Node.js 原生 fetch 可以通过 AbortSignal.timeout() 设置取消时间；该方法在 Node.js 文档中有明确说明。对于 axios，timeout 的单位是毫秒，超过后请求会被中止，见 Node.js 官方文档 和 axios 请求配置文档。
const controller = AbortSignal.timeout(60000);
const res = await fetch("https://api.apimart.ai/v1/chat/completions", {
method: "POST",
signal: controller,
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.APIMART_API_KEY}`
},
body: JSON.stringify({
model: process.env.APIMART_MODEL,
messages: [{ role: "user", content: "ping" }],
max_tokens: 16
})
});
console.log(res.status, await res.text());
axios 示例：const axios = require("axios");
const res = await axios.post("https://api.apimart.ai/v1/chat/completions", {
model: process.env.APIMART_MODEL,
messages: [{ role: "user", content: "ping" }],
max_tokens: 16
}, {
timeout: 60000,
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.APIMART_API_KEY}`
}
});
console.log(res.status, res.data);
Java 11+ HttpClient
Java 的 HttpClient.Builder.connectTimeout()控制建立连接的时间，HttpRequest.Builder.timeout()控制单个请求等待响应的时间；如果不设置请求 timeout，JDK 文档说明其效果相当于无限等待。参考 Java HttpClient.Builder 文档 和 Java HttpRequest.Builder 文档。
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.apimart.ai/v1/chat/completions"))
.timeout(Duration.ofSeconds(60))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + System.getenv("APIMART_API_KEY"))
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
重试、流式和异步任务：什么时候可以继续发请求
超时后的重试不是无条件安全的。对于只读或明确幂等的请求，可以在连接错误、408、429、部分 5xx 情况下采用有限次数的指数退避；如果响应包含 Retry-After，优先遵循服务端给出的等待提示。OpenAI Python SDK 的公开实现展示了有限重试、指数退避和随机抖动的做法，但这不等于 APIMart 的固定重试政策。
- 不要盲目重试 400、401、403、404：先修正请求体、Key、权限、Base URL 或路径。
- 429：降低并发，读取
Retry-After，设置最大重试次数和总等待上限。 - 500、502、503、504：可做少量重试，但要记录状态码和请求 ID；连续失败时应熔断或转人工排查。
- 生成类 POST：超时后可能无法确认服务端是否已受理。若接口支持
Idempotency-Key、task_id或状态查询，应优先使用这些机制，避免重复生成。
流式请求适合需要尽早看到首段输出的文本场景，但客户端必须持续消费数据，并区分“已经收到部分内容后断开”和“一个字节都没收到”。前者不要简单从头重放，否则可能造成重复输出或重复扣费；OpenAI Python SDK 也明确提示，流式消费本身不会自动重试，因为重放可能重复已经交付的输出。
图像、视频或其他长耗时任务不应把客户端一直阻塞在一次同步请求上。若当前 APIMart 接口文档提供 task_id 和状态查询，就采用“提交任务—保存 task_id—按退避间隔轮询—读取结果”的流程；如果当前接口没有公开异步字段，不要自行假设存在固定轮询地址。
一次排查应记录哪些字段？
为了判断是客户端设置问题还是上游处理变慢，至少记录以下字段：请求开始时间、Base URL 主机名、接口路径、模型名、客户端版本、连接耗时、首字节耗时、总耗时、HTTP 状态码、响应错误类型、request ID、输入输出 token（如果响应提供）以及是否发生重试。日志中只保留 Key 是否存在，不要写入完整 Key、Authorization 头、完整提示词或可能包含隐私的数据。
- 先用最小提示词和小输出验证基础链路。
- 再逐步增加上下文长度、图片尺寸、输出上限或工具调用，观察是哪一项让首字节或总耗时明显增加。
- 比较非流式与流式请求时，保持模型和输入一致，避免把模型变化误认为 timeout 配置生效。
- 如果只有某一个模型超时，先核对该模型当前是否可用；公开资料未核实的模型状态、网关 SLA、固定限额和具体价格，都应以 APIMart 当前文档或控制台为准。
参考资料
本文关键配置和概念来自以下公开资料：APIMart Gemini CLI 接入文档、OpenAI Python SDK 官方 README、Node.js 官方文档、axios 请求配置文档、Java HttpRequest.Builder 文档 和 curl 官方手册。APIMart 具体模型、账户权限、状态和计费以当前官方文档与控制台显示为准。
常见问题
APIMart API 超时是不是一定代表 APIMart 服务故障？
不是。超时可能发生在 DNS、TLS、代理、客户端连接、读取、网关等待或模型处理阶段。先看是否能拿到 HTTP 状态码，再用 curl 的连接耗时、首字节耗时和总耗时区分层级。公开资料未核实 APIMart 对所有模型统一适用的网关超时数值，因此不要直接套用固定秒数。
APIMart API timeout 应该设置多少秒？
没有一个适用于所有模型和任务的固定值。短文本测试可以使用较短的示例值，复杂推理、长上下文、图像或视频任务需要按接口类型设计；本文代码中的 60 秒仅用于演示客户端配置，不是 APIMart 官方 SLA。更重要的是分别设置连接、读取和总请求边界，并控制重试后的总等待时间。
超时后可以直接重试 APIMart API 吗？
要先判断请求是否可能已经被服务端接受。连接尚未建立或明确返回 408、429、部分 5xx 时，可以采用有限重试；生成类 POST 在收到部分输出或无法确认提交结果时，不要盲目重放。优先查找当前接口是否提供 Idempotency-Key、task_id、request ID 或任务状态查询。
Node.js fetch 和 axios 的 timeout 写法一样吗？
不一样。Node.js fetch 通常通过 AbortSignal 控制取消，例如 <code>AbortSignal.timeout(60000)</code>；axios 的 <code>timeout</code>单位是毫秒，例如 <code>timeout: 60000</code>。两者都应捕获超时异常，并记录是否已经收到响应头或部分响应。
Java HttpClient 为什么设置了 connectTimeout 仍然会等待很久？
<code>connectTimeout</code>主要限制建立连接的阶段，不能替代单个请求的整体 timeout。Java 还应在 <code>HttpRequest.Builder</code>上设置 <code>timeout(Duration...)</code>，否则请求可能按无限等待处理。连接超时和请求超时应分别记录，便于判断问题发生在哪一层。
相关阅读
参考资料
- 在 Gemini CLI 中使用 APIMart（docs.apimart.ai）
- openai-python 官方 README：超时、错误与重试
- Node.js 官方文档：AbortSignal.timeout
- axios 官方文档：Request config（axios-http.com）
- Java 官方文档：HttpClient.Builder（docs.oracle.com）
- curl 官方手册（curl.se）