KNOWLEDGE NOTE / AI · LangChain

LangChain(资料整编)

梳理 LangChain 的模型、消息、提示词、工具、Agent、结构化输出和观测能力。

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

LangChain(资料整编)

摘要

LangChain 把模型调用、消息与提示词、工具、结构化输出、检索和 Agent 组织为可组合的应用层组件。模型提出工具调用后,仍由运行时校验并执行工具。流程需要精确分支、循环、持久状态或人工审批时,进一步学习 LangGraph(资料整编)。

1. 解决什么问题

直接调用一个模型 API 可以完成单轮生成,真实应用还要管理对话历史、切换模型服务、约束输出格式、调用业务函数、检索文档、调试链路并评估质量。LangChain 为这些步骤提供抽象和组合方式,但不能替代权限设计、数据治理和测试。

2. 核心组件

组件作用注意点
Chat Model(聊天模型)根据消息生成回答或工具调用请求不同服务商的参数、限流和结构输出能力不同
Message(消息)表示 system、user、assistant、tool 等角色角色和顺序会影响模型行为
Prompt Template(提示模板)组合固定指令与动态变量不要把不可信文本拼成高权限指令
Structured Output(结构化输出)按 Schema(结构定义)返回字段仍要校验字段、范围和业务规则
Tool(工具)暴露函数或外部能力服务端需验证权限、参数和副作用
Retriever(检索器)从知识库取回相关片段检索质量限制生成质量
Middleware(中间件)在模型或工具调用前后执行策略可做校验、日志、重试、审批
LangSmith记录轨迹、调试与评估日志不可泄漏密钥和敏感数据

3. 消息、提示词与结构化结果

消息不只是字符串,还包含角色和可能的多模态内容。对话通常由系统指令、用户消息、助手消息和工具结果组成。历史管理要明确保留什么、何时摘要或删除,以及是否按用户隔离。

结构化输出可把回答限制为分类、答案、证据来源等字段,提高格式稳定性,但内容不因此自动正确。服务端仍应检查必填字段、枚举值、数值范围和引用。

4. 工具调用的真实流程

  1. 应用把用户问题和可用工具描述发给模型。
  2. 模型决定直接回答,或提出工具及参数。
  3. 应用检查工具名称、参数、用户权限和风险等级。
  4. 通过校验后,应用执行工具。
  5. 工具结果返回模型,模型继续决策或回答。

模型只提出调用意图,应用才执行真实操作。发邮件、删除文件、支付、公开发布等有副作用的操作应要求明确授权,并设置参数白名单、重复提交保护和审计。

5. Agent 与适用场景

Agent 把模型与工具组合成有停止条件的循环:模型依据观察选择下一步动作,直到完成或达到预算上限。它不是“模型本身拥有电脑权限”。

适合采用 Agent:下一步依赖前一步结果、任务无法预先拆成固定步骤、工具接口清晰,并且能设置调用次数、超时、权限和终止条件。若流程完全固定,普通函数或确定性工作流通常更容易测试。自主性越高,越要加强权限和人工确认。

6. 上下文与记忆

对话历史是被保留或重新提供的上下文,不等同于永久记忆:

  • 本次调用上下文:当前请求、指令和必要工具结果。
  • 会话历史:同一用户的一段对话,可裁剪或摘要。
  • 长期记忆:跨会话保存的偏好或资料,需要来源、用途、权限和删除规则。
  • RAG 知识库:可检索的外部文档,不应混同于聊天记忆。

无限追加历史会增加 Token 成本并降低相关信息密度;摘要也可能丢失事实,需按任务保留关键内容。

7. 版本提醒

尚硅谷课件《LangChain 1.2 概述》按其对应版本讲解。资料指出,LangChain 1.x 的高层入口聚焦 Agent,旧式 Chain、Retriever、Memory API 可能位于 classic 兼容层。因此不要把旧面试资料里的代码直接复制到新项目。

学习或运行代码前确认 langchain、langchain-core、langgraph 的版本,核对导入路径、弃用提示和模型提供方接口。此笔记保留稳定概念,具体代码按项目锁定版本核对。

8. 何时转向 LangGraph

流程需要显式状态、多分支、并行、循环、检查点、恢复执行、人工中断或子图时,LangGraph 更适合表达运行时控制。LangChain 侧重应用抽象;LangGraph 侧重状态图和执行过程,两者可组合。

