大模型应用开发实战：高频异常处理与容错体系设计指南

我这两年做AI大模型应用开发，最深的感受不是模型能力不够，而是异常处理没做好的话，再强的模型也扛不住生产环境的一顿毒打。尤其是晚上挂一个批量生成任务，第二天起来发现程序在第一个请求就崩了，后面几百条全没跑，报错信息翻来覆去就那么几个：timeout、rate limit、content length exceeded。这篇文章就聊聊我在大模型开发里积累的try-except实战经验，把高频报错怎么定位、怎么处理、怎么设计一套不容易翻车的异常处理体系，一次性讲清楚。

我默认你至少用Python调过一次大模型API，不管是OpenAI、Claude还是国产模型，底层的异常处理思路绝大多数是相通的。这篇文章不会讲那种“try一下看看”的入门写法，而是偏实战、偏工程化，适合正在做Agent应用、批量处理脚本、RAG管道或者AI产品后端的人参考。

1. 大模型项目里的报错，和普通Python异常差了一个维度

1.1 多出来的那个维度：服务端不可知

以前写普通Python程序，try-except处理的基本是自己代码里的问题：文件不存在、键名写错、除数为零、连接超时。这些错误的共同点是——你控制了整个运行环境。

大模型开发不一样。你的代码只是发了一个HTTP请求出去，真正干活的是别人的服务。这意味着你面对的是三重不确定性：

1. 网络不可靠：用户的网络、机房到API服务器的链路、代理、DNS解析，任何一个环节抖动，请求就失败。
2. 服务端状态不可控：模型服务可能过载、限流、升级、临时故障，返回的可能是5xx、429，甚至是一个你从没见过的错误码。
3. 返回内容不可信：模型生成的是概率输出的文本，不是结构化数据。就算API调用成功，返回的内容也可能不是合法的JSON，或者格式对不对全靠运气。

普通程序是“我写的代码出错了”，大模型程序是“别人的系统出错了，我还得想办法优雅地接住”。这完全是两套思维模式。很多初学者把普通Python的异常处理习惯直接搬过来，写个try-except把错误打印出来就完事，这在生产环境里是远远不够的。

1.2 初学者最常见的误区：把try-except当“豁免金牌”

我在Code Review里看过太多次这样的写法：

python复制try:
    response = openai.ChatCompletion.create(
        model="gpt-4o",
        messages=messages
    )
except Exception as e:
    print(f"Error: {e}")

这段代码的“作用”只是让程序不崩，但问题完全没解决。你以为它处理了异常，实际上它只是把异常变成了一个print输出，然后程序继续往下跑，返回一个空结果或者错误结果，到上层逻辑里引发更奇怪的连锁反应。

还有更离谱的：

python复制try:
    result = parse_json(model_output)
except:
    pass

这种写法直接吞掉了所有异常，模型返回烂数据的时候你根本不知道出了什么问题，排查的时候连从哪下手都不知道。异常处理的核心目的不是“不报错”，而是“在出错的时候知道发生了什么、怎么恢复、怎么给用户一个合理的交代”。记住这句话，后面所有设计都围绕它展开。

2. 从零搭建一套分层异常体系，再写业务代码

做正式项目之前，我强烈建议先定义清楚异常处理的层次。大模型调用链路通常可以分成三层，每一层对应不同的异常类型和处理策略。

2.1 第一层：网络与连接异常

这层负责处理“根本连不上服务器”的情况。

• requests.exceptions.ConnectionError：连不上API服务器，可能是网络断了、域名解析失败。
• requests.exceptions.Timeout：请求发出去了，但长时间没有响应。
• urllib3.exceptions.MaxRetryError：底层重试次数耗尽。

这类异常的特点是：和模型无关、和参数无关，纯粹是链路问题。处理策略是重试，但重试要有讲究，不能无脑一失败就重来。我后面专门讲重试策略。

2.2 第二层：API服务端业务错误

请求成功到达服务器，但服务器告诉你“不行”。

• openai.AuthenticationError：API Key无效。
• openai.RateLimitError：触发限流，通常伴随429状态码。
• openai.APITimeoutError：服务端响应超时。
• openai.BadRequestError：参数有问题，比如模型名不存在、请求格式错误。
• openai.InternalServerError：服务端内部故障，5xx。

