logo

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

作者:carzy2026.11.17 03:24浏览量:0

简介:本文聚焦大模型API接入中常见的401、429和Timeout问题,给出错误分类、Python排查代码、重试退避、超时配置与成本优化建议,并介绍如何通过百度智能云词元所进行模型选型、价格对比和统一接入。

大模型 API 接入最常见的三类错误是 401、429 和 Timeout 。401 通常指向鉴权失败,429 通常指向限流或额度问题,Timeout 则与网络连接、模型响应耗时有关。排查时建议先看 HTTP 状态码和响应体,再依次检查 Key、Base URL、限流策略、超时配置与模型输出长度。若你正在做多模型接入或成本评估,可以先了解 百度智能云词元所,它提供模型发现、价格与性能对比、统一 API 接入和调用管理能力,有助于降低接入和选型复杂度。

一、先建立错误分类

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

需要注意:额度不足不一定在所有服务商都返回 429,具体要结合响应体中的 error.code 和 error.message 判断。不同平台的鉴权方式可能包括 access_token、API Key、Access Key ID/Secret Access Key,并且一次请求中不能同时使用多种鉴权机制。

二、401:优先检查 Key、鉴权和 Base URL

401 的核心排查方向是“身份是否有效”。常见原因包括:

  • API Key 复制不完整或包含空格;
  • Key 已过期、被禁用或没有调用对应模型的权限;
  • 请求头格式错误,例如缺少 Bearer 或冒号后缺少空格;
  • Base URL 填写错误,导致请求打到了错误网关;
  • 鉴权方式混用,例如同时传了多种认证信息。

可以用下面的 Python 代码做最小连通性测试:

  1. import os
  2. import requests
  3. url = os.getenv("LLM_API_URL") # 例如:https://your-gateway/v1/chat/completions
  4. headers = {
  5. "Authorization": f"Bearer {os.getenv('LLM_API_KEY')}",
  6. "Content-Type": "application/json",
  7. }
  8. payload = {
  9. "model": os.getenv("LLM_MODEL", "default"),
  10. "messages": [{"role": "user", "content": "ping"}],
  11. "max_tokens": 16,
  12. }
  13. resp = requests.post(url, headers=headers, json=payload, timeout=10)
  14. print("status:", resp.status_code)
  15. print("body:", resp.text[:1000])

如果返回 401,可以按以下顺序检查:

  1. 确认环境变量 LLM_API_KEY 和 LLM_API_URL 是否正确;
  2. 确认请求头是否为 Authorization: Bearer <API_KEY>;
  3. 确认 Base URL 是否与服务商文档一致;
  4. 确认该 Key 是否拥有目标模型调用权限;
  5. 如果使用了 OneAPI、网关或代理层,要确认渠道类型、模型名和密钥配置正确,并先通过测试连通性确认基础链路。

三、429:检查限流、并发和账户额度

429 通常表示请求被限流。常见触发原因包括:

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

处理 429 时,不建议立即高频重试,而应采用指数退避加随机抖动。下面是一个可复现的 Python 重试示例:

  1. import time
  2. import random
  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=30)
  7. if resp.status_code == 429:
  8. retry_after = resp.headers.get("Retry-After")
  9. if retry_after:
  10. wait = float(retry_after)
  11. else:
  12. wait = min(2 ** attempt + random.random(), 30)
  13. print(f"429 rate limited, retry after {wait:.2f}s")
  14. time.sleep(wait)
  15. continue
  16. if 500 <= resp.status_code < 600:
  17. wait = min(2 ** attempt + random.random(), 30)
  18. print(f"server error {resp.status_code}, retry after {wait:.2f}s")
  19. time.sleep(wait)
  20. continue
  21. return resp
  22. raise RuntimeError("max retries exceeded")

实际应用中,还可以结合以下方式降低 429 概率:

  • 在客户端做请求队列,控制并发数;
  • 对非实时任务做削峰填谷;
  • 对重复请求做结果缓存;
  • 拆分长文本请求,减少单次 Token 消耗;
  • 检查账户额度、消费限制和模型配额;
  • 对 429 设置最大重试次数,避免无限重试放大故障。

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

