05 · 结构化输出：让模型交出”保证格式”的数据

本片目标：让模型不只输出文本，而是输出符合你定义的 schema 的对象——客服工单、抽取字段、分类结果。核心是 with_structured_output + Pydantic 蓝图。 新增规定性：5（输出契约：定义 BaseModel 蓝图，模型输出必须匹配） 数据字典：with_structured_output 参数、Pydantic 蓝图、method 三种模式。 进程线程模型：同 invoke（同步阻塞）。 网络模型：tool_calling 模式 = 模型走”工具调用”通道返回结构化 JSON（不是靠提示词”请输出 JSON”）。

1. 上集回顾

第 04 篇让模型输出文本和流式。但业务真正要的是结构化数据：

客服：从用户吐槽里抽出 intent、order_id、urgency；
RAG：回答完还要返回引用来源列表；
报表：输出字段名必须对，方便程序直接读。

靠提示词”请输出 JSON”是脆弱的：模型可能输出多余说明文字、字段名拼错、JSON 语法错。你需要一个契约——模型必须输出符合你定义结构的对象，格式错了框架就重试或报错。这就是 with_structured_output。

2. 数据字典：Pydantic 蓝图（规定性 5 的核心）

2.1 蓝图定义

from pydantic import BaseModel, Field

class SupportTicket(BaseModel):
    intent: str                              # 必填字段
    order_id: str | None = Field(default=None, description="订单号，没有则为 None")
    urgency: int = Field(description="紧急程度 1-5")

元素	类型	说明
`intent: str`	类型注解	必填字符串
`order_id: str	None = Field(default=None, …)`	可选字段	用 `Field(description=...)` 给模型提示
`urgency: int = Field(...)`	带描述必填	description 会进提示词，指导模型填值

关键：Pydantic 蓝图既是提示词的一部分（描述指导模型），又是输出校验器（解析结果必须符合）。

2.2 `with_structured_output` 签名

structured_model = model.with_structured_output(
    schema,              # Pydantic 类（或 TypedDict / JsonSchema dict）
    method="function_calling",   # 见下表
)
result = structured_model.invoke("我的订单 20260701001 一直没发货，很生气！")
# result: SupportTicket(intent='投诉', order_id='20260701001', urgency=5)

`method`	底层机制	适用
`"function_calling"`（默认）	把 schema 变成工具定义，模型”调用工具”返回 JSON	最稳，几乎所有模型支持
`"json_mode"`	强制模型输出合法 JSON	不支持工具调用的模型
`"json_schema"`	用 JSON Schema 约束（各家支持不一）	部分新模型

返回值：invoke 后直接返回 Pydantic 实例（不是 AIMessage！）。type(result) 就是你的蓝图类。

2.3 它内部是什么？（衔接 04 篇的 parser 家族）

with_structured_output 不是”魔法 API”——它内部就是一个模型 + 一个解析器组成的管道（实测源码确认）：

# with_structured_output 内部等价于：
llm = model.bind_tools([schema], tool_choice="any")      # ① 模型：按工具 schema 生成 JSON
output_parser = PydanticToolsParser(tools=[schema])       # ② 解析器：tool_calls → Pydantic 实例
return llm | output_parser                                # ③ 串成管道 → RunnableSequence

关键认知：这就是你在 04 篇学的 parser，只是”剥的壳”不同：

	04 篇 `StrOutputParser`	本篇 `PydanticToolsParser`
属于	`output_parsers` 模块	`output_parsers` 模块（同一家族）
剥什么壳	`AIMessage.content` → str	`tool_calls` → Pydantic 实例
共同祖先	`BaseOutputParser`	`BaseOutputParser`

04 篇说过”StrOutputParser 实现了通用接口 BaseOutputParser，以后自定义解析器只需实现 parse 方法”——PydanticToolsParser 就是这个家族里”最重”的成员。它把模型返回的 tool_calls（JSON）解析成你的蓝图对象。所以 with_structured_output 返回 RunnableSequence 而不是普通模型，就是因为它是 bind_tools 的模型 | PydanticToolsParser 两步管道。完整 parser 家族全景（StrOutputParser / JsonOutputParser / PydanticToolsParser 等）见第 13 篇全地图的 output_parsers 模块。

3. 关键方法

方法	签名	说明
`with_structured_output`	`with_structured_output(schema, method="function_calling", **kwargs) -> Runnable`	包一层，返回结构化版模型
`structured_model.invoke(input)`	`-> Pydantic 实例`	直接得对象
`structured_model.stream(input)`	`-> Iterator[AIMessageChunk]`	流式（部分模型支持）
`result.model_dump()`	`-> dict`	对象 → dict
`result.model_dump_json()`	`-> str`	对象 → JSON 字符串

3.1 嵌套蓝图：字段里带 `list`

蓝图可以嵌套——字段类型是 list[另一个蓝图]，框架递归解析。典型场景：一次返回”一批工单”：

class TicketList(BaseModel):
    tickets: list[SupportTicket] = Field(description="一批工单")

batch = model.with_structured_output(TicketList).invoke(
    "订单 20260701001 没发货（投诉，紧急）；订单 20260701002 想退货（退货，一般）。")
