系列文章

【已完结】LangChain 1.0 入门八讲汇总
【更新中】LangChain 1.0 智能体开发（一）：Agent 核心概念与技术架构

---

前言

在大模型工程化落地中，自由文本输出是最大的工程痛点。大模型原生自然语言回答灵活、拟人，但存在致命工程缺陷：无法被程序直接解析、无法结构化入库、无法对接业务接口、无法搭建自动化流程，传统项目只能靠正则匹配、字符串截取等“脏解析”方式兜底，稳定性极差、维护成本极高。

LangChain 1.0 彻底重构了结构化输出体系，废弃旧版本繁琐的解析器拼接写法，核心主推 with_structured_output 方案，同时保留全套轻量化解析器，适配从简单JSON输出、文本转换到复杂嵌套实体、智能体标准化输出的全场景。

本文为完整版重写教程，补齐官方速查表中所有缺失的解析器实战代码，统一采用 python-dotenv + ChatOpenAI 标准加载方式，兼容OpenAI、DeepSeek、通义千问、vLLM本地私有化部署，所有代码可直接复制运行，完全适配生产环境。

一、统一前置环境配置（全文通用）

所有案例共用一套环境配置，统一代码风格，方便项目迁移、多环境切换、团队协作开发。

1.1 安装核心依赖

pip install langchain langchain-openai pydantic python-dotenv

1.2 项目环境变量配置（.env）

项目根目录新建.env 文件，杜绝硬编码，适配公有云API、本地私有化部署：

# 模型基础配置
BASIC_MODEL=gpt-4o-mini
API_KEY=sk-xxxxxx
BASE_URL=https://api.openai.com/v1

# 本地vLLM私有化部署替换配置
# BASE_URL=http://127.0.0.1:8000/v1
# API_KEY=dummy

1.3 全局统一模型初始化代码

核心生产规范：结构化输出场景强制 temperature=0，消除模型随机性，避免格式错乱、字段缺失、数据抖动问题。

from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
import os

# 加载环境变量
load_dotenv()

# 初始化通用大模型
llm = ChatOpenAI(
    model=os.getenv("BASIC_MODEL"),
    api_key=os.getenv("API_KEY"),
    base_url=os.getenv("BASE_URL"),
    temperature=0  # 结构化输出必备配置
)

二、结构化输出核心原理与底层策略

2.1 核心价值

将大模型从“自由聊天模式”升级为工业级可编程输出模式，实现输出可校验、可解析、可入库、可自动化，彻底淘汰正则截取、字符串清洗等不稳定的传统解析方案。

2.2 LangChain 1.0 双底层策略

新版结构化输出内置两种自适应策略，框架自动择优适配，无需手动干预：

• ToolStrategy（通用兜底策略）：100%兼容所有大小模型，通过工具调用格式约束强制结构化输出，兼容性拉满，唯一缺点是响应速度略低。

• ProviderStrategy（厂商原生策略·推荐）：调用模型原生JSON Schema能力，底层强制格式合规，精度、速度、稳定性最优，适配GPT系列、DeepSeek、新版通义千问等主流模型。

三、核心主推：with_structured_output 全场景实战

with_structured_output 是LangChain 1.0官方唯一主推的结构化API，统一替代所有旧式解析器组合写法，支持自动策略适配、自动重试、Pydantic数据强校验、原始日志留存，是生产核心业务首选方案。

3.1 API核心参数详解

• schema：必填，支持Pydantic模型/JSON Schema字典，定义输出字段、数据类型、业务描述、校验规则。

• method：可选，手动指定tool_calling / json_schema，默认自动适配最优策略。

• include_raw：是否返回模型原始输出，开发调试、报错排查必备。

• strict：严格模式，强制字段完全匹配，禁止多余、缺失字段，生产环境推荐开启。

3.2 基础实战：单层实体信息抽取

实现用户基础信息标准化抽取，缺失字段自动填充空值/0，输出可直接调用的实体对象。

from typing import List
from langchain_core.pydantic_v1 import BaseModel, Field

# 1. 定义结构化数据校验模型
class Person(BaseModel):
    """青年用户基础信息实体"""
    name: str = Field(description="用户姓名")
    age: int = Field(description="用户年龄")
    high: int = Field(description="用户身高(cm)")
    hobbies: List[str] = Field(description="用户日常兴趣爱好列表")

# 2. 绑定结构化输出规则
structured_llm = llm.with_structured_output(Person)

