1. 三行调用背后那两百多行到底在忙什么先把标题里那个数字落差说透。调用一个大模型 API核心代码确实就三行拿到客户端、拼一个 messages 数组、把请求发出去。任何一个刚学 Python 的人照着文档十分钟就能跑通。但只要你把这个调用放进真实业务里尤其是让模型去调用工具、返回结构化数据、串联多步任务代码量会瞬间膨胀到两三百行而且膨胀出来的部分几乎全在干同一件事——约束模型的行为让它别乱来。我最早做 Agent 项目的时候也天真过觉得模型这么聪明我告诉它输出 JSON 它就会输出 JSON。结果上线第一天就被现实教育模型在 90% 的情况下乖乖返回合法 JSON剩下 10% 会给你加一句好的以下是结果或者在 JSON 外面套一层 markdown 代码块或者在字段里塞一个不存在的枚举值。这 10% 落到生产环境就是 100% 的故障率因为下游解析器直接崩了。所以这篇东西我想聊的不是怎么调用大模型那个太简单了。我想聊的是那 250 行防御代码到底在防什么、为什么必须防、以及怎么防得优雅。涉及的关键词包括大模型 API、LangGraph、OpenAI、结构化输出这几个词基本构成了当前 Agent 开发的主干。如果你正在做类似让 AI 真的下地干活的项目比如基于 FastAPI LangChain LangGraph 的智能体那这篇内容应该能帮你少走不少弯路。适合的读者已经能跑通基础 API 调用、准备把 demo 推向生产的人或者正在被模型不听话折磨、想系统梳理防御思路的人。纯新手也能看我会把每个防御点的来龙去脉讲清楚。2. 为什么能跑通和能上线之间隔着一整个防御层2.1 模型的本质是概率机器不是确定性函数这是所有防御代码的根源。你写def add(a, b): return a b输入 1 和 2 永远得到 3。但你调用大模型同样的输入今天返回这个明天可能返回那个甚至同一分钟内两次调用结果都不一样。这不是 bug这是它的工作方式——它在做概率采样不是在执行逻辑。理解这一点之后很多防御就不再显得多余了。你防的不是模型坏你防的是概率分布的长尾。绝大多数时候它落在正确区间但长尾一旦出现你的系统就得有兜底。这跟传统后端的思路完全不同传统后端你防的是网络抖动、数据库超时这里你防的是模型今天心情不好。2.2 三类最常见的不听话以及它们各自的破坏力我把实际踩过的坑归成三类破坏力从低到高排列类型典型表现破坏力是否可自动恢复格式漂移JSON 外套 markdown、多一句解释、字段名大小写不一致中可重试恢复语义越界枚举值编造、数值超范围、引用不存在的 ID高需校验拦截工具误用该调 A 工具却调 B、参数缺字段、无限循环调用极高需状态机约束格式漂移最好处理加个解析容错就行。语义越界麻烦一点因为模型看起来返回了合法结构但内容是错的你得靠业务校验兜住。工具误用最致命尤其在 LangGraph 这种多节点编排里一个错误的工具调用可能触发连锁反应把整个流程带偏。2.3 一个真实的比例防御代码为什么能占到 98%我统计过自己一个中等复杂度 Agent 项目的代码分布真正调用模型 API 的部分大概 3 到 5 行而围绕它的输入清洗、输出解析、重试、校验、状态管理、日志、超时控制加起来接近 250 行。比例大概是 1:50。这个数字听起来夸张但拆开看很合理——每一次模型调用你都要为它的不确定性准备一整套安全气囊。提示如果你发现自己的防御代码占比远低于这个数先别高兴很可能是你还没遇到长尾而不是你的模型特别听话。3. 结构化输出从求它听话到逼它守规矩3.1 为什么自然语言解析是条死路早期我试过让模型返回自然语言然后用正则去抠字段。这条路走了不到一周就放弃了。原因很简单自然语言的表达空间是无限的你永远写不全正则。模型今天说价格是 99 元明天说售价99后天说该商品定价 99.00 人民币你的正则改到崩溃。结构化输出Structured Output的核心思路是不要解析模型的自由文本而是约束它只能输出符合 schema 的内容。这是从事后解析到事前约束的范式转变也是那 250 行防御代码里最值钱的部分。3.2 JSON Schema 约束的三种实现层次按可靠性从低到高我把它分成三层第一层Prompt 里写清楚格式要求。就是在 system prompt 里写你必须返回如下 JSON 格式{...}。这层最弱模型遵守率大概 85% 到 95%取决于模型能力和 prompt 质量。它的问题在于没有任何强制力模型该漂移还是漂移。第二层利用 API 原生的结构化输出能力。现在主流的大模型 API 基本都支持传入一个 response_format 或 json_schema 参数服务端会在解码阶段就约束输出。这层的遵守率能到 99% 以上因为约束发生在 token 采样层面不是靠模型自觉。代价是 schema 不能太复杂嵌套层级和字段数量都有限制。第三层本地校验 重试闭环。无论前两层多可靠你都得有第三层。因为 API 层的约束可能因为版本、参数、网络等原因失效而且它管不了语义正确性。第三层就是拿到输出后用 Pydantic 之类的工具做严格校验失败就带着错误信息重试。from pydantic import BaseModel, ValidationError, field_validator class OrderInfo(BaseModel): order_id: str amount: float status: str field_validator(status) classmethod def status_must_be_valid(cls, v): allowed {pending, paid, shipped, done} if v not in allowed: raise ValueError(fstatus 必须是 {allowed} 之一) return v def parse_with_retry(raw: str, max_retry: int 3): for i in range(max_retry): try: return OrderInfo.model_validate_json(raw) except ValidationError as e: # 把校验错误回灌给模型让它自己修 raw call_model_with_feedback(raw, str(e)) raise RuntimeError(重试耗尽模型始终无法产出合法结构)这段代码就是典型的防御——它不产生任何业务价值但没有它下游全崩。3.3 校验失败后错误信息怎么回灌才有效这里有个细节很多人做错重试时只把原始输出丢回去说格式错了重来模型大概率还是错。正确做法是把具体的校验错误告诉它比如字段 status 的值 completed 不在允许集合内请从 pending/paid/shipped/done 中选。我实测下来带具体错误信息的重试一次修复率能到 80% 以上不带错误信息的重试一次修复率不到 40%。差别就在于模型需要知道错在哪而不是你错了。注意重试次数一定要设上限我一般设 2 到 3 次。超过就说明要么 schema 设计有问题要么这个输入本身就不适合模型处理继续重试只是烧钱。4. LangGraph 里的工具调用状态机才是真正的缰绳4.1 为什么单靠 prompt 管不住工具调用让模型调用工具最朴素的做法是在 prompt 里列出工具清单让它自己决定调哪个。这在简单场景能用但一旦工具有五六个以上、存在依赖关系、或者需要多步串联模型就开始犯迷糊该先查库存却先下了单、参数漏传、同一个工具反复调用陷入死循环。LangGraph 的价值就在这里。它把 Agent 的执行过程建模成一张状态图每个节点是一个明确的步骤调用模型、执行工具、校验结果边是转移条件。模型只能在图允许的范围内做选择而不是在无限空间里自由发挥。这就是缰绳——不是不让它跑是给它划好跑道。4.2 用条件边把不该走的路直接堵死LangGraph 里最实用的防御手段是条件边conditional edge。举个例子一个下单流程必须经过校验库存 → 扣减库存 → 创建订单三步绝不允许跳过校验直接下单。用条件边就能强制这个顺序from langgraph.graph import StateGraph, END def route_after_check(state): if not state.get(stock_ok): return reject return deduct graph StateGraph(AgentState) graph.add_node(check_stock, check_stock_node) graph.add_node(deduct, deduct_node) graph.add_node(create_order, create_order_node) graph.add_node(reject, reject_node) graph.set_entry_point(check_stock) graph.add_conditional_edges(check_stock, route_after_check, { deduct: deduct, reject: reject, }) graph.add_edge(deduct, create_order) graph.add_edge(create_order, END) graph.add_edge(reject, END)这段图定义本身就是防御代码。它保证了无论模型多想抄近路流程都必须走完校验。模型在这里的角色被降级成在节点内做决策而不是决定整个流程怎么走。4.3 循环检测防止 Agent 陷入无限工具调用多步 Agent 最容易出的问题是死循环模型调用工具 A拿到结果觉得不对又调 A如此往复。LangGraph 本身不会自动帮你检测这个你得自己加。我的做法是在状态里维护一个调用计数器同一个工具连续调用超过 N 次就强制中断转入人工兜底或直接报错def should_continue(state): counts state.get(tool_call_counts, {}) last_tool state.get(last_tool) if counts.get(last_tool, 0) 3: return abort return continue这个阈值 3 是我踩坑踩出来的。设 2 太敏感正常的多轮修正会被误杀设 5 又太宽松等到发现时已经烧了不少 token。3 是个比较平衡的值你可以根据自己的工具特性调整。4.4 工具参数校验别信模型传进来的任何东西模型调用工具时传的参数本质上和用户输入一样不可信。我见过模型把字符串 null 当成 None 传进去也见过它把日期格式写成 2024年1月1日 而不是 2024-01-01。所以每个工具函数的第一件事永远是参数校验def deduct_node(state): args state[tool_args] qty args.get(quantity) if not isinstance(qty, int) or qty 0: return {error: quantity 必须是正整数, tool_args: args} # 校验通过才真正执行 ...这看起来啰嗦但它是把模型的错误挡在业务逻辑之外的最后一道墙。5. 那些文档不会写、但上线必踩的坑5.1 401 和 400两类最烦人的 API 报错热词里出现了unexpected status 401 unauthorized: incorrect api key provided和api error: 400 this models maximum context length is 1048576 tokens这两个我太熟了。401 基本就是 key 的问题要么 key 写错了要么环境变量没加载上要么 key 被禁用或额度耗尽。排查顺序是先确认环境变量真的读到了打印一下前几位再确认 key 没过期最后看账户状态。我遇到过最坑的一次是本地.env文件里 key 后面多了个空格肉眼完全看不出来查了半小时。400 里的 context length 超限更隐蔽。它不是说你的输入超了而是输入加输出超了。很多人只算输入 token忘了给输出留空间。正确做法是模型的最大上下文减去你期望的最大输出长度才是输入的安全上限。比如 128k 上下文的模型你希望输出最多 4k那输入就该控制在 124k 以内还要留点余量给系统提示词。5.2 依赖缺失missing optional dependency类报错热词里那个missing optional dependency openai/codex-win32-x64是典型的平台相关依赖问题。这类报错的特征是在别人机器上好好的到你这就缺东西。根因通常是某个包针对特定平台编译了原生模块而你的环境没匹配上。处理思路很固定先看报错里点名的是哪个包然后确认你的 Node 或 Python 版本、操作系统架构是否匹配最后重新安装那个包。如果是全局安装的 CLI 工具npm install -g重装一遍往往能解决。别急着怀疑代码这类问题 90% 是环境问题。5.3 结构化输出和工具调用同时用时的冲突这是个进阶坑。当你既要求模型返回结构化 JSON又让它调用工具时两者会打架工具调用的返回格式和结构化输出的格式不是一回事。我的经验是分阶段处理——需要工具调用的轮次就让模型正常返回工具调用工具执行完、进入最终汇总阶段时再切换到结构化输出模式。不要试图在一轮里同时满足两个约束模型会顾此失彼。5.4 超时和重试的配合别让重试把超时放大很多人写重试逻辑时只考虑失败了再试一次忘了每次重试都要重新计时。如果单次调用超时设 30 秒重试 3 次最坏情况就是 90 秒。在同步接口里这足以拖垮整个请求链路。正确做法是给整个重试过程设一个总预算比如总超时 45 秒单次超时 15 秒重试时用剩余预算动态调整。或者干脆把重试放到异步任务里别阻塞主请求。6. 把防御做薄从 250 行压缩到可维护的规模6.1 防御代码也需要架构否则它会自己变成屎山写到后面你会发现防御代码如果不加组织会比业务代码还乱。我的做法是把它拆成三层输入层负责清洗和校验用户输入调用层负责模型调用、重试、超时输出层负责解析和语义校验。每层职责单一互不干扰。这样拆的好处是当某个模型换了、某个 schema 改了你只需要动对应那一层不用满代码库找散落的校验逻辑。6.2 用配置驱动而不是硬编码校验规则、重试次数、超时阈值这些全部抽到配置文件里。我见过太多项目把max_retry 3硬编码在函数里后来想调成 5 得改代码重新部署。用配置驱动之后调参就是改个 yaml重启都不用。model: name: your-model timeout: 15 max_retry: 3 total_budget: 45 validation: strict: true max_enum_retry: 26.3 日志要记什么才能事后复盘防御代码的另一半价值是可观测性。每次模型调用我至少记这几样原始输入、原始输出、解析后的结构、校验结果、重试次数、耗时。出问题时这些日志能让你在五分钟内定位是格式问题还是语义问题而不是靠猜。特别提醒原始输出一定要记哪怕它很长。因为模型的行为只有看原始输出才能理解解析后的结构会丢失很多信息。6.4 什么时候该放弃防御直接换方案最后说个反直觉的经验不是所有不听话都值得防。如果一个模型在某个任务上反复失败重试三次都修不好那大概率不是防御不够而是这个任务本身不适合用这个模型、或者不该用自然语言接口来做。这时候正确的选择是换模型、换方案而不是继续加防御代码。我踩过这个坑为了一个模型死活做不好的字段抽取写了上百行后处理逻辑最后换成另一个模型三行 prompt 就搞定了。防御是有边界的识别出该换方案的信号比会写防御代码更重要。7. 我个人的几条实操心得做了几个 Agent 项目下来有几条体会是文档里不会写的分享给正在这条路上的朋友。第一先跑通再加固但别在加固上偷懒。demo 阶段三行代码能跑会让你产生这很简单的错觉。真正的工作量在加固而加固的质量直接决定项目能不能上线。我现在的习惯是任何模型调用在写第一行业务逻辑之前先把校验和重试的骨架搭好。第二schema 设计要克制。字段越少、嵌套越浅、枚举越明确模型遵守得越好。我见过有人设计了一个五层嵌套、二十多个字段的 schema然后抱怨模型总出错。这不是模型的锅是 schema 的锅。能用扁平结构就别嵌套能用字符串枚举就别用自由文本。第三把模型当成一个能力很强但偶尔会犯迷糊的实习生。你会放心让实习生直接操作生产数据库吗不会。你会给他明确的步骤、清晰的边界、出错时的兜底。对待模型也是这个思路。那 250 行防御代码本质上就是你给这个实习生配的护栏和检查清单。第四重试不是万能的但没重试是万万不能的。我统计过加上带错误反馈的重试之后整体成功率能从 88% 提到 99% 以上。这 11 个百分点就是能不能上线的分水岭。最后再分享一个小技巧如果你用的是 LangGraph善用它的 checkpointer 机制。它能把每一步的状态持久化下来出问题时可以从中断点恢复而不是从头重跑。这在调试多步 Agent 时能省下大量时间和 token。我一开始没重视这个功能后来发现它几乎是排查复杂流程问题的唯一高效手段。