实测：模型输出裹了代码围栏，解析器能救回来吗

版权与内容来源声明
本文为原创整理。文中涉及官方文档、开源仓库、论文与公开报道的内容，均在附表 A 中标注来源；引用官方原文保持原样，不作改写。文中命令、版本号与界面截图以本文成文时的实测/核验结果为准，标注「待验证」的部分请以你本地环境实际输出为判断依据。本文不推荐任何不合规的软件获取方式，也不对任何收益结果作承诺。转载请注明出处。

第1章 模型裹了一层围栏，先别急着改提示词

1.1 每天都在重复的那个画面

只要你把大模型的输出接进程序里，早晚会撞上这个画面：你要求模型返回一段 JSON，它也确实返回了 JSON，但外面裹了一层东西——三个反引号加json打头，再以三个反引号收尾。人看着很清楚，程序拿到手就是一整段带外壳的字符串。

先给两个术语的人话解释，后面会反复用到：

• 输出解析器（output parser）：把模型吐出来的一段文本，按你事先定好的格式「翻译」成程序能直接用的结构（字典或者对象）的那一层代码。
• 代码围栏（fenced code block）：Markdown 里用三个反引号把一段内容包起来的写法，开头常跟着语言名（比如json），结尾是一行同样的三个反引号。

面对围栏，团队里通常有三种反应：第一种，在提示词里反复叮嘱「只输出 JSON，不要加任何解释」；第二种，干脆不用解析器，自己写正则把中间那段抠出来；第三种，加一个「重试」，失败就再问一遍。这三种反应哪个对、哪个是白费力气，光靠争论没有结论。

1.2 本文要回答的三个问题

这篇文章不讨论「为什么要约束输出格式」——那是业务层面的必要性，属于另一个话题。这里只做一件事：把「解析器到底能容错到什么程度」用本机实测量出来。具体回答三问：

1. 围栏本身是不是问题？带围栏的输出能不能被直接解析？
2. 除了围栏，还有哪些「脏输出」会挂？哪些能救、哪些必须靠重试或兜底？
3. 字段校验这件事，该指望哪一个解析器、放在哪一层？

这三个问题的答案，最后会落到一张「上线前的解析兜底清单」上，也就是第 7 章。

1.3 官方文档的核验说明

按本号惯例，先交代来源的出处在哪。截至 2026-10-14，用抓取工具实测：python.langchain.com上旧的how_to/output_parser_json路径已经不再返回那一页，而是被重定向到了框架总览页；LangChain 现在的正式文档落在docs.langchain.com与reference.langchain.com两个域名下，输出解析器的内容可以在reference.langchain.com/python/langchain-core/output_parsers/找到。

该官方模块页对输出解析器的定位原文大意是：输出解析器是把 LLM 调用的输出解析成结构化数据的类；它属于「早期为了让模型输出结构化而出现的方案」，现在多数模型已原生支持结构化输出，这种场景下解析器可能不必要，但在模型不支持原生结构化输出、或你需要对输出做额外处理与校验时，它依然有价值。

这段话很关键：官方自己就把解析器的价值框定在「额外校验」上。本文的实测正好能验证这句话到底成不成立。

第2章 实测方法：10 种脏输出，同时喂给两个解析器

2.1 环境与脚本

不用 API key 是刻意设计的：解析器的容错能力是纯函数行为，跟你用哪家模型、模型贵不贵没关系。只要把「模型可能返回的字符串」原样喂进去，就能把边界测出来，而且结果可复现——别人在你的机器上重跑，数字应该一样。

2.2 测的是什么

被测对象是一个三字段的数据模型，模拟工单场景：category（工单分类，字符串）、priority（优先级，整数，1 最高）、need_human（是否需要人工介入，布尔值）。选三个不同类型的字段，是为了让「类型不符」这类脏输出能被测出来——如果三个字段全是字符串，很多类型问题就暴露不了。

然后构造 10 种「模型可能返回的脏字符串」，逐一喂给两个解析器，记录成功还是失败。

fromlangchain_core.output_parsersimportJsonOutputParser,PydanticOutputParserfrompydanticimportBaseModel,FieldclassTicket(BaseModel):category:str=Field(description="工单分类")priority:int=Field(description="优先级，1 最高")need_human:bool=Field(description="是否需要人工介入")cases={"① 干净 JSON":'{"category": "退款", "priority": 1, "need_human": true}',"② 带 ```json 围栏":'```json\n{"category": "退款", "priority": 1, "need_human": true}\n```',"③ 带裸围栏":'```\n{"category": "退款", "priority": 1, "need_human": true}\n```',"④ 前后带说明文字":'好的，这是结果：\n{"category": "退款", "priority": 1, "need_human": true}\n希望有帮助。',"⑤ 字段缺失（少 need_human）":'{"category": "退款", "priority": 1}',"⑥ 类型不符（priority 给字符串）":'{"category": "退款", "priority": "高", "need_human": true}',"⑦ 单引号":"{'category': '退款', 'priority': 1, 'need_human': true}","⑧ 尾随逗号":'{"category": "退款", "priority": 1, "need_human": true,}',"⑨ 空字符串":'',"⑩ 纯自然语言（无 JSON）":'这个工单看起来是退款，比较急，需要人工。',}json_parser=JsonOutputParser()pyd_parser=PydanticOutputParser(pydantic_object=Ticket)

