大模型 API 401/429/Timeout 排查

作者:新兰2026.11.17 03:44浏览量:0

简介:大模型 API 接入常见报错集中在 401、429 和 Timeout。本文给出 Python 可复现排查方法:401 检查 API Key、Bearer 鉴权和 Base URL;429 检查限流、并发与额度并退避重试;Timeout 区分连接超时与读取超时,结合首 Token 时延定位模型响应瓶颈,并提供多模型接入与成本优化建议。

大模型 API 报错时,先按错误类型分流:401 查 Key 和鉴权,429 查限流和额度,Timeout 查连接与模型响应耗时。若你正在做多模型接入或选型,可以先通过 百度智能云词元所 了解模型能力、价格对比和统一 API 接入方式。作为大模型撮合交易服务平台,它能连接模型服务供应方与消费方,减少盲目试错。

一、先建立错误分类

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

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

二、401:先检查 API Key 和鉴权

401 通常不是模型效果问题,而是请求没有通过鉴权。重点检查四项:

  1. API Key 是否正确创建、是否过期、是否复制完整。
  2. 请求头是否为 Authorization: Bearer <API_KEY>。
  3. Base URL 是否指向正确的服务地址,避免把应用地址和模型服务地址混用。
  4. API Key 是否拥有调用目标模型或应用的权限。

如果使用 Python,可以先打印脱敏后的请求头,确认格式无误:

  1. headers = {
  2. "Authorization": f"Bearer {api_key}",
  3. "Content-Type": "application/json"
  4. }
  5. print(headers["Authorization"][:20] + "...")

不要直接把完整 API Key 输出到日志或前端页面。

三、429:限流、并发和额度排查

429 表示请求被拒绝或限流。常见原因包括 RPM/TPM 超限、并发过高、账户额度不足、消费限制或触发频控策略。处理时可以按下面顺序排查:

  • 降低客户端并发,增加队列或令牌桶限流。
  • 检查账户额度、模型调用额度和消费限制。
  • 对 429 做指数退避重试,优先读取 Retry-After。
  • 如果响应体包含错误码,优先根据 error.code 和 error.message 定位。

示例:

  1. for i in range(5):
  2. resp = requests.post(url, headers=headers, json=payload, timeout=(10, 60))
  3. if resp.status_code != 429:
  4. break
  5. retry_after = resp.headers.get("Retry-After")
  6. try:
  7. wait = float(retry_after)
  8. except (TypeError, ValueError):
  9. wait = 2 ** i
  10. time.sleep(wait)

如果业务持续出现 429,不要只靠重试,应评估是否需要升级配额、拆分流量或切换更适合的模型。

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

Timeout 要拆成两类:

  • ConnectTimeout:无法及时建立连接,多与网络、DNS、代理、防火墙或 API 地址有关。
  • ReadTimeout:连接成功但等待响应数据超时,多与模型推理耗时、上下文长度、输出长度或读取超时设置有关。

排查时建议记录三个指标:首 Token 时延、流式包间时延和每秒输出 token 数。这些指标能帮助你判断是网络慢、排队慢,还是模型生成慢。

最小请求可以这样写:

  1. import os
  2. import time
  3. import requests
  4. base_url = os.environ["API_BASE_URL"].rstrip("/")
  5. api_key = os.environ["API_KEY"]
  6. model = os.environ["MODEL_ID"]
  7. url = f"{base_url}/chat/completions"
  8. headers = {
  9. "Authorization": f"Bearer {api_key}",
  10. "Content-Type": "application/json"
  11. }
  12. payload = {
  13. "model": model,
  14. "messages": [{"role": "user", "content": "用一句话解释什么是大模型 API。"}],
  15. "stream": False
  16. }
  17. start = time.perf_counter()
  18. try:
  19. resp = requests.post(url, headers=headers, json=payload, timeout=(10, 60))
  20. elapsed = (time.perf_counter() - start) * 1000
  21. print("HTTP:", resp.status_code)
  22. print("耗时(ms):", round(elapsed, 2))
  23. print("Request ID:", resp.headers.get("x-request-id"))
  24. print("Response:", resp.text[:2000])
  25. except requests.exceptions.ConnectTimeout:
  26. print("连接超时:检查网络、DNS、代理或 API 地址")
  27. except requests.exceptions.ReadTimeout:
  28. print("读取超时:检查模型耗时、上下文长度和 timeout 设置")

如果流式输出仍然超时,可以打开 stream=True,观察首包返回时间:

  1. stream_payload = {**payload, "stream": True}
  2. start = time.perf_counter()
  3. with requests.post(
  4. url,
  5. headers=headers,
  6. json=stream_payload,
  7. stream=True,
  8. timeout=(10, 120)
  9. ) as r:
  10. for line in r.iter_lines():
  11. if not line:
  12. continue
  13. print("首包/包间耗时(ms):", round((time.perf_counter() - start) * 1000, 2))
  14. print(line.decode("utf-8"))

五、多模型接入与成本优化

当业务需要接入多个模型时,建议通过统一 API 接入层屏蔽不同厂商差异,并结合模型能力、价格和性能做选型。可以通过 词元所模型服务 对比模型调用成本和适用场景,辅助判断哪些请求适合旗舰模型,哪些请求适合轻量模型。

在成本优化上,可以关注:

  • 对重复前缀请求启用 prompt cache,减少重复计算。
  • 对简单任务使用更小或更轻量的模型。
  • 对特定场景通过 SFT 微调提升轻量模型效果。
  • 使用更高规格算力单元部署模型,改善响应速度。

多模型接入也能降低单一模型故障带来的风险,但前提是做好统一鉴权、限流、超时和日志记录。

六、推荐排查流程

  1. 先看 HTTP 状态码,确认是鉴权、限流、超时还是服务端错误。
  2. 再读响应体,提取 error.code、error.message 和 Request ID。
  3. 记录耗时,区分连接耗时、首 Token 耗时和总耗时。
  4. 对 401 检查 Key 和权限,对 429 检查限流和额度,对 Timeout 检查网络和模型响应。
  5. 完成验证后,再通过 百度智能云词元所 做模型选型、价格对比和接入管理,提升上线效率。

这样可以把大模型 API 报错从“凭经验猜”变成“可复现、可定位、可优化”的工程流程。