LangChain格式化输出：从非结构化文本到可靠结构化数据的核心技术

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与之深度集成，能将这个数据模型的“模式”作为指令的一部分发送给大模型，要求模型生成符合该模式的内容。

为什么选择这种方式？

1. 类型安全与自动验证：Pydantic会在模型返回内容后自动进行类型验证。如果模型返回的“年龄”是个字符串“二十五”，但你在模型里定义的是age: int，Pydantic会尝试转换或直接报错，这为你的数据质量提供了第一道保障。
2. 开发体验极佳：在IDE中，你可以获得完整的代码补全和类型提示。直接通过obj.field_name的方式访问数据，比用字典的obj[“field_name”]要安全和方便得多。
3. 清晰的契约：你的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”, temperature=0) # temperature设为0可以使输出更稳定、更倾向于遵循格式 # 2. 创建输出解析器（虽然叫Parser，但这里用于生成结构化提示） parser = PydanticOutputParser(pydantic_object=WeatherInfo) # 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 | parser

parser.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_object=WeatherForecast)

模型会理解它需要生成一个包含days列表的对象，列表中的每个元素都符合DailyWeather的格式。这极大地扩展了结构化输出的表达能力。

4. 避坑指南与高级技巧

在实际使用中，你肯定会遇到各种问题。下面是我从大量实践中总结出的经验和解决方案。

4.1 常见问题与排查清单

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_object=WeatherInfo) retry_parser = RetryOutputParser.from_llm(parser=parser, llm=llm) # 在链中使用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 v

4.3 性能考量：什么时候不该用结构化输出？

结构化输出不是银弹。在以下场景，你可能需要权衡：

1. 极简输出：如果输出只是一个单词或一个短句（例如情感分类“正面/负面”），使用StrOutputParser然后简单判断可能更快。
2. 流式传输优先：在需要逐字显示结果的聊天场景，结构化输出通常需要等待整个JSON对象生成完毕才能解析，会破坏流式体验。可以考虑先流式传输原始文本，或在客户端进行轻量解析。
3. 对延迟极度敏感：生成结构化指令会增加提示词的长度，理论上可能略微增加模型的思考时间（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( llm=llm, prompt=prompt, tools=tools, # 关键：这里LLM会使用我们定义的格式来输出其“思考” ) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) # 当用户输入“我想下周五从北京飞上海”时， # 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/RAGFlow：Dify和RAGFlow是更上层的无代码/低代码AI应用平台。它们提供了可视化界面来编排工作流、管理知识库。在底层，它们可能也使用了LangChain或类似的技术栈。如果你需要快速搭建一个标准化的RAG应用，用这些平台可能更快。但如果你需要深度定制逻辑、集成特殊的数据源或工具，或者你的应用逻辑非常复杂，那么直接使用LangChain（并掌握好格式化输出这类核心技能）会给你带来更大的灵活性和控制力。

最终的选择取决于你的需求：追求开发效率和标准化，可以考虑平台；追求灵活性和深度控制，则从LangChain入手，而格式化输出是你必须扎实掌握的第一个关键技能。它看似简单，却是连接AI的“智能”与程序的“逻辑”之间那座最重要的桥梁。