2.3 这 10 种形态分别从哪来

上表的 10 种不是拍脑袋凑的，每一种在真实项目里都能对上号：

2.4 一个说明：解析失败长什么样

实测里，解析失败统一表现为「抛出输出解析异常」，异常信息里会带上这段无法解析的原文，方便定位。本文不抄那些英文异常行，一律用中文转述成「失败」，因为抄英文报错对读者没用，你要的是判断依据，不是错误堆栈。

另外要提前区分两个概念，后面第 6 章会用到：

• 字段校验：检查该有的字段是不是都在。少一个字段，就叫没通过字段校验。
• 类型校验：检查字段的值的类型对不对。本该是数字却给了字符串，就叫没通过类型校验。

第3章 围栏根本不是问题，别把力气花在这

3.1 三种围栏形态全部成功

这是本文第一个硬结论，也是最反直觉的一条：带json标记的围栏、带裸围栏的输出，两种解析器都吃下了，解析结果与干净 JSON 完全相同。

实测里，输入形态 ①②③ 三种（干净 JSON、带 json 标记围栏、带裸围栏）在JsonOutputParser与PydanticOutputParser下的结果都是「成功」，且返回的内容一字不差。

日志片段（中文转述版）：

① 干净 JSON -> 成功 ② 带 json 标记的围栏 -> 成功 ③ 带裸围栏 -> 成功

3.2 为什么围栏能被吃掉

实测现象就是：解析器在拿到一段带围栏的文本时，会先把外层那圈代码块外壳处置掉，再按 JSON 去解析。你可以把它理解成「解析器自带一把小剪刀，遇到围栏先剪掉外壳」——这个动作是自动的，不需要你在提示词里额外叮嘱，也不需要你自己写正则去扒。

这就带来一个很实际的判断：如果你的失败样本里，只有带围栏的那几条挂了，那才需要处理围栏。而本次实测里，围栏这一组一条都没挂。

3.3 由此可以砍掉的两个动作

既然围栏不是问题，下面两个动作可以直接砍掉：

1. 不用在提示词里三令五申「不要加围栏」。这句话在提示词里占位置、还可能把模型的注意力带偏，收益接近零。
2. 不用自己写正则去抠 JSON。手写正则在遇到嵌套对象、字符串里带花括号时会崩，而且你自己维护的正则还得跟着输出格式改，不如把这个活交给解析器。

省下来的精力，应该花在第 4 章和第 5 章讲的那两类真正会挂的输入上。

第4章 真正挂掉的是这 5 种，而且分两类

4.1 5 种情况，两种解析器一律失败

第二个硬结论：「前后带说明文字 / 单引号 / 尾随逗号 / 空字符串 / 纯自然语言」这 5 种情况，两种解析器一律失败。

注意「一律」两个字——不是「JsonOutputParser 挂、PydanticOutputParser 能救」，而是两个都挂。也就是说，指望换个更严格的解析器来解决这 5 种，是无效的：严格只能拦「格式对但内容不对」，拦不了「格式本身就不对」。

4.2 但这 5 种要分成两类看

虽然表现都是「失败」，根因和处理手段完全不同，这是本章最有用的一个区分：

前三种是文本噪声——内容是对的，只是外面沾了脏东西，属于「确定性可修」；后两种是模型没照做——内容本身就是错的，你怎么洗都洗不出 JSON 来。

4.3 异常捕获要写在哪

实测的调用方式是逐个try捕获，成功记成功、失败记失败：

defrun(name,parser,text):tag=parser.__class__.__name__try:r=parser.parse(text)print(f"[{tag}]{name}-> 成功:{str(r)[:70]}")exceptExceptionase:print(f"[{tag}]{name}-> 失败{type(e).__name__}")

这里有个容易忽略的细节：不要只捕获一种异常。解析失败可能来自 JSON 语法错误，也可能来自字段校验不通过，两者抛出的异常类型不一定相同。统一按「解析不通过」处理，才能保证第 5 章那两类「不报错但返回脏数据」的情况之外的失败都被接住。

另外，parse返回的可能是字典、也可能是 Pydantic 对象，代码里对返回值的假设必须和解析器类型对齐——这一点在第 5 章会变成一张很关键的对照表。

