“别再用正则抠 JSON 了LangChain 结构化输出的三种正确姿势”我最早干过一件特别蠢的事让大模型输出一段包含电影信息的文本然后自己写正则去匹配片名、导演、评分。当时还觉得自己挺聪明直到换了一个模型版本输出格式里多了个换行符我的正则全军覆没。后来换了 LangChain 的结构化输出方案十分钟改完之后再也没碰过正则抠数据这种活。如果你也正在做 LLM 应用开发大概率遇到过这类场景从大模型的回复里提取关键信息、生成固定格式的数据、把模型输出直接落到数据库或下游系统。这时候如果还在用正则慢慢抠真的可以停下来看看这篇文章。我会直接给你 LangChain 三种成熟的结构化输出方案从原理到代码全部讲透帮你彻底告别脆弱、难维护、一改就崩的字符串处理。这篇内容适合正在上手 LangChain 的开发者也适合已经在做 Agent、知识库问答、数据抽取类项目但被输出格式折腾过的朋友。我不讲空话直接上实战。1. 为什么正则抠 JSON 注定是个坑1.1 正则匹配 JSON 的典型翻车现场先看一个最常见的场景。假设你让大模型从一段影评里提取电影信息模型给出了这样的输出{movie: 盗梦空间, director: 克里斯托弗·诺兰, rating: 9.3}用正则提的话大概会写成这样import re text {movie: 盗梦空间, director: 克里斯托弗·诺兰, rating: 9.3} match re.search(rmovie:\s*([^]), text) print(match.group(1))看着没问题对吧但你把这段代码放到生产环境三天后就会遇到这些情况模型输出变成了单引号的 JSON{movie: 盗梦空间}正则直接匹配不到输出里多了空格、换行、甚至 Markdown 代码块标记json\n{movie: 盗梦空间...}电影名称里本身带了引号或特殊字符正则在[^]这部分就断了字段顺序发生了变化director跑到了rating后面你如果用了依赖顺序的正则结果就是错的这些问题的根源在于正则只能处理符合既定模式的文本而大模型的输出天生就是概率性的。同一个问题同一个模型每次返回的文本细节都可能不一样。你用针对某一次输出的正则去套所有输出本质上是在赌运气。1.2 结构化输出到底在解决什么问题结构化输出的核心思路不是“从文本里提取结构”而是“让模型在生成时就遵循结构”。这就好比你去餐厅点餐与其对着服务员描述一堆要求然后赌他记得住不如直接填一张点菜单——服务员照着格子勾选信息自然就规整了。LangChain 的结构化输出方案做的就是“点菜单”这件事。它通过给模型明确的格式约束让输出在生成阶段就符合预设的数据结构再通过解析器把模型输出转换成 Python 对象或字典。你的代码里拿到的是一个可索引、可校验、可直接使用的数据结构而不是需要再用正则去“猜”的文本。对比一下方案拿到的东西出错概率维护成本正则 手动解析字符串片段高高LangChain 结构化输出Python 对象 / 字典低低而且 LangChain 的方案不仅仅是把 JSON 解析出来它还能做类型校验、字段默认值、嵌套结构、枚举约束等等。这些能力用正则几乎不可能优雅地实现。2. 方案一Pydantic 模型 输出解析器2.1 核心原理让解析器替你干活LangChain 生态里最经典的结构化输出组合是PydanticOutputParser。这个方案分成三步用 Pydantic 定义一个数据模型声明字段名、类型、必填项把模型的格式说明注入到 Prompt 里告诉大模型“按这个格式输出”模型输出后用解析器做反序列化直接得到一个 Pydantic 对象这个方案的价值在于Pydantic 本身就是一个非常成熟的数据校验库。你在 schema 里写了rating: float解析器解析时发现模型输出的是九点三它会直接报错而不是默默返回一个错误类型的数据。这对于下游系统来说太重要了。2.2 完整实战从模型定义到结果解析我写一个实际用过的例子。假设我在做一个电影信息提取工具需要从一段文本里抽出电影名称、导演、评分、上映年份和类型。先定义 Pydantic 模型from pydantic import BaseModel, Field from typing import List class Movie(BaseModel): title: str Field(description电影名称) director: str Field(description导演姓名) rating: float Field(description豆瓣评分保留一位小数) year: int Field(description上映年份) genres: List[str] Field(description电影类型列表可以是多个)接着创建解析器和 Promptfrom langchain.output_parsers import PydanticOutputParser from langchain.prompts import PromptTemplate from langchain_openai import ChatOpenAI parser PydanticOutputParser(pydantic_objectMovie) prompt PromptTemplate( template从用户输入的影评中提取电影信息。\n{format_instructions}\n用户输入{input_text}, input_variables[input_text], partial_variables{format_instructions: parser.get_format_instructions()}, ) model ChatOpenAI(modelgpt-4o-mini, temperature0) chain prompt | model | parser result chain.invoke({input_text: 诺兰导演的《星际穿越》太震撼了2014年上映豆瓣9.4分科幻和剧情都拍得非常好。}) print(result) print(type(result)) print(result.title, result.rating)关键一步在parser.get_format_instructions()。这个方法会根据你的 Pydantic 模型自动生成一段 JSON 格式说明放到 Prompt 里相当于提前给模型看了“答题模板”。运行后result是一个Movie实例直接通过属性访问字段完全不用碰字符串。2.3 这个方案的关键细节用这个方法有个容易踩的坑字段描述不要写得太随意。Field(description...)里的描述会直接进入 Prompt直接影响大模型的输出质量。我见过有人图省事不写 description结果模型老是漏字段或填错类型。描述越具体模型理解越准确。另外如果你用的是gpt-4o或更新的模型别忘了可以配合response_format设置 JSON 输出模式能进一步提高稳定性。后面我会专门讲这种方案。3. 方案二with_structured_output 一行搞定3.1 为什么还要换一种姿势PydanticOutputParser虽然好用但有个天然局限它依赖 Prompt 里的格式说明去“引导”模型输出。如果模型能力弱或者 Prompt 不够清晰输出照样可能跑偏。后来 LangChain 推出了with_structured_output这是我认为当前最推荐的一档方案。它利用了模型对 Function Calling 或 JSON Mode 的原生支持直接在模型调用层约束输出结构。简单理解之前是你让解析器“事后检查”现在是让模型“开箱就输出结构”。输出的可靠性不是一个数量级的。我搞过一个小测试同样一个模型用 Prompt 解析器的成功率在 90% 左右而切换到with_structured_output之后几乎可以达到 99% 以上。3.2 实操最简洁的强约束输出这个方法还是用同一个 Pydantic 模型但调用方式变得极其简洁from langchain_openai import ChatOpenAI class Movie(BaseModel): title: str director: str rating: float year: int genres: List[str] model ChatOpenAI(modelgpt-4o-mini, temperature0) model_with_structure model.with_structured_output(Movie) result model_with_structure.invoke( 《盗梦空间》是诺兰2010年的作品评分9.3类型是科幻、悬疑。 ) print(result) print(result.title, result.year)注意看我这里根本没有写 Prompt 模板、没有手写格式说明也没有配解析器。with_structured_output(Movie)传进去一个 Pydantic 模型返回的对象直接就是一个Movie实例。背后的机制是LangChain 会把 Pydantic 模型的结构转成 JSON Schema然后根据当前模型的能力自动选择实现方式——支持 Function Calling 的走 Function Calling不支持的走 JSON Mode再不行就退回 Prompt 路线。这套自动降级机制非常贴心。3.3 进阶从字典到嵌套结构的处理实际项目里你不可能只做单层结构经常需要嵌套。比如我要在同一段文本里同时提取电影信息和观影渠道class Cinema(BaseModel): name: str location: str class MovieDetail(BaseModel): movie: Movie available_cinemas: List[Cinema]with_structured_output对这种嵌套结构是天然支持的你只需要在 Pydantic 里定义好嵌套关系别的都不用操心。但要注意嵌套越深模型出错的空间越大。我的建议是如果业务允许把嵌套控制在两层以内超过两层就考虑拆成多次调用。还有个很多人没注意到的参数method。这个参数可以手动指定结构化输出的方式比如methodfunction_calling强制走 Function Calling。默认的 Auto 模式足够覆盖绝大多数场景但如果你在调试中发现走了 Prompt 降级导致效果不稳可以手动指定更可靠的方式。4. 方案三JsonOutputParser 与 LangGraph 中的结构化输出4.1 JsonOutputParser 能干什么第三个方案是JsonOutputParser。它也是 LangChain 官方提供的解析器和PydanticOutputParser功能上类似但不要求你先定义完整的 Pydantic 模型直接用字典或类型提示就能搞定。适合快速原型验证也适合结构比较简单的场景。示例from langchain.output_parsers import JsonOutputParser from langchain.prompts import PromptTemplate from langchain_core.pydantic_v1 import BaseModel, Field class Movie(BaseModel): title: str director: str rating: float parser JsonOutputParser(pydantic_objectMovie) prompt PromptTemplate( template提取电影信息\n{input}\n{format_instructions}, input_variables[input], partial_variables{format_instructions: parser.get_format_instructions()}, ) chain prompt | model | parser data chain.invoke({input: 《千与千寻》宫崎骏作品豆瓣9.4。}) print(data) # 这是一个字典不是 Pydantic 对象 print(data[title])注意输出结果是dict类型而PydanticOutputParser输出的是 Pydantic 对象。这点在选择时要注意如果你的下游代码习惯用字典取数据JsonOutputParser 更省事如果需要强类型校验就选方案一。4.2 LangGraph 场景下的结构化输出再聊一个和 LangGraph 结合的点。LangGraph 里的节点之间传递的是状态字典每个节点运行完都会更新状态。如果你在某个节点的 LLM 调用里做了结构化输出那数据就直接以结构化形式注入状态图后续节点读取非常方便。我用一个简单的例子说明在电影推荐系统里先用一个节点抽取用户偏好再用另一个节点生成推荐。from typing import TypedDict from langgraph.graph import StateGraph, END class MoviePrefs(BaseModel): genres: List[str] min_rating: float class MovieRecommendation(BaseModel): recommended: List[Movie] def extract_prefs(state): structured_model llm.with_structured_output(MoviePrefs) prefs structured_model.invoke(state[user_input]) return {prefs: prefs} def recommend(state): structured_model llm.with_structured_output(MovieRecommendation) recs structured_model.invoke(f推荐风格类似{state[prefs].genres}的电影评分不低于{state[prefs].min_rating}) return {recs: recs} graph StateGraph(TypedDict(State, {user_input: str, prefs: MoviePrefs, recs: MovieRecommendation})) graph.add_node(extract, extract_prefs) graph.add_node(recommend, recommend) graph.set_entry_point(extract) graph.add_edge(extract, recommend) graph.add_edge(recommend, END) app graph.compile()做到这一步你的 Agent 状态流转里全程都是结构化数据根本不存在“手动解析中间文本”这个环节。我在实际项目里用 LangGraph 做信息抽取类任务时这种组合越用越顺。5. 三种方案的选型对比与我的心法5.1 横向对比到底该选哪一种三种方案各有适用场景我整理了一张表方便你决策时快速对号入座方案输出类型是否强约束上手难度适用场景PydanticOutputParserPydantic 对象中中需要校验的复杂场景没有 Function Calling 的旧模型with_structured_outputPydantic 对象高低当前主流模型的推荐首选JsonOutputParser字典中低快速原型下游只用字典定位数据我的个人习惯是新项目无脑用with_structured_output它是我实测下来最省心、最稳的姿势。碰到老模型不支持 Function Calling就退回PydanticOutputParser。如果只是临时试个想法不写 Pydantic 模型就用JsonOutputParser。5.2 选型时要避开的坑选型本身不难难的是别踩坑。这里分享几个我亲身踩过、以后不想再踩的别在 Prompt 里既放格式说明又用 with_structured_output 强约束。两个机制叠加反而可能让模型困惑输出质量下降。不要用过时的开源模型做结构化输出。很多老模型的 Function Calling 支持不完善结构化输出效果大打折扣。有条件就上新模型。一定要设置 temperature 为 0 或接近 0。结构化输出的场景里创造性是不需要的温度太高会破坏格式稳定性。字段名别用缩写。比如rt、dir这种模型很容易理解错。用全称rating、director描述写清楚模型准确率高得多。5.3 判断输出是否可靠的技巧结构化输出不是 100% 不出错的所以你得有个兜底。我的做法是给解析加一层 try-except解析失败时自动重试一次。有人会觉得麻烦但在生产环境里这一层极其重要。from langchain.output_parsers import OutputFixingParser fix_parser OutputFixingParser.from_llm( parserparser, llmChatOpenAI(modelgpt-4o-mini) ) try: result chain.invoke({input_text: ...}) except Exception: result fix_parser.parse_with_fix(...)OutputFixingParser会拿着解析失败的数据去问大模型“哪里不对、怎么修”通常一次就能修好。这比你自己写几十行正则去补救要靠谱太多了。6. 常见问题与排查技巧实录6.1 最常遇到的错误速查表结构化输出看着简单实际用起来还是有一堆容易出问题的地方。我把我在社区里见过和亲自踩过的坑整理成了一张表方便你遇到问题时直接对照错误信息原因解决办法OutputParserException: Failed to parse模型输出不是合法 JSON或者缺少必填字段换成with_structured_output加OutputFixingParserValidationError: field requiredPydantic 模型里有必填字段没被填充检查 Prompt 里的格式说明是否清晰赋值时别漏字段JSONDecodeError: Expecting value模型输出里有 Markdown 代码块或前后废话加大模型使用 JSON Mode用解析器前先清洗AttributeError: dict object has no attribute xxx你用了JsonOutputParser拿到的是字典却当成对象访问改成data[xxx]或者改用 Pydantic 解析器Failed to deserialize the JSON body into the target type下游接口的 JSON 结构和你的输出不匹配检查字段名、类型、嵌套层级是否与目标类型一致6.2 排查思路先定位是模型的问题还是代码的问题遇到输出不符合预期时第一件事是分辨问题出在哪个环节。我的排查顺序是先让模型裸奔直接在对话里问“请输出制定格式的数据”看模型本身能不能按格式给出来。如果给不出来问题在模型选型或 Prompt 设计。裸奔能出来但代码里解析失败问题在解析器配置或 Pydantic 模型定义。解析成功但数据不对比如年份少了一年、类型多了个空格问题在字段描述不够具体或者模型能力不够。把问题定位到这个粒度排查时间至少砍半。6.3 一个让我记忆深刻的真实排障有次我在做物流信息抽取需要从一段签收通知里提取包裹单号、签收人、签收时间、地址。用PydanticOutputParser调了半天连续十几条数据都报错“missing field”。当时没多想就一直微调 Prompt怎么调都没用。后来我把模型裸输出打印出来一看发现模型给的时间字段是2025-03-02 10:00:00但我在 Pydantic 里定义的是datetime: str按说没问题。仔细一看问题的根源是模型输出里的地址字段带了换行符JSON 直接断了。这类问题靠 Prompt 是修不好的正确的解法是用OutputFixingParser让模型修复格式错误或者直接换with_structured_output。那次之后我学到的教训是遇到反复调 Prompt 解决不了的问题先怀疑模型输出的原始格式再回来改代码。6.4 提高成功率的三个小动作最后送你三个我在实际项目中验证过的小技巧第一给关键字段设置default或Optional。有些字段不是每次都有的比如“票房”这种可能缺失的信息你不设默认值模型一没给就直接报错。from typing import Optional class Movie(BaseModel): title: str director: str rating: float box_office: Optional[float] None第二尽量让模型的输出只包含目标数据不要在前面加“以下是提取结果”之类的废话。你可以在 Prompt 里强调“直接输出 JSON不要额外解释”。配合with_structured_output这个问题的战斗基本就赢了。第三如果你对接的下游系统对 JSON 字段命名有自己的规范比如movie_name而不是title可以在 Pydantic 字段上用别名from pydantic import Field class Movie(BaseModel): movie_name: str Field(aliastitle)这样模型输出title后Pydantic 会自动映射到movie_name下游拿数据毫无压力。我个人在实际操作中的体会是结构化输出这件事本质是“把对模型输出的信任建立在约束上而不是建立在运气上”。正则方案总让你觉得自己在做安全检查其实只是把不确定性问题延迟到了未来某个毫无防备的时刻。而 LangChain 这三种方案无论选哪种核心思路都是让模型输出从一开始就长成你想要的样子省掉了解析、清洗、兜底这些重复劳动。如果你手头正好有项目还在用正则抠 JSON真心建议挑一个方案试一把改完你会回来感谢自己。