agent笔记（二）Langchain关键对象

LangChain 入门实战笔记：基于智谱AI GLM-4 快速上手

一、环境准备与初始化

1. 依赖安装（避坑版）

LangChain 迭代速度快，版本不兼容是高频报错根源，推荐使用以下命令安装全套稳定兼容的依赖，彻底解决版本冲突问题：

# 卸载所有冲突的旧版本包
pip uninstall -y langchain langchain-core langchain-community langchain-ollama langsmith
# 安装最新稳定版全套依赖
pip install --upgrade langchain langchain-core langchain-community pydantic zhipuai

安装完成后，必须重启 Python/Jupyter 内核，确保新安装的包生效。

2. 智谱AI 模型初始化

基于智谱AI GLM-4 模型完成 LangChain 大模型对象的初始化，后续所有调用均基于该对象实现：

import os
from langchain_community.chat_models import ChatZhipuAI

# 配置智谱AI API Key
key = "你的智谱AI API Key"
os.environ["ZHIPUAI_API_KEY"] = key

# 初始化大模型对象
chat = ChatZhipuAI(
    model="glm-4",
    temperature=0.5, # 生成文本的随机程度，取值0-1，值越小输出越确定，值越大输出越发散
)

二、核心组件1：提示词模板（Prompt 模板）

核心作用

提示词模板是 LangChain 体系中大模型调用的入口标准，核心解决原生大模型调用的核心痛点，是实现工程化复用的基础，核心价值如下：

1. 彻底解决提示词硬编码问题：将固定的提示词框架与动态变化的业务参数解耦，无需重复编写相同格式的提示词，仅通过变量替换即可实现不同场景的调用，大幅提升代码复用性。
2. 标准化输入，保障输出稳定性：统一大模型的输入格式，避免因人工编写提示词的格式、措辞差异，导致大模型输出结果波动，大幅提升大模型调用的可预期性。
3. 业务与提示词解耦，便于迭代优化：提示词可单独维护、批量调整，业务代码仅需负责传入业务参数，无需修改核心逻辑，适配企业级场景中提示词的持续调优需求。
4. 全生态兼容适配：作为 LangChain 全链路的标准输入组件，可无缝对接后续的链式调用、输出解析器、工具调用、检索增强等所有组件，是搭建复杂大模型应用的基础单元。

主要分类与核心用法

提示词模板主要分为两类基础用法，覆盖绝大多数业务场景。

1. 基础 PromptTemplate

适用于单轮、单角色的提示词场景，支持自定义变量填充，实现提示词的动态生成。

from langchain_core.prompts import PromptTemplate

# 1. 定义提示词模板，用{}包裹动态变量
template = "你是一个{role},请用{style}风格回答问题：{question}"

# 2. 从模板创建模板对象
prompt_template = PromptTemplate.from_template(template)

# 3. 变量填充，两种调用方式均可
# 方式1：format 方法，返回填充后的字符串
filled_prompt = prompt_template.format(
    role="数学老师", 
    style="通俗易懂", 
    question="勾股定理是什么？"
)
# 方式2：invoke 方法，返回LangChain标准PromptValue对象，适配新版调用规范
filled_prompt = prompt_template.invoke({
    "role": "数学老师", 
    "style": "通俗易懂", 
    "question": "勾股定理是什么？"
})

# 4. 调用大模型获取结果
ai_message = chat.invoke(filled_prompt)
# 打印大模型返回的文本内容
print(ai_message.content)

2. 对话式 ChatPromptTemplate

适用于多角色对话场景，可清晰区分系统提示词（system）、用户输入（human）、模型回复（ai）等角色，更贴合对话大模型的调用规范，是多轮对话、角色设定场景的首选方案。

from langchain_core.prompts import ChatPromptTemplate

# 1. 定义分角色的提示词模板
sys_template = "你是一个数学老师,请用{style}风格回答问题"
user_template = "请用通俗易懂的方式解释：{question}"