第5章 最危险的一类：不报错，但给你脏数据

5.1 JsonOutputParser 不做字段校验

本文第三个硬结论，也是整篇最重要的一条：JsonOutputParser不做字段校验。字段缺失、类型不符，它都会「成功」返回，但返回的是脏数据。

实测对照如下：

这张表就是本文的核心——「哪种脏输出能被救、哪种必须重试」看这一张就够。它把 10 种输入按两种解析器列成对照，横向比较就看得出两个解析器的分工差异。

5.2 脏数据为什么比报错更可怕

看第 5 行：字段缺失时，JsonOutputParser返回了{'category': '退款', 'priority': 1}——少了need_human这个字段，但它照样算「成功」。

这意味着下游代码会拿到一个缺字段的字典。你如果写的是r["need_human"]，程序在运行到这一行时才崩；如果写的是r.get("need_human")，拿到的是一个None，而这个None会悄悄流进你的业务逻辑里，可能一路不报错，直到某个统计报表出现空白才发现。

看第 6 行：类型不符时，JsonOutputParser返回{'priority': '高'}——优先级本该是整数，它给了字符串「高」。如果你后面写if r["priority"] <= 2:，Python 会在运行到这一行时直接报类型比较错误。也就是说，错误被推迟到了业务代码里，而不是在解析那一步就暴露。

**报错是好事，脏数据才是坏事。**报错至少让你当场知道「这里有问题」；脏数据是「静默通过」，它伪装成正常结果，把问题往后推。

5.3 PydanticOutputParser 才是有把守的那一层

第四个硬结论：PydanticOutputParser会做校验。字段缺失、类型不符，两种都失败——这才是能把关的那一层。

对照表的第 5、6 行右侧写得很清楚：同样的脏输入，换到 Pydantic 版就直接失败。失败意味着异常被抛出，你的重试或兜底逻辑有机会接手；而JsonOutputParser的「成功」等于把阀门焊死了。

这里要说清两者的分工，别混用：

结论很简单：只要下游会按字段名取值或比较，就该用 Pydantic 版；JsonOutputParser适合「先看看模型能返回什么结构」的探索阶段，不适合直接接业务。

LangChain 与 LangGraph 实战资料包：第 5 章讲的是「校验该放在哪一层」，配套视频课里从私有化部署一路讲到 Agent 编排，正好可以对照着把这条链子自己跑一遍、把校验层的位置亲手试出来。放在资料包里，扫码即可获取：

第6章 模型为什么爱加围栏：官方示例自己就带着

6.1 实测：格式化说明里就含围栏

第五个硬结论：PydanticOutputParser.get_format_instructions()返回的示例文本里，本身就包含代码围栏。

get_format_instructions()是解析器提供的一个方法，作用是生成一段「告诉模型该怎么排版」的说明文本，你把它塞进提示词里，模型照着它输出的概率会更高。实测检查这段文本里有没有围栏：

pyd_parser=PydanticOutputParser(pydantic_object=Ticket)fi=pyd_parser.get_format_instructions()print("是否含 markdown 字样:","markdown"infi.lower())print("是否含三个反引号:","```"infi)

实测结果（中文转述）：

是否含 markdown 字样: False 是否含三个反引号: True

6.2 这说明什么

这段说明文本本身是给模型看的「格式示范」。实测证明：**官方给出的这个示范里，就带着代码围栏。**也就是说，模型爱加围栏，一部分原因就是它看到的「格式示例」本身就长这样——示范方自己也这么写，模型跟着写完全符合它学到的模式。

这就把第 3 章的结论彻底闭环了：既然官方示例带着围栏、解析器又能吃下围栏，那围栏从头到尾就不是一个需要解决的问题，它是一个被官方默认接受的写法。

6.3 力气该往哪花

把这五条硬结论连起来看，一个反常识的结论浮出来了：在提示词里反复强调「不要加围栏」的收益，远小于「把字段和类型约束住」。

原因很直白：

• 围栏这一组，解析器本来就能自己处理，你再叮嘱一遍是重复劳动。
• 字段缺失、类型不符这一组，提示词里叮嘱「请务必填满所有字段」，效果也不稳定——模型漏填、填错类型是随机的，靠自然语言约束挡不住，只能靠解析器这一层的硬校验兜。

所以正确的用力方向是：**提示词负责「尽量让模型按格式答」，解析器负责「答得不对时能立刻发现」。**前者是提高质量的软约束，后者是保证不出错的硬闸门，两者不能互相替代。

第7章 上线前的解析兜底清单

7.1 三层防线，各管一段

把上面五条结论变成可执行的东西，就是这张清单。核心思路是分三层，每层管一类脏输出，别指望一层包打天下：

