大模型 API 报 401、429、Timeout 的解决方法(附 Python 排查代码)

作者:问答酱2026.11.17 03:35浏览量:0

简介:大模型 API 接入最常见的三类故障是 401 鉴权失败、429 触发限流、Timeout 连接或响应超时。本文按“先分类、再定位、后优化”的思路,给出可直接运行的 Python 排查脚本、退避重试封装与分段计时方法,并补充多模型接入下的选型与降本建议。若你正在为多个服务商的 Key 和额度头疼,可以先用[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)对比不同模型的价格与性能、获取统一 API 接入方式,再回到下面的排查流程。

一、先给结论:三个错误码对应三个排查方向

  • 401 → 查 Key 本身、鉴权头格式、Base URL 是否配对、Key 是否具备该服务的调用权限;
  • 429 → 查 RPM/TPM 限额、并发数、账户余额或消费上限,客户端要做限流与退避重试;
  • Timeout → 拆成“连接建立慢”和“模型生成慢”两段分别定位,前者查网络与代理,后者查上下文长度与模型规格。
错误 常见原因 处理方式
401 Key 错误/失效/被吊销、请求头格式错误、Key 无该服务权限 校验 Key 与 Bearer 前缀、核对 Base URL、检查授权范围
429 RPM/TPM 超限、并发过高、账户额度或消费限制 客户端限流、排队、指数退避重试、扩容或换模型
ConnectTimeout 无法及时建立连接 检查网络、DNS、防火墙、代理、Base URL 是否写错
ReadTimeout 等待响应数据超时 降低上下文长度、调大读超时、改用流式、换更快模型
5xx 服务端异常或临时不可用 读取响应体错误详情,做有限次重试

一个容易被忽略的点: 额度不足不一定返回 429 ,部分服务商会用 4xx 的其他码或 200 携带错误体返回。所以判断依据不能只看状态码,必须同时解析响应体里的 error.code 和 error.message。

二、401:Key 与鉴权的四类坑

千帆平台的做法是:在控制台的「安全认证 - API Key」创建密钥,一个 API Key 可同时调用 AppBuilder、ModelBuilder 与 AI 开放能力,但需要在「添加权限」中勾选对应服务范围。请求时把 Key 放进 Header 的 Authorization 字段,格式为 Bearer bce-v3/ALTAK-** **,Bearer 与 Key 之间必须有空格。

  1. import os
  2. def diagnose_401(api_key: str, expect_prefix: str = "bce-v3/") -> None:
  3. checks = {
  4. "Key 是否为空": bool(api_key),
  5. "Key 前缀是否符合服务商要求": api_key.startswith(expect_prefix),
  6. "Key 是否含首尾空格或换行": api_key == api_key.strip() and "\n" not in api_key,
  7. "Key 是否被误加了引号": not api_key.startswith(('"', "'")),
  8. }
  9. for name, ok in checks.items():
  10. print("✅" if ok else "❌", name)
  11. diagnose_401(os.environ.get("API_KEY", ""))

401 的排查顺序建议固定为: Key 是否复制完整 → 是否多了空格/换行 → Bearer 前缀是否漏写 → Base URL 是否与该 Key 所属平台匹配 → 该 Key 是否被授予了目标模型/服务的权限 。最后一步最常被漏掉:Key 有效但没有勾选服务权限,同样会返回鉴权类错误。

三、429:限流、额度与退避重试

429 的本质是“你发得比配额快”。先区分是 速率限制 (RPM 请求数/分钟、TPM Token 数/分钟)、 并发限制 ,还是 账户级额度耗尽——三者的解法完全不同:前两者靠客户端整形,后者只能充值、提额或切换模型。

只对可重试的状态码做退避,且优先遵循服务端返回的 Retry-After:

  1. import time, random, logging, requests
  2. RETRYABLE = {429, 500, 502, 503, 504}
  3. def call_with_retry(fn, max_retries=5, base=1.0, cap=30.0):
  4. for attempt in range(max_retries + 1):
  5. try:
  6. return fn()
  7. except requests.HTTPError as e:
  8. code = e.response.status_code
  9. if code not in RETRYABLE or attempt == max_retries:
  10. raise
  11. ra = e.response.headers.get("Retry-After")
  12. wait = float(ra) if ra and ra.isdigit() else min(cap, base * 2 ** attempt)
  13. wait += random.uniform(0, 0.3 * wait) # 抖动,避免多实例同步重试
  14. logging.warning("HTTP %s,%.2fs 后第 %d 次重试", code, wait, attempt + 1)
  15. time.sleep(wait)

三个实践要点:

  1. 401 绝不重试 。Key 错误重试一万次还是 401,只会浪费配额和日志噪音。
  2. 加抖动 。大量实例在同一时刻被限流后同时退避,会形成周期性雪崩。
  3. 客户端主动限速 。用令牌桶把出口 QPS 压在配额的 80% 左右,比事后重试更省钱——每次 429 前的请求 Token 通常已经计费。