# 2. 创建对话模板对象，按角色拆分消息
prompt_template = ChatPromptTemplate.from_messages([
    ("system", sys_template),  # 系统提示词，定义模型的角色和行为
    ("human", user_template)   # 用户输入模板，承载用户的问题和动态变量
])

# 3. 变量填充并调用
filled_prompt = prompt_template.invoke({
    "style": "生动有趣", 
    "question": "勾股定理是什么？"
})

# 4. 调用大模型并输出结果
ai_message = chat.invoke(filled_prompt)
print(ai_message.content)

三、核心组件2：结构化输出解析器（格式化输出）

核心作用

格式化输出的核心载体是 LangChain 的输出解析器，它解决了大模型原生调用的核心痛点------大模型默认返回无结构的自然语言文本，无法直接被程序解析、入库和后续业务逻辑调用，是大模型能力落地到业务系统的关键桥梁，核心价值如下：

1. 实现自然语言到结构化数据的转换：强制大模型按照预设的字段、类型、格式返回内容，将自由文本转换为可被程序直接调用的字典、对象等结构化数据，打通大模型与业务系统的链路。
2. 内置格式容错与自动修复 ：相比原生的 json.loads 只能处理完美格式的JSON，LangChain 解析器可自动修复大模型输出的格式瑕疵（如多余的注释、markdown包裹、括号缺失、换行错误等），大幅降低线上报错率。
3. 严格的类型安全校验：基于 Pydantic 实现字段类型校验，可自动校验字段的类型、取值范围（如置信度必须是0-1的浮点数、年龄必须是正整数），避免脏数据进入后续业务流程。
4. 降低提示词编写成本：自动生成符合大模型理解逻辑的格式指令，无需手动编写复杂的格式要求提示词，同时保证不同大模型的兼容性，无需针对不同模型单独调整格式提示。
5. 无缝衔接业务全链路：解析后的结构化数据可直接写入数据库、调用第三方API、传入后续的大模型链路，无需额外做文本清洗、格式转换，大幅降低开发成本。

官方推荐方案：PydanticOutputParser

LangChain 新版已不推荐使用 StructuredOutputParser + ResponseSchema 方案，优先使用基于 Pydantic 数据模型的 PydanticOutputParser，稳定性更强、类型校验更严格、适配性更好。

核心实现步骤

1. 基于 Pydantic 的 BaseModel 定义输出数据结构，通过 Field 补充字段描述
2. 创建解析器对象，绑定预设的数据模型
3. 在提示词模板中注入格式指令，让大模型知晓输出规范
4. 串联提示词、大模型、解析器，完成端到端的结构化输出

实战场景1：信息提取

从自然语言文本中提取指定字段，转换为结构化对象：

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

# 1. 定义输出数据结构
class Person(BaseModel):
    name: str = Field(description="人的姓名")
    age: int = Field(description="人的年龄")

# 2. 创建解析器
parser = PydanticOutputParser(pydantic_object=Person)

# 3. 提示词模板，必须注入format_instructions格式指令
template = """
你是一个信息提取助手，从文本中提取信息，严格按照JSON格式返回。
文本：{input_text}
{format_instructions}
"""

