理解LangChain的结构化输出

在现代 LLM 系统中，自然语言生成的自由文本虽然灵活，但对于自动化工作流、Agent 调度和工具调用而言，存在可靠性和可执行性不足的问题。
**结构化输出（Structured Output）**应运而生，它通过为 LLM 输出定义明确的数据结构，使生成内容可以被程序直接解析和使用，从而提升系统的稳定性、可维护性和可验证性。

本文将从原理、设计动机、实现方式、使用场景及工程实践等方面，对 LangChain 的结构化输出进行系统总结。

1. 概念与定义

结构化输出指的是：

将 LLM 的输出严格按照预定义的数据结构（Schema）生成，使其可被直接解析、验证和操作，而非返回非结构化的自由文本。

在 LangChain 中，结构化输出主要依赖以下类型体系：

• Pydantic Model：支持字段验证、默认值、嵌套结构和序列化
• TypedDict / Dataclass：轻量类型检查，适用于简单结构

示例：

frompydanticimportBaseModelclassUser(BaseModel):name:strage:int

LLM 的输出将被解析为：

User(name="John",age=25)

与自由文本相比：

"John is 25 years old"

• 类型明确
• 可直接用于程序逻辑
• 避免解析失败

2. 设计动机

2.1 自由文本的局限

• 解析脆弱：文本格式不统一，正则解析容易出错
• 逻辑执行困难：程序无法直接对文本进行条件判断或工具调用
• 系统验证缺失：无法自动校验数据完整性和类型

2.2 结构化输出的价值

1. 类型安全：LLM 输出与 Python 类型系统对齐
2. 程序可执行性：可直接作为函数参数、路由决策或 Agent 行为
3. 系统可靠性：支持 Schema 验证、自动修复和重试
4. 跨模块接口：LLM 输出成为系统组件间的统一接口

3. 实现机制

3.1 Schema 驱动生成

• Pydantic 模型或TypedDict作为 Schema
• LLM 在 Prompt 中被约束生成符合 Schema 的输出
• LangChain 内部提供structured output wrapper对 LLM 输出进行解析与验证

fromlangchain_openaiimportChatOpenAIfrompydanticimportBaseModelclassOrder(BaseModel):item:strquantity:intllm=ChatOpenAI(model="gpt-4o-mini")structured_llm=llm.with_structured_output(Order)result=structured_llm.invoke("I want 3 pizzas")print(result)# Order(item='pizzas', quantity=3)

3.2 自动验证与重试

• 输出不符合 Schema → 抛出 ValidationError
• LangChain 可自动重试生成，确保符合预期结构
• 可与工具调用、Agent Action 或工作流节点无缝集成

4. 典型使用场景

4.1 信息抽取（Information Extraction）

从非结构化文本中提取关键数据：

John Smith, 35, works at Google

结构化输出：

{"name":"John Smith","age":35,"company":"Google"}

应用：合同解析、医疗记录分析、简历处理

4.2 Agent 决策与路由

Agent 输出需要被系统解析成动作指令：

{"action":"search_docs","input":"LangGraph checkpoint"}

• Router 可根据action字段进行节点调度
• 避免自由文本解析错误，提高 Agent 稳定性

4.3 工具调用（Tool Calling）

LLM 输出直接映射到函数参数：

{"tool":"get_weather","arguments":{"city":"Boston"}}

• 可直接调用 Python 函数
• 支持多工具和多参数组合

4.4 工作流控制与状态管理

在 LangChain/ LangGraph 工作流中：

• LLM 输出可直接更新State
• State 可使用Pydantic Model / TypedDict类型保证结构化
• 使复杂工作流可预测、可恢复、可审计

5. 工程实践建议

1. 轻量 State：TypedDict + LLM 输出 → 快速执行
2. 复杂 State / 持久化：Pydantic Model → 自动验证 + Checkpoint
3. LLM 输出与 Schema 对齐：尽量让输出字段与系统字段一一对应
4. 统一接口：结构化输出成为系统间标准 API
5. 容错与重试：利用 ValidationError 捕获异常，保证可靠性

6. 对比分析

结论：Structured Output 不是简单的 JSON 格式，而是 LLM 与程序系统之间的接口规范。

7. 总结

• 结构化输出是 LLM 从文本生成器向数据生成器的进化
• 它解决了自由文本在程序化执行、工具调用、Agent 行为与工作流控制中的可靠性问题
• 在 LangChain 架构中，几乎所有关键能力（Agent、Tool Calling、Router、State 更新）都依赖结构化输出
• 推荐在工程实践中，将 LLM 输出与 Pydantic/TypedDict 对齐，保证系统可维护、可验证、可扩展

LangChain 的结构化输出不仅是数据格式问题，而是LLM 系统工程的核心设计原则，它定义了 LLM 与应用程序之间的接口契约。

# ============================================================ # Example 1: Structured Output # The LLM returns a structured object (SearchQuery) instead of plain text # This is useful when you need machine-readable, typed responses # ============================================================ # Schema for structured output from pprint import pprint from dotenv import load_dotenv import openai from pydantic import BaseModel, Field from langchain_openai import ChatOpenAI load_dotenv() llm = ChatOpenAI(model="gpt-5") class SearchQuery(BaseModel): search_query: str = Field(default="", description="Query that is optimized web search.") justification: str = Field( default="", description="Why this query is relevant to the user's request." ) # Augment the LLM with schema for structured output structured_llm = llm.with_structured_output(SearchQuery) # Invoke the augmented LLM output = structured_llm.invoke("How does Calcium CT score relate to high cholesterol?") print("\n" + "="*60) print("STRUCTURED OUTPUT RESULT:") print("="*60) print("Input: 'How does Calcium CT score relate to high cholesterol?'") print("-" * 60) print("Output (SearchQuery object):") pprint(output) print("="*60 + "\n") # ============================================================ # Example 2: Tool Calling # The LLM decides to call a function/tool based on user input # Useful for calculations, API calls, database queries, etc. # ============================================================ # Define a tool def multiply(a: int, b: int) -> int: """Multiply two numbers""" return a * b # Augment the LLM with tools llm_with_tools = llm.bind_tools([multiply]) # Invoke the LLM with input that triggers the tool call msg = llm_with_tools.invoke("What is 2 times 3?") # Get the tool call print("\n" + "="*60) print("TOOL CALLING RESULT:") print("="*60) print("Input: 'What is 2 times 3?'") print("-" * 60) print("LLM Response (contains tool call request):") pprint(msg) print("="*60 + "\n")