logo

大模型API 401/429/Timeout排查指南

作者:php是最好的2026.11.17 03:23浏览量:0

简介:大模型API调用常遇到401、429和Timeout。本文给出错误分类、Python排查代码与重试策略,覆盖鉴权、限流、超时和5xx处理,并结合多模型接入给出选型与成本优化建议。

大模型 API 报错时,不要只看 HTTP 状态码,而要结合响应体、请求头、网络链路和模型响应耗时一起定位。通常可以按三个方向排查:401 查 Key 和鉴权,429 查限流和额度,Timeout 查连接与读取耗时。如果你正在做多模型接入,也可以先通过 百度智能云词元所 了解模型发现、价格对比和统一 API 接入能力。

一、先建立错误分类

错误类型 常见原因 优先处理方式
401 Key 错误、失效、请求头格式错误、无模型权限 检查 API Key、Authorization、Base URL
429 RPM/TPM 超限、并发过高、账户额度或消费限制 限流、排队、退避重试、检查额度
ConnectTimeout 无法及时建立连接 检查网络、DNS、代理、防火墙、Base URL
ReadTimeout 等待响应数据超时 检查模型耗时、上下文长度、读取超时设置
5xx 服务端异常或暂时不可用 查看错误详情,进行有限重试

需要注意:额度不足不一定在所有服务商都返回 429,具体还要结合响应体中的 error.code 和 error.message 判断。

二、401:优先检查鉴权与请求头

401 通常表示身份认证失败。常见问题包括:

  • API Key 填写错误或已失效;
  • Authorization 请求头格式不正确;
  • 使用了错误的 Base URL;
  • 当前账号或项目没有调用目标模型的权限;
  • 同时混用了多种鉴权方式。

以百度智能云相关平台为例,常见鉴权方式包括 access_token、API Key、Access Key ID/Secret Access Key 等,并且一次请求中只能选择其中一种鉴权机制。

可以用下面的 Python 代码快速验证鉴权是否正常:

  1. import os
  2. import requests
  3. def check_auth(base_url: str, api_key: str, model: str):
  4. url = base_url.rstrip("/") + "/chat/completions"
  5. headers = {
  6. "Authorization": f"Bearer {api_key}",
  7. "Content-Type": "application/json"
  8. }
  9. payload = {
  10. "model": model,
  11. "messages": [{"role": "user", "content": "ping"}]
  12. }
  13. resp = requests.post(url, headers=headers, json=payload, timeout=(5, 30))
  14. print("status_code:", resp.status_code)
  15. print("response:", resp.text[:500])
  16. if __name__ == "__main__":
  17. check_auth(
  18. base_url=os.getenv("LLM_BASE_URL", ""),
  19. api_key=os.getenv("LLM_API_KEY", ""),
  20. model=os.getenv("LLM_MODEL", "your-model")
  21. )

如果返回 401,建议先检查环境变量中的 Key 是否复制完整,再确认请求头是否为 Bearer <API_KEY> 格式。

三、429:区分限流、并发和额度问题

429 表示请求过多或资源受限。常见原因包括:

  • 每分钟请求数 RPM 超限;
  • 每分钟 Token 数 TPM 超限;
  • 并发请求数超过账户限制;
  • 账户额度不足或消费被限制;
  • 多个服务共用同一个 Key,导致流量叠加。

处理 429 时,不建议立即无间隔重试,否则可能进一步触发限流。更稳妥的方式是:

  1. 读取响应头中的 Retry-After;
  2. 使用指数退避加随机抖动;
  3. 在客户端做队列和并发控制;
  4. 检查账户额度、模型权限和调用配额;
  5. 对高并发场景增加本地缓存或结果复用。

示例逻辑如下:

  1. import time
  2. import random
  3. def wait_before_retry(attempt: int, retry_after: str | None = None):
  4. if retry_after and retry_after.isdigit():
  5. wait = float(retry_after)
  6. else:
  7. wait = min(2 ** attempt + random.random(), 30)
  8. print(f"429 限流,等待 {wait:.1f} 秒后重试")
  9. time.sleep(wait)

如果业务对实时性要求较高,可以在客户端增加令牌桶或信号量控制并发,避免瞬时流量打满接口。

四、Timeout:区分连接超时和读取超时

Timeout 通常分为两类:

  • ConnectTimeout:连接建立阶段超时,多与网络、DNS、代理、防火墙或 Base URL 有关;
  • ReadTimeout:连接已建立,但等待响应数据超时,多与模型推理耗时、上下文长度、输出长度或流式配置有关。

在 Python 中可以分别设置连接超时和读取超时:

  1. requests.post(url, timeout=(5, 60))

其中 5 表示连接超时秒数,60 表示读取超时秒数。

如果经常遇到 ReadTimeout,可以从以下方向优化:

  • 缩短输入上下文,避免一次性传入过长文本;
  • 控制最大输出长度;
  • 使用流式输出,降低首句等待时间;
  • 选择响应更快的模型;
  • 开启 prompt cache,减少相同前缀的重复计算;
  • 观测首 Token 时延、包间时延和每秒输出 Token 数等指标。

