跳转到主要内容

LangChain

07 · 输出解析器与结构化输出

拿到结构化数据的三条路线

  • LangChain
  • Python

本节速览

这一节的每一块内容,分别是干什么的:

内容是干什么的
StrOutputParser从 AIMessage 里取出纯文本
with_structured_output按 pydantic 模型直接拿结构化对象(首选)
PydanticOutputParser完全控制注入模型的格式指令文本
CommaSeparatedListOutputParser输出逗号分隔的字符串列表
OutputFixingParser模型输出不合格式时,让模型自己修复

模型返回的 AIMessage 不能直接给程序用。OutputParser 承担两个职责:一是把返回对象解析为程序需要的类型(字符串、对象、列表);二是部分 Parser 内置格式指令,注入 prompt 引导模型按指定格式输出。

StrOutputParser:提取文本

没有它会怎样——链的输出是 AIMessage 对象,直接 print 给用户看的是一串 content='...' additional_kwargs={...};存库、返给前端都得再剥一层。

有了它——管道末端接上它,出来的就是纯字符串,拿来就用。

最简单的 Parser,提取 content 为纯字符串:

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_core.output_parsers import StrOutputParser   # 提取纯文本

load_dotenv()

llm = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

chain = llm.pipe(StrOutputParser())
chain.invoke("讲一个笑话")   # 返回 str,不再是 AIMessage

with_structured_output:结构化输出首选

