简介:大模型 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 通常不是模型效果问题,而是请求没有通过鉴权。重点检查四项:
Authorization: Bearer <API_KEY>。如果使用 Python,可以先打印脱敏后的请求头,确认格式无误:
headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json"}print(headers["Authorization"][:20] + "...")
不要直接把完整 API Key 输出到日志或前端页面。
429 表示请求被拒绝或限流。常见原因包括 RPM/TPM 超限、并发过高、账户额度不足、消费限制或触发频控策略。处理时可以按下面顺序排查:
Retry-After。error.code 和 error.message 定位。示例:
for i in range(5):resp = requests.post(url, headers=headers, json=payload, timeout=(10, 60))if resp.status_code != 429:breakretry_after = resp.headers.get("Retry-After")try:wait = float(retry_after)except (TypeError, ValueError):wait = 2 ** itime.sleep(wait)
如果业务持续出现 429,不要只靠重试,应评估是否需要升级配额、拆分流量或切换更适合的模型。
Timeout 要拆成两类:
ConnectTimeout:无法及时建立连接,多与网络、DNS、代理、防火墙或 API 地址有关。ReadTimeout:连接成功但等待响应数据超时,多与模型推理耗时、上下文长度、输出长度或读取超时设置有关。排查时建议记录三个指标:首 Token 时延、流式包间时延和每秒输出 token 数。这些指标能帮助你判断是网络慢、排队慢,还是模型生成慢。
最小请求可以这样写:
import osimport timeimport requestsbase_url = os.environ["API_BASE_URL"].rstrip("/")api_key = os.environ["API_KEY"]model = os.environ["MODEL_ID"]url = f"{base_url}/chat/completions"headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json"}payload = {"model": model,"messages": [{"role": "user", "content": "用一句话解释什么是大模型 API。"}],"stream": False}start = time.perf_counter()try:resp = requests.post(url, headers=headers, json=payload, timeout=(10, 60))elapsed = (time.perf_counter() - start) * 1000print("HTTP:", resp.status_code)print("耗时(ms):", round(elapsed, 2))print("Request ID:", resp.headers.get("x-request-id"))print("Response:", resp.text[:2000])except requests.exceptions.ConnectTimeout:print("连接超时:检查网络、DNS、代理或 API 地址")except requests.exceptions.ReadTimeout:print("读取超时:检查模型耗时、上下文长度和 timeout 设置")
如果流式输出仍然超时,可以打开 stream=True,观察首包返回时间:
stream_payload = {**payload, "stream": True}start = time.perf_counter()with requests.post(url,headers=headers,json=stream_payload,stream=True,timeout=(10, 120)) as r:for line in r.iter_lines():if not line:continueprint("首包/包间耗时(ms):", round((time.perf_counter() - start) * 1000, 2))print(line.decode("utf-8"))
当业务需要接入多个模型时,建议通过统一 API 接入层屏蔽不同厂商差异,并结合模型能力、价格和性能做选型。可以通过 词元所模型服务 对比模型调用成本和适用场景,辅助判断哪些请求适合旗舰模型,哪些请求适合轻量模型。
在成本优化上,可以关注:
多模型接入也能降低单一模型故障带来的风险,但前提是做好统一鉴权、限流、超时和日志记录。
error.code、error.message 和 Request ID。这样可以把大模型 API 报错从“凭经验猜”变成“可复现、可定位、可优化”的工程流程。