1. 项目概述为什么“格式化输出”是LangChain的必修课如果你刚开始接触LangChain可能会觉得它就是一个帮你“调用大模型”的框架把问题扔进去答案拿出来就完事了。但当你真正开始构建一个能用的应用时第一个让你头疼的往往不是模型本身而是模型返回的那些“五花八门”的文本。大模型很聪明但它也很“随意”。你让它“返回一个JSON”它可能给你一个没有闭合大括号的字符串你让它“用逗号分隔列表”它可能在最后一个元素后面也加个逗号。这种不确定性是程序化应用的天敌。这就是“格式化输出”要解决的核心问题将大模型自由、非结构化的自然语言输出驯服成我们程序能够稳定、可靠解析的结构化数据。这不仅仅是让输出“好看”而已。想象一下你构建了一个智能客服Agent用户问“今天天气如何”。模型可能回答“今天北京晴气温15-25度微风”。作为人类我们一眼就能提取出“地点北京”、“天气晴”、“温度15-25度”、“风力微风”这些信息。但你的程序呢它看到的只是一个字符串。如果你想根据天气情况触发后续动作比如下雨就建议带伞就必须写一堆复杂的正则表达式去“猜”和“抠”这些信息既脆弱又低效。而LangChain的格式化输出能力就是让你能提前定义好一个“模板”或“结构”告诉模型“请严格按照我这个格式来回答”。这样模型返回的就会是一个标准的JSON对象、一个Pydantic模型实例或者一个用特定分隔符组织好的字符串。你的程序可以直接将其反序列化为Python对象像操作字典一样轻松获取“weather”字段的值。这从根本上提升了AI应用的可靠性、可维护性和集成便利性。所以掌握格式化输出是从“玩具Demo”迈向“生产级应用”的关键一步。2. 核心思路拆解LangChain实现格式化输出的三种武器LangChain提供了多种工具来实现格式化输出每种都有其适用的场景和背后的设计哲学。理解它们的区别能帮助你在不同需求下做出最合适的选择。2.1 结构化输出与Pydantic的强强联合这是目前最推荐、也是最强大的方式。它的核心思想是用Pydantic数据模型来定义你期望的输出结构。Pydantic是一个用于数据验证和设置管理的Python库通过Python类型注解来定义数据结构。LangChain与之深度集成能将这个数据模型的“模式”作为指令的一部分发送给大模型要求模型生成符合该模式的内容。为什么选择这种方式类型安全与自动验证Pydantic会在模型返回内容后自动进行类型验证。如果模型返回的“年龄”是个字符串“二十五”但你在模型里定义的是age: intPydantic会尝试转换或直接报错这为你的数据质量提供了第一道保障。开发体验极佳在IDE中你可以获得完整的代码补全和类型提示。直接通过obj.field_name的方式访问数据比用字典的obj[“field_name”]要安全和方便得多。清晰的契约你的Pydantic模型就是一份清晰的数据契约文档任何阅读代码的人都能立刻明白输出包含哪些字段各自是什么类型。它的工作原理是LangChain会将Pydantic模型的JSON Schema一种描述JSON数据结构的标准注入到给模型的系统提示或用户提示中。模型在生成时会“意识”到需要遵循这个结构。2.2 输出解析器灵活处理字符串输出在Pydantic模型流行之前输出解析器是更通用的解决方案。它的思路是先让模型自由生成一段文本然后再用一段解析逻辑Parser将这段文本转换成结构化的形式。LangChain内置了多种解析器CommaSeparatedListOutputParser: 解析逗号分隔的列表。StructuredOutputParser: 根据你提供的格式指令如“用‘答案’开头”来解析。PydanticOutputParser: 这其实是上面“结构化输出”的底层实现之一它利用Pydantic模型来解析模型返回的文本。它的适用场景是当你无法或不想使用结构化输出提示例如某些模型或较老版本不支持或者你的输出结构非常简单比如就是一个列表使用解析器会更轻量。但它的缺点是“两步走”先生成再解析。如果生成的内容偏离预期太远解析就可能失败可靠性不如直接要求模型按结构生成。2.3 自定义格式指令最原始但最可控的方式有时你可能只需要一个非常简单的特定格式比如“用三个反引号包裹代码”。这时你可以直接在提示模板中通过自然语言描述你的格式要求。例如在你的提示词末尾加上请将你的回答用以下格式输出 json { “thought”: “你的思考过程”, “answer”: “你的最终答案” }这种方式极度灵活完全依赖于你提示词工程的能力和模型的理解能力。它没有额外的框架开销但同样缺乏自动验证和类型安全需要你自己编写后续的解析代码更适合快速原型或格式极其固定的简单场景。 **注意**在实际项目中我强烈建议优先使用**结构化输出Pydantic**。它代表了当前将大模型集成到生产应用中的最佳实践在可靠性、开发效率和可维护性上取得了最佳平衡。下面我们将重点深入这种方法。 ## 3. 实战演练一步步实现Pydantic结构化输出 让我们通过一个完整的例子看看如何为一个“天气查询智能体”定义和获取结构化输出。假设我们希望模型返回城市、天气状况、温度范围和一项建议。 ### 3.1 第一步定义你的数据模型 首先你需要用Pydantic定义一个模型类。这个类精确描述了你希望得到什么。 python from pydantic import BaseModel, Field from typing import List class WeatherInfo(BaseModel): 天气信息数据模型 city: str Field(description查询的城市名称) condition: str Field(description天气状况如晴、多云、雨、雪等) temperature_low: int Field(description最低气温单位为摄氏度) temperature_high: int Field(description最高气温单位为摄氏度) suggestion: str Field(description根据天气给出的出行或穿着建议) # 你可以轻松地扩展更多字段例如 # humidity: Optional[int] Field(None, description湿度百分比) # wind: str Field(description风力描述)这里的关键点Field(description“...”)非常重要这个描述不仅作为你代码的文档更会被LangChain传递给大模型帮助模型理解每个字段的含义。写得越清晰模型填充得越准确。使用Python类型注解str,int,List[str]等Pydantic会据此进行验证。3.2 第二步创建支持结构化输出的链接下来我们将这个模型绑定到LLM和提示模板上。from langchain_openai import ChatOpenAI # 以OpenAI为例 from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser, PydanticOutputParser # 1. 初始化模型 llm ChatOpenAI(model“gpt-4o”, temperature0) # temperature设为0可以使输出更稳定、更倾向于遵循格式 # 2. 创建输出解析器虽然叫Parser但这里用于生成结构化提示 parser PydanticOutputParser(pydantic_objectWeatherInfo) # 3. 构建提示模板 # 注意我们通过 get_format_instructions() 方法将格式要求注入提示词 prompt ChatPromptTemplate.from_messages([ (“system”, “你是一个专业的天气助手。请根据用户的问题提取天气信息并严格按照给定格式回答。\n{format_instructions}”), (“human”, “{query}”) ]) # 4. 创建链 chain prompt | llm | parser # 这里parser不仅用于解析在prompt阶段也会提供format_instructions # 另一种更显式的写法便于理解流程 # chain { # “format_instructions”: lambda _: parser.get_format_instructions(), # “query”: lambda x: x[“query”] # } | prompt | llm | parserparser.get_format_instructions()这个方法会生成一段详细的自然语言文本向模型解释输出格式。对于上面的WeatherInfo模型生成的指令大致是“请输出一个JSON对象包含以下键city, condition, temperature_low, temperature_high, suggestion。其中city是字符串condition是字符串...”3.3 第三步调用并获取结构化对象现在我们可以像调用函数一样使用这个链并直接得到一个WeatherInfo实例。# 用户输入 user_query “请问北京今天的天气怎么样” # 调用链 try: result: WeatherInfo chain.invoke({“query”: user_query}) # 注意invoke的输入字典键名要与提示模板中的变量名一致这里是“query” except Exception as e: print(f“解析失败: {e}”) # 这里可以加入重试或降级逻辑 result None if result: print(f“城市: {result.city}”) print(f“天气: {result.condition}”) print(f“温度: {result.temperature_low}°C ~ {result.temperature_high}°C”) print(f“建议: {result.suggestion}”) # 因为result是一个Pydantic对象你可以轻松地将其转为字典或JSON weather_dict result.dict() weather_json result.json() print(f“JSON格式: {weather_json}”)运行后你将直接获得一个WeatherInfo对象result。result.city、result.suggestion这些属性都可以直接访问类型明确无需手动解析JSON字符串。3.4 第四步处理复杂嵌套结构现实中的数据模型往往更复杂。Pydantic和LangChain能很好地处理嵌套。from pydantic import BaseModel, Field from typing import List, Optional class DailyWeather(BaseModel): date: str Field(description“日期格式YYYY-MM-DD”) condition: str temp_range: str Field(description“温度范围如’15-25°C‘”) class WeatherForecast(BaseModel): location: str days: List[DailyWeather] Field(description“未来几天的天气预报列表”) update_time: Optional[str] Field(None, description“数据更新时间”) # 后续创建parser和chain的步骤完全相同 parser PydanticOutputParser(pydantic_objectWeatherForecast)模型会理解它需要生成一个包含days列表的对象列表中的每个元素都符合DailyWeather的格式。这极大地扩展了结构化输出的表达能力。4. 避坑指南与高级技巧在实际使用中你肯定会遇到各种问题。下面是我从大量实践中总结出的经验和解决方案。4.1 常见问题与排查清单问题现象可能原因解决方案抛出OutputParserException1. 模型输出完全不符合JSON格式。2. 字段类型不匹配如要求数字却给了字符串。3. 缺少必需字段。1.检查提示词确保format_instructions被正确加入系统提示。可先打印parser.get_format_instructions()查看。2.降低Temperature尝试将temperature设为0或0.1减少随机性。3.增强指令在系统提示中强调“必须输出有效的JSON”。4.使用更强大模型GPT-4系列在遵循复杂格式上远优于GPT-3.5。模型返回了JSON但字段值为空或“N/A”1. 模型在输入中未找到对应信息。2. 字段描述(description)不够清晰。1.优化查询确保用户问题中包含足够信息。对于缺失信息考虑在Pydantic模型中使用Optional类型。2.细化描述将description写得更具体例如Field(description“股票代码例如’AAPL‘或’00700.HK‘”)。解析速度慢1. 模型生成时间长。2. 输出非常长解析耗时。1.使用流式输出如果支持使用chain.stream()边生成边处理提升用户体验。2.简化模型非必要不使用过于复杂的嵌套结构。需要兼容多个模型不同模型对结构化输出的支持程度不同。1.优先使用ChatModel大多数Chat模型OpenAI, Anthropic, DeepSeek对结构化输出支持较好。2.降级方案对于不支持原生结构化的模型可以回退到StructuredOutputParser让模型生成文本后再解析但需增加错误处理。4.2 高级技巧让输出更稳定可靠技巧一提供示例Few-Shot Prompting对于极其复杂的格式仅靠格式指令可能不够。你可以在系统提示中提供一两个完整的输出示例。system_prompt “”” 你是一个天气助手。请提取信息并严格按以下JSON格式输出。 示例输出 {{ “city”: “上海”, “condition”: “多云转晴”, “temperature_low”: 18, “temperature_high”: 26, “suggestion”: “早晚温差大建议穿薄外套。” }} 请严格遵循上述格式。 {format_instructions} “””技巧二使用RetryOutputParser进行自动重试LangChain提供了一个非常实用的RetryWithErrorOutputParser。当第一次解析失败时它会将错误信息和原始输出一起反馈给模型要求模型重试一次。from langchain.output_parsers import RetryOutputParser from langchain_core.output_parsers import PydanticOutputParser parser PydanticOutputParser(pydantic_objectWeatherInfo) retry_parser RetryOutputParser.from_llm(parserparser, llmllm) # 在链中使用retry_parser chain prompt | llm | retry_parser这能显著提高在复杂场景下的成功率相当于给模型一次“修正错误”的机会。技巧三为可选字段设置默认值不是所有信息都能从用户查询中提取。对于可能缺失的字段使用Optional并设置合理的默认值可以避免解析失败。from typing import Optional class WeatherInfo(BaseModel): city: str condition: str temperature_low: Optional[int] None # 允许为None temperature_high: Optional[int] None suggestion: str “请根据实际情况增减衣物。” # 提供默认值技巧四后处理与数据清洗即使解析成功数据也可能需要清洗。你可以在Pydantic模型中使用validator装饰器。from pydantic import validator class WeatherInfo(BaseModel): city: str condition: str validator(‘condition‘) def condition_to_lowercase(cls, v): # 将天气状况统一转为小写便于后续比较 return v.lower() validator(‘temperature_high‘) def temp_high_greater_than_low(cls, v, values): if ‘temperature_low‘ in values and v values[‘temperature_low‘]: # 如果最高温低于最低温交换它们一种简单的纠错 values[‘temperature_low‘], v v, values[‘temperature_low‘] return v4.3 性能考量什么时候不该用结构化输出结构化输出不是银弹。在以下场景你可能需要权衡极简输出如果输出只是一个单词或一个短句例如情感分类“正面/负面”使用StrOutputParser然后简单判断可能更快。流式传输优先在需要逐字显示结果的聊天场景结构化输出通常需要等待整个JSON对象生成完毕才能解析会破坏流式体验。可以考虑先流式传输原始文本或在客户端进行轻量解析。对延迟极度敏感生成结构化指令会增加提示词的长度理论上可能略微增加模型的思考时间Token数。在毫秒必争的场景下需要实测评估影响。5. 在真实Agent场景中的应用格式化输出在智能体Agent工作流中至关重要。一个典型的Agent往往由“思考-行动-观察”循环构成其“思考”的输出必须被精确解析以决定下一步调用哪个工具。假设我们构建一个旅行规划Agent它有一个工具是get_flight_info。我们需要模型决定何时调用这个工具。from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.pydantic_v1 import BaseModel, Field # 1. 定义Agent的“动作”输出格式 class AgentAction(BaseModel): “””Agent决定执行的动作“”” thought: str Field(description“对当前情况和下一步行动的思考过程”) action: str Field(description“要执行的动作名称必须是以下之一: ‘get_flight_info‘, ‘search_hotel‘, ‘final_answer‘”) action_input: dict Field(description“调用动作时需要的输入参数以字典形式提供”) # 2. 在创建Agent时将该格式绑定给LLM # 假设我们已经定义了prompt和tools agent create_tool_calling_agent( llmllm, promptprompt, toolstools, # 关键这里LLM会使用我们定义的格式来输出其“思考” ) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 当用户输入“我想下周五从北京飞上海”时 # LLM会输出符合AgentAction格式的JSON例如 # { # “thought”: “用户想查询航班。我需要调用获取航班信息的工具需要出发城市、到达城市和日期。”, # “action”: “get_flight_info”, # “action_input”: {“departure”: “北京”, “arrival”: “上海”, “date”: “2024-10-25”} # } # AgentExecutor会解析这个JSON然后调用对应的工具。如果没有这种强制的格式化输出LLM可能会用一段自由文本来描述它的决定比如“我觉得应该先查一下航班从北京到上海下周五”。程序很难稳定地从这种文本中精确提取出action和action_input。结构化输出确保了Agent决策的可机器解析性这是实现自动化工作流的基石。6. 与相关技术的对比与选择在LangChain生态中你可能会听到LangGraph、Agent SDK等其他概念。理解格式化输出在其中的位置很重要。LangChain vs LangGraph你可以把LangChain看作一套构建AI应用的基础工具箱包含模型I/O、提示模板、链、记忆、Agent等。而LangGraph是建立在LangChain之上的一个库专门用于构建有状态的、多步骤的、循环的工作流比如一个复杂的客服对话流程。在LangGraph中每个节点的输出通常也需要是结构化的决定了下一个要执行的节点。因此格式化输出是LangGraph中节点间可靠传递信息的前提。工具调用 vs Function Calling这是两个容易混淆的概念。大模型原生的Function Calling如OpenAI的tools参数是一种让模型输出一个结构化调用请求函数名和参数的协议。LangChain的工具调用是对此协议的封装和增强。当你使用create_tool_calling_agent时底层就是利用了大模型的Function Calling能力来实现结构化输出。LangChain帮你处理了格式协商、错误重试等细节并提供统一的接口。LangChain vs Dify/RAGFlowDify和RAGFlow是更上层的无代码/低代码AI应用平台。它们提供了可视化界面来编排工作流、管理知识库。在底层它们可能也使用了LangChain或类似的技术栈。如果你需要快速搭建一个标准化的RAG应用用这些平台可能更快。但如果你需要深度定制逻辑、集成特殊的数据源或工具或者你的应用逻辑非常复杂那么直接使用LangChain并掌握好格式化输出这类核心技能会给你带来更大的灵活性和控制力。最终的选择取决于你的需求追求开发效率和标准化可以考虑平台追求灵活性和深度控制则从LangChain入手而格式化输出是你必须扎实掌握的第一个关键技能。它看似简单却是连接AI的“智能”与程序的“逻辑”之间那座最重要的桥梁。