转写说明

本文基于已校验的公开原文进行结构化转写与事实梳理，非原文转载。 转写保留可核验的技术事实，并将工程建议与来源观点明确分开。

核心结论

with_structured_output 是 LangChain 中连接大模型自然语言输出与下游业务代码结构化数据需求的桥梁。引入该机制主要解决三类问题：模型输出的客套话导致 JSON 解析失败、字段名与类型不稳定、关键字段缺失引发程序报错。

定义输出格式支持四种方式：Pydantic、TypedDict、JSON Schema、dataclass。其中 Pydantic 是实战首选，支持运行时强校验、报错信息精准、生态集成完善。TypedDict 仅提供代码提示，无任何强制校验能力。JSON Schema 是底层通信协议，手写成本极高。dataclass 在该场景下形同阉割版 Pydantic，缺乏校验且返回值仍为字典。

能力机制

with_structured_output 的核心流程是：开发者预先定义数据结构并传入方法，模型输出后由 Pydantic 或底层协议完成解析与校验。

在 Pydantic 模式下，Field(description="...") 用于向模型传达字段提取指令。可选字段使用 Optional 类型修饰。输出范围限制可通过 Literal 或继承 str 的 Enum 实现，两者底层均转化为 JSON Schema Enum 格式。嵌套结构通过嵌套 BaseModel 子类定义。校验规则如 min_length、gt、ge 等在模型返回不符合条件的数据时会抛出 ValidationError。

TypedDict 必须配合 Annotated 才能附加描述文本，且返回值为纯字典而非类实例，缺乏运行时拦截能力，不同模型对缺失必填字段的处理行为不一致。

include_raw=True 参数可在返回结构化对象的同时输出包含原始响应与 token 消耗信息的字典，用于开发调试。

快速开始

基础 Pydantic 模型定义流程：

1
2
3
4
5
6
7
8
9

from pydantic import BaseModel, Field

class Person(BaseModel):
    name: str = Field(description="姓名")
    age: int = Field(description="年龄")
    occupation: str = Field(description="职业")

structured_model = model.with_structured_output(Person)
result = structured_model.invoke("张三是一名30岁的软件工程师")

属性访问方式为 result.name，返回类型为 Person 类实例。列表提取需在子结构中定义 BaseModel 后以 List[Actor] 类型声明。校验失败时 invoke 方法会抛出 ValidationError。

适用边界

Pydantic 适用于绝大多数业务场景，是生产环境的默认选择。TypedDict 仅建议在阅读他人代码或文档时接触，实战项目应完全避免。JSON Schema 的合理用途仅限于低代码平台等需要在运行时动态拼接提取规则的极客场景，日常开发中禁止人工手写。dataclass 在该场景下不具备实用价值，与 Pydantic 相比无任何优势。

核验清单

Schema 定义是否全部使用 Pydantic BaseModel。Field description 是否为每个字段提供了清晰、具体的提取指令。可选字段是否正确标记为 Optional 而非使用模型凭空填补。Enum/Literal 的选择是否基于选项数量与复用范围评估。数值校验规则是否与业务合理性一致。包含 include_raw=True 的调试代码是否在正式发布前移除。

来源与核验

  • 原始文章
  • 页面事实以原始来源及其引用的官方资料为准；版本、星标和模型能力会随时间变化。
  • AI Stack 不公开抓取到的全文快照，只发布独立转写与来源入口。

站内链接

相关文章