目录一、前言二、Langchain 结构化输出介绍2.1 什么是结构化输出2.2 传统方式 vs 结构化输出2.3 结构化输出模式三、四种结构化输出格式使用3.1 Pydantic 使用3.1.1 基本使用3.1.2 设置枚举类型3.1.3 列表提取3.1.4 嵌套结构3.1.5 限制条件3.2 TypedDict3.2.1 什么是 TypedDict3.2.2 Annotated 使用3.2.3 嵌套结构3.3 JSON Schema3.4 dataclass3.5 获取结构化结果方式3.5.1 使用with_structured_output四、写在最后一、前言在使用Langchain 过程中为了更好的控制大模型结果的输入输出通常需要对参数进行严格的控制而主流的方式就是通过参数对象化的方式进行传递将大模型绑定对象化的参数后可以让输出结果更稳定更精确本篇将详细介绍下Langchain 中几种常用的结构化输出。二、Langchain 结构化输出介绍2.1什么是结构化输出LangChain的结构化输出Structured Output 指的是要求模型最终返回一个符合预定义结构的数据对象例如固定字段的JSON、Pydantic 模型、TypedDict而不再是无格式的自然语言文本。它的核心目标是把“ 自然语言回答 ”变成“ 程序可以稳定消费的数据 ”。比如让它输出成类似这样的结构{ title: 盗梦空间, year: 2010, director: 克里斯托弗·诺兰, rating: 9.3 }这样做的价值主要有三点更容易被代码处理下游系统可以直接读字段而不是再从自然语言里做解析。结果更稳定减少“模型说法变了但意思差不多”导致的解析失败。更适合工程化适用于表单抽取、分类、路由、调用工具参数生成、工作流状态传递等场景。2.2传统方式 vs 结构化输出1、传统的几种方式繁琐、不推荐# 1. 提示词要求JSON prompt 以JSON格式返回{name, age, occupation} response model.invoke(prompt)# 2. 手动解析 import json data json.loads(response.content)# 3. 手动验证类型 if not isinstance(data[age], int): raise ValueError(age must be int)# 4. 手动创建对象 person Person(**data2、结构化输出简洁# 一步到位 structured_llm model.with_structured_output(Person) person structured_llm.invoke(张三是一名 30 岁的软件工程师) # ✅ 自动解析、验证、创建对象为什么第2种结构化输出机制这么受欢迎在没有 Pydantic 等结构化方案之前开发者需要写大量的 Prompt 苦口婆心地求大模型“请返回 JSON不要带任何解释”然后自己写繁琐的 json.loads() 和 try...except 。而有了 Pydantic 等结构化方案结合 .with_structured_output() 之后Prompt 变干净了字段的 description 直接充当了 Prompt 的一部分。类型安全编辑器能自动补全代码运行前就能做类型检查。极其稳定依托大模型厂商底层的 JSON 模式输出错误率降到了极低。2.3 结构化输出模式目前LangChain 1.x 支持多种Schema与结构化输出方式Pydantic字段校验、描述、嵌套结构功能最丰富TypedDict轻量类型约束JSONSchema与前后端/跨语言接口最通用dataclass模型对象可以调用 with_structured_output() 绑定输出模式schema。只有 Pydantic 返回的是Schema类实例其余三种方式返回的都是 字典 也只有 Pydantic 在类型不匹配时会抛出异常。问题现在所有模型都支持“本章要讲解的结构化输出方式”吗大部分现代模型支持通过函数调用✅ OpenAI (gpt-4, gpt-3.5-turbo)✅ Anthropic (claude-3)✅ Groq (llama-3)❌ 某些旧模型不支持如果不支持LangChain 会回退到提示词 JSON 解析。三、四种结构化输出格式使用接下来通过案例演示下这四种结构化输出格式的使用。3.1Pydantic 使用Pydantic通过在运行时强制执行类型提示确保数据的正确性和一致性是生产场景下的首选。3.1.1 基本使用使用Pydantic需要满足的几个要素所有结构化输出的数据模型都必须继承 BaseModel使用 类型提示 。Pydantic 支持丰富的字段类型str 、int、float、List[xxx]、Optional[xxx]等使用 Field() 添加字段默认值和描述帮助 LLM 理解字段含义1大模型初始化from pydantic import BaseModel,Field from langchain_core.utils.function_calling import convert_to_openai_tool from rich import print as rprint from langchain_core.tools import tool from typing import Literal from dotenv import load_dotenv import os from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv (OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv (OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, )2定义 Pydantic 模型使用清晰的字段描述没有描述LLM 可能格式错误LangChain 会要求 LLM 的输出必须能填充这些字段from pydantic import BaseModel, Field class Person(BaseModel): 人物信息 name: str Field(description姓名) age: int Field(description年龄) occupation: str Field(description职业)3使用 with_structured_output 即可引导模型进行结构化输出Optional 标识参数可选default 给参数设置默认值from pydantic import BaseModel, Field class Person(BaseModel): 人物信息 name: str Field(description姓名) age: Optional[int] Field(description年龄,default10) occupation: str Field(description职业) # 创建结构化输出的 LLM structured_llm model.with_structured_output(Person) #模型调用 result structured_llm.invoke(张三是一名 30 岁的软件工程师) print(result) print(type(result)) # result 是 Person 实例 print(result.name) # 张三 print(result.age) # 30 print(result.occupation) # 软件工程师运行一下效果如下3.1.2 设置枚举类型在实际开发中可能需要对某些字段的取值范围进行限制那么如何限制字段的可选值此时可以使用枚举如下from enum import Enum class Priority(str, Enum): LOW 低 MEDIUM 中 HIGH 高 class Task(BaseModel): title: str priority: Priority # 只能是 LOW/MEDIUM/HIGH具体的使用案例import os from enum import Enum from typing import Optional from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from pydantic import BaseModel, Field # 定义你的优先级枚举类 class Priority(str, Enum): LOW 低 MEDIUM 中 HIGH 高 class CustomerInfo(BaseModel): 客户信息 name: str Field(description客户姓名) phone: str Field(description电话号码) email: Optional[str] Field(description邮箱) issue: str Field(description问题描述) urgency: Priority Field(description紧急程度) # 创建结构化输出的 LLM structured_llm model.with_structured_output(CustomerInfo) conversation 客服: 您好请问有什么可以帮助您 客户: 我是王小明电话 138-1234-5678我的订单一直没发货很着急 客服: 好的我帮您查一下 result structured_llm.invoke(f从以下客服对话中提取客户信息\n{conversation}) print(result) print(\n提取结果) print(f 客户: {result.name}) print(f 电话: {result.phone}) print(f 邮箱: {result.email or 未提供}) print(f 问题: {result.issue}) print(f 紧急程度: {result.urgency.value})补充如果嫌单独定义一个 Enum 类太麻烦也可以直接导入 typing 中的 Literal 直接在字段里把允许的值写死。class CustomerInfo(BaseModel): 客户信息 name: str Field(description客户姓名) phone: str Field(description电话号码) email: Optional[str] Field(description邮箱) issue: str Field(description问题描述) # urgency: Priority Field(description紧急程度) urgency: Literal[低,中,高] Field(description紧急程度)3.1.3 列表提取如果一段信息中可能是多个数据就可以使用列表来定义import os from enum import Enum from typing import Optional from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter from typing import Optional, Literal # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from pydantic import BaseModel, Field from typing import List class Person(BaseModel): 人物信息 name: str age: int class PersonList(BaseModel): 人物列表信息 people: List[Person] # 多个 Person 对象 structured_llm model.with_structured_output(PersonList) result structured_llm.invoke(张三 30岁李四 25岁) print(result)3.1.4 嵌套结构在一个类型中还嵌套了其他类型此时就可以使用嵌套结构import os from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from pydantic import BaseModel class Address(BaseModel): 地点描述 city: str district: str class Company(BaseModel): 公司信息 name: str address: Address structured_llm model.with_structured_output(Company) result structured_llm.invoke(阿里巴巴在杭州滨江区) print(result)运行一下结果如下注意LLM 能力有限复杂嵌套结构可能会出错。所以建议嵌套层级 ≤ 3 层使用清晰的 description必要时拆分成多个调用如下是一个嵌套带列表的完整调用示例from pydantic import BaseModel,Field from langchain_core.utils.function_calling import convert_to_openai_tool from rich import print as rprint from langchain_core.tools import tool from typing import Literal, Optional,List from dotenv import load_dotenv import os from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from pydantic import BaseModel class Aspect(BaseModel): 评论维度 name: str Field(description维度名称如质量、价格、服务) score: int Field(description评分1-5) comment: str Field(description具体评价) class ProductReview(BaseModel): 产品评论分析 overall_sentiment: str Field(description整体情感positive/negative/neutral) overall_score: int Field(description综合评分1-5) aspects: List[Aspect] Field(description各维度评价) summary: str Field(description一句话总结) # 创建结构化模型 structured_model model.with_structured_output(ProductReview) review_text 这款笔记本电脑性能非常强大运行大型软件毫无压力。 屏幕色彩鲜艳看视频很舒服。 不过价格有点贵而且风扇噪音较大。 客服态度很好物流也快。 总体来说还是值得购买的。 result structured_model.invoke( f分析以下产品评论\n{review_text} ) print(f整体情感: {result.overall_sentiment}) print(f综合评分: {result.overall_score}/5) print(f\n各维度评价:) for aspect in result.aspects: print(f - {aspect.name}: {aspect.score}/5 - {aspect.comment}) print(f\n总结: {result.summary})3.1.5 限制条件即限制结构化对象中的某些参数的取值范围比如限制邮箱格式限制字符串的长度等from pydantic import BaseModel,Field from langchain_core.utils.function_calling import convert_to_openai_tool from rich import print as rprint from langchain_core.tools import tool from typing import Literal, Optional,List from dotenv import load_dotenv import os from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from pydantic import BaseModel class Product(BaseModel): 产品信息严格验证 name: str Field(description产品名称字符串类型, min_length2) price: float Field(description价格数字类型, gt0) stock: int Field(description库存整数类型, ge0) structured_llm model.with_structured_output(Product) response structured_llm.invoke(华为mate 80 promax 价格是-7999当前库存-100) print(response)3.2TypedDict3.2.1什么是 TypedDictTypedDict 是 Python 3.8 引入的一种类型提示工具即带有类型声明的字典结构。适合需要快速定义字典结构且无需 Pydantic 重量级功能的场景。普通的dict 没有类型消息{ title: 盗梦空间, year: 2010, director: 克里斯托弗·诺兰, rating: 9.3 }而TypedDict 可以进一步说明这个字典应该有哪些字段每个字段的类型是什么TypedDict 主要是类型声明不是运行时强校验器。如下基本使用示例实例化字典时给出的字段名称和TypedDict不完全一致此时IDE的静态类型检查会标记from typing_extensions import TypedDict class MovieDict(TypedDict): title: str year: int director: str rating: float movie: MovieDict { title1: 盗梦空间, year: 2010, director: 克里斯托弗·诺兰, rating: 8.8, } print(movie)3.2.2Annotated 使用Annotated 用来在“类型”之外再附加一些额外信息即元数据。类似于 Pydantic 的 Field 。基本形式如下Annotated[类型, 附加信息1, 附加信息2, ...]如下完整的使用案例from pydantic import BaseModel,Field from langchain_core.utils.function_calling import convert_to_openai_tool from rich import print as rprint from langchain_core.tools import tool from typing import Literal, Optional from dotenv import load_dotenv import os from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv (OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv (OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) 使用 TypedDict 模型定义结构化输出 from typing_extensions import TypedDict, Annotated class MovieTypedDict(TypedDict): 电影的详细信息 title: Annotated[str, 电影的正式名称例如《盗梦空间》] year: Annotated[int, 电影的公映年份使用四位数字表示] director: Annotated[str, 电影导演的全名] rating: Annotated[float, 电影在10分制下的评分可包含一位小数] # 设置模型结构化输出 structured_llm model.with_structured_output(MovieTypedDict) # 调用模型并获取结构化输出 response structured_llm.invoke(给我介绍下电影《星际穿越》) print(type(response)) print(response)3.2.3 嵌套结构在一个TypedDict修饰的类中再嵌套另一个类import os from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv (OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv (OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from typing import TypedDict, List, Annotated # 使用TypedDict定义嵌套结构 class Actor(TypedDict): 演员情况 name: Annotated[str, 演员姓名] role: Annotated[str, 饰演的角色] class Movie(TypedDict): 电影情况 title: Annotated[str, 电影标题] year: Annotated[int, 上映年份] director: Annotated[str, 导演] cast: Annotated[List[Actor], 演员列表] # 嵌套列表定义 rating: Annotated[float, 评分] # 设置模型结构化输出 structured_llm model.with_structured_output(Movie) # 调用模型并获取结构化输出 resp structured_llm.invoke(给我介绍下电影《盗梦空间》) # 访问嵌套数据 print(f电影名: {resp[title]}) print(f上映年份: {resp[year]}) print(f导演: {resp[director]}) print(f演员列表:{resp[cast]}) print(f评分: {resp[rating]})3.3JSONSchema这种方式需要按照JSON Schema规范拼接JSON字符串比较繁琐并且缺少校验机制。在实际开发中不推荐。import os from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) json_schema { title: Movie, description: A movie with details, type: object, properties: { title: { type: string, description: The title of the movie }, year: { type: integer, description: The year the movie was released }, director: { type: string, description: The director of the movie }, rating: { type: number, description: The movies rating out of 10 }, required: [title, year, director, rating] } } structured_model model.with_structured_output( json_schema, methodjson_schema ) response structured_model.invoke(给出盗梦空间的信息) print(response) print(type(response))3.4dataclassdataclass是 Python 标准库 dataclasses 提供的类装饰器用于简化“以字段为核心”的数据类定义。给类加上 dataclass 后Python 会根据字段声明自动生成常用方法例如__init____repr____eq__因此从对象行为上看 dataclass 创建的类常常 近似于 手写这些方法的普通类。from dataclasses import dataclass dataclass class Movie: title: str year: int director: str rating: float这种写法的好处是让“数据结构定义”更简洁、更清虽然 dataclass 在行为上接近于手写 init 、 repr 、 eq 的普通类但二者并不完全等价。 dataclass 修饰后的类仍然是普通的python类但它会被标准库标记为数据类并携带dataclass的字段元信息手写 init 等方法的普通类不能替代dataclass修饰的类。前者可以作为Langchain的Schema而后者不行。下面看一个完整的示例import os from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from dataclasses import dataclass from pydantic import Field dataclass class Movie(): 电影的详细信息 title: str Field(description电影标题) year: int Field(description电影上映年份) director: str Field(description导演) rating: float Field(description电影评分满分十分) structured_model model.with_structured_output(Movie) response structured_model.invoke(给出盗梦空间的信息) print(response) print(type(response))3.5获取结构化结果方式以上定义输出结构的四种模式中我们都是通过调用“with_structured_output”来获取结构化输出结果除了这种方式外还可以通过使用输出解释器来获取结构化输出结果。下面介绍这两种获取结构化结果的方式。3.5.1使用with_structured_output这种方式是 最新 、 最简洁 的API直接让模型“理解”你需要的数据结构并返回解析好的对象。此外我们可以在with_structured_output方法中传入 include_rawTrue 参数表示返回解析前的 原始AIMessage 从而访问令牌用量等元数据。import os from dotenv import load_dotenv from langchain_openrouter import ChatOpenRouter from pydantic import Field # 1、加载配置文件 load_dotenv(overrideTrue) OPENROUTER_API_KEY os.getenv(OPENROUTER_API_KEY) OPENROUTER_API_BASE os.getenv(OPENROUTER_API_BASE) # 2、模型初始化 model ChatOpenRouter( modeldeepseek/deepseek-v3.2, api_keyOPENROUTER_API_KEY, base_urlOPENROUTER_API_BASE, ) from pydantic import BaseModel class Product(BaseModel): 产品信息严格验证 name: str Field(description产品名称字符串类型, min_length2) price: float Field(description价格数字类型, gt0) stock: int Field(description库存整数类型, ge0) structured_llm model.with_structured_output(Product) response structured_llm.invoke(华为mate 80 promax 价格是-7999当前库存-100) print(response)如果设置了include_rawTrue在输出结果中会把AIMessage输出model_with_structure model.with_structured_output(Movie,include_rawTrue四、写在最后本文通过较大的篇幅详细介绍了Langchain 中结构化输出的几种方式希望对看到的同学有用哦本篇到此结束感谢观看。