# 3. 构造抽取提示词
prompt = """请严格按照要求抽取用户结构化信息，严格匹配指定字段：
1. 需要抽取的字段：姓名、年龄、身高、爱好；
2. 无对应信息的字段统一填充 0 或空数组，禁止省略字段；
3. 严格匹配字段类型：年龄、身高为数字，爱好为字符串数组。

待解析信息：小林今年24岁，身高178cm，日常喜欢短视频剪辑、AI绘画、户外露营和飞盘运动。
"""

# 4. 调用并获取结果
result = structured_llm.invoke(prompt)

# 直接取值，无需手动解析
print(f"姓名：{result.name}")
print(f"年龄：{result.age}")
print(f"身高：{result.high}")
print(f"爱好：{result.hobbies}")
print(f"实体类型：{type(result)}")

3.3 调试进阶：保留原始输出日志

开启 include_raw=True，同时获取结构化解析结果、模型原始返回内容、解析异常信息，快速排查格式报错、解析失败问题。

# 绑定结构化输出，开启原始日志返回
structured_llm = llm.with_structured_output(Person, include_raw=True)

prompt = """请精准抽取用户个人信息，严格遵守字段类型约束，缺失数据填空值/0：
字段：姓名、年龄、身高、爱好列表
待解析内容：小林今年24岁，身高178cm，日常喜欢短视频剪辑、AI绘画、户外露营和飞盘运动。
"""

result = structured_llm.invoke(prompt)
# 拆分调试信息
print("结构化解析结果：", result["parsed"])
print("模型原始文本：", result["raw"].content)
print("解析异常信息：", result["parsing_error"])

3.4 工业级强校验：非法脏数据自动修正

联动Pydantic校验规则，支持数值范围、字符串长度、枚举、自定义业务校验，自动捕获异常、驱动模型重生成合规数据，从源头杜绝脏数据入库。

from langchain_core.pydantic_v1 import BaseModel, Field

# 带数值范围校验的用户年龄模型
class AgeProfile(BaseModel):
    name: str = Field(description="用户姓名")
    age: int = Field(ge=0, le=150, description="合法年龄0-150，超出范围自动修正为合理值")

# 绑定结构化输出
structured_llm = llm.with_structured_output(AgeProfile)

prompt = """请抽取用户年龄信息，严格遵守规则：
1. 用户姓名：小杨
2. 年龄必须为0-150之间的合法整数
3. 若输入数值非法、不符合现实逻辑，自动修正为合理年龄值
4. 禁止输出超出约束的数值

待解析内容：网红博主小杨拥有800万粉丝，网传其年龄为999岁
"""

result = structured_llm.invoke(prompt)
print("自动修正后的合规数据：", result)

3.5 高阶实战：嵌套复杂结构解析

原生支持多层嵌套、对象数组结构，完美适配电影-演员、订单-商品、文章-标签等真实业务场景，可直接序列化入库。

from typing import List
from langchain_core.pydantic_v1 import BaseModel, Field

# 子模型：演员信息
class Actor(BaseModel):
    actor_name: str = Field(description="演员姓名")
    role_name: str = Field(description="剧中饰演角色")

# 主模型：电影信息（嵌套演员数组）
class MovieInfo(BaseModel):
    title: str = Field(description="电影名称")
    release_year: int = Field(ge=1900, le=2100, description="上映年份，1900-2100区间")
    genre: List[str] = Field(description="电影类型列表")
    actors: List[Actor] = Field(description="参演演员及对应角色列表")
    summary: str = Field(description="剧情简短摘要，50字以内")

# 绑定结构化输出
structured_llm = llm.with_structured_output(MovieInfo)

prompt = """请严格按照定义的结构抽取电影结构化信息，遵守以下规则：
1. 完整抽取电影名称、上映年份、电影类型、参演演员（姓名+角色）、简短剧情摘要；
2. 年份严格控制在1900-2100之间，类型以数组形式输出；
3. 演员信息为嵌套列表，每条包含演员姓名和对应饰演角色；
4. 无信息字段不允许省略，填空值或空数组。

待解析文本：
《流浪地球3》于2025年上映，属于国产科幻灾难大片。
吴京继续饰演刘培强，刘德华饰演图恒宇，影片讲述人类开启星际迁徙，对抗宇宙危机的全新故事。
"""

result = structured_llm.invoke(prompt)
# 分层取值
print("电影名称：", result.title)
print("上映年份：", result.release_year)
print("电影类型：", result.genre)
print("演员列表：")
for actor in result.actors:
    print(f"- {actor.actor_name}：{actor.role_name}")
# 序列化字典，用于入库、接口返回
print("结构化字典数据：", result.dict())