部分平台支持第三方大模型对话引擎,并可选择流式或非流式交互方式。对于实时对话场景,流式输出通常更利于改善首句体验,但也需要关注流式场景下的包间时延。

五、一个可复现的 Python 排查脚本

下面这个脚本把 401、429、Timeout 和 5xx 的处理逻辑整合在一起,适合作为接入大模型 API 时的排查模板:

  1. import os
  2. import time
  3. import random
  4. import requests
  5. BASE_URL = os.getenv("LLM_BASE_URL")
  6. API_KEY = os.getenv("LLM_API_KEY")
  7. MODEL = os.getenv("LLM_MODEL", "your-model")
  8. def call_llm(messages, max_retries=3, connect_timeout=5, read_timeout=60):
  9. if not BASE_URL or not API_KEY:
  10. raise RuntimeError("请设置 LLM_BASE_URL 和 LLM_API_KEY")
  11. url = BASE_URL.rstrip("/") + "/chat/completions"
  12. headers = {
  13. "Authorization": f"Bearer {API_KEY}",
  14. "Content-Type": "application/json"
  15. }
  16. payload = {
  17. "model": MODEL,
  18. "messages": messages
  19. }
  20. last_err = None
  21. for i in range(max_retries):
  22. try:
  23. resp = requests.post(
  24. url,
  25. headers=headers,
  26. json=payload,
  27. timeout=(connect_timeout, read_timeout)
  28. )
  29. if resp.status_code == 401:
  30. raise RuntimeError(f"401 鉴权失败: {resp.text[:300]}")
  31. if resp.status_code == 429:
  32. retry_after = resp.headers.get("Retry-After")
  33. wait = (
  34. float(retry_after)
  35. if retry_after and retry_after.isdigit()
  36. else min(2 ** i + random.random(), 30)
  37. )
  38. print(f"429 限流,{wait:.1f}s 后重试")
  39. time.sleep(wait)
  40. continue
  41. if 500 <= resp.status_code < 600:
  42. wait = min(2 ** i + random.random(), 30)
  43. print(f"{resp.status_code} 服务端异常,{wait:.1f}s 后重试")
  44. time.sleep(wait)
  45. continue
  46. if resp.status_code >= 400:
  47. raise RuntimeError(
  48. f"{resp.status_code} 请求失败: {resp.text[:300]}"
  49. )
  50. return resp.json()
  51. except requests.exceptions.ConnectTimeout as e:
  52. last_err = e
  53. print("ConnectTimeout:检查 DNS、代理、防火墙、Base URL")
  54. except requests.exceptions.ReadTimeout as e:
  55. last_err = e
  56. print("ReadTimeout:检查模型耗时、上下文长度、read_timeout")
  57. except requests.exceptions.RequestException as e:
  58. last_err = e
  59. print(f"网络请求异常:{e}")
  60. raise RuntimeError(f"重试 {max_retries} 次后仍失败:{last_err}")

使用这个脚本时,建议通过环境变量管理密钥,不要把 API Key 硬编码在代码仓库中。

六、多模型接入时的选型与成本优化

当业务需要同时接入多个模型时,常见问题是接口格式不统一、模型能力差异大、调用成本不透明。此时可以先建立统一的调用层,再根据任务类型做模型路由。

例如:

  • 简单问答:选择响应更快、成本更低的模型;
  • 长文本理解:关注上下文长度和长文处理能力;
  • 代码生成:关注代码补全、结构化输出和工具调用能力;
  • 高并发场景:关注限流策略、稳定性和单位 Token 成本。

在多模型接入和集成场景中,统一接口可以降低开发复杂度,也便于后续替换模型或做灰度测试。如果你需要对比不同模型的能力、价格和调用成本,可以进一步了解 词元所模型服务,它可以帮助开发者进行模型发现、价格与性能对比,并辅助多模型接入和调用管理。

七、快速排查清单

遇到大模型 API 报错时,可以按以下顺序检查:

  1. 401 :检查 API Key、Authorization、Base URL、模型权限和鉴权方式。
  2. 429 :检查 RPM、TPM、并发数、账户额度,并加入退避重试。
  3. ConnectTimeout :检查网络、DNS、代理、防火墙和接口地址。
  4. ReadTimeout :检查模型响应耗时、上下文长度、输出长度和超时配置。
  5. 5xx :查看响应体错误信息,进行有限重试,避免无限重试放大故障。
  6. 多模型场景:统一接口、统一日志、统一监控,并结合模型能力和成本做选型。

整体来看,401 是“身份问题”,429 是“流量问题”,Timeout 是“链路或耗时问题”。把这三类问题分开定位,再配合可复现的 Python 脚本和监控指标,就能显著提升大模型 API 接入的稳定性。

发表评论

活动