9. 一次完整调用的消息流

以“把用户问题整理成有依据的简答”为例:

步骤数据变化检查点
接收HTTP 表单/程序调用得到 question是否为空、超长或包含敏感信息
组装指令、用户问题、必要历史组成消息列表历史是否属于同一用户/会话
调模型Chat Model 返回 AIMessage超时、限流、拒答、用量和结束原因
解析文本或结构化片段转为应用数据Schema 失败时是否保留脱敏原始响应用于排查
校验引用、枚举和业务规则独立检查输出是否有证据、是否越权
返回转成面向 UI/API 的结果不把内部状态、密钥或其他用户数据暴露给前端

Chat Model 通常接收带角色的消息并返回助手消息;传统文本补全模型可能采用不同的字符串输入/输出约定。集成包会屏蔽部分差异,但模型能力和提供方特定参数仍需单独核对。

10. Message(消息)与 Prompt Template(提示模板)

10.1 角色与内容

  • System 消息承载应用侧的高优先级任务说明,但它本身仍是送入模型的文本/协议字段,并非服务器的权限系统。
  • Human/User 消息包含用户请求。
  • AI/Assistant 消息可能是自然语言回答,也可能包含工具调用请求、结构化内容块和提供方元数据。
  • Tool 消息承载外部工具的执行结果,通常要与原调用 ID 匹配。

完整对话通常要由应用保存和重新发送必要消息;不能仅因为在 SDK 中创建了一个模型对象就认为它记住了之前的请求。长历史应设计裁剪/摘要策略并评估信息损失,按用户隔离数据。

10.2 模板变量的职责与边界

模板将固定文本与运行时变量组合,适合复用系统指令和避免每次手动拼接。变量应有明确名称、类型、必填规则和来源;缺失变量最好在应用层尽早报错。用户文本、网页、PDF 和检索片段即使被插入模板,也必须作为不可信数据看待。

MessagesPlaceholder 一类能力可在模板中预留历史消息位置,但具体类名和导入路径属于 API 细节,要核对当前包版本。模板能组织上下文,不会自动过滤注入或完成权限校验。

11. Runnable、组合与调用形式

Runnable 是组件之间共享的输入/输出运行契约,令提示模板、模型、解析器和自定义函数可以按流水线组合。LCEL(LangChain Expression Language,LangChain 表达式语言)使用管道式写法表达相邻阶段,但核心不是记住符号,而是明确每段输入和输出。

调用方式适合场景注意事项
单次调用一个输入等待一个结果设置超时、错误分类和取消策略
异步调用网络 I/O 等待期间释放执行资源异步方法不代表模型推理本身更快
批处理多个相互独立输入确认并发上限、限流、顺序和失败项处理
流式调用逐段向用户呈现长回答组件链要支持流式;中间块不是最终结果

组合之前检查:模板输出的消息能否被模型接受;模型输出是不是 AIMessage;解析器期待什么结构;批处理是否有并发上限;流式内容是否会泄露内部字段。流水线不是数据库事务,也不保证外部副作用只执行一次。

12. 结构化输出与解析

12.1 分层验证

  1. 解析层:输出是否能转成目标数据结构。
  2. Schema 层:字段、数据类型、必填、枚举和长度是否合规。
  3. 业务层:日期、数值、资源归属、引用和权限是否合理。

例如“退款金额是数字”只属于类型校验,还需要验证不得超过订单可退金额、订单归当前用户。Schema 通常用于约束形状,不会让模型的事实判断自动正确。

12.2 提供方差异

模型服务可能支持原生结构化响应、工具协议或仅按提示生成 JSON;同一个 LangChain API 背后也可能因提供方而走不同机制。课程中的 Pydantic、TypedDict、JSON Schema 和 dataclass 示例,其运行时校验性质不同。使用前应检查当前集成文档,测试缺字段、错误类型、额外字段和超范围值。

解析失败时可以让应用返回可理解的失败、进行有限且可审计的纠正重试,或转人工;不要无限重试,也不要丢失失败率指标。

13. Retriever、Document 与 RAG 边界

