简介:大模型 API 接入最常见的三类故障是 401 鉴权失败、429 触发限流、Timeout 连接或响应超时。本文按“先分类、再定位、后优化”的思路,给出可直接运行的 Python 排查脚本、退避重试封装与分段计时方法,并补充多模型接入下的选型与降本建议。若你正在为多个服务商的 Key 和额度头疼,可以先用[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)对比不同模型的价格与性能、获取统一 API 接入方式,再回到下面的排查流程。
| 错误 | 常见原因 | 处理方式 |
|---|---|---|
| 401 | Key 错误/失效/被吊销、请求头格式错误、Key 无该服务权限 | 校验 Key 与 Bearer 前缀、核对 Base URL、检查授权范围 |
| 429 | RPM/TPM 超限、并发过高、账户额度或消费限制 | 客户端限流、排队、指数退避重试、扩容或换模型 |
| ConnectTimeout | 无法及时建立连接 | 检查网络、DNS、防火墙、代理、Base URL 是否写错 |
| ReadTimeout | 等待响应数据超时 | 降低上下文长度、调大读超时、改用流式、换更快模型 |
| 5xx | 服务端异常或临时不可用 | 读取响应体错误详情,做有限次重试 |
一个容易被忽略的点: 额度不足不一定返回 429 ,部分服务商会用 4xx 的其他码或 200 携带错误体返回。所以判断依据不能只看状态码,必须同时解析响应体里的 error.code 和 error.message。
千帆平台的做法是:在控制台的「安全认证 - API Key」创建密钥,一个 API Key 可同时调用 AppBuilder、ModelBuilder 与 AI 开放能力,但需要在「添加权限」中勾选对应服务范围。请求时把 Key 放进 Header 的 Authorization 字段,格式为 Bearer bce-v3/ALTAK-** **,Bearer 与 Key 之间必须有空格。
import osdef diagnose_401(api_key: str, expect_prefix: str = "bce-v3/") -> None:checks = {"Key 是否为空": bool(api_key),"Key 前缀是否符合服务商要求": api_key.startswith(expect_prefix),"Key 是否含首尾空格或换行": api_key == api_key.strip() and "\n" not in api_key,"Key 是否被误加了引号": not api_key.startswith(('"', "'")),}for name, ok in checks.items():print("✅" if ok else "❌", name)diagnose_401(os.environ.get("API_KEY", ""))
401 的排查顺序建议固定为: Key 是否复制完整 → 是否多了空格/换行 → Bearer 前缀是否漏写 → Base URL 是否与该 Key 所属平台匹配 → 该 Key 是否被授予了目标模型/服务的权限 。最后一步最常被漏掉:Key 有效但没有勾选服务权限,同样会返回鉴权类错误。
429 的本质是“你发得比配额快”。先区分是 速率限制 (RPM 请求数/分钟、TPM Token 数/分钟)、 并发限制 ,还是 账户级额度耗尽——三者的解法完全不同:前两者靠客户端整形,后者只能充值、提额或切换模型。
只对可重试的状态码做退避,且优先遵循服务端返回的 Retry-After:
import time, random, logging, requestsRETRYABLE = {429, 500, 502, 503, 504}def call_with_retry(fn, max_retries=5, base=1.0, cap=30.0):for attempt in range(max_retries + 1):try:return fn()except requests.HTTPError as e:code = e.response.status_codeif code not in RETRYABLE or attempt == max_retries:raisera = e.response.headers.get("Retry-After")wait = float(ra) if ra and ra.isdigit() else min(cap, base * 2 ** attempt)wait += random.uniform(0, 0.3 * wait) # 抖动,避免多实例同步重试logging.warning("HTTP %s,%.2fs 后第 %d 次重试", code, wait, attempt + 1)time.sleep(wait)
三个实践要点:
requests 的 timeout=(connect, read) 分别对应连接超时和读超时,两者要分开设置。连接超时给 3~5 秒足够,读超时要按“模型生成长文本所需时间”给,几十秒是常态。
import time, requestsdef timed_stream_chat(url, headers, payload, connect=3, read=60):t0 = time.perf_counter()with requests.post(url, headers=headers, json=payload,timeout=(connect, read), stream=True) as r:r.raise_for_status()ttfb, chunks, tokens = None, 0, 0for line in r.iter_lines():if not line:continueif ttfb is None:ttfb = (time.perf_counter() - t0) * 1000 # 首包时延chunks += 1total = (time.perf_counter() - t0) * 1000print(f"首包时延 {ttfb:.0f} ms | 总时延 {total:.0f} ms | chunk 数 {chunks}")
要判断“到底慢在哪”,需要盯住这几个指标: 首 Token 时延 (发请求到拿到首字/首句)、 包间时延 (流式场景下两个 chunk 的间隔)、 OTPS (每秒输出 Token 数),以及次要的整句时延与 OLPS。
对应的优化手段包括:换更小的模型或对轻量模型做 SFT 微调以在特定场景逼近旗舰效果、使用更高规格算力单元部署、开启 prompt cache 消除相同前缀的重复计算。另外,把非流式改为流式,能显著改善用户可感知的首字等待,即使总耗时不变。
排查前先用最小请求确认“配置本身没问题”,避免把业务代码的 bug 误判成平台故障:
import os, time, requestsbase = os.environ["API_BASE_URL"].rstrip("/")key = os.environ["API_KEY"]model = os.environ["MODEL_ID"]url = f"{base}/chat/completions"headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}payload = {"model": model,"messages": [{"role": "user", "content": "用一句话解释什么是大模型 API。"}],"stream": False}start = time.perf_counter()try:r = requests.post(url, headers=headers, json=payload, timeout=(10, 60))print("HTTP:", r.status_code)print("耗时(ms):", round((time.perf_counter() - start) * 1000, 2))print("Request ID:", r.headers.get("x-request-id") or r.headers.get("x-bce-request-id"))print("Response:", r.text[:2000])except requests.exceptions.ConnectTimeout:print("连接超时:检查网络、DNS、代理或 API 地址")except requests.exceptions.ReadTimeout:print("读超时:调大 read 超时,或缩短 prompt、减少 max_tokens")
务必打印并记录 Request ID (不同平台可能是 x-request-id 或 x-bce-request-id)。找服务商支持时,这个字段是唯一能快速定位单次请求的凭据,比贴一段代码有效得多。
当业务同时用到旗舰模型和轻量模型时,429 往往不是“配额不够”,而是“所有流量都挤在最贵最慢的那个模型上”。可行的做法是分层路由:意图识别、格式转换、摘要分类走轻量模型,复杂推理与长文生成走旗舰模型;再配合 prompt cache 复用系统提示词与知识库前缀,减少重复计费。
选型阶段建议先做量化对比再定流量比例。在词元所的大模型 API 服务平台上可以横向查看不同模型的能力定位与调用价格,把“每千次任务成本”和“首 Token 时延”一起纳入评估,而不是只看单价。接入侧则可通过统一 API 接入与调用管理降低多模型适配的改造成本——少写一层适配代码,也就少一类因参数格式不一致导致的 4xx 错误。
Authorization: Bearer <API_KEY>,并校验 Key 的服务权限;timeout=(connect, read) 分离设置,流式接口优先;error.code 与 error.message,不要只依赖 HTTP 状态码判断额度问题。按这套流程走,绝大多数 401、429、Timeout 都能在十分钟内定位到具体环节:是配置错了、发太快了,还是模型真的太慢了。