Agent 结构化输出

前面调用模型时，返回结果通常是一段自然语言。

但在 Agent 开发里，很多结果不是给人直接看的，而是要继续交给程序处理，比如：

• 提取用户资料
• 判断任务类型
• 生成工具参数
• 返回可保存的 JSON 数据

这时候就需要 Output Parser。

这一篇主要看这些内容：

JsonOutputParser
  -> PydanticOutputParser
  -> with_structured_output
  -> Parser / Tool / with_structured_output 的区别
  -> 什么时候需要 Output Parser
  -> 流式输出
  -> 非 JSON 格式

先记住一句话：Output Parser 的作用，是把模型返回的字符串解析成程序更好处理的数据。

为什么需要 Parser

最直接的想法是：在 Prompt 里要求模型返回 JSON，然后自己 json.loads()。

import json


question = (
    "请介绍一下勒布朗詹姆斯的信息。请以 JSON 格式返回，"
    "包含字段：name、birth_year、nationality、major_achievements。"
)

try:
    # 1. 先直接调用模型，拿到模型返回的文本
    response = model.invoke(question)
    print(response.content)

    # 2. 直接 json.loads 容易失败，因为模型可能返回 Markdown 代码块
    result = json.loads(response.content)
    print(result)
except Exception as error:
    print("解析失败:", error)

问题是，模型经常会返回 Markdown 代码块：

```json
{
  "name": "勒布朗·詹姆斯"
}
```

这对人很友好，但对 json.loads() 不友好。

Output Parser 解决的就是这类问题：

• 在 Prompt 里补充格式要求。
• 接收模型返回的原始文本。
• 解析出真正的对象。
• 遇到 Markdown JSON 代码块时，也能更稳地处理。

JsonOutputParser

JsonOutputParser 适合解析普通 JSON。

from langchain_core.output_parsers import JsonOutputParser


# 1. 创建一个 JSON parser
parser = JsonOutputParser()

# 2. 把 parser 的格式说明放进 prompt，让模型知道应该返回什么格式
question = f"""请介绍一下勒布朗詹姆斯的信息。
请以 JSON 格式返回，包含以下字段：
- name：姓名
- birth_year：出生年份
- nationality：国籍
- major_achievements：主要成就，数组

{parser.get_format_instructions()}"""

# 3. 调用模型，拿到原始文本
response = model.invoke(question)

# 4. 用 parser 把模型文本解析成对象
result = parser.parse(response.content)

print(result)

这段代码里有三个关键点：

• JsonOutputParser()：创建 JSON 解析器。
• get_format_instructions()：拿到一段格式说明，放进 Prompt。
• parse()：把模型返回的字符串解析成对象。

这里的重点不是 parse() 本身，而是 get_format_instructions()。

它会告诉模型尽量按可解析的 JSON 输出，减少自由发挥。

PydanticOutputParser

JsonOutputParser 只能说"我要 JSON"。

PydanticOutputParser 可以进一步说明"这个 JSON 长什么样"，并把结果解析成 Pydantic 对象。

from langchain_core.output_parsers import PydanticOutputParser
from pydantic import BaseModel, Field


class PlayerInfo(BaseModel):
    # Field 的 description 会进入格式说明，帮助模型理解字段含义
    name: str = Field(description="姓名")
    birth_year: int = Field(description="出生年份")
    nationality: str = Field(description="国籍")
    major_achievements: list[str] = Field(description="主要成就")


# 1. 根据 Pydantic 模型创建 parser
parser = PydanticOutputParser(pydantic_object=PlayerInfo)

# 2. 把格式说明放进 prompt
question = f"""请介绍一下勒布朗詹姆斯的信息。

{parser.get_format_instructions()}"""

# 3. 模型返回文本，parser 再解析成 Pydantic 对象
response = model.invoke(question)
result = parser.parse(response.content)

print(result)

这时候格式说明会比普通 JSON 要更明确，因为它要把字段名、字段类型和字段含义都告诉模型。

这段代码里：

• BaseModel 负责描述结构。
• Field(description=...) 负责给模型看的字段说明。
• PydanticOutputParser 负责生成格式说明并解析结果。

with_structured_output

常规结构化输出，更推荐优先用模型的 with_structured_output()。

from pydantic import BaseModel, Field


class PlayerInfo(BaseModel):
    # Pydantic 模型就是结构化输出的 schema
    name: str = Field(description="姓名")
    birth_year: int = Field(description="出生年份")
    nationality: str = Field(description="国籍")
    major_achievements: list[str] = Field(description="主要成就")


# 1. 让模型直接按 PlayerInfo 返回结构化对象
structured_model = model.with_structured_output(PlayerInfo)

# 2. 这里拿到的 result 已经是解析后的对象
result = structured_model.invoke("介绍一下勒布朗詹姆斯")

print(result)

with_structured_output() 的好处是：

• 写法更短。
• schema 和模型调用绑定在一起。
• 支持 tool calling 或 provider 原生结构化输出的模型通常会更稳定。

所以简单判断可以这样记：

常规结构化输出：优先 with_structured_output
需要手动控制 Prompt 或解析文本：使用 Output Parser

底层大概做了什么

with_structured_output() 可以理解成 LangChain 给常见结构化输出做的一层封装。

它不是简单地帮你调用 parser.parse()，而是会把 schema 交给模型适配层，让模型尽量按结构化方式返回结果。

不同模型底层策略不完全一样，常见路线是：

支持 provider 原生结构化输出：优先交给 provider 保证格式
支持 tool calling：把 schema 转成"工具参数"形式，让模型生成 tool call 参数
不支持这些能力：才可能退回到提示词约束 + parser 解析这类方式

所以它的定位是：