每种错误处理方式不一样：限流要等待退避，认证错误要立刻停止并通知人去检查配置，参数错误通常是代码bug要直接暴露出来。如果全都走同一个except分支，调试的时候会非常痛苦。

2.3 第三层：本地解析与后处理异常

API调用成功了，但数据“用不了”。

• json.JSONDecodeError：模型返回的字符串不是合法JSON。
• KeyError：JSON解析成功，但缺少预期的字段。
• ValueError：字段值类型不符合预期，比如需要整数却返回了"是"。
• UnicodeDecodeError：编码问题。

这一层是大模型项目独有的痛点——模型声称返回JSON，实际返回了一堆废话；声称返回数字，实际返回了一段散文。处理这类异常的核心不是“让程序继续跑”，而是重新调用模型让它修正输出，或者用规则化手段做兜底解析。

2.4 分层之后：一套完整的调用模板

下面是我在项目里常用的调用模板，你可以直接参考：

python复制import openai
import json
from tenacity import (
    retry,
    stop_after_attempt,
    wait_exponential,
    retry_if_exception_type
)
from openai import (
    APITimeoutError,
    RateLimitError,
    InternalServerError,
    BadRequestError,
    AuthenticationError
)

class LLMService:
    def __init__(self, api_key: str, model: str = "gpt-4o"):
        openai.api_key = api_key
        self.model = model

    @retry(
        retry=retry_if_exception_type((
            APITimeoutError,
            RateLimitError,
            InternalServerError,
            ConnectionError,
        )),
        wait=wait_exponential(multiplier=1, min=2, max=30),
        stop=stop_after_attempt(4),
        reraise=True
    )
    def _request_with_retry(self, messages, **kwargs):
        return openai.chat.completions.create(
            model=self.model,
            messages=messages,
            **kwargs
        )

    def chat(self, messages, **kwargs):
        # 第二层：API业务异常
        try:
            response = self._request_with_retry(messages, **kwargs)
            content = response.choices[0].message.content
        except AuthenticationError:
            raise RuntimeError("API Key无效，请检查配置") from None
        except BadRequestError as e:
            # 参数错误通常是代码bug，直接抛出让上层暴露
            raise
        except RateLimitError:
            raise RuntimeError("触发限流，重试后仍然失败") from None
        except Exception as e:
            raise RuntimeError(f"未知API错误: {e}") from e

        # 第三层：解析后处理
        try:
            return json.loads(content)
        except (json.JSONDecodeError, TypeError):
            # 解析失败，这里可以做二次修正或规则兜底
            return self._repair_json(content)

这段代码的核心思想是：每一层异常都有明确的归属，重试逻辑只作用于可恢复的异常，不可恢复的异常直接暴露出来，避免被吞掉。

3. 大模型开发里最常见的六类报错，逐项拆解

3.1 Token超限类：context_length_exceeded

这类报错的提示一般是：

code复制This model's maximum context length is 8192 tokens. However, you requested 9000 tokens ...

根因：请求的输入token数加上输出token数超过了模型的上下文窗口限制。大模型的输入输出共享同一个token预算。你塞了很长的历史对话、很长的知识库片段，或者一次性丢给模型几千行代码，都会触发。

处理策略：

1. 计算token用量。不要用字符数估算，中文一个字约1.5-2个token，英文一个词约1.3个token。tiktoken库可以精确计算，生产环境建议用它。
2. 截断或摘要。超出预算时，优先截断最老的历史消息；如果是知识库内容，先做摘要再拼进context。
3. 调整max_tokens参数。有些API里它叫max_tokens，有些叫max_completion_tokens，注意别把输出预算设置得太大。

python复制import tiktoken

def count_tokens(text: str, model: str = "gpt-4o") -> int:
    encoder = tiktoken.encoding_for_model(model)
    return len(encoder.encode(text))

def trim_messages(messages, max_tokens=8000, model="gpt-4o"):
    """从最旧的消息开始丢弃，直到token数满足要求"""
    total = 0
    trimmed = []
    for msg in reversed(messages):
        msg_tokens = count_tokens(msg["content"], model)
        if total + msg_tokens > max_tokens:
            # 保留最后一条新的
            continue
        trimmed.insert(0, msg)
        total += msg_tokens
    return trimmed

经验：不要只截断到正好等于上限，建议留10%-15%的缓冲，因为token计算在极端情况下会有偏差，而且模型输出的token数也在同一个预算里。

