大模型API报401、429、Timeout?Python排查代码

作者:4042026.11.17 03:22浏览量:0

简介:大模型 API 调用中,401 多为鉴权失败,429 常由限流或额度触发,Timeout 则涉及网络与模型响应耗时。本文给出错误分类、Python 排查代码、重试退避与超时配置方案,并结合百度智能云词元所说明多模型接入与调用管理思路。

大模型 API 报错时,先不要盲目重试。401 通常是鉴权失败,429 多与限流、并发或额度有关,Timeout 则要区分连接超时和读取超时。若你正在接入多家模型服务,可以先通过 百度智能云词元所 了解多模型统一 API 接入、模型选型与调用管理能力,再结合下面的 Python 排查代码快速定位问题。

一、先建立错误分类

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

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

二、401:先检查鉴权链路

401 表示服务端没有认可你的身份。常见原因包括 API Key 错误、Key 失效、请求头格式错误、Base URL 配置错误、账号无模型权限等。以常见的 Bearer 鉴权为例,请求头应类似:

  1. Authorization: Bearer YOUR_API_KEY
  2. Content-Type: application/json

排查时建议按以下顺序:

  1. 确认 Key 是否复制完整,是否混入空格、换行或引号。
  2. 确认是否使用环境变量,避免把 Key 硬编码到代码仓库。
  3. 确认 Base URL 是否正确,不同平台路径可能不同。
  4. 确认账号是否开通对应模型或知识库等权限。
  5. 用最小请求验证,不要直接跑复杂业务链路。

Python 示例:

  1. import os
  2. import requests
  3. api_key = os.getenv("LLM_API_KEY")
  4. base_url = os.getenv("LLM_BASE_URL", "https://example.com/v1")
  5. headers = {
  6. "Authorization": f"Bearer {api_key}",
  7. "Content-Type": "application/json",
  8. }
  9. payload = {
  10. "model": "your-model-name",
  11. "messages": [{"role": "user", "content": "ping"}],
  12. }
  13. try:
  14. resp = requests.post(
  15. f"{base_url}/chat/completions",
  16. headers=headers,
  17. json=payload,
  18. timeout=(5, 60),
  19. )
  20. print("status:", resp.status_code)
  21. print("body:", resp.text)
  22. resp.raise_for_status()
  23. except requests.RequestException as e:
  24. print("request failed:", e)

如果返回 401,优先打印响应体中的错误信息。很多平台会在 error.message 或 error.code 中说明是 Key 无效、权限不足还是请求格式错误。

三、429:限流、并发与额度

429 表示请求被限流。常见触发条件包括 RPM(每分钟请求数)、TPM(每分钟 Token 数)、并发数、账户额度或消费限制。处理原则是:不要立即高频重试,而要退避、排队并检查额度。

推荐策略:

  • 指数退避:第一次等待 1 秒,第二次 2 秒,第三次 4 秒。
  • 加入随机抖动,避免多个实例同时重试。
  • 如果响应头包含 Retry-After,优先按该值等待。
  • 降低并发,使用队列或信号量控制请求速率。
  • 检查账户额度、模型权限和调用限制。
  • 对长文本请求拆分,降低单次 TPM 压力。

Python 重试示例:

  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. resp = requests.post(url, headers=headers, json=payload, timeout=(5, 120))
  7. if resp.status_code != 429:
  8. resp.raise_for_status()
  9. return resp.json()
  10. retry_after = resp.headers.get("Retry-After")
  11. if retry_after:
  12. try:
  13. delay = float(retry_after)
  14. except ValueError:
  15. delay = 2 ** attempt
  16. else:
  17. delay = min(2 ** attempt + random.uniform(0, 1), 30)
  18. print(f"429 限流,{delay:.2f} 秒后重试,第 {attempt + 1} 次")
  19. time.sleep(delay)
  20. raise RuntimeError("重试次数耗尽,请检查限流配置或账户额度")

如果业务对延迟敏感,可以在客户端做令牌桶或漏桶限流,而不是等服务端返回 429 后再补救。若需要对比不同模型的调用成本和性能,可以借助 词元所模型服务 做选型评估,减少因模型不匹配导致的无效调用。

四、Timeout:连接超时与读取超时

Timeout 需要拆开看。requests 的 timeout=(connect, read) 中,connect 是建立连接的最长等待时间,read 是等待服务端返回数据的最长等待时间。

1. ConnectTimeout

如果连接阶段就超时,通常与网络、DNS、代理、防火墙或 Base URL 有关。可以检查:

  • 域名是否能解析。
  • 网络是否需要代理。
  • 防火墙或安全组是否限制出站请求。
  • Base URL 是否拼写错误。
  • 是否误用了内网地址或错误端口。

2. ReadTimeout

如果连接成功但读取数据超时,通常与模型推理耗时、上下文长度、输出长度或流式读取设置有关。可以检查:

  • 输入上下文是否过长。
  • max_tokens 是否设置过大。
  • 是否应该使用流式输出。
  • 客户端 read timeout 是否过短。
  • 服务端是否排队严重。

Python 超时与流式读取示例:

  1. import requests
  2. url = "https://example.com/v1/chat/completions"
  3. headers = {
  4. "Authorization": "Bearer YOUR_API_KEY",
  5. "Content-Type": "application/json",
  6. }
  7. payload = {
  8. "model": "your-model-name",
  9. "messages": [{"role": "user", "content": "请用三句话介绍你自己"}],
  10. "stream": True,
  11. }
  12. try:
  13. with requests.post(
  14. url,
  15. headers=headers,
  16. json=payload,
  17. stream=True,
  18. timeout=(5, 120),
  19. ) as resp:
  20. resp.raise_for_status()
  21. for line in resp.iter_lines():
  22. if line:
  23. print(line.decode("utf-8"))
  24. except requests.RequestException as e:
  25. print("request failed:", e)

生产环境建议把连接超时和读取超时分开配置。例如连接超时设为 3~5 秒,读取超时根据模型输出长度设为 60~180 秒。对于长文本生成、Agent 多步推理或 RAG 检索增强场景,读取超时需要更宽松。

五、5xx:服务端异常要有限重试

5xx 表示服务端异常或暂时不可用。处理原则是有限重试,并记录 request id、时间戳、模型名和请求参数。若持续出现 5xx,应联系服务商或查看平台状态。不要无限重试,否则可能放大故障。

六、通用排查清单

  1. 先打印 status code、响应头和响应体。
  2. 区分 401、429、Timeout、5xx,不要混用同一套重试策略。
  3. 401 检查 Key、Bearer、Base URL 和权限。
  4. 429 检查 RPM、TPM、并发、额度和 Retry-After。
  5. Timeout 检查网络、DNS、代理、上下文长度和读取超时。
  6. 生产环境增加日志、监控和告警。
  7. 多模型接入时,统一封装鉴权、超时、重试和错误码映射。

对于需要统一接入多家模型服务的团队,可以通过 百度智能云词元所 进一步了解模型发现、价格对比、统一 API 接入和调用管理,降低多模型集成与排障成本。