没有它会怎样——prompt 里写「请输出 JSON」,拿到的常是带 ```json 围栏的字符串;json.loads 一把梭,遇到字段缺失、类型不对当场抛异常,一天崩几回。

有了它——定义 pydantic 模型,出来直接是类型安全的对象,少一个字段、错一个类型当场报清楚。

只求稳定拿到结构化数据时,用模型的原生结构化输出能力。with_structured_output(schema) 直接接收 pydantic 模型类,返回一个「输出经 schema 校验对象」的 Runnable:

import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from pydantic import BaseModel, Field   # 数据模型与字段描述
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

class AnswerWithConfidence(BaseModel):
    answer: str = Field(description="用户问题的答案")
    confidence: int = Field(description="问题答案的可信度评分,满分 100", ge=0, le=100)

model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

structured_model = model.with_structured_output(AnswerWithConfidence)

res = structured_model.invoke("蒙娜丽莎的作者是谁?是什么时候绘制的")
print(res)
# AnswerWithConfidence(answer='蒙娜丽莎的作者是达芬奇……', confidence=95)

要点:

  • schema 由提供方 API 与 LangChain 共同校验,不需要手写格式指令。
  • Field(description=...) 的描述会进入 schema,写得越清楚返回越符合预期。
  • 类型注解与约束直接生效:int 是数字,ge=0, le=100 限范围,int | None 允许缺失。
  • 需要原始 AIMessage(拿 token 用量)时传 include_raw=True,输出变为 {"raw": ..., "parsed": ...}。

include_raw=True 的用法:

import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
from pydantic import BaseModel, Field   # 数据模型与字段描述

load_dotenv()

model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

class AnswerWithConfidence(BaseModel):
    answer: str = Field(description="用户问题的答案")
    confidence: int = Field(description="问题答案的可信度评分,满分 100", ge=0, le=100)

structured_model = model.with_structured_output(AnswerWithConfidence, include_raw=True)

res = structured_model.invoke("蒙娜丽莎的作者是谁?")
print(res["parsed"])   # AnswerWithConfidence(answer='……', confidence=95)
print(res["raw"].usage_metadata)   # 这条调用的 token 用量,做成本统计用

打标签和关系提取是同一模式的两类应用。枚举字段用 Literal 锁死取值:

from typing import Literal   # 枚举类型注解
from pydantic import BaseModel, Field   # 数据模型与字段描述


class Tagging(BaseModel):
    emotion: Literal["pos", "neg", "neutral"] = Field(description="文本的情感")
    language: str = Field(description="文本的核心语言(ISO 639-1 代码)")

提取嵌套关系时,防幻觉靠两层:schema 层把可能缺失的字段设为 int | None,prompt 层写明「没有明确提供就不要猜测,可以只提取部分信息」。完整例子:

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from pydantic import BaseModel, Field   # 数据模型与字段描述

load_dotenv()

llm = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

class Person(BaseModel):
    """提取关于一个人的信息"""

    name: str = Field(description="人的名字")
    age: int | None = Field(default=None, description="人的年龄")

class Relation(BaseModel):
    people: list[Person] = Field(description="提取所有人")
    relation: str = Field(description="人之间的关系,尽量简洁")

extractor = llm.with_structured_output(Relation)

print(extractor.invoke("小明现在 18 岁了,她妈妈是小丽"))
# Relation(
#   people=[Person(name='小明', age=18), Person(name='小丽')],
#   relation='小丽是小明的妈妈',
# )   # 小丽的年龄原文没给 → 字段缺失,而不是编一个数字

PydanticOutputParser:完全控制指令文本

没有它会怎样——with_structured_output 的格式指令是框架内部生成的黑盒,你要中文字段说明、嵌套结构、特殊枚举,它插不进你的话术。

有了它——get_format_instructions() 把格式指令拿在手里,prompt 想怎么写怎么写,格式描述和业务上下文融为一体。

需要自己控制注入 prompt 的格式指令时用这条路线。pydantic 模型定义结构,get_format_instructions() 生成指令文本,作为变量注入模板:

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from pydantic import BaseModel, Field   # 数据模型与字段描述
from langchain_core.output_parsers import PydanticOutputParser   # 按 pydantic 模型解析输出
from langchain_core.prompts import PromptTemplate   # 字符串模板

load_dotenv()

llm = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

class AnswerWithConfidence(BaseModel):
    answer: str = Field(description="用户问题的答案")
    confidence: int = Field(description="问题答案的可信度评分,满分 100", ge=0, le=100)

parser = PydanticOutputParser(pydantic_object=AnswerWithConfidence)

prompt = PromptTemplate.from_template(
    "尽可能的回答用户的问题\n{instructions}\n{question}"
)

chain = prompt.pipe(llm).pipe(parser)

res = chain.invoke({
    "question": "蒙娜丽莎的作者是谁?",
    "instructions": parser.get_format_instructions(),
})
# AnswerWithConfidence(answer='……', confidence=100)

格式指令由三部分构成:格式声明(要求输出符合 JSON Schema 的 JSON 实例)、few-shot 正反例、实际 schema。pydantic 的类型与约束会转换为 JSON Schema:int 变 "type":"integer",ge=0, le=100 变 "minimum":0, "maximum":100。解析阶段用 pydantic 校验,类型不符或超范围抛 ValidationError。

CommaSeparatedListOutputParser:列表输出

没有它会怎样——让模型「列几个关键词」,它热情地回你一段带序号和解释的小作文,程序切都切不开。

有了它——专用 parser 注入「逗号分隔」指令并解析,出来直接是 list[str]。

输出格式简单时选简单的 Parser。要求模型输出逗号分隔的列表,解析为字符串列表:

from langchain_openai import ChatOpenAI   # OpenAI 聊天模型
import os   # 读取环境变量
from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_core.output_parsers import CommaSeparatedListOutputParser   # 解析逗号分隔列表
from langchain_core.prompts import ChatPromptTemplate   # 带角色的消息模板

load_dotenv()

llm = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)

parser = CommaSeparatedListOutputParser()
# parser.get_format_instructions() 返回的就是这句英文指令:
# Your response should be a list of comma separated values, eg: `foo, bar, baz` ...

prompt = ChatPromptTemplate.from_messages([
    ("human", "列出 3 家科技巨头公司的名字。\n{format_instructions}"),   # ← 占位符
]).partial(format_instructions=parser.get_format_instructions())        # ← 指令注入这里

chain = prompt.pipe(llm).pipe(parser)

result = chain.invoke({})   # ← 点火
print(result)
# ['苹果', '谷歌', '微软']

关键一步:{format_instructions} 占位符 + .partial() 注入。少了这一步,模型根本不知道要按逗号分隔输出——parser 只负责「解析」,格式指令要靠你亲手送进 prompt。

OutputFixingParser:格式出错时修复

没有它会怎样——模型偶尔多打个逗号、少个引号,json.loads 当场炸、整条链中断;用户重试一次它可能又好了——最烦人的偶发故障。

有了它——解析失败自动把错误信息和原文喂回模型让它自己改,把偶发崩溃变成偶尔多等一秒。

格式解析失败时,让模型重跑整条链通常还会错。OutputFixingParser 把格式指令和报错信息交给一个 LLM,只修复输出本身:

import json   # 序列化演示数据

from pydantic import BaseModel, Field   # 数据模型与字段描述
from langchain_classic.output_parsers import OutputFixingParser   # 需 pip install langchain-classic
from langchain_core.output_parsers import PydanticOutputParser   # 按模型解析输出
import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)


class Flower(BaseModel):
    name: str = Field(description="花名")
    price: int = Field(description="价格,整数元")


parser = PydanticOutputParser(pydantic_object=Flower)

# price 是字符串——类型不对,直接 parse 必失败,正好演示修复
wrong_output = {"name": "玫瑰", "price": "9"}

# 先看直接解析的下场:当场抛 ValidationError
try:
    parser.parse(json.dumps(wrong_output, ensure_ascii=False))   # ← 直接翻车
except Exception as e:
    print("直接解析失败:", e)
    # 直接解析失败: Input should be a valid integer, unable to parse string as an integer ...

fix_parser = OutputFixingParser.from_llm(model, parser)

output = fix_parser.parse(json.dumps(wrong_output, ensure_ascii=False))

print(output)
# Flower(name='玫瑰', price=9)   ← 模型把 "9" 修成了整数 9

使用要点:

  • 修复只针对格式,不针对语义。超范围的值会被改成约束内的合法值,那是编造,不是真实评分。
  • 不要把原始问题一起交给 fix_parser,否则失去「一次低成本调用」的成本优势。
  • fixer 用低规格模型即可,格式修复不需要强模型能力。
  • 1.x 中该类位于 langchain-classic,官方主推 with_structured_output,从源头减少格式错误。

选型

场景用法
只要纯文本StrOutputParser
要稳定的结构化数据with_structured_output(schema)
要完全控制格式指令文本PydanticOutputParser + {instructions} 注入
格式偶尔出错,需要兜底修复OutputFixingParser.from_llm(低规格模型)

上一节:Prompt 模板 · 下一节:RAG 原理