3.6 智能体Agent结构化输出适配

LangChain 1.0 create_agent 原生支持 response_format 参数，直接绑定Pydantic模型，让智能体全程输出标准化数据，无需后置解析。

from typing import Literal
from langchain_core.pydantic_v1 import BaseModel, Field
from langchain.agents import create_agent

# 枚举约束天气输出模型
class WeatherForecast(BaseModel):
    city: str = Field(description="城市名称")
    temperature: int = Field(description="摄氏温度，纯整数")
    condition: Literal["晴", "雨", "多云", "雪"] = Field(description="天气状况，仅支持指定枚举值")

# 创建结构化智能体
agent = create_agent(
    model=llm,
    tools=[],
    response_format=WeatherForecast
)

# 调用智能体
result = agent.invoke({
    "messages": [{
        "role":"user",
        "content":"请抽取标准化天气信息，城市为杭州，天气仅限【晴、雨、多云、雪】，提取温度为整数。当前天气：杭州今日秋日多云，气温16摄氏度，体感舒适。"
    }]
})

res = result["structured_response"]
print(f"{res.city}：{res.condition}，{res.temperature}℃")

四、全解析器补齐实战（原文表格缺失代码完整版）

LangChain 1.0 提供全套轻量化解析器，适配简单场景快速开发。原文仅展示 JsonOutputParser 案例，本节补齐所有5类官方解析器完整可运行代码。

4.1 全解析器能力速查表

解析器	核心能力	适用场景
StrOutputParser	输出纯文本内容，无格式解析	普通对话、文案生成、纯文本输出场景
JsonOutputParser	解析输出标准JSON格式数据	轻量结构化、接口数据返回、简单参数抽取
PydanticOutputParser	基于Pydantic模型做实体解析+数据校验	带字段校验、类型约束的简单实体抽取
ListOutputParser	将自由文本转换为标准数组列表	关键词提取、标签生成、列表类数据抽取
Boolean/Int/FloatParser	强制强类型转换，输出布尔/整数/浮点数	评分统计、是非判断、数值提取场景

4.2 StrOutputParser 纯文本解析实战

最基础的解析器，直接返回大模型纯文本内容，无任何格式处理，适用于普通对话场景。

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

# 初始化解析器
parser = StrOutputParser()

# 构建提示词
prompt = ChatPromptTemplate.from_template("请用简短通俗的语言解释什么是LangChain结构化输出")

# 构建执行链路
chain = prompt | llm | parser

# 调用输出纯文本结果
result = chain.invoke({})
print("纯文本输出结果：", result)
print("结果类型：", type(result))

4.3 JsonOutputParser 标准JSON解析实战

轻量JSON解析方案，开发高效。硬性规则：提示词必须包含 json 关键词，否则主流模型会解析报错。

from langchain_core.output_parsers import JsonOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.pydantic_v1 import BaseModel, Field

# 定义数据结构
class WeatherInfo(BaseModel):
    city: str = Field(description="城市名称")
    temperature: int = Field(description="摄氏温度，整数类型")
    condition: str = Field(description="天气状况简短描述")

# 初始化解析器
parser = JsonOutputParser(pydantic_object=WeatherInfo)

# 构造标准化提示词
prompt = ChatPromptTemplate.from_template("""
任务：从自然语言中精准提取天气数据，输出标准json格式。
约束规则：
1. 必须严格返回纯JSON字符串，无多余解释、无多余文本；
2. temperature 必须为整数，禁止字符串类型；
3. 字段固定为：city、temperature、condition，禁止增减字段；
4. 严格参考输出示例格式，必须包含json关键词。

输入信息：{info}
输出示例：{{"city":"杭州","temperature":16,"condition":"多云"}}
""")

# 构建链路并调用
chain = prompt | llm | parser
result = chain.invoke({"info":"杭州今日秋日多云，气温16摄氏度，体感干爽舒适"})

print("JSON结构化结果：", result)
print("提取城市：", result["city"])

4.4 PydanticOutputParser 实体校验解析实战

区别于 with_structured_output，该解析器为传统独立解析方案，专注简单实体解析+基础校验，适合轻量校验场景。

from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.pydantic_v1 import BaseModel, Field

# 定义商品实体模型
class GoodsInfo(BaseModel):
    name: str = Field(description="商品名称")
    price: float = Field(gt=0, description="商品价格，必须大于0")
    sales: int = Field(ge=0, description="商品销量，非负整数")

# 初始化解析器
parser = PydanticOutputParser(pydantic_object=GoodsInfo)