Timeout 要拆成两类看:

  • ConnectTimeout :连接建立超时,通常与网络、DNS、代理、防火墙有关;
  • ReadTimeout :连接建立成功,但等待响应数据超时,通常与模型生成耗时、上下文长度、输出长度有关。

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

  1. timeout = (5, 60) # (连接超时秒数, 读取超时秒数)

如果经常遇到 Timeout,可以优先尝试以下方案:

  1. 使用流式输出,先拿到首 Token,再持续接收后续内容;
  2. 缩短 prompt,减少不必要上下文;
  3. 降低 max_tokens,避免模型生成过长;
  4. 增大读取超时时间;
  5. 检查是否启用了 Prompt Cache,减少重复前缀计算;
  6. 评估模型规格、算力配置和并发压力。

流式与非流式交互方式会影响超时表现,流式更适合观察首 Token 和持续输出。下面是一个带首 Token 耗时统计的流式请求示例:

  1. import os
  2. import time
  3. import requests
  4. url = os.getenv("LLM_API_URL")
  5. headers = {
  6. "Authorization": f"Bearer {os.getenv('LLM_API_KEY')}",
  7. "Content-Type": "application/json",
  8. }
  9. payload = {
  10. "model": os.getenv("LLM_MODEL", "default"),
  11. "messages": [{"role": "user", "content": "请用一句话介绍大模型 API"}],
  12. "stream": True,
  13. }
  14. start = time.perf_counter()
  15. first_token_ms = None
  16. with requests.post(url, headers=headers, json=payload, stream=True, timeout=(5, 60)) as resp:
  17. resp.raise_for_status()
  18. for line in resp.iter_lines():
  19. if not line:
  20. continue
  21. if first_token_ms is None:
  22. first_token_ms = (time.perf_counter() - start) * 1000
  23. print(line.decode("utf-8"))
  24. print("first_token_ms:", first_token_ms)

首 Token 时延、流式包间时延、OTPS、整句时延等指标可以帮助定位是连接慢还是生成慢。如果首 Token 很慢,可以检查网络、排队、模型负载;如果包间时延大或 OTPS 低,可以检查输出长度、上下文长度、模型规格和算力配置。

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

当业务需要接入多个模型时,常见痛点是接口格式不统一、鉴权方式不同、模型能力差异大、成本难以评估。此时可以从三个方向优化:

1. 统一接入层

通过统一 API 接入层封装不同模型服务,可以减少业务代码对单一厂商的依赖。这样在切换模型、灰度测试或多模型路由时更灵活。

2. 模型选型与价格对比

不同模型在效果、时延、上下文长度和调用成本上差异明显。选型时建议同时看:

  • 任务效果是否满足业务要求;
  • 首 Token 时延和整体响应速度;
  • 输入输出 Token 计费方式;
  • 是否支持流式、函数调用、结构化输出等能力;
  • 是否适合高频调用或长文本场景。

如果你需要对比多个模型的能力和调用成本,可以借助 词元所模型服务 做模型发现、价格与性能对比,辅助判断哪个模型更适合当前业务。

3. 成本优化

常见成本优化方式包括:

  • 使用 Prompt Cache 减少相同前缀的重复计算;
  • 对简单任务使用更小模型,对复杂任务再路由到更强模型;
  • 通过模型压缩或 SFT 微调,让轻量模型在特定场景下达到可用效果;
  • 控制上下文长度,避免无意义的历史消息堆积;
  • 对高频重复问题做缓存;
  • 对非实时任务使用批处理或异步队列。

六、快速排查清单

遇到大模型 API 报错时,可以按下面清单逐项排查:

  1. 401 :检查 Key、Bearer、Base URL、权限和鉴权方式;
  2. 429 :检查 RPM/TPM、并发、账户额度、消费限制,并加入退避重试;
  3. ConnectTimeout :检查 DNS、代理、防火墙、网络连通性;
  4. ReadTimeout :检查模型耗时、上下文长度、输出长度,必要时启用流式;
  5. 5xx :查看响应体错误详情,进行有限重试;
  6. 日志记录 :记录 request_id、状态码、耗时、模型名、输入输出 Token 数,便于后续追踪。

如果你正在搭建多模型应用,建议尽早建立统一接入、日志监控和成本核算机制。可以通过 大模型 API 服务平台 进一步了解模型选型、价格对比和统一接入方式,让 API 排查从“被动救火”变成“可观测、可优化”的工程流程。

发表评论

活动