3.2 请求超时：TimeoutError

这类报错在生产环境非常常见，尤其在网络不稳定的场景。

code复制openai.APITimeoutError: Request timed out.

根因：网络抖动、服务端推理过慢、模型输出太长。大模型生成速度和输出字数强相关——你要它生成2000字，它可能要跑30秒，默认超时根本不够。

处理策略：

1. 设置合理的超时时间。根据任务复杂度调整，普通对话30秒，长文本生成60-90秒。
2. 利用SDK的timeout参数，同时做好重试。
3. 超时之后要判断请求是否已经成功处理。这是个隐蔽的坑——客户端超时了，服务端可能已经生成完，只是响应没传回来。重试会导致重复扣费或重复写入数据库。解决方案是给请求设计幂等标识，重试时带上同一个ID。

python复制client = openai.OpenAI(
    api_key="your-key",
    timeout=60.0,
    max_retries=2
)

注意：超时重试的次数不要太多，一次请求从发出到最终失败，整个链路的总耗时是被用户感知的。如果你把超时设为60秒，重试4次，最坏情况用户要等4分钟才算失败，这个体验是灾难性的。建议短超时+少量重试组合。

3.3 限流触发：429 RateLimitError

code复制openai.RateLimitError: Error code: 429

根因：请求频率超过了账号的RPM（每分钟请求数）或TPM（每分钟token数）限制。

处理策略：

1. 指数退避重试。第一次失败等2秒，第二次等4秒，第三次等8秒，封顶30秒。
2. 在应用层做并发控制。用信号量或队列限制同时发出的请求数量。
3. 区分是RPM限流还是TPM限流。如果是TPM，光减少请求数量没用，得压缩单次请求的token。

网上有个热词提到“java中redis++increment报错不是integer or out of range”，这和限流有个相似的教训：计数器的精度问题。如果自己实现限流模块，别把计数器放在多线程共享变量里硬加，容易出并发问题。用现成的限流组件或者Redis Lua脚本，别自己造轮子。

python复制import time
import random

def call_with_rate_limit(func, max_retries=4):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt + random.uniform(0, 0.5)
            time.sleep(wait_time)

3.4 JSON解析失败：模型返回了“不干净”的内容

这是大模型项目里最折磨人的报错，没有之一。你让模型返回JSON，它给你输出：

json复制好的，这是你要的JSON：
```json
{"name": "张三", "age": 18}
```我是按你要求写的，请查收~

直接json.loads()一定会报JSONDecodeError。具体报错类似：

code复制Expecting value: line 2 column 1 (char 1)

根因：模型的指令遵循能力再强，也扛不住输出时“加戏”。尤其你要求它包含示例、解释、或者对话式指令不够严格时。

处理策略：

1. 提示词里明确指定“只输出JSON，不要任何其他内容”。
2. 用响应格式约束。OpenAI的response_format={"type": "json_object"}能大幅提高生成JSON的成功率。
3. 写一个强健的兜底解析函数，从文本里提取可能的JSON片段。

python复制import json
import re

def extract_json(text: str):
    """从模型输出中提取JSON对象"""
    if not text:
        raise ValueError("empty content")
    
    # 先尝试直接解析
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass
    
    # 去掉markdown代码块标记
    cleaned = re.sub(r"```(?:json)?", "", text).strip()
    
    # 尝试找最外层的JSON对象
    try:
        start = cleaned.find("{")
        end = cleaned.rfind("}") + 1
        if start >= 0 and end > start:
            return json.loads(cleaned[start:end])
    except json.JSONDecodeError:
        pass
    
    # 最后尝试用 findall 提取大括号内的内容
    matches = re.findall(r"\{.*?\}", text, re.DOTALL)
    for match in reversed(matches):
        try:
            return json.loads(match)
        except json.JSONDecodeError:
            continue
    
    raise ValueError(f"无法从模型输出中提取JSON: {text[:200]}")

更工程化的方案：如果JSON解析失败且业务逻辑允许，把原输出和错误信息拼接进提示词，让模型重新生成一份合法的JSON。这属于“自我修正”机制，成功率比规则兜底更高，但会多一次API调用。

