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(低规格模型) |