LangChain 与 LangGraph 基础
摘要
LangChain 提供组织模型调用、提示、消息、工具和检索流程的组件;LangGraph 以状态、节点和边表达可循环、可恢复的流程。两个项目的 API 会随版本变化,学习时先看当前项目锁定版本,再对照官方文档,不要把旧课件代码直接当成最新写法。
正文
1. LangChain 的组成
- 模型:封装聊天模型或文本模型的调用。
- 消息:区分 system、human 和 assistant 等角色。
- 提示模板:将固定指令与动态变量组合。
- Runnable 与组合流程:把提示、模型、解析器等步骤串联。
- 输出解析:把模型文本变成可检查的结构。
- Retriever:从外部知识源找相关片段。
- Tool:把受控应用函数暴露为模型可请求的操作。
- 观测工具:查看链路、耗时、错误和评测结果。
重要原则:模型输出需解析和校验;外部工具的副作用不能由未经检查的模型参数直接触发。
2. RAG 应用中的框架位置
文档加载、文本切分、Embedding、向量存储、检索、重排和生成是可替换组件。应用要清楚保存来源元数据,并把权限过滤放在数据访问层。框架减少胶水代码,不会自动解决数据质量、授权、评估或安全问题。
3. LangGraph 的状态图
图由 State(共享状态)、Node(处理逻辑)和 Edge(控制流)构成。节点读取状态并返回更新;普通边表达固定顺序,条件边根据状态选择分支,循环表达重复决策。复杂流程还可能需要并行汇聚、子图和递归限制。
构建时明确状态字段及更新规则、节点何时执行、正常结束和失败如何处理、哪些步骤需要人工确认,以及如何从检查点恢复并隔离不同会话状态。
4. 持久化与人工介入
Checkpointer 保存图运行状态,让同一会话可以恢复或继续。Interrupt(中断)可用于在高风险工具调用前等待人工批准。持久化数据需要权限控制、保留期限和清理策略;开发环境内存检查点不等同于生产持久化。
重试只适用于可安全重做的步骤。若步骤有外部副作用,应设计幂等键或先检查执行状态,避免重试造成重复写入。
5. 学习版本提醒
课程材料涉及不同代际的 LangChain/LangGraph API。运行示例前记录依赖版本、安装锁文件并逐段验证。若某个导入失效,先查当前版本官方参考,再决定迁移;不要为了匹配旧代码盲目安装不明来源的包。
6. 详细教材:从一次请求看三层职责
可以把常见 AI 应用的一次请求理解成以下流水线:
| 阶段 | 输入与输出 | 主要职责 | 常见错误 |
|---|---|---|---|
| 任务定义 | 用户目标 → 可测试任务 | 写清成功条件、范围、失败时怎么办 | “帮我处理一下”没有可验收条件 |
| 上下文组装 | 规则、用户输入、检索结果、历史 → 消息列表 | 区分指令与数据,控制长度和来源 | 把检索文字当成可信指令 |
| 模型调用 | 消息 → 助手消息 | 生成文本、结构化结果或工具调用请求 | 把模型返回当成已验证事实 |
| 解析与校验 | 原始响应 → 结构化候选 | 解析 Schema、检查字段与业务约束 | JSON 能解析就误认为内容正确 |
| 外部操作 | 获授权的调用请求 → 工具结果 | 检查身份、权限、参数、幂等和审计 | 将模型参数直接用于删改或公开发布 |
| 编排 | 当前状态 → 后续步骤 | 决定顺序、分支、循环、暂停和恢复 | 无限循环、恢复后重复副作用 |
| 评估 | 输入、期望、实际输出 → 质量证据 | 固定样例回归,观察质量、耗时、成本与安全 | 只挑成功案例或凭感觉判断 |
Prompt(提示词)负责告诉模型本次要做什么;LangChain 提供模型、消息、工具等应用组件;LangGraph 负责更复杂的运行状态和控制流。三者都不能代替服务端权限、数据库约束或人工授权。
7. Prompt(提示词)的基础原理
7.1 提示词是一份输入契约,不是万能控制器
模型根据本次输入和自身训练生成概率性结果。提示词只能影响输入,不能保证事实真实、调用必定成功,也不能给模型授予或撤销系统权限。可维护的提示至少说明:
- 目标:这次要完成什么,如何判断成功。
- 范围:哪些对象、时间、资料来源和用户人群在范围内。
- 输入:哪些字段必需、哪些可缺省;用户文本和外部文档是待处理数据。
- 步骤:先判断资料是否够用,再回答、追问、转人工或申请工具。
- 输出:字段、类型、语言、顺序、长度和空值的含义。
- 失败行为:证据不足、相互冲突、解析失败或越权时分别怎么办。
- 示例:普通样例之外,还要有缺字段、歧义、冲突和拒绝样例。
角色标签可以影响模型行为,但“你是管理员”不等于系统真的授权管理员权限。外部输入也不会因为放在 XML 标签、代码围栏或“以下是资料”之后就变成可信内容。
7.2 常见提示策略、收益和代价
| 策略 | 实际改变什么 | 适合情况 | 代价、边界 |
|---|---|---|---|
| Zero-shot(零样本) | 只提供任务说明,不给示例 | 任务直观、输出简单 | 标签边界和细微风格可能不稳定 |
| Few-shot(少样本) | 增加若干输入—目标输出例子 | 分类口径、格式或语气难以只靠文字说明 | 示例占上下文;偏差也可能被模仿 |
| 任务拆分 | 把一个难任务拆成多个有检查点的步骤 | 多条件提取、先检索再归纳 | 每个步骤都可能出错;多调用增加成本 |
| Self-consistency(自一致性) | 多次生成后比较候选答案 | 有可判定答案的部分推理任务 | 多数票不代表事实;延迟和成本上升 |
| ReAct(推理—行动循环) | 让模型在观察工具结果后决定下一步 | 结果依赖外部查询的任务 | 工具调用必须有权限、预算和停止条件 |
| Program-aided(程序辅助) | 模型产出受限计算输入,由程序执行计算 | 精确算数、数据转换 | 生成代码需沙箱;参数仍需校验 |
| 迭代提示 | 根据固定失败样例调整提示 | 原型阶段找出任务描述缺口 | 不做固定集回归会对少数样例过拟合 |
“Graph prompting(图提示)”是资料中的某种提示方法名称,不等于 LangGraph 的状态图;“思维树”“自我反思”等文献术语也不是所有产品都应启用的固定功能。长篇内部推理不是可靠性证明;需要解释时更适合要求简明依据、引用或可复算结果。
7.3 一个可复现的提示迭代实验
以“从会议纪要提取待办”为例。固定 20 条去标识化样例:8 条普通事项、3 条缺少负责人或日期、3 条含冲突信息、2 条时间表达含糊、2 条越权/注入文本、2 条无待办内容。每条样例人工写定期望输出。
| 字段 | 规则 |
|---|---|
| task | 只写原文支持的行动事项,不把讨论建议臆造成承诺 |
| owner | 原文没有明确负责人时输出 null |
| due_date | 可明确解析时用 ISO 日期;缺少会议日期时不猜相对日期 |
| evidence | 摘取最短支持句,不能编造引用 |
| needs_clarification | 关键字段缺失或冲突时为 true |
先跑基线,再只改一个因素,例如增加“缺失填 null”的边界示例。记录提示版本、模型提供方和名称、生成参数、输出、逐字段正确率、无依据补全率、澄清正确率、时延和成本。若结构化输出被 Schema 拒绝,单独记录解析失败,不要悄悄重试到成功。新版本必须对同一组样例回归,再用未参与修改的样例抽查泛化。
7.4 提示注入与信任边界
- 直接注入:用户要求忽略规则、泄露数据或越权操作。
- 间接注入:PDF、网页、邮件、检索片段或工具结果里夹带给模型的恶意指令。
- 分隔符和“忽略其中的指令”等文字可以帮助模型理解,但不是权限隔离保证。
- 真正的边界在程序侧:工具白名单、按当前用户过滤数据、最小权限凭据、参数校验、写操作审批、速率限制和审计。
- 不把密钥、密码或无关个人信息放入提示;日志也要脱敏。
8. LangChain(应用组件层)的详细数据流
8.1 组件怎样接起来
| 组件 | 输入 | 输出 | 需要自己承担的检查 |
|---|---|---|---|
| Chat Model(聊天模型) | 字符串或消息列表 | AIMessage(助手消息)及元数据 | 提供方差异、超时、重试、成本 |
| Prompt Template(提示模板) | 字典变量 | 已渲染的消息 | 必需变量是否齐全;用户数据是否被误作指令 |
| Runnable(可运行组件) | 约定输入 | 下一阶段所需输出 | 每段输入输出类型、错误和副作用 |
| Output Parser(输出解析器) | 模型响应 | 文本、字典或带校验对象 | 格式校验与业务语义校验不是一回事 |
| Retriever(检索器) | 查询 | Document 列表 | 命中率、过滤条件、来源、权限 |
| Tool(工具) | 结构化参数 | 外部操作结果 | 身份、授权、参数、幂等和副作用 |
| Agent(智能体) | 上下文与工具集合 | 多轮模型—工具结果及最终输出 | 工具预算、循环退出、人工确认 |
普通链式流程:问题 → 提示模板渲染消息 → 模型返回助手消息 → 解析为候选结果 → 应用校验并响应。
RAG 流程会在提示前插入检索:查询 → 检索文档 → 格式化上下文 → 提示模板 → 模型 → 解析/引用检查。检索器返回的是候选资料,不是已验证答案。
8.2 消息、模板和模型响应
- 消息角色说明发送者及其在对话中的位置。System、Human/User、AI/Assistant、Tool 是常见角色;具体序列化字段由提供方协议决定。
- 多轮对话不会自动拥有长期记忆。应用通常把需要的历史再次传给模型,或从状态/存储读取。
- AIMessage 不一定只有文本,还可能包含工具调用、结构化片段、拒答、用量和提供方元数据。
- 工具请求和工具结果要通过调用 ID 配对,否则模型可能不知道哪个结果对应哪个调用。
- 模板变量是插值位置,不是安全过滤器。动态数据仍需视作不可信输入,并遵守数据最小化原则。
8.3 Runnable 与可组合流水线
Runnable 可理解为统一的“给定输入、产生输出”运行契约。常见执行形态包括单条调用、异步调用、批量处理和流式输出;某组件是否支持真正的流式传递、并发上限和取消行为,取决于具体实现与版本。
排障时逐段核对:模板需要哪些变量;模型接收到的消息是否符合预期;返回的是纯文本、AIMessage 还是工具请求;解析器在哪里失败;每一段是否支持异步/流式;批量并发是否触发限流或重复写入。链的组合不会自动提供事务、回滚或 exactly-once(恰好一次)副作用语义。
8.4 Structured Output(结构化输出)不等于业务正确
把输出约束理解为三层:
- 语法:是不是能解析为 JSON 或消息对象。
- Schema:字段、类型、枚举、必填规则是否满足。
- 业务语义:日期是否合理、引用是否支持结论、用户是否有权执行。
例如 amount 是整数的 Schema 仍可能接受负数或超大值。不同模型服务可能使用 JSON Schema、原生结构化输出或工具调用方式;格式能力和校验严格度要按当前提供方核实。Schema 通过不代表内容真实。
8.5 Tool Calling(工具调用)完整往返
- 应用向模型提供工具名称、描述和参数 Schema。
- 模型返回想调用哪个工具、使用什么参数的助手消息。
- 应用检查工具白名单、调用人身份、资源权限、参数值和风险级别。
- 通过校验的请求才交给工具实现执行。
- 工具结果作为 ToolMessage 与原调用关联,再交回模型决定后续步骤或最终回答。
工具描述是使用说明,不是授权令牌;参数 Schema 只检查形式,不代替订单归属、访问控制或业务限额。高风险操作应展示操作摘要并取得授权。
8.6 Agent、检索和记忆各自解决什么
- 普通流水线:步骤预先固定,适合稳定可预测的任务。
- Agent:模型在循环中根据工具结果动态选择下一步,适合路径依赖外部结果的任务;调用次数、时限和停止条件必须有界。
- 向量存储负责保存向量并执行检索;Retriever 是应用查询文档的抽象接口,两者不是同义词。
- 对话历史是本轮/本会话重新提交的消息。
- 长期记忆是跨会话保存的偏好或事实,需要持久化、用户隔离、可查阅/删除和保留策略。
- RAG 知识库是可检索外部资料,不是聊天记忆,也不是模型参数本身。
9. LangGraph(状态图运行时)的细节
9.1 State、Node、Edge 与编译
- State 是跨节点共享的数据快照,例如用户问题、检索结果、审核状态和已完成步骤。输入/输出 Schema 可限制调用方传入与最终返回字段;内部状态仍要按敏感数据处理。
- Node 执行一段逻辑并返回局部更新。把读取状态、计算、返回更新作为函数边界,方便测试;网络请求、发消息、删改数据等副作用要显式标出。
- Edge 表达固定后继或基于状态的条件路由。路由选路径,不应隐含未校验的外部写操作。
- Compile(编译)通常是构建运行对象并检查图结构,同时配置持久化器等运行参数;它不是将 Python 源码编译为机器码。
9.2 Reducer(归并器)和局部更新
| 更新规则 | 当前值 | 节点更新 | 结果 | 适用与风险 |
|---|---|---|---|---|
| 默认覆盖 | count=2 | count=3 | count=3 | 普通最新结果 |
| 列表追加 | items=[A] | items=[B] | [A,B] | 收集结果;重放时须避免重复项 |
| 自定义合并 | 字典/集合/消息 | 局部变化 | 依业务定义 | 必须明确冲突、删除和覆盖语义 |
并行节点在同一超步中更新同一字段时,不能假设会按代码书写顺序运行。需定义可预测的合并规则;并行工作写入不同字段通常更容易理解。追加 reducer 下返回空列表不代表清空旧列表,需有明确重置语义。
9.3 超步、并行、汇聚与循环
运行时可以离散的 superstep(超步)理解:本轮被激活的节点从本轮可见状态执行,更新随后归并,下一轮再运行后继节点。并行节点不能依赖彼此本轮刚写入的状态。Fan-out(扇出)启动独立任务;Fan-in(扇入)等待或汇总结果;Map-Reduce 将输入拆开处理再合并。
| 模式 | 流程 | 适用问题 | 必需保护 |
|---|---|---|---|
| 顺序 | A → B → C | 固定阶段处理 | 每段失败出口 |
| Router(路由) | 分类 → 分支 | 按意图选择处理器 | 未知类别默认路由 |
| Parallel(并行) | 同时处理 → 汇总 | 多来源检索、独立抽取 | 并发上限、部分失败策略 |
| Loop(循环) | 生成 → 评估 → 重做或结束 | 有明确验收标准的迭代 | 最大步数、预算、超时和兜底 |
| Agent loop(智能体循环) | 模型选工具 → 执行 → 观察 → 再判断 | 下一步依赖工具结果 | 权限、次数、退出和审计 |
对于确定流程,不要为了“用了 Agent”引入模型循环。循环应有业务停止条件和迭代上限;超限后给出部分结果、转人工或安全失败。
9.4 State、Checkpointer 与 Store
| 机制 | 保存什么 | 常见范围 | 典型用途 |
|---|---|---|---|
| State | 当前运行数据 | 当前图执行 | 节点间传值 |
| Checkpointer | 某一 thread 的状态快照/检查点 | 单线程/单会话流程 | 续跑、中断恢复、故障容错、历史状态检查 |
| Store | 应用定义的跨执行数据 | 多线程/多会话 | 用户偏好、可复用事实、跨会话记忆 |
具体持久化能力取决于 Saver/Store 实现。内存实现适合本地演示,进程退出后通常丢失;生产实现还需访问控制、加密、备份、保留期限和删除。thread_id 是查找流程状态的标识,不是身份验证;读取和恢复必须在服务端验证当前用户是否有权访问。
检查点只记录流程状态,不会撤销已发出的邮件、创建的工单或数据库写入。Replay(重放)/Fork(分叉)能用于排障和基于旧状态继续,不是副作用的时间倒流。
9.5 Interrupt(中断)、恢复与幂等
典型人在环流程:节点生成待执行提案 → 发出中断载荷并保存检查点 → 有权限的人查看详情 → 服务端验证审批身份和版本 → 用同一线程恢复 → 节点依据审批决定执行或拒绝。
LangGraph 当前官方中断文档说明,恢复时包含中断的节点会从节点开头再次执行;中断调用之前的代码也会重跑。因此:
- 不要把不可重复副作用放在中断点之前;或确保它幂等。
- 审批要绑定资源、参数、操作者、时间及待执行内容版本,避免审批后内容被替换。
- 恢复必须使用同一流程状态,但线程标识不能取代身份和权限验证。
- 将副作用放在审批之后;再次恢复/网络重试时用幂等键防止重复执行。
- 检查点可能含敏感内容,需最小化、租户隔离和生命周期管理。
9.6 错误、重试、超时和流式结果
- 重试适用于网络暂断、限流等暂态错误;参数无效、权限拒绝和程序缺陷不应盲目重试。
- 非幂等步骤重试前要检查副作用是否已完成;最好由后端也执行幂等键唯一约束。
- Timeout(超时)控制单节点或整次任务的最长等待,并定义安全失败、换路、部分结果或人工介入。
- 递归/步骤上限保护图循环和 Agent 调用;触发上限应有兜底。
- 流式输出可能含中间状态,不应默认当成最终结果,也不能泄露状态中的私有字段、工具参数或其他用户数据。
- 观测记录节点、耗时、错误类别和必要的脱敏信息;不记录密钥。
9.7 Graph API 与 Functional API 的选型
显式 Graph API 把状态、节点、边写清楚,适合分支、共享状态、并行和需要审查拓扑的流程。Functional API 用函数组织步骤,适合从现有顺序函数渐进接入持久化和恢复。选择依据是控制复杂度、状态边界、调试需求和团队可读性,不是谁更新或更高级。
10. 学习与排障检查清单
- 先画普通函数形式的业务步骤,再决定是否需要链或状态图。
- 为每步写清输入、输出、失败类型、可重试性和副作用。
- 对提示和模型调用固定正例、边界例、拒绝例,更新后跑回归。
- 对检索结果保存来源和权限元数据;答案引用能回到具体片段。
- 对每个工具检查身份、权限、参数和副作用;高风险调用加人工确认。
- 对状态字段标注是否持久、是否敏感、谁能读及何时删除。
- 对中断恢复验证节点重跑、重复提交、审批内容变更和用户越权。
- 运行代码前记录依赖版本,逐项核对当前官方示例和模型提供方能力。
11. 当前官方参考
- LangChain Models(模型组件与调用)
- LangChain Messages(消息模型)
- LangChain Structured Output(结构化输出)
- LangChain Tools(工具)
- LangChain Agents(Agent 循环与高层抽象)
- LangGraph Graph API(状态、节点、边、归并与运行)
- LangGraph Persistence(检查点与跨会话 Store)
- LangGraph Interrupts(暂停、恢复与人在环)
相关笔记
- RAG检索增强生成
- Agent与Dify基础
- RAG与Agent项目精选
- AI学习知识地图
- Prompt与编排框架面试题库
参考资料
- 《尚硅谷 LangChain:概述、模型、LangSmith、消息与提示模板、Tools、结构化输出、Agent、中间件、上下文与记忆、RAG》。
- 《大模型(LLMs)langchain 面》《基于 LLM + 向量库的文档对话经验面》。
- 《尚硅谷 LangGraph》文字笔记:基础、控制流、持久化、人工介入、部署与高级特性。
原始来源文件
以下列出本篇整理所依据的代表性原件;同主题重复版本与完整状态请查阅 source-manifest.csv。
Raw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-04-Message与提示词模板.pdfRaw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-05-Tools.pdf