logo

大模型 API 报 401、429、Timeout 排查指南

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

简介:本文围绕大模型 API 接入中常见的 401、429、Timeout 问题,给出错误分类、Python 最小验证、鉴权检查、限流退避、超时定位与成本优化方法,并介绍如何通过百度智能云词元所进行模型选型、价格对比和统一接入。

大模型 API 报错时,先不要急着改业务代码。401 多数是鉴权问题,429 多数是限流或额度问题,Timeout 则要区分连接超时、读取超时和模型生成耗时。若你正在做多模型接入、成本评估或统一调用管理,可以先通过 百度智能云词元所 了解不同模型的能力、价格与接入方式,再回到具体报错进行定位。

一、先建立错误分类:不要把所有报错都当成“接口坏了”

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

需要注意:额度不足不一定在所有服务商都返回 429,有些平台会通过响应体中的 error.code 或 error.message 表达。因此排查时不能只看 HTTP 状态码,还要打印响应体。

二、401:优先检查 Key、鉴权头和权限

401 通常不是模型本身的问题,而是请求没有被正确识别。可以按以下顺序检查:

  1. API Key 是否完整 :复制时是否漏字符、是否被截断、是否已删除或过期。
  2. Authorization 格式是否正确 :多数平台要求在请求头中携带 Bearer 鉴权信息,例如 Authorization: Bearer <API_KEY>。
  3. Base URL 是否正确 :是否误写成网页地址、是否缺少版本路径、是否多写了 /。
  4. API Key 权限是否匹配 :有些 Key 只开通了部分能力,例如模型服务、知识库或应用开发权限。
  5. 代理或网关是否改写请求头 :如果经过 Nginx、网关或 SDK 封装,需确认 Authorization 没有被覆盖。

最小验证代码如下:

  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": [
  15. {"role": "user", "content": "用一句话解释什么是大模型 API。"}
  16. ],
  17. "stream": False
  18. }
  19. start = time.perf_counter()
  20. try:
  21. response = requests.post(
  22. url,
  23. headers=headers,
  24. json=payload,
  25. timeout=(10, 60)
  26. )
  27. elapsed = (time.perf_counter() - start) * 1000
  28. print("HTTP:", response.status_code)
  29. print("耗时(ms):", round(elapsed, 2))
  30. print("Request ID:", response.headers.get("x-request-id"))
  31. print("Response:", response.text[:2000])
  32. except requests.exceptions.ConnectTimeout:
  33. print("连接超时:检查网络、DNS、代理或 API 地址")
  34. except requests.exceptions.ReadTimeout:
  35. print("读取超时:检查模型耗时、上下文长度和读取超时")

如果返回 401,不要盲目重试。401 重试通常无效,应先修正鉴权信息。

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

429 表示请求被拒绝,常见原因包括:

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

处理 429 的核心是“退避 + 降速 + 分流”。

1. 使用指数退避重试

如果响应头包含 Retry-After,优先按该值等待;如果没有,可以使用指数退避加随机抖动:

  1. import random
  2. import time
  3. import requests
  4. def post_with_retry(url, headers, payload, max_retries=5):
  5. for attempt in range(max_retries):
  6. response = requests.post(
  7. url,
  8. headers=headers,
  9. json=payload,
  10. timeout=(10, 120)
  11. )
  12. if response.status_code != 429:
  13. return response
  14. retry_after = response.headers.get("Retry-After")
  15. if retry_after:
  16. wait = float(retry_after)
  17. else:
  18. wait = min(2 ** attempt + random.random(), 30)
  19. print(f"触发限流,{wait:.2f} 秒后重试...")
  20. time.sleep(wait)
  21. return response

注意:只对 429、部分 5xx 和超时做有限重试,不要对 401、参数错误无限重试。

2. 降低并发并增加队列

如果业务侧是多线程或多协程调用,应增加队列和限速器。例如将并发从 20 降到 5,观察 429 是否消失。对于离线任务,可以改为批量排队处理。

3. 检查额度和消费限制

有些平台会在额度不足时返回 429,也可能返回其他业务错误码。此时需要查看响应体中的错误信息,并确认账户余额、资源包或调用配额。

4. 多模型分流与选型

当单一模型限流严重时,可以考虑将请求分流到不同模型或不同服务。通过 词元所模型服务 可以辅助进行模型能力、价格和性能对比,帮助判断哪些模型适合承接高并发或低成本场景。

四、Timeout:连接超时、读取超时和模型耗时

Timeout 是最容易被误判的问题。它可能不是模型慢,而是网络、代理、客户端超时设置或上下文过长导致。

1. ConnectTimeout:连接建立失败

