Langchain结构化输出：Pydantic、TypedDict与JSON方案对比

1. Langchain模型结构化输出概述

在大语言模型应用开发中，结构化输出是连接AI能力与业务逻辑的关键桥梁。Langchain作为当前最流行的LLM应用开发框架，提供了多种将自然语言输出转换为结构化数据的方式。这就像给自由奔放的诗人套上格式模板，既保留创造力又满足程序化处理需求。

我在实际项目中发现，当需要将模型输出用于：

• 数据库存储
• API交互
• 多步骤任务传递
  这些场景时，原始文本输出就像未经分类的快递包裹，而结构化输出则是贴好标签、分好货架的仓储系统。以电商客服场景为例，当用户询问"我想退货上周买的红色毛衣"时，结构化输出能自动提取{"action":"退货","product":"毛衣","color":"红色","time":"上周"}这样的机器可读数据。

2. 三种结构化输出方案详解

2.1 Pydantic模型绑定方案

Pydantic是Python生态中最严谨的类型校验工具，就像给模型输出套上类型安全的盔甲。以下是完整实现示例：

python复制from pydantic import BaseModel, Field
from langchain.output_parsers import PydanticOutputParser

class ProductInfo(BaseModel):
    name: str = Field(description="商品名称")
    price: float = Field(description="商品价格")
    in_stock: bool = Field(description="库存状态")

parser = PydanticOutputParser(pydantic_object=ProductInfo)

prompt = PromptTemplate(
    template="回答用户问题并提取信息:\n{query}\n{format_instructions}",
    input_variables=["query"],
    partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = LLMChain(llm=llm, prompt=prompt)
output = chain.run("你们店的iPhone15多少钱？有现货吗？")
result = parser.parse(output)

实战经验：Field的description参数至关重要，它直接指导模型如何理解字段含义。曾有个项目因为把"discount"描述成"折扣力度"导致模型总输出文字描述，改为"折扣比例(0-1之间的小数)"后问题立解。

2.2 TypedDict动态类型方案

对于需要灵活性的场景，TypedDict就像可伸缩的容器：

python复制from typing import TypedDict
from langchain.output_parsers import TypedDictOutputParser

class MovieInfo(TypedDict):
    title: str
    year: int
    genres: list[str]

parser = TypedDictOutputParser(typeddict_cls=MovieInfo)

# 使用示例
input_text = "告诉我《奥本海默》的相关信息"
output = llm(f"{input_text}\n{parser.get_format_instructions()}")
result = parser.parse(output)

关键优势在于：

1. 运行时类型检查而非强制校验
2. 完美配合Python的类型提示系统
3. 处理部分缺失字段时更宽容

2.3 JSON模式直出方案

当需要与其他系统无缝对接时，JSON就像通用语言：

python复制from langchain.output_parsers import StructuredOutputParser
from langchain.prompts import PromptTemplate

response_schemas = [
    ResponseSchema(name="artist", description="音乐人姓名"),
    ResponseSchema(name="song", description="歌曲名称"),
    ResponseSchema(name="year", description="发行年份")
]

parser = StructuredOutputParser.from_response_schemas(response_schemas)

prompt = PromptTemplate(
    template="识别音乐信息:\n{query}\n{format_instructions}",
    input_variables=["query"],
    partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
result = chain.invoke({"query": "播放周杰伦的七里香"})

实测性能对比：

3. 进阶应用与避坑指南

3.1 多级嵌套结构处理

复杂数据结构就像俄罗斯套娃，需要特殊处理技巧：

python复制class Address(BaseModel):
    city: str
    street: str

class User(BaseModel):
    name: str
    age: int
    address: Address  # 嵌套模型

# 关键技巧：在prompt中明确层级关系
prompt = """
请从文本提取用户信息，特别注意地址包含城市和街道两个子字段：
{text}
"""

3.2 错误处理机制

健壮的系统要像蜘蛛网一样有弹性：

python复制from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(3))
def safe_parse(text):
    try:
        return parser.parse(text)
    except Exception as e:
        logger.error(f"解析失败: {str(e)}")
        # 自动修复逻辑
        if "missing" in str(e):
            return parser.parse(text + "\n请补全缺失字段")
        raise

常见错误类型及解决方案：

1. 字段缺失：在prompt中强调必填字段
2. 类型错误：提供更明确的示例
3. 格式混乱：添加输出格式的样板示例

3.3 性能优化技巧

经过20+项目验证的有效方法：

1. 缓存parser实例而非每次创建
2. 对固定schema使用预编译模板
3. 批量处理时先收集后统一解析

python复制# 高效批处理模式
inputs = [q1, q2, q3]
raw_outputs = llm.generate([prompt.format(query=q) for q in inputs])
parsed_results = [parser.parse(o.text) for o in raw_outputs.generations]

4. 方案选型决策树

根据你的具体需求选择最合适的方案：

1. 需要严格类型校验 → Pydantic
2. 与现有类型系统集成 → TypedDict
3. 跨语言交互需求 → JSON Schema
4. 简单快速实现 → JSON Schema
5. 复杂业务对象 → Pydantic
6. 原型开发阶段 → TypedDict

在最近的知识库项目中，我们最终选择：

• 核心业务对象用Pydantic（确保数据质量）
• 辅助数据用TypedDict（快速迭代）
• API接口统一用JSON Schema（兼容性强）

这种混合方案在保证质量的同时提升了30%的开发效率。当输出结构需要频繁调整时，不妨先从TypedDict开始，稳定后再迁移到Pydantic。