LangGraph结构化输出实战:5分钟搞定Pydantic模型验证与JSON解析
你是否曾花费数小时,只为从大语言模型(LLM)那自由奔放的文本输出中,精准地提取出几个结构化的字段?比如,你只想让模型返回一个包含“产品名称”、“价格”和“库存状态”的JSON对象,但它却可能给你一段散文式的描述,夹杂着无关的说明和感叹。在构建自动化流程、数据管道或智能代理时,这种不确定性是致命的。今天,我们不谈空洞的理论,直接上手一个能让你在五分钟内解决这个痛点的实战方案:利用LangGraph的with_structured_output方法,结合Pydantic的强大验证能力,驯服LLM的输出,让它乖乖交出你想要的格式。
这篇文章面向的是已经熟悉Python基础,并开始在实际项目中集成LLM的开发者。我们将绕过复杂的源码迷宫,聚焦于如何快速、可靠地实现结构化输出。你将学到的不只是调用一个API,而是理解其背后的设计逻辑、如何处理常见的解析陷阱,以及如何将这套机制无缝融入你的LangGraph工作流中。准备好了吗?让我们开始吧。
1. 为什么需要结构化输出?从混乱到秩序
在传统的软件开发中,函数的返回值类型是明确的。但在LLM的世界里,输出本质上是非结构化的文本流。当你需要将LLM的响应作为下游代码的输入时,这种不确定性就成了绊脚石。想象一下,你正在构建一个电商客服机器人,用户问:“你们还有黑色的iPhone 15 Pro吗?” 你期望的响应可能是一个结构化的数据对象:
{
"product_name": "iPhone 15 Pro",
"color": "黑色",
"in_stock": true,
"estimated_delivery_days": 3
}
然而,LLM的原生回复可能是:“您好!目前iPhone 15 Pro的黑色版本库存充足,预计3个工作日内可以送达。” 虽然信息齐全,但你的代码无法直接、稳定地从中提取出in_stock: true这个布尔值。
结构化输出就是为了弥合这个鸿沟。它通过给LLM一个明确的“输出模板”(schema),引导模型生成符合特定格式的数据。这不仅仅是“格式化”,更包含了数据验证。如果模型返回的“库存”字段是一个字符串“充足”,而你的schema期望一个布尔值,验证机制会立即捕获这个错误,防止错误数据污染后续流程。
注意:结构化输出的实现,依赖于LLM本身支持“工具调用”(Tool use)或“函数调用”(Function calling)能力。这本质上是让模型学习“为了完成某个任务,我需要按照特定格式输出数据”。主流模型如GPT-4、Claude 3、DeepSeek等都已支持此功能。
LangGraph的with_structured_output方法,正是将这一系列复杂操作——绑定schema、调用模型、解析响应、验证数据——封装成了一个简洁的Runnable接口。你的代码从处理文本的泥潭中解放出来,开始处理确定性的对象。
2. 核心武器:Pydantic模型定义与验证
在深入LangGraph之前,我们必须先掌握Pydantic这个利器。Pydantic是一个基于Python类型注解的数据验证和设置管理库。它让你能用Python类来清晰定义数据形状,并自动处理验证、序列化和文档生成。
2.1 定义你的数据契约
让我们为上面的电商查询场景定义一个Pydantic模型。这就像为LLM的输出起草一份“合同”。
from pydantic import BaseModel, Field
from typing import Optional
class ProductQueryResult(BaseModel):
"""产品库存查询结果"""
product_name: str = Field(description="产品的具体名称,如 iPhone 15 Pro")
color: Optional[str] = Field(None, description="产品颜色,如无特定颜色则为None")
in_stock: bool = Field(description="当前是否有库存")
estimated_delivery_days: int = Field(ge=0, description="预计送达天数,必须为非负整数")
price: Optional[float] = Field(None, gt=0, description="产品价格,单位元,必须大于0")
这个简单的类蕴含了强大的约束:
- 类型安全:
in_stock必须是布尔值,estimated_delivery_days必须是整数。 - 字段描述:
Field(description=...)不仅为人类提供文档,更重要的是,这些描述会被传递给LLM,帮助它理解每个字段应该填充什么内容。 - 高级验证:
ge=0确保送达天数非负,gt=0确保价格为正数。Pydantic支持丰富的验证器。 - 可选字段:
Optional[str]表示颜色和价格字段可能为None,这在实际场景中非常实用。
2.2 验证的力量:拦截错误数据
定义模型只是第一步,验证才是保障数据质量的防火墙。看看Pydantic如何工作:
# 正确的数据
good_data = {
"product_name": "iPhone 15 Pro",
"color": "黑色",
"in_stock": True,
"estimated_delivery_days": 3
}
result = ProductQueryResult(**good_data)
print(result)
# 输出:ProductQueryResult(product_name='iPhone 15 Pro', color='黑色', in_stock=True, estimated_delivery_days=3, price=None)
# 错误的数据:送达天数为负数
bad_data = {
"product_name": "MacBook Air",
"in_stock": True,
"estimated_delivery_days": -2 # 无效值!
}
try:
result = ProductQueryResult(**bad_data)
except Exception as e:
print(f"验证错误: {e}")
# 输出:validation error for ProductQueryResult...
# estimated_delivery_days: ensure this value is greater than or equal to 0...
这种严格的验证,确保了流入你业务逻辑的数据是干净、合规的。当与LLM结合时,它能在第一时间发现模型输出的格式或逻辑错误,而不是让错误潜伏到业务代码深处才爆发。
3. 五分钟实战:LangGraph with_structured_output 全流程
现在,我们将Pydantic模型和LangGraph结合起来。假设你已经安装好了langgraph和openai等基础库,并设置好了API密钥。
3.1 基础用法:最简单的结构化输出
首先,我们创建一个支持结构化输出的LLM链。这里以OpenAI的Chat模型为例。
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field
# 1. 定义输出模型
class Joke(BaseModel):
"""一个笑话"""
setup: str = Field(description="笑话的开头或问题部分")
punchline: str = Field(description="笑话的包袱或答案部分")
category: str = Field(description="笑话的分类,如‘程序员’、‘生活’")
# 2. 初始化模型
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.5)
# 3. 应用结构化输出
structured_llm = llm.with_structured_output(Joke)
# 4. 调用!直接得到Pydantic对象
joke_result = structured_llm.invoke("给我讲一个关于程序员的笑话。")
print(type(joke_result)) # <class '__main__.Joke'>
print(joke_result.setup) # 直接访问属性
print(joke_result.punchline)
print(f"分类: {joke_result.category}")
就这么简单!invoke方法返回的直接就是一个Joke类的实例对象,而不是原始的AIMessage或字典。你可以像使用任何Python对象一样使用它:点号访问属性、传递给其他函数、序列化成JSON等。
3.2 处理原始输出与错误:include_raw参数
在开发调试或需要更高容错性的场景下,你可能既想得到解析后的结构化数据,又想保留模型的原始响应,以便在解析失败时进行诊断。include_raw=True参数就是为此而生。
# 启用包含原始输出的模式
structured_llm_with_raw = llm.with_structured_output(Joke, include_raw=True)
response = structured_llm_with_raw.invoke("讲个冷笑话。")
print(response.keys()) # dict_keys(['raw', 'parsed', 'parsing_error'])
# 解析成功的情况
if response['parsing_error'] is None:
joke = response['parsed'] # 这里就是Joke对象
print(f"笑话包袱: {joke.punchline}")
# 你还可以查看原始消息
raw_message = response['raw']
print(f"原始响应内容: {raw_message.content}")
print(f"工具调用参数: {raw_message.additional_kwargs.get('tool_calls')}")
else:
# 解析失败的情况
print(f"解析出错: {response['parsing_error']}")
print(f"原始响应可供调试: {response['raw']}")
返回的字典包含三个键:
raw: 原始的AIMessage对象,包含模型返回的全部信息。parsed: 解析后的Pydantic对象。如果解析失败,则为None。parsing_error: 解析过程中抛出的异常对象。如果解析成功,则为None。
这种模式非常适合构建生产级的稳健应用,你可以根据parsing_error来决定重试、降级处理或记录日志。
3.3 使用字典Schema:更灵活的轻量级选择
并非所有场景都需要Pydantic的重量级验证。有时,你只需要一个简单的字典结构。with_structured_output也支持直接传入OpenAI函数格式的字典schema。
from langchain_core.utils.function_calling import convert_to_openai_tool
# 方法一:从Pydantic模型转换(推荐,保持一致性)
dict_schema = convert_to_openai_tool(Joke)
print(dict_schema)
# 输出一个符合OpenAI函数调用规范的字典
# 方法二:手动定义字典schema
manual_schema = {
"type": "function",
"function": {
"name": "extract_info",
"description": "从文本中提取关键信息",
"parameters": {
"type": "object",
"properties": {
"main_topic": {"type": "string"},
"sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
"key_entities": {"type": "array", "items": {"type": "string"}}
},
"required": ["main_topic", "sentiment"]
}
}
}
# 应用字典schema
llm_dict = llm.with_structured_output(manual_schema)
result_dict = llm_dict.invoke("用户反馈说新版本的APP启动速度变快了,但偶尔会闪退。")
print(result_dict)
# 输出如: {'main_topic': 'APP版本反馈', 'sentiment': 'positive', 'key_entities': ['APP', '启动速度', '闪退']}
使用字典schema时,返回的直接是Python字典。它更轻量,但牺牲了Pydantic提供的自动类型转换和复杂验证。如何选择?一个简单的原则:如果数据结构简单且稳定,用字典;如果数据结构复杂、需要严格验证或可能频繁演变,用Pydantic。
4. 避坑指南:实战中常见的JSON解析问题
即使使用了with_structured_output,你仍可能遇到一些棘手的解析问题。下面是一些典型场景及其解决方案。
4.1 模型“不听话”:输出不符合Schema
有时,模型会忽略你的指令,返回自由文本而不是结构化的工具调用。这通常有几个原因:
- 温度(Temperature)过高:过高的温度值会增加模型的随机性。对于需要严格遵循格式的任务,建议将
temperature设置为0或一个较低的值(如0.1-0.3)。 - Schema描述不清:Pydantic字段的
description至关重要。模糊的描述会导致模型困惑。确保描述清晰、无歧义,并说明字段的格式(例如,“日期,格式为YYYY-MM-DD”)。 - 系统提示词(System Prompt)缺失或不当:在调用链前加入明确的系统提示词,强调输出格式要求。
from langchain_core.prompts import ChatPromptTemplate
# 强化系统指令
system_prompt = """你是一个严格的数据提取助手。你必须将你的回答格式化为一个JSON对象,严格遵循提供的工具调用格式。
不要添加任何解释性文字、前缀或后缀,只输出工具调用。"""
human_prompt = "{query}"
prompt = ChatPromptTemplate.from_messages([
("system", system_prompt),
("human", human_prompt)
])
# 将提示词链与结构化LLM结合
chain = prompt | structured_llm
result = chain.invoke({"query": "分析这段文本的情绪..."})
4.2 处理嵌套与复杂对象
现实世界的数据很少是扁平的。Pydantic完美支持嵌套模型和复杂类型。
from typing import List
from pydantic import BaseModel
class Author(BaseModel):
name: str
affiliation: str
class ResearchPaper(BaseModel):
title: str
authors: List[Author] # 嵌套模型列表
abstract: str
keywords: List[str]
publication_year: int
citations: Optional[int] = None
# 定义链
paper_extractor = llm.with_structured_output(ResearchPaper)
# 调用 - 模型会自动处理嵌套的authors列表
paper_info = paper_extractor.invoke("""
请从以下描述中提取信息:论文《深度学习在医疗影像中的应用》由张三(北京大学)和李四(清华大学)合作完成,
发表于2023年,摘要讨论了CNN和Transformer的融合,关键词包括‘深度学习’、‘医疗影像’、‘诊断’。
""")
print(f"第一作者: {paper_info.authors[0].name}")
print(f"关键词数量: {len(paper_info.keywords)}")
当模型返回嵌套的JSON时,Pydantic会递归地进行验证和实例化,确保整个对象树都符合定义。
4.3 部分JSON解析与流式输出
在一些流式或渐进式生成的场景中,你可能希望处理“不完整”的JSON。with_structured_output底层解析器支持partial=True参数,但这通常由框架在流式响应时内部处理。对于普通开发者,一个更实用的技巧是:如果担心模型生成残缺的JSON,可以在schema中为关键字段设置默认值,或使用Optional类型,并在后续代码中做空值检查。
class PartialInfo(BaseModel):
name: Optional[str] = None
age: Optional[int] = None
# 即使模型没输出age,解析也不会失败,结果为None
# 另一种策略:使用更宽松的验证,先拿到数据再说
from pydantic import validator
class TolerantModel(BaseModel):
score: str # 先用字符串接收
@validator('score', pre=True)
def parse_score(cls, v):
# 尝试将各种输入转换为字符串
if isinstance(v, (int, float)):
return str(v)
return v
4.4 性能与成本考量
结构化输出依赖于模型的工具调用能力,这可能会略微增加提示词的令牌消耗(因为需要传输schema)。为了优化:
- 精简Schema:只定义必要的字段,删除冗余的描述。过长的字段名和描述会增加Token开销。
- 缓存结果:对于相同schema和相似输入的频繁查询,考虑对最终的结构化输出结果进行缓存。
- 批量处理:如果可能,将多个查询合并到一个提示词中,并让模型返回一个对象数组(这需要更复杂的schema设计)。
下表对比了不同场景下的选择建议:
| 场景特征 | 推荐方案 | 关键理由 |
|---|---|---|
| 数据结构简单,仅需基本提取 | 字典Schema | 轻量,无额外依赖,解析速度快。 |
| 数据需严格验证,类型复杂 | Pydantic模型 | 提供运行时类型安全和丰富验证,代码自文档化。 |
| 需要调试或错误诊断 | include_raw=True | 保留原始响应,便于分析解析失败原因。 |
| 生产环境,要求高鲁棒性 | Pydantic + include_raw=True + 错误处理 | 结合了验证、原始数据备份和自定义降级策略。 |
| 流式响应或需要中间结果 | 使用LangChain的解析器回调 | 可以处理部分结果,实现渐进式UI更新。 |
5. 融入LangGraph智能体与工作流
LangGraph的核心价值在于构建有状态的、多步骤的智能体工作流。结构化输出在这里扮演着“标准化接口”的角色,确保不同节点之间传递的数据是清晰、可预测的。
假设我们构建一个简单的产品调研智能体,它有两个步骤:1) 从网络评论中提取产品特征;2) 根据特征生成总结报告。
from langgraph.graph import StateGraph, END
from typing import TypedDict, List
from pydantic import BaseModel
# 定义状态
class AgentState(TypedDict):
user_query: str
extracted_features: List[str] # 存储第一步的结果
final_report: str # 存储第二步的结果
# 第一步:特征提取的Pydantic模型
class ProductFeatures(BaseModel):
features: List[str] = Field(description="从文本中提取出的产品特性关键词")
# 第二步:报告生成(这里我们不需要结构化输出,直接返回文本)
feature_extractor = llm.with_structured_output(ProductFeatures)
report_generator = llm # 普通LLM,用于生成文本报告
# 定义节点函数
def extract_features_node(state: AgentState):
query = state["user_query"]
# 使用结构化输出提取特征
features_result = feature_extractor.invoke(f"从以下用户评论中提取产品特性:{query}")
# 将结构化的Pydantic对象数据存入状态
return {"extracted_features": features_result.features}
def generate_report_node(state: AgentState):
features = state["extracted_features"]
# 使用提取出的特征(已是列表)来生成报告
report = report_generator.invoke(f"基于这些产品特性{features},生成一份简短的总结报告。")
return {"final_report": report.content}
# 构建图
workflow = StateGraph(AgentState)
workflow.add_node("extract", extract_features_node)
workflow.add_node("report", generate_report_node)
workflow.set_entry_point("extract")
workflow.add_edge("extract", "report")
workflow.add_edge("report", END)
app = workflow.compile()
# 执行工作流
final_state = app.invoke({"user_query": "这款手机拍照色彩很真实,夜景模式很强,但电池续航一般,充电速度慢。"})
print("提取的特征:", final_state["extracted_features"])
print("生成的报告:", final_state["final_report"])
在这个工作流中,extract_features_node使用了结构化输出,确保extracted_features状态一定是一个字符串列表。这为generate_report_node提供了可靠、类型明确的输入,避免了在节点间传递数据时还需要进行字符串解析或错误检查的麻烦。整个系统的可靠性因此大大提升。
结构化输出不是LangGraph中一个孤立的技巧,而是构建稳健、可维护的AI工作流的基石。它让LLM从一个“黑盒文本生成器”,转变为你代码库中一个具有明确接口的“数据处理组件”。花五分钟掌握它,为你接下来的AI应用开发铺平道路。
522



被折叠的 条评论
为什么被折叠?