Document 通常由正文和 metadata(元数据)构成。正文用于检索/生成,元数据可包含源文件、页码、时间、租户或访问级别。Retriever 负责把查询转成候选文档;底层可能用稀疏检索、向量数据库或混合方法。

  • Retriever 不等于 Vector Store(向量存储):前者是查询接口抽象,后者是实现存储/向量相似搜索的基础设施之一。
  • 检索命中不代表答案正确。应用需过滤过期或无权读取资料,必要时重排,再把可追溯引用传给模型。
  • 权限过滤要在服务端查询层做,不能只让模型“忽略私密资料”。
  • RAG 的 chunk、embedding、检索、重排和评估方法见 RAG检索增强生成。

14. Tools、Agent 与 Middleware 的职责

14.1 Tool schema 只是调用合同

Tool 的名称和说明帮助模型理解何时提出调用请求;类型声明或 JSON Schema 帮助解析参数。它们都不能证明调用人有权访问目标资源。服务端执行前要再次检查身份、资源所有权、允许字段、数值范围和副作用;危险操作需审批和审计。

一次典型循环为:应用给模型工具描述 → 模型返回工具请求 → 应用校验并运行工具 → 工具结果回到对话 → 模型决定继续或结束。模型说“已成功”不能代替检查实际工具返回。

14.2 Agent 与固定工作流

Agent 将模型决策和工具执行组织为循环,下一步会基于观察动态变化。任务步骤完全确定时,直接写函数/工作流更容易预测和测试;开放任务确实需要选择外部工具时,再用 Agent 并限制调用预算、最大步骤、时间和可访问资源。

当前 LangChain 高层 Agent 抽象建立在 LangGraph 的运行能力之上;当需要显式状态、分支、恢复、人工审批或控制图拓扑时,可直接构建 LangGraph。不同版本的 Agent 构造接口变更较多,旧代码里的 initialize_agent、AgentExecutor 等不可直接假定适用于当前版本。

14.3 Middleware 与 Trace

Middleware(中间件)可以在模型/工具调用前后挂接动态上下文、校验、脱敏、重试、预算、审批和日志。它不是权限本身;真正授权仍应在服务端工具实现中执行。

Tracing(链路追踪)可记录哪个组件以什么输入和配置运行、花了多久、在哪失败。追踪系统也会接触提示、模型响应和用户数据,因此要做脱敏、最小化、访问控制和保留期限。不要因调试方便就把密钥或个人数据写入 Trace。

15. 最小测试方案

每个 Runnable 组件至少检查正常输入、缺少字段、错误类型、模型超时、解析失败和意外额外字段。集成级别还要检查模型工具调用后的身份授权、工具失败、达到最大循环、用户中断以及恢复重复提交。模型变更和 SDK 升级都跑固定回归集,并分别记录质量、成本、时延与安全结果。

16. 版本与当前参考

本地《尚硅谷 LangChain 1.2 概述》明确按 LangChain 1.2 教学;模型、消息、工具和结构化输出课件也含 1.x 示例。版本信息只是课程材料的基准,并不意味着未来版本接口不变。

新项目记录 Python 版本、langchain、langchain-core、langgraph 和 provider integration(提供方集成包)的锁定版本。发生导入错误时先读弃用提示和当前参考,不要混装多个旧教程的依赖,也不要只升级其中一个相关包。

当前官方概念文档:

相关笔记

  • 大模型基础原理
  • LangGraph(资料整编)
  • Agent、MCP与Skill
  • RAG检索增强生成
  • 评测幻觉与多模态
  • Prompt与编排框架面试题库

参考资料

  • 尚硅谷《LangChain 1.2 概述》《模型的创建与调用》《Message 与提示词模板》。
  • 尚硅谷《Tools》《结构化输出》《智能体》《中间件》《上下文与记忆》《RAG》课件。
  • 《大模型(LLMs)langchain面》《基于 LangChain RAG 问答应用实战》。
  • 《LangChain 入门指南:构建高可复用、可扩展的 LLM 应用》。
  • 未使用课程目录中的 IDE 激活说明、激活码与环境配置文件。

原始来源文件

以下列出本篇整理所依据的代表性原件;同主题重复版本与完整状态请查阅 source-manifest.csv。

  • Raw sources/大模型官方课程-视频资料/AI应用开发学习路线/13-基于langchain RAG问答应用实战.pdf
  • Raw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-04-Message与提示词模板.pdf

放弃未保存的修改?

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