# 4. 创建提示词对象，通过partial_variables预注入格式指令
prompt = PromptTemplate(
    template=template,
    input_variables=["input_text"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

# 5. 填充内容并调用大模型
input_text = "张三今年25岁。"
filled_prompt = prompt.format(input_text=input_text)
ai_message = chat.invoke(filled_prompt)

# 6. 解析大模型输出，得到结构化对象
parsed_output = parser.parse(ai_message.content)
print(parsed_output)
# 输出示例：name='张三' age=25

实战场景2：问答带置信度的结构化返回

实现问答能力的同时，强制返回答案和置信度两个核心字段，方便后续业务逻辑判断：

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

# 1. 定义输出数据结构
class MathAnswer(BaseModel):
    answer: str = Field(description="问题的答案")
    confidence: float = Field(description="答案的置信度，取值范围0到1之间")

# 2. 创建解析器
parser = PydanticOutputParser(pydantic_object=MathAnswer)

# 3. 提示词模板
template = """
你是一名数学老师，请用{style}风格回答问题。
问题：{question}
{format_instructions}
"""

# 4. 创建提示词对象
prompt = PromptTemplate(
    template=template,
    input_variables=["style", "question"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

# 5. LCEL 链式调用（替代废弃的LLMChain）
chain = prompt | chat | parser

# 6. 一键调用链，自动完成提示词填充、模型调用、结果解析
result = chain.invoke({
    "style": "生动有趣", 
    "question": "勾股定理是什么？"
})

# 7. 输出结构化结果
print("答案：", result.answer)
print("置信度：", result.confidence)

四、LangChain 新版核心语法：LCEL 链式调用

核心作用

LCEL（LangChain Expression Language）是 LangChain 新版官方强推的链式调用语法，完全替代了旧版的 LLMChain、SequentialChain 等链式对象，是搭建复杂大模型应用的核心骨架，核心价值如下：

1. 极简语法实现复杂链路 ：通过管道符 | 即可串联多个组件，前一个组件的输出自动作为后一个组件的输入，替代旧版数十行代码才能实现的链式逻辑，代码量大幅减少，可读性和可维护性极强。
2. 组件化解耦，灵活扩展：链路中的每个组件都是完全独立的，可随时替换、新增、删除组件（比如更换大模型、替换解析器、新增数据预处理/后处理逻辑），无需重构整条链路，适配业务快速迭代的需求。
3. 原生支持企业级工程化特性：开箱即用支持流式输出、异步调用、自动重试、超时控制、并行执行、分支逻辑，无需自己编写额外的代码实现这些工程化能力，大幅降低开发门槛。
4. 全链路可观测与调试：和 LangSmith 监控体系无缝衔接，可监控整条链路中每一个组件的输入输出、耗时、报错情况，快速定位线上问题，适配企业级应用的运维需求。
5. 统一的调用规范 ：无论链路多复杂，都支持统一的 invoke()（同步调用）、stream()（流式输出）、batch()（批量调用）、ainvoke()（异步调用）方法，学习成本极低，不同场景的代码风格完全统一。
6. 彻底解决旧版 Chain 的痛点 ：旧版 LLMChain 存在扩展性差、自定义难度高、不支持流式输出、组件耦合严重等问题，LCEL 完全重构了链路逻辑，是 LangChain 官方现在唯一推荐的链路实现方式。

核心语法

基础链式结构为 组件1 | 组件2 | 组件3，前一个组件的输出会作为后一个组件的输入，最常用的基础链路为：

提示词模板 | 大模型 | 输出解析器

• 提示词模板：接收用户输入的变量，生成标准化的提示词
• 大模型：接收提示词，生成对应的文本响应
• 输出解析器：接收大模型的响应，解析为预设的结构化对象

通过 invoke() 方法即可触发整条链路的执行，传入的参数会自动传递给提示词模板完成变量填充，无需手动分步处理。

五、高频踩坑避坑指南

1. 版本兼容问题

   禁止混合安装新旧版本的 LangChain 相关包，出现依赖冲突时，优先执行全量卸载后重新安装最新稳定版，安装完成后必须重启 Python 内核。

2. 导入路径错误（最高频报错）

   LangChain 大版本升级后，核心组件已全部迁移至 langchain_core 包，旧路径已废弃，核心正确导入路径如下：

   • 提示词模板：from langchain_core.prompts import PromptTemplate/ChatPromptTemplate
   • 结构化解析器：from langchain_core.output_parsers import PydanticOutputParser
     禁止使用 from langchain.prompts import xxx、from langchain.output_parsers import xxx 等旧路径。

3. 废弃API 问题

   • LLMChain 已完全废弃，必须使用 LCEL 链式调用替代
   • StructuredOutputParser + ResponseSchema 已不推荐使用，优先使用 PydanticOutputParser 实现结构化输出

4. 结构化输出解析失败

   必须在提示词模板中注入 {format_instructions} 格式指令，否则大模型无法知晓输出规范，会导致解析器解析失败；同时可降低 temperature 参数，提升大模型输出格式的稳定性。