KNOWLEDGE NOTE / AI · 框架

LangChain 与 LangGraph 基础

概括模型、消息、提示模板、工具、检索与状态图核心概念,并提醒课程代码存在版本差异。

创建
2026年9月24日
更新
2026年10月15日

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 提示词是一份输入契约,不是万能控制器

模型根据本次输入和自身训练生成概率性结果。提示词只能影响输入,不能保证事实真实、调用必定成功,也不能给模型授予或撤销系统权限。可维护的提示至少说明:

  1. 目标:这次要完成什么,如何判断成功。
  2. 范围:哪些对象、时间、资料来源和用户人群在范围内。
  3. 输入:哪些字段必需、哪些可缺省;用户文本和外部文档是待处理数据。
  4. 步骤:先判断资料是否够用,再回答、追问、转人工或申请工具。
  5. 输出:字段、类型、语言、顺序、长度和空值的含义。
  6. 失败行为:证据不足、相互冲突、解析失败或越权时分别怎么办。
  7. 示例:普通样例之外,还要有缺字段、歧义、冲突和拒绝样例。

角色标签可以影响模型行为,但“你是管理员”不等于系统真的授权管理员权限。外部输入也不会因为放在 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(结构化输出)不等于业务正确

把输出约束理解为三层:

  1. 语法:是不是能解析为 JSON 或消息对象。
  2. Schema:字段、类型、枚举、必填规则是否满足。
  3. 业务语义:日期是否合理、引用是否支持结论、用户是否有权执行。

例如 amount 是整数的 Schema 仍可能接受负数或超大值。不同模型服务可能使用 JSON Schema、原生结构化输出或工具调用方式;格式能力和校验严格度要按当前提供方核实。Schema 通过不代表内容真实。

8.5 Tool Calling(工具调用)完整往返

  1. 应用向模型提供工具名称、描述和参数 Schema。
  2. 模型返回想调用哪个工具、使用什么参数的助手消息。
  3. 应用检查工具白名单、调用人身份、资源权限、参数值和风险级别。
  4. 通过校验的请求才交给工具实现执行。
  5. 工具结果作为 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=2count=3count=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. 学习与排障检查清单

  1. 先画普通函数形式的业务步骤,再决定是否需要链或状态图。
  2. 为每步写清输入、输出、失败类型、可重试性和副作用。
  3. 对提示和模型调用固定正例、边界例、拒绝例,更新后跑回归。
  4. 对检索结果保存来源和权限元数据;答案引用能回到具体片段。
  5. 对每个工具检查身份、权限、参数和副作用;高风险调用加人工确认。
  6. 对状态字段标注是否持久、是否敏感、谁能读及何时删除。
  7. 对中断恢复验证节点重跑、重复提交、审批内容变更和用户越权。
  8. 运行代码前记录依赖版本,逐项核对当前官方示例和模型提供方能力。

11. 当前官方参考

相关笔记

  • 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与提示词模板.pdf
  • Raw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-05-Tools.pdf

放弃未保存的修改?

有未保存的修改,离开会丢失这些内容。