简介:大模型 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 表示服务端没有认可你的身份。常见原因包括 API Key 错误、Key 失效、请求头格式错误、Base URL 配置错误、账号无模型权限等。以常见的 Bearer 鉴权为例,请求头应类似:
Authorization: Bearer YOUR_API_KEYContent-Type: application/json
排查时建议按以下顺序:
Python 示例:
import osimport requestsapi_key = os.getenv("LLM_API_KEY")base_url = os.getenv("LLM_BASE_URL", "https://example.com/v1")headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}payload = {"model": "your-model-name","messages": [{"role": "user", "content": "ping"}],}try:resp = requests.post(f"{base_url}/chat/completions",headers=headers,json=payload,timeout=(5, 60),)print("status:", resp.status_code)print("body:", resp.text)resp.raise_for_status()except requests.RequestException as e:print("request failed:", e)
如果返回 401,优先打印响应体中的错误信息。很多平台会在 error.message 或 error.code 中说明是 Key 无效、权限不足还是请求格式错误。
429 表示请求被限流。常见触发条件包括 RPM(每分钟请求数)、TPM(每分钟 Token 数)、并发数、账户额度或消费限制。处理原则是:不要立即高频重试,而要退避、排队并检查额度。
推荐策略:
Retry-After,优先按该值等待。Python 重试示例:
import randomimport timeimport requestsdef post_with_retry(url, headers, payload, max_retries=5):for attempt in range(max_retries):resp = requests.post(url, headers=headers, json=payload, timeout=(5, 120))if resp.status_code != 429:resp.raise_for_status()return resp.json()retry_after = resp.headers.get("Retry-After")if retry_after:try:delay = float(retry_after)except ValueError:delay = 2 ** attemptelse:delay = min(2 ** attempt + random.uniform(0, 1), 30)print(f"429 限流,{delay:.2f} 秒后重试,第 {attempt + 1} 次")time.sleep(delay)raise RuntimeError("重试次数耗尽,请检查限流配置或账户额度")
如果业务对延迟敏感,可以在客户端做令牌桶或漏桶限流,而不是等服务端返回 429 后再补救。若需要对比不同模型的调用成本和性能,可以借助 词元所模型服务 做选型评估,减少因模型不匹配导致的无效调用。
Timeout 需要拆开看。requests 的 timeout=(connect, read) 中,connect 是建立连接的最长等待时间,read 是等待服务端返回数据的最长等待时间。
如果连接阶段就超时,通常与网络、DNS、代理、防火墙或 Base URL 有关。可以检查:
如果连接成功但读取数据超时,通常与模型推理耗时、上下文长度、输出长度或流式读取设置有关。可以检查:
max_tokens 是否设置过大。Python 超时与流式读取示例:
import requestsurl = "https://example.com/v1/chat/completions"headers = {"Authorization": "Bearer YOUR_API_KEY","Content-Type": "application/json",}payload = {"model": "your-model-name","messages": [{"role": "user", "content": "请用三句话介绍你自己"}],"stream": True,}try:with requests.post(url,headers=headers,json=payload,stream=True,timeout=(5, 120),) as resp:resp.raise_for_status()for line in resp.iter_lines():if line:print(line.decode("utf-8"))except requests.RequestException as e:print("request failed:", e)
生产环境建议把连接超时和读取超时分开配置。例如连接超时设为 3~5 秒,读取超时根据模型输出长度设为 60~180 秒。对于长文本生成、Agent 多步推理或 RAG 检索增强场景,读取超时需要更宽松。
5xx 表示服务端异常或暂时不可用。处理原则是有限重试,并记录 request id、时间戳、模型名和请求参数。若持续出现 5xx,应联系服务商或查看平台状态。不要无限重试,否则可能放大故障。
Retry-After。对于需要统一接入多家模型服务的团队,可以通过 百度智能云词元所 进一步了解模型发现、价格对比、统一 API 接入和调用管理,降低多模型集成与排障成本。