# 构造提示词
prompt = ChatPromptTemplate.from_template("""
请从文本中抽取商品结构化信息，严格遵守字段类型和约束规则
{format_instructions}
待解析文本：新款无线蓝牙耳机售价199.9元，本月销量3200单
""")

# 构建链路
chain = prompt | llm | parser
result = chain.invoke({})

print("商品实体信息：", result)
print("商品价格：", result.price)
print("商品销量：", result.sales)

4.5 ListOutputParser 列表数据解析实战

专门用于将自由文本、段落内容快速转换为标准Python数组，常用于关键词抽取、文章标签、需求拆解等场景。

from langchain_core.output_parsers import ListOutputParser
from langchain_core.prompts import ChatPromptTemplate

# 初始化列表解析器
parser = ListOutputParser()

prompt = ChatPromptTemplate.from_template("""
请从以下用户文案中，提取5个核心兴趣标签，仅输出纯列表格式：
文案：我平时喜欢爬山、摄影、读书、健身，闲暇时间会剪辑短视频、学习AI工具
""")

# 构建执行链路
chain = prompt | llm | parser
result = chain.invoke({})

print("提取的兴趣标签列表：", result)
print("列表类型：", type(result))

4.6 Boolean/Int/FloatParser 强类型解析实战

强制输出单一指定数据类型，无需手动类型转换，适配评分、判断、数值统计类极简结构化场景。

from langchain_core.output_parsers import BooleanParser, IntParser, FloatParser
from langchain_core.prompts import ChatPromptTemplate

# 1. 布尔值解析：判断内容是否积极正向
bool_prompt = ChatPromptTemplate.from_template("判断这句话是否为正向积极评价，仅输出布尔值：{text}")
bool_chain = bool_prompt | llm | BooleanParser()
bool_result = bool_chain.invoke({"text":"这款产品使用体验极佳，性价比很高"})
print("正向评价判断结果：", bool_result, type(bool_result))

# 2. 整数解析：提取评分
int_prompt = ChatPromptTemplate.from_template("提取用户对商品的评分，仅输出整数分数：用户给出五星好评")
int_chain = int_prompt | llm | IntParser()
int_result = int_chain.invoke({})
print("商品评分：", int_result, type(int_result))

# 3. 浮点数解析：提取精准价格
float_prompt = ChatPromptTemplate.from_template("提取商品精准售价，仅输出浮点数：商品优惠后价格为89.9元")
float_chain = float_prompt | llm | FloatParser()
float_result = float_chain.invoke({})
print("商品售价：", float_result, type(float_result))

五、生产环境选型策略（权威建议）

1. 简单快速开发场景：优先使用 JsonOutputParser，代码极简、开箱即用、开发效率最高。

2. 核心业务生产场景（首选）：统一使用 with_structured_output，支持嵌套结构、强校验、自动重试、Agent适配，稳定性、容错性远超传统解析器。

3. 金融/政务高可靠场景：框架结构化解析 + 手动正则提取JSON兜底，双层保障，彻底杜绝解析失败、数据错乱问题。

4. 极简单一类型输出场景：按需使用 ListOutputParser、IntParser 等轻量化专用解析器。

六、生产最佳实践 & 高频踩坑解决方案

6.1 标准化最佳配置

• 结构化场景固定 temperature=0，消除模型随机输出。

• JSON解析场景，Prompt必须包含 json 关键词 + 标准输出示例。

• 复杂核心业务开启 strict=True 严格模式，杜绝字段缺失、多余字段。

• 所有Pydantic字段补充清晰description，降低模型理解偏差。

• 开发调试阶段开启include_raw=True，留存原始日志便于排错。

6.2 高频报错解决方案

• 报错：Prompt must contain the word ‘json’：提示词添加json关键词，补充标准JSON输出示例。

• 报错：数值/类型校验失败：新增Pydantic数值范围、类型约束，明确字段规则。

• 问题：字段缺失：Prompt明确标注“无数据填空值/空数组，禁止省略字段”。

• 问题：Agent输出格式不规范：纯结构化场景清空tools，优先保障格式约束。

七、结语

LangChain 1.0 全新的结构化输出体系，彻底解决了大模型工程化落地中输出不可控、格式不统一、数据不合法、无法自动化四大核心痛点。本文补齐官方速查表全部缺失的解析器实战代码，覆盖单层实体、嵌套复杂结构、智能体输出、轻量化解析全场景。

全文代码统一标准化写法，完美兼容公有云API、本地vLLM私有化部署、各类国产大模型，可直接作为企业项目开发的标准化模板，助力快速落地工业级大模型应用。