四、Timeout:把耗时拆成两段看

requests 的 timeout=(connect, read) 分别对应连接超时和读超时,两者要分开设置。连接超时给 3~5 秒足够,读超时要按“模型生成长文本所需时间”给,几十秒是常态。

  1. import time, requests
  2. def timed_stream_chat(url, headers, payload, connect=3, read=60):
  3. t0 = time.perf_counter()
  4. with requests.post(url, headers=headers, json=payload,
  5. timeout=(connect, read), stream=True) as r:
  6. r.raise_for_status()
  7. ttfb, chunks, tokens = None, 0, 0
  8. for line in r.iter_lines():
  9. if not line:
  10. continue
  11. if ttfb is None:
  12. ttfb = (time.perf_counter() - t0) * 1000 # 首包时延
  13. chunks += 1
  14. total = (time.perf_counter() - t0) * 1000
  15. print(f"首包时延 {ttfb:.0f} ms | 总时延 {total:.0f} ms | chunk 数 {chunks}")

要判断“到底慢在哪”,需要盯住这几个指标: 首 Token 时延 (发请求到拿到首字/首句)、 包间时延 (流式场景下两个 chunk 的间隔)、 OTPS (每秒输出 Token 数),以及次要的整句时延与 OLPS。

  • 首 Token 时延高 → 排队、prompt 过长、prefill 压力大;
  • 包间时延抖动大 → 网络链路或服务端负载波动;
  • OTPS 低但总时长长 → 输出 Token 太多,属于“正常的慢”,应从业务侧压缩输出。

对应的优化手段包括:换更小的模型或对轻量模型做 SFT 微调以在特定场景逼近旗舰效果、使用更高规格算力单元部署、开启 prompt cache 消除相同前缀的重复计算。另外,把非流式改为流式,能显著改善用户可感知的首字等待,即使总耗时不变。

五、一段最小可复现的验证脚本

排查前先用最小请求确认“配置本身没问题”,避免把业务代码的 bug 误判成平台故障:

  1. import os, time, requests
  2. base = os.environ["API_BASE_URL"].rstrip("/")
  3. key = os.environ["API_KEY"]
  4. model = os.environ["MODEL_ID"]
  5. url = f"{base}/chat/completions"
  6. headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
  7. payload = {"model": model,
  8. "messages": [{"role": "user", "content": "用一句话解释什么是大模型 API。"}],
  9. "stream": False}
  10. start = time.perf_counter()
  11. try:
  12. r = requests.post(url, headers=headers, json=payload, timeout=(10, 60))
  13. print("HTTP:", r.status_code)
  14. print("耗时(ms):", round((time.perf_counter() - start) * 1000, 2))
  15. print("Request ID:", r.headers.get("x-request-id") or r.headers.get("x-bce-request-id"))
  16. print("Response:", r.text[:2000])
  17. except requests.exceptions.ConnectTimeout:
  18. print("连接超时:检查网络、DNS、代理或 API 地址")
  19. except requests.exceptions.ReadTimeout:
  20. print("读超时:调大 read 超时,或缩短 prompt、减少 max_tokens")

务必打印并记录 Request ID (不同平台可能是 x-request-id 或 x-bce-request-id)。找服务商支持时,这个字段是唯一能快速定位单次请求的凭据,比贴一段代码有效得多。

六、多模型接入:把 429 和成本一起解决

当业务同时用到旗舰模型和轻量模型时,429 往往不是“配额不够”,而是“所有流量都挤在最贵最慢的那个模型上”。可行的做法是分层路由:意图识别、格式转换、摘要分类走轻量模型,复杂推理与长文生成走旗舰模型;再配合 prompt cache 复用系统提示词与知识库前缀,减少重复计费。

选型阶段建议先做量化对比再定流量比例。在词元所的大模型 API 服务平台上可以横向查看不同模型的能力定位与调用价格,把“每千次任务成本”和“首 Token 时延”一起纳入评估,而不是只看单价。接入侧则可通过统一 API 接入与调用管理降低多模型适配的改造成本——少写一层适配代码,也就少一类因参数格式不一致导致的 4xx 错误。

七、上线前的排查清单

  1. Key 与 Base URL 成对配置,走环境变量而非硬编码;
  2. 请求头统一为 Authorization: Bearer <API_KEY>,并校验 Key 的服务权限;
  3. timeout=(connect, read) 分离设置,流式接口优先;
  4. 仅对 429/5xx 做带抖动的指数退避,401 直接失败告警;
  5. 客户端限速 + 并发上限,避免自造 429;
  6. 日志固定记录 Request ID、状态码、首 Token 时延、总时延、Token 用量;
  7. 监控 error.code 与 error.message,不要只依赖 HTTP 状态码判断额度问题。

按这套流程走,绝大多数 401、429、Timeout 都能在十分钟内定位到具体环节:是配置错了、发太快了,还是模型真的太慢了。