python复制def get_json_response(messages, max_retries=2):
    for attempt in range(max_retries):
        content = call_llm(messages)
        try:
            return json.loads(content)
        except json.JSONDecodeError as e:
            if attempt == max_retries - 1:
                raise
            # 把错误反馈给模型
            messages.append({"role": "assistant", "content": content})
            messages.append({
                "role": "user",
                "content": f"输出不是合法JSON：{e}。请重新输出，只包含合法JSON对象。"
            })

3.5 内容安全拦截：moderation相关报错

这类报错在中文场景容易被忽略，但它确实存在。

code复制openai.BadRequestError: ... content policy violation

根因：输入或输出触发了内容安全策略。提示词注入、违禁内容、或者模型的输出被内容审核标记。

处理策略：

1. 在输入侧做前置过滤，主动检测违规内容再决定是否调用模型。
2. 捕获到这类错误后，不要把原始内容原样展示给用户，而是返回一个预设的安全提示。
3. 记录违规内容的关键特征，方便调整提示词和过滤规则。

这类错误的处理原则是“不要硬试”，重试再多次结果都一样，应该直接走降级流程。

3.6 参数错误：怎么快速定位是自己写错还是SDK版本问题

参数类报错很容易踩坑，尤其是模型名称。比如：

code复制openai.BadRequestError: Error code: 400 - The model 'gpt-4o-mini' does not exist or you do not have access to it.

根因：

1. 模型名拼写错误。注意大小写、连字符、下划线。
2. 账号没有某个模型的访问权限。
3. SDK版本太旧，不支持你传的某些新参数。

处理策略：

第一件事，检查错误信息里的param字段，它通常会明确告诉你哪个参数不对。第二件事，对比SDK当前版本的官方文档，排查参数名是否变了。我遇到过一个很典型的案例：某个模型接口还在用frequency_penalty，新SDK版本换成了penalty系列参数，代码里没更新，跑出来全是400错误。

另外，有的报错来自本地环境问题，比如网上热词提到的“vscode运行java报错乱码”“pycharm报错filenotfounderror”之类的，虽然语言和场景不同，但排查思路是一样的：看控制台完整报错栈，不要只看第一行；确认工作目录和文件路径；检查环境变量。大模型项目还有个额外坑——.env文件里的API Key带了个隐藏换行符，导致认证一直失败，这类问题肉眼很难发现。

python复制def check_api_key(key: str) -> bool:
    """检查API Key是否是合法格式（以sk-开头且长度合理）"""
    return key.startswith("sk-") and len(key) >= 20

4. 一次“偶尔失败”事故的完整排查复盘

4.1 问题现象：批量任务跑到一半就停了

有一次我负责的批量摘要服务在跑一个7000多条新闻的离线任务。任务设计是每处理100条打一个checkpoint，断点续跑。第一个checkpoint很顺利，第二个checkpoint开始，任务卡住不动了，日志里没有任何异常输出。

看一下日志，最后一条记录是：

code复制Processing item 235...

然后就没有然后了。程序没有退出，没有抛异常，就像睡着了一样。

4.2 排查过程：从日志往前倒推

这是典型的“无异常但程序不跑”的情况。排查链路如下：

第一步，看进程状态。用ps aux确认进程还活着，处于SLEEP状态。

第二步，抓线程栈。用py-spy dump --pid <pid>看到线程停在requests库的urlopen上面，说明在等HTTP响应。

第三步，看一下当前的网络连接状态和API服务状态。排查到这一步，发现API服务商那段时间正好有公告，部分区域的网络超时率升高。

第四步，看代码里的超时设置。当初的代码只设置了socket层面的默认超时，没有设置应用层的timeout参数。这意味着requests库默认认为连接建立之后等待响应是“无限期”的——连接没断，服务器也一直不返回，程序就永远挂在那里。

4.3 真正根因：重试逻辑叠加重试逻辑

修复超时参数之后，任务继续跑，但很快就暴露了第二个问题：某个请求确实触发了超时，SDK内部自动重试了2次，我的业务代码外层又套了一个for循环重试3次，两层叠加，最坏情况下一个失败请求要占用十几分钟。

更隐蔽的是，外层重试没有区分异常类型，把BadRequestError也当成了可重试的临时错误。有一个请求因为参数问题稳定失败，外层代码硬是重试了3次才放弃，日志里连续4条相同错误，后面的任务全被拖慢了。

4.4 最终修复方案

修复后的代码做了三件事：