一句话记法：确定性文本噪声靠预清洗，结构正确性靠 Pydantic 校验，模型没照做靠重试加兜底。

7.2 重试是官方认可的处理路径

有人会担心「重试是不是土办法」。不是。截至 2026-10-14，LangChain 官方在结构化输出的文档里明确提供了一套错误处理策略：支持在结构化输出校验失败时捕获错误，用默认错误模板、或你自定义的错误消息回喂给模型让它改，也允许你按异常类型限定捕获范围，或者干脆关掉重试、让异常直接抛出来。

这就说明：「解析失败 → 把失败原因和格式要求一起回喂 → 让模型重来一次」是官方设计里就给好的路子，不是你自己硬凑的补丁。你要做的只是决定重试几次、失败之后落到哪里。

顺带提一句方向：官方文档也指出，模型原生支持结构化输出时，优先用模型自带的能力（比如with_structured_output这类接口），把输出解析器留给不支持原生结构化输出的模型，或者留给你需要额外校验的场景。这是官方给的建议，截至 2026-10-14 依然成立。

7.3 一条完整的兜底链路

把三层拼起来，大致长这样（注意这一段的组合逻辑没有跑过，属于示意骨架）：

⚠️代码待验证

importjsondefpre_clean(text:str)->str:"""预清洗：只处理确定性文本噪声，处理不了原样返回。"""t=text.strip()ifnott:returnt# 截取第一个花括号到最后一个花括号（应对前后说明文字）start,end=t.find("{"),t.rfind("}")ifstart!=-1andend>start:t=t[start:end+1]t=t.replace("'",'"')# 单引号转双引号t=t.replace(",}","}").replace(",]","]")# 去尾随逗号returntdefparse_with_fallback(text:str,parser,max_retry:int=2):cleaned=pre_clean(text)try:returnparser.parse(cleaned)# 校验层：字段缺失 / 类型不符会在这里失败exceptException:pass# 重试层：把失败原因和格式要求一起回喂，由调用方重新请求模型for_inrange(max_retry):retry_text=call_model_again(text,reason="上次输出不符合格式要求")try:returnparser.parse(pre_clean(retry_text))exceptException:continuereturnNone# 兜底层：交给上层决定默认值 / 转人工 / 记日志

这里有个顺序上的讲究：一定要先预清洗、再校验，而不是先重试。因为前后带说明文字、单引号、尾随逗号这三种，是确定性的文本问题，本地改一刀就能救回来，为此再发一次模型请求是浪费。只有清洗完还不行（空字符串、纯自然语言），才值得动用重试。

另一条讲究是：校验必须放在parser.parse这一层，不能挪到业务代码里。原因是本文第 5 章实测出来的——脏数据会静默通过，如果你把校验寄希望于「下游用到的时候自然会报错」，那错误暴露的位置会离根因很远，排查成本会翻好几倍。

7.4 三条止损线

最后给三个「什么时候该停下来」的判据，避免你在容错这条路上无限投入：

1. 同一类脏输出反复出现：说明不是偶发噪声，而是提示词本身有问题，该回头改提示词，别一直加清洗规则。
2. 预清洗规则超过 3 条：说明你在用正则对抗一个本该由模型保证的格式，这种情况下换用支持原生结构化输出的模型，比继续堆规则更划算。
3. 重试次数超过 2 次：单次解析要重试到第 3 次才成功，说明模型对你这个格式的把握很差，问题在任务设定或格式设计上，不在容错层。

大模型学习路线图 + 在线知识库：第 7 章给的是上线前的兜底清单，路线图那一份里把「工程化能力」拆成了可以逐项自查的条目，配合着看会更容易判断自己缺的是哪一块。放在资料包里，扫码即可获取：

附表 A：本文引用事实与出处对照表

附表 B：术语速查表

写在最后：这篇用到的资料

写这篇文章时，把相关的官方文档和源码又翻了一遍，顺手也整理了几份配套的东西：

• 大模型学习路线图：从零基础到能自己动手做 Agent，按阶段说明每一步该学什么、哪些可以先跳过
• 《LangChain + LangGraph + MCP 智能体开发实战》视频课：7 个模块，从私有化部署、Embedding+RAG 到 MCP+Agent 全流程
• AI 大模型知识库（在线可查）：Agent Skills 从入门到落地、Claude Skills 完全指南等专题，按目录浏览即可
• 640 套 AI 大模型行业报告 + 经典 PDF 书籍：看行业落地案例和别人怎么做的时候用得上
• 大模型零基础到精通教学视频：跟着敲一遍，比只读文档快得多

资料是我自己整理的，放在下面这个码上，扫码即可获取：

添加时备注「AI」，优先通过。

资料按「先路线、再动手、最后查漏」的顺序整理好了，建议先看学习路线那一份，照着它挑一条适合自己当前基础的路径再往下看。