LangChain 结构化输出从入门到踩坑摘要结构化输出让 Agent 返回可预测的 JSON/Pydantic 模型而不是自然语言。本文深入解析 Provider Strategy 和 Tool Strategy 两种策略附完整代码和踩坑经验。一、为什么会写这篇最近在项目里做 Agent 开发遇到一个头疼的问题大模型返回的内容格式飘忽不定有时候是 JSON有时候是纯文本解析起来特别痛苦。后来发现 LangChain 提供了**结构化输出Structured Output**机制能让 Agent 按照我们定义的格式返回数据。听起来简单实际踩了不少坑。门主这篇文章把结构化输出的两种策略讲清楚顺便把踩过的坑分享出来帮你少走弯路。二、什么是结构化输出结构化输出允许Agent以特定的、可预测的格式返回数据。这样你无需解析自然语言响应就能获得JSON 对象、Pydantic 模型或数据类dataclasses形式的结构化数据供应用程序直接使用。简单说就是你定义好格式模型按格式返回。from pydantic import BaseModel, Fieldfrom langchain.agents import create_agentclass Answer(BaseModel): summary: str confidence: floatagent create_agent(modelopenai:gpt-5.5, response_formatAnswer)result agent.invoke({messages: [{role: user, content: 总结 AI 趋势}]})# 直接拿到结构化对象print(result[structured_response]) # Answer(summary..., confidence...)三、响应格式类型LangChain 的create_agent通过response_format参数控制结构化输出方式类型说明适用场景ToolStrategy通过工具调用实现结构化输出所有支持工具调用的模型ProviderStrategy使用提供商原生结构化输出OpenAI、Anthropic、xAI 等type[Schema]自动选择最佳策略推荐写法None不请求结构化输出默认自动选择逻辑四、提供商策略Provider Strategy4.1 原理部分模型提供商通过 API 原生支持结构化输出如 OpenAI、xAI、Gemini、Anthropic。这是最可靠的方式。当模型支持原生结构化输出时直接传 Schema 类型即可自动启用from pydantic import BaseModel, Fieldfrom langchain.agents import create_agentclass ContactInfo(BaseModel): 联系人信息 name: str Field(description姓名) email: str Field(description邮箱) phone: str Field(description电话)# 自动选择 ProviderStrategyagent create_agent( modelopenai:gpt-5.5, response_formatContactInfo)result agent.invoke({ messages: [{role: user, content: 提取联系人张三, zhangsanexample.com, 13800138000}]})print(result[structured_response])# ContactInfo(name张三, emailzhangsanexample.com, phone13800138000)4.2 支持的 Schema 类型Schema 类型返回类型特点Pydantic ModelPydantic 实例支持字段验证推荐Dataclassdict简单轻量TypedDictdict类型提示友好JSON Schemadict灵活但无代码提示4.3 严格模式ProviderStrategy支持strict参数启用严格模式需要langchain1.2from langchain.agents.structured_output import ProviderStrategyagent create_agent( modelopenai:gpt-5.5, response_formatProviderStrategy(schemaContactInfo, strictTrue))门主提醒严格模式要求模型完全遵守 Schema部分国产模型可能不支持建议先测试再上线。五、工具调用策略Tool Strategy5.1 原理对于不支持原生结构化输出的模型LangChain 通过工具调用实现结构化输出。模型会假装调用一个工具工具的参数就是结构化数据。这是兼容性最好的方式几乎所有支持工具调用的模型都能用。5.2 基本用法from pydantic import BaseModel, Fieldfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyfrom langchain.tools import tool# 定义输出格式class WeatherStrategy(BaseModel): city: str Field(description城市名称) weather: str Field(description天气描述) temperature: str Field(description温度) activity: str Field(description建议活动)# 定义工具tool(description查询城市天气的工具)def get_weather(city: str): return f今天{city}的天气晴,温度为30度,适合户外活动# 创建 Agentagent create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy(WeatherStrategy),)result agent.invoke({ messages: [{role: user, content: 长沙今天是什么天气}]})print(result[structured_response])# WeatherStrategy(city长沙, weather晴, temperature30度, activity适合户外活动)5.3 执行流程六、自定义工具消息内容tool_message_content参数允许自定义生成结构化输出时对话历史中显示的消息from langchain.agents.structured_output import ToolStrategyagent create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy( schemaWeatherStrategy, tool_message_content天气查询已完成 ),)对比效果设置ToolMessage 内容不设置Returning structured response: {city: 长沙, ...}设置后天气查询已完成门主建议生产环境建议自定义方便日志排查和调试。七、错误处理模型在通过工具调用生成结构化输出时可能会出错。LangChain 提供了智能的重试机制。7.1 handle_errors 参数值行为True捕获所有错误使用默认错误模板默认值str捕获所有错误使用自定义消息type[Exception]只捕获指定异常类型Callable[[Exception], str]自定义错误处理函数False不重试直接抛出异常7.2 完整示例from typing import Literalfrom pydantic import BaseModel, Field, field_validatorfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyfrom langchain.tools import toolclass WeatherStrategy(BaseModel): city: str Field(description城市名称) weather: str Field(description天气) temperature: str Field(description温度) activity: str Field(description建议活动) field_validator(city) classmethod def check_city(cls, value): # 模拟 Schema 校验失败 raise ValueError(故意触发 Schema 校验失败)tool(description查询天气)def get_weather(city: str): return f城市{city}\n天气晴\n温度30℃\n建议适合出去玩agent create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy( schemaWeatherStrategy, tool_message_content天气查询完成, handle_errorsTrue # 开启错误重试 ),)result agent.invoke({ messages: [{role: user, content: 长沙今天什么天气}]})7.3 常见错误类型错误类型原因解决方案Schema 校验失败模型返回数据不符合 Schema检查 Schema 定义开启重试多次调用结构化输出工具模型一次返回多个结构化数据LangChain 自动处理工具调用格式错误模型生成的 JSON 格式不正确使用更强大的模型八、多格式动态选择不同问答不同 Schema实际项目中经常会遇到这种情况用户问天气 → 返回天气格式用户问联系人 → 返回联系人格式用户问产品信息 → 返回产品格式总不能写死一个 Schema 吧LangChain 提供了几种方式解决这个问题。8.1 Union Types多 Schema 自动匹配ToolStrategy支持传入Union类型模型会根据上下文自动选择最合适的 Schemafrom pydantic import BaseModel, Fieldfrom typing import Literal, Unionfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyclass ProductReview(BaseModel): 产品评价分析 rating: int | None Field(description产品评分 1-5, ge1, le5) sentiment: Literal[positive, negative] Field(description情感倾向) key_points: list[str] Field(description关键要点)class CustomerComplaint(BaseModel): 客户投诉 issue_type: Literal[product, service, shipping, billing] Field(description问题类型) severity: Literal[low, medium, high] Field(description严重程度) description: str Field(description问题描述)class WeatherInfo(BaseModel): 天气信息 city: str Field(description城市) weather: str Field(description天气状况) temperature: str Field(description温度)# 多个 Schema 联合模型自动选择agent create_agent( modelchanAI, toolstools, response_formatToolStrategy(Union[ProductReview, CustomerComplaint, WeatherInfo]))# 模型会根据用户问题自动匹配合适的 Schemaresult1 agent.invoke({messages: [{role: user, content: 分析这个评价质量很好5星推荐}]})# → ProductReview(rating5, sentimentpositive, key_points[质量很好])result2 agent.invoke({messages: [{role: user, content: 长沙今天天气怎么样}]})# → WeatherInfo(city长沙, weather晴, temperature25°C)执行流程8.2 运行时动态切换 Schema如果需要更灵活的控制可以在不同场景下创建不同的 Agent 实例from langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategy# 定义多个 Schemaclass WeatherSchema(BaseModel): city: str Field(description城市) temperature: str Field(description温度) weather: str Field(description天气)class ContactSchema(BaseModel): name: str Field(description姓名) phone: str Field(description电话) email: str Field(description邮箱)class OrderSchema(BaseModel): order_id: str Field(description订单号) status: str Field(description订单状态) amount: float Field(description金额)# 工厂函数根据场景创建不同 Agentdef create_agent_by_scene(scene: str): scene_config { weather: { schema: WeatherSchema, system_prompt: 你是天气查询助手, tool_message_content: 天气查询完成 }, contact: { schema: ContactSchema, system_prompt: 你是联系人管理助手, tool_message_content: 联系人信息提取完成 }, order: { schema: OrderSchema, system_prompt: 你是订单查询助手, tool_message_content: 订单查询完成 } } config scene_config.get(scene, scene_config[weather]) return create_agent( modelchanAI, response_formatToolStrategy( schemaconfig[schema], tool_message_contentconfig[tool_message_content] ), system_promptconfig[system_prompt] )# 使用示例weather_agent create_agent_by_scene(weather)contact_agent create_agent_by_scene(contact)8.3 根据用户意图动态路由更智能的做法是先识别用户意图再路由到对应的 Agentfrom pydantic import BaseModel, Fieldfrom typing import Literalclass IntentSchema(BaseModel): 用户意图识别 intent: Literal[weather, contact, order, other] Field(description用户意图) extracted_info: str Field(description提取的关键信息)def smart_route(user_input: str): # 先用轻量模型识别意图 intent_agent create_agent( modelchanAI, response_formatIntentSchema ) intent_result intent_agent.invoke( {messages: [{role: user, content: user_input}]} ) intent intent_result[structured_response].intent # 根据意图路由到对应 Agent agent create_agent_by_scene(intent) return agent.invoke( {messages: [{role: user, content: user_input}]} )# 使用result smart_route(帮我查一下北京的天气)8.4 对比总结方式优点缺点适用场景Union Types简单一行代码模型可能选错 SchemaSchema 数量少差异明显工厂模式清晰可控需要预设场景场景固定数量有限意图路由最灵活可扩展多一次模型调用复杂场景Schema 数量多门主建议如果 Schema 不超过 5 个直接用 Union 就行。场景很多的话上意图路由更稳。九、两种策略对比维度Provider StrategyTool Strategy可靠性⭐⭐⭐⭐⭐⭐⭐⭐⭐兼容性仅支持原生输出的模型所有支持工具调用的模型性能更快一次调用可能需要多次调用Schema 复杂度支持复杂 Schema同样支持错误处理提供商处理LangChain 自动重试推荐场景OpenAI/Anthropic 等国产模型/开源模型十、实战代码完整示例10.1 基础示例古诗生成from langchain_openai import ChatOpenAIfrom langchain.agents import create_agentfrom pydantic import BaseModel, Fieldfrom langchain.agents.structured_output import ToolStrategyimport dotenvdotenv.load_dotenv()chanAI ChatOpenAI( modelqwen3.7-plus, temperature0.7, extra_body{enable_thinking: False})class PoemStrategy(BaseModel): name: str Field(description古诗名称) content: str Field(description古诗内容)agentChat create_agent( modelchanAI, response_formatPoemStrategy,)result agentChat.invoke({ messages: [ {role: system, content: 你是一个古诗创作助手}, {role: user, content: 今天长沙的天气如何} ]})print(result[structured_response])# PoemStrategy(name长沙今日即景, content湘水悠悠绕古城...)10.2 进阶示例带工具的天气查询from langchain.tools import toolfrom langchain.agents.structured_output import ToolStrategyclass WeatherStrategy(BaseModel): city: str Field(description城市名称) weather: str Field(description天气描述) temperature: str Field(description温度) activity: str Field(description建议活动)tool(description查询城市天气的工具)def get_weather(city: str): return f今天{city}的天气晴,温度为30度,适合户外活动agentChat create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy( schemaWeatherStrategy, tool_message_content天气查询已完成, handle_errorsTrue ),)result agentChat.invoke({ messages: [{role: user, content: 长沙今天是什么天气}]})print(result[structured_response])# WeatherStrategy(city长沙, weather晴, temperature30度, activity适合户外活动)学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】