with_structured_output：把常见结构化输出封装起来

也就是你不用太关心底层到底是 provider 原生能力、tool calling，还是 parser 解析。

它的缺点

with_structured_output() 省事，但不是所有结构化场景都适合它。

主要缺点有几个：

• 它通常要等完整结构生成并解析之后，才返回一个可靠对象。
• 它不适合边生成边展示自然语言文本。
• 它主要面向 JSON / schema 这类结构化对象，不适合 XML、YAML、Markdown 表格这类自定义文本格式

简单说：如果只是拿结构化对象，with_structured_output() 最省事；如果你需要控制生成过程或解析过程，就回到 Output Parser。

如果你还想保留原始响应，可以使用支持 include_raw=True 的模型实现：

# include_raw=True 会同时保留原始消息和解析结果，适合调试
structured_model = model.with_structured_output(PlayerInfo, include_raw=True)
response = structured_model.invoke("介绍一下勒布朗詹姆斯")

print(response["raw"])
print(response["parsed"])
print(response["parsing_error"])

这适合调试结构化输出，因为你能同时看到：

• 模型原始消息。
• 解析后的对象。
• 解析错误。

什么时候需要 Output Parser

学 Output Parser 不是为了替代 with_structured_output()。

更准确地说：Output Parser 主要用在 with_structured_output() 实现不了，或者实现起来不舒服的场景。

常见有三类：

1. 需要实时展示文本，同时最后还要拿结构化对象。
2. 需要处理 XML、YAML、Markdown 表格等非标准 JSON 输出。
3. 已经拿到一段模型返回的文本，后续程序还需要把它提取成 JSON / 对象。

所以它的价值不在"更短"，而在"更可控"：

with_structured_output：直接拿最终结构化对象
Output Parser：先让模型生成文本，再由 parser 解析文本

流式输出

先看普通流式输出。

# 普通 stream 返回的是模型原始消息流
stream = model.stream("简单介绍勒布朗詹姆斯的信息。")

full_content = ""

for chunk in stream:
    # chunk.content 是本次流式返回的文本片段
    content = chunk.content or ""
    full_content += content

    # 边接收边输出，就能形成实时展示效果
    print(content, end="", flush=True)

model.stream() 返回的是原始消息流。

你可以边接收边展示，所以适合做"打字机效果"。

但如果使用 with_structured_output()：

# with_structured_output 返回的是结构化模型
structured_model = model.with_structured_output(PlayerInfo)

# 这里的 stream 不再适合作为逐字文本流来展示
stream = structured_model.stream("详细介绍勒布朗詹姆斯的信息。")

for chunk in stream:
    print(chunk)

看到的不是逐字文本，而是已经解析好的结构化对象。

原因是结构化输出通常要等模型生成完整参数并通过解析之后，才能给到一个可靠对象。

如果想要"边展示文本，最后再拿结构化对象"，可以用 parser：

from langchain_core.output_parsers import PydanticOutputParser
from pydantic import BaseModel, Field


class PlayerInfo(BaseModel):
    # 定义最终要解析出来的结构
    name: str = Field(description="姓名")
    birth_year: int = Field(description="出生年份")
    nationality: str = Field(description="国籍")
    occupation: str = Field(description="职业")


# 1. 根据结构创建 parser
parser = PydanticOutputParser(pydantic_object=PlayerInfo)

# 2. 格式说明仍然放进 prompt
prompt = f"""详细介绍勒布朗詹姆斯的信息。

{parser.get_format_instructions()}"""

# 3. 先按普通文本流接收模型输出
stream = model.stream(prompt)
full_content = ""

for chunk in stream:
    content = chunk.content or ""
    full_content += content
    print(content, end="", flush=True)

# 4. 文本收集完整后，再统一解析成结构化对象
result = parser.parse(full_content)
print(result)

这个流程是：

流式展示原始文本 -> 收集完整文本 -> parser.parse() 得到结构化对象

XML 转换

Output Parser 不只处理 JSON。

有些场景不是要模型直接返回 JSON 对象，而是要它先返回 XML 这类文本格式，再由解析器转成程序能处理的数据。

可以先用标准库写一个最小例子理解这个流程：

import xml.etree.ElementTree as ET


# 1. 让模型按 XML 格式输出
question = """请提取以下文本中的人物信息，并返回 XML：
阿尔伯特·爱因斯坦出生于 1879 年，是一位伟大的物理学家。

返回格式：
<person>
  <name>姓名</name>
  <birth_year>出生年份</birth_year>
  <occupation>职业</occupation>
</person>
"""

# 2. 模型返回 XML 文本
response = model.invoke(question)
xml_text = response.content

# 3. 标准库负责把 XML 文本解析成节点树
root = ET.fromstring(xml_text)

# 4. 再把节点树整理成程序更容易使用的 dict
result = {
    "name": root.findtext("name"),
    "birth_year": root.findtext("birth_year"),
    "occupation": root.findtext("occupation"),
}

print(result)

这段代码想表达的不是"以后都手写 XML 解析"，而是 Output Parser 的核心流程：

Prompt 约束模型输出 XML -> 模型返回 XML 文本 -> parser 把 XML 转成对象

在真实项目里，可以把 ET.fromstring() 这段解析逻辑封装成自己的 parser，让调用模型和解析结果的边界更清楚。

小结

这一篇要记住几个核心点：

1. JsonOutputParser 适合解析普通 JSON。
2. PydanticOutputParser 可以描述更明确的字段结构。
3. Pydantic schema 能让 Python 版结构更清楚。
4. 常规结构化输出优先考虑 with_structured_output()。
5. JsonOutputParser 可以用于流式解析部分 JSON。
6. Output Parser 也可以处理 XML 这类非 JSON 格式。