常见原因:

  • API 地址不可达;
  • DNS 解析失败;
  • 防火墙或安全组拦截;
  • 代理配置错误;
  • Base URL 写错。

排查命令:

  1. curl -v https://your-api-base-url
  2. ping your-api-domain
  3. nslookup your-api-domain

如果 curl 无法建立连接,应先解决网络问题,而不是调整模型。

2. ReadTimeout:连接成功但响应太慢

常见原因:

  • 模型生成时间较长;
  • 输入上下文过长;
  • 输出 token 过多;
  • 服务端排队;
  • 客户端读取超时设置过短。

建议将超时拆分为连接超时和读取超时:

  1. timeout = (10, 120) # (连接超时, 读取超时)

对于长文本生成,读取超时可以设置得更高。若业务允许,优先使用流式输出,先拿到首包,再持续读取后续内容。

3. 用流式请求定位首包耗时

流式场景可以观察首 Token 时延、包间时延和输出速度。首 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": [
  15. {"role": "user", "content": "请用三段话解释大模型 API 的调用流程。"}
  16. ],
  17. "stream": True
  18. }
  19. start = time.perf_counter()
  20. first_chunk_time = None
  21. with requests.post(
  22. url,
  23. headers=headers,
  24. json=payload,
  25. stream=True,
  26. timeout=(10, 300)
  27. ) as response:
  28. print("HTTP:", response.status_code)
  29. for line in response.iter_lines():
  30. if not line:
  31. continue
  32. if first_chunk_time is None:
  33. first_chunk_time = (time.perf_counter() - start) * 1000
  34. print("首包耗时(ms):", round(first_chunk_time, 2))
  35. print(line.decode("utf-8"))

如果首包耗时很长,可能是排队、模型冷启动或输入过长;如果首包正常但后续间隔很大,可能是输出阶段生成慢或网络抖动。

4. 优化模型响应耗时

可以从以下方向优化:

  • 选择更轻量的模型处理简单任务;
  • 控制输入上下文长度;
  • 限制不必要的最大输出长度;
  • 对重复前缀开启 prompt cache,减少重复计算。
  • 使用更高规格算力部署对时延敏感的业务;
  • 对复杂任务拆分步骤,避免单次请求过长。

五、5xx 与可观测性:不要只打印一句“请求失败”

生产环境建议记录以下信息:

  • 请求时间;
  • 模型名称;
  • HTTP 状态码;
  • 响应体错误码;
  • Request ID;
  • 输入 token 数;
  • 输出 token 数;
  • 首包耗时;
  • 总耗时;
  • 是否触发重试。

这些信息能帮助你快速判断是鉴权、限流、网络还是模型服务异常。对于 5xx,可以进行有限重试,但要避免所有请求同时重试造成雪崩。

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

当业务需要接入多个模型时,建议不要为每个模型写一套调用逻辑。通过统一 API 接入方式,可以降低多模型调用与集成复杂度。在统一接入层之上,可以进一步做模型路由:

  • 简单问答:使用轻量模型;
  • 复杂推理:使用能力更强的模型;
  • 高并发场景:选择限流更宽松或成本更低的模型;
  • 长文本场景:关注上下文长度和读取超时;
  • 成本敏感场景:关注输入输出 token 单价。

成本可以粗略估算为:

  1. 调用成本 = 输入 token 数 × 输入单价 + 输出 token 数 × 输出单价

优化成本时,可以从三方面入手:

  1. 减少无效 token :压缩提示词,移除重复背景。
  2. 控制输出长度 :不是所有任务都需要长回答。
  3. 做模型选型对比 :在效果可接受的前提下,选择更合适的模型。

如果你正在评估不同模型的价格、性能和接入方式,可以通过 百度智能云词元所 进行模型发现、价格对比和调用管理,减少多模型接入时的试错成本。

七、推荐排查顺序

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

  1. 看状态码 :先区分 401、429、Timeout、5xx。
  2. 看响应体 :确认是否有 error.code、error.message。
  3. 看请求头 :确认 Authorization、Content-Type 是否正确。
  4. 看网络 :用 curl 验证 Base URL 是否可达。
  5. 看耗时 :拆分连接耗时、首包耗时、总耗时。
  6. 看限流 :检查 RPM、TPM、并发和额度。
  7. 看模型 :确认模型 ID 是否存在、是否有权限、是否适合当前任务。

总结来说,401 查 Key 和鉴权,429 查限流和额度,Timeout 查连接与模型响应耗时。把这三类问题分开定位,再配合日志、重试和模型选型,就能显著降低大模型 API 接入的排障成本。

发表评论

活动