1. 所有API调用都显式设置timeout参数，绝对不依赖系统默认值。
2. 重试只针对APITimeoutError、RateLimitError、InternalServerError、ConnectionError，其他异常直接上抛。
3. 重试逻辑收敛到一处，SDK的内置重试和外层业务重试只保留一个。

排查这次事故最大的教训是：大模型项目的“假死”比“报错”更可怕。报错至少有个异常对象可以分析，假死则意味着你完全失去了程序的控制权，只能靠超时机制兜底。任何一次外部API调用，都必须设置超时时间，这是铁律。

5. 大模型项目异常处理的几条实战心法

5.1 重试策略：不是所有失败都值得重试

可重试和不可重试的异常，要分得清清楚楚。我的判断标准很简单：

• 网络抖动、限流、服务端5xx、超时：属于临时故障，值得重试。
• 参数错误、认证错误、内容安全拦截、权限不足：属于永久性错误，重试只会浪费时间和费用。

用表格总结就是：

重试时的等待时间，指数退避比固定等待好。因为限流场景下，固定等待会让所有客户端在同一时间点重试，又撞在一起。加上一个随机抖动（jitter），可以避免“惊群效应”。

5.2 降级与兜底：失败时怎么给用户一个体面的结果

重试耗尽还是失败，怎么办？这是异常处理里最容易忽略的一环。

好的做法是设计降级链路：

1. 换模型：主力模型失败了，用备用模型（比如从gpt-4o降到gpt-4o-mini）再试一次，代价是质量下降但功能可用。
2. 缓存兜底：如果问题之前生成过相似回答，直接返回缓存结果。
3. 明确告知：如果所有降级都失败，至少返回一个明确错误信息给用户，而不是前端看到一个空的响应或者转圈圈。

python复制def robust_generate(prompt, messages):
    try:
        return call_model(prompt, model="gpt-4o")
    except (TimeoutError, RateLimitError):
        try:
            return call_model(prompt, model="gpt-4o-mini")
        except Exception:
            cached = get_similar_response(prompt)
            if cached:
                return cached
            return {
                "success": False,
                "error": "服务暂时不可用，请稍后重试"
            }

5.3 日志记录：必须留下可追溯的证据链

“没有日志就没有排查路径”，大模型项目尤其如此。因为大模型返回的内容是动态的，同样的输入每次输出都不同，出错时的上下文信息比普通程序重要得多。

一条合格的大模型调用错误日志，至少要包含：

python复制import logging

logger = logging.getLogger("llm_service")

def log_llm_error(e: Exception, model: str, messages: list, response: str = None):
    logger.error({
        "event": "llm_call_failed",
        "error_type": type(e).__name__,
        "error_detail": str(e),
        "model": model,
        "message_count": len(messages),
        "last_message_preview": messages[-1]["content"][:100] if messages else None,
        "response_preview": response[:200] if response else None,
        "request_id": get_current_request_id(),
    })

如果同时记录输入请求和输出内容，一定要做好脱敏。用户提交的内容可能包含个人隐私，API Key和敏感信息绝对不允许进日志。

5.4 别忽略SDK版本差异带来的“假报错”

最后说一个实战中很容易踩的坑：SDK更新换代导致的“假报错”。网上有个热词提到“java项目报错 + name jdbc is not bound in this context”，这就是典型的资源上下文没绑定问题；还有“axf文件报错”“geoserver报错”这类特定工具链的报错，本质上都是一个类型——环境和代码版本不匹配。

大模型SDK的迭代速度非常快，OpenAI的Python SDK从0.x升到1.x的时候，接口从openai.ChatCompletion.create变成了client.chat.completions.create，大量老代码直接报AttributeError或TypeError。如果你在网上查到一个解决方案，先确认它对应的SDK版本，再套用到自己的项目里。我处理过的很多报错，最终根因根本不是业务代码，而是pip依赖里锁定的SDK版本和代码写法不一致。

建议在requirements.txt里固定主版本号，例如openai>=1.0.0,<2.0.0，然后升级SDK的时候跑一遍完整的错误回归测试，把所有异常分支都触发一次，确认处理逻辑没有被SDK内部改动击穿。

大模型开发里的异常处理，说到底是工程问题：提前想清楚每一层会出什么错，每类错误怎么恢复，恢复不了怎么降级，降级还不行怎么让用户知道。把这套体系搭好，你的项目才算真正有了生产环境生存能力。