batch.tickets
# → [SupportTicket(intent='投诉', order_id='20260701001', urgency=5),
#    SupportTicket(intent='退货', order_id='20260701002', urgency=3)]

嵌套蓝图的用处：一次模型调用拿到”一批结构化结果”。第 09 篇 RAG 组装、第 15 篇完整后端项目会用这个能力返回”答案 + 引用来源列表”（list[str] 类型的 sources 字段）——那个蓝图结构在 05 篇你已经会写了，只是还没接上检索。

4. 进程线程模型

structured_model.invoke(...)
  ├─ 内部: 模型收到(原消息 + 工具定义[你的schema])
  ├─ 模型返回 tool_calls=[{name:'SupportTicket', args:{...}}]   ← 网络往返 1 次
  └─ 框架把 tool_calls[0].args 解析成 SupportTicket 实例       ← 纯内存

网络往返仍只有 1 次——结构化输出不是”先生成再校验重试”（除非解析失败）。它是一次调用，模型直接通过工具调用通道吐出 JSON。

5. 网络模型

invoke → POST .../v1/messages
  Body 里带 tools=[{...schema 转成的 JSON Schema 工具定义...}]
  模型响应 tool_calls=[{"name": "SupportTicket", "args": {"intent": "投诉", "order_id": "20260701001", "urgency": 5}}]

关键洞察：with_structured_output 底层用的是工具调用协议——模型被”要求调用一个返回 JSON 的工具”。这是各家模型厂商都稳定支持的能力，比”提示词里写请输出 JSON”可靠得多。

6. 验证：跑起来

配套代码 code/05_structured.py：

定义 SupportTicket 蓝图；
with_structured_output 包模型；
传一段吐槽，打印返回对象的类型、字段值、model_dump()；
对比普通 invoke 的字符串输出；
嵌套蓝图：一次返回一批工单。

cd enterprise-rag-course\code
python 05_structured.py

预期输出（节选，实测）：

===== 普通 invoke（自由文本） =====
你的订单 20260701001 已查到，正在加急处理...

===== with_structured_output（契约输出） =====
返回类型: <class '__main__.SupportTicket'>
intent  : 投诉
order_id: 20260701001
urgency : 4
model_dump(): {'intent': '投诉', 'order_id': '20260701001', 'urgency': 4}

===== 嵌套蓝图 =====
intent=投诉, order_id=20260701001, urgency=5
intent=退货, order_id=20260701002, urgency=3

7. 边界

字段越多越容易错——蓝图字段太多、描述不清时模型可能填错。保持字段少而清晰，description 写清楚。
method 选择：默认 function_calling 优先；你的模型不支持工具调用再降级 json_mode。
嵌套结构：蓝图可以嵌套（BaseModel 里有 list[AnotherModel]），框架递归解析。
枚举/校验：Pydantic 的 Field(ge=1, le=5) 等约束会在解析时校验，超出会报错。

8. 未完待续

现在”输入”（模板）和”输出”（解析/结构化）都齐了。但有一个致命问题第 01 篇就埋下了：模型没有记忆。

你：我叫小林。
模型：你好小林！
你：我叫什么名字？   ← 模型：？？？刚才你说过吗？

每次调用模型都是”金鱼脑”——不记得上次说了什么。怎么让对话连贯？这就是第 06 篇：记忆与会话。 → 06 · 记忆与会话

RAG 教程

小林学 LangChain

05 · 结构化输出：让模型交出"保证格式"的数据

05 · 结构化输出：让模型交出”保证格式”的数据

1. 上集回顾

2. 数据字典：Pydantic 蓝图（规定性 5 的核心）

2.1 蓝图定义

2.2 `with_structured_output` 签名

2.3 它内部是什么？（衔接 04 篇的 parser 家族）

3. 关键方法

3.1 嵌套蓝图：字段里带 `list`

4. 进程线程模型

5. 网络模型

6. 验证：跑起来

7. 边界

推荐资料（延伸阅读）

8. 未完待续

​05 · 结构化输出：让模型交出”保证格式”的数据

​1. 上集回顾

​2. 数据字典：Pydantic 蓝图（规定性 5 的核心）

​2.1 蓝图定义

​2.2 with_structured_output 签名

​2.3 它内部是什么？（衔接 04 篇的 parser 家族）

​3. 关键方法

​3.1 嵌套蓝图：字段里带 list

​4. 进程线程模型

​5. 网络模型

​6. 验证：跑起来

​7. 边界

​推荐资料（延伸阅读）

​8. 未完待续

05 · 结构化输出：让模型交出”保证格式”的数据

1. 上集回顾

2. 数据字典：Pydantic 蓝图（规定性 5 的核心）

2.1 蓝图定义

2.2 `with_structured_output` 签名

2.3 它内部是什么？（衔接 04 篇的 parser 家族）

3. 关键方法

3.1 嵌套蓝图：字段里带 `list`

4. 进程线程模型

5. 网络模型

6. 验证：跑起来

7. 边界

推荐资料（延伸阅读）

8. 未完待续