LangChain 现代 API 与旧课件迁移
1. 先定位 LangChain 在应用中的层次
LangChain 把模型、消息、提示、工具和 Agent 组成应用级抽象;LangGraph 提供图式控制流与持久运行时。如今 LangChain 的高层 Agent 入口是 create_agent;需要显式循环、复杂分支、恢复、人工审批或自定义状态时,可以下沉到 LangGraph(资料整编)。简单调用不需要为了使用框架而强行建一个 Agent。
框架的价值是统一常见操作和组合接口,不会自动提高模型准确率,也不会替应用完成权限校验、事务、幂等或评测。
2. 消息、模型和提示
对话不是单个字符串,而是有角色和内容的消息序列:系统/开发者指令、用户消息、AI 消息,以及与工具调用对应的工具结果消息。多模态模型的消息内容还可能是文本、图像、音频或其他块。
提示模板负责把可变输入安全、清楚地注入指令结构。格式化输入时要避免把用户内容拼接成高优先级指令;检索文本、网页和工具结果都视为不可信输入。稳定提示应有可测试的输入 Schema、版本记录和回归用例。
3. 工具调用是“模型提议 + 应用执行”
from langchain.tools import tool
from langchain.agents import create_agent
@tool
def lookup_order(order_id: str) -> str:
"""查询当前用户有权查看的订单状态。"""
# 生产代码还要从已验证的运行上下文取得用户身份并执行 ACL 检查。
return f"订单 {order_id}:运输中"
agent = create_agent(
model="provider:model-name", # 替换为项目已安装 Provider 支持的模型标识
tools=[lookup_order],
system_prompt="只查询当前用户有权访问的订单;缺少订单号时先追问。",
)
result = agent.invoke({"messages": [{"role": "user", "content": "查一下 A-17"}]})
@tool 的函数签名/类型和文档字符串用于形成工具描述与输入约束。执行链路是:模型返回结构化 tool call → 框架识别调用 → 应用运行函数 → 工具结果以匹配调用 ID 的消息回传 → 模型继续或结束。模型输出“我要调用工具”本身不等于工具已经执行。
生产工具应做到:输入做 schema 校验;权限从服务端上下文得出而不是模型传参;读写工具分开;危险操作做二次确认;超时、限流、审计、幂等和错误分级;只把最小必要结果回传给模型。不要把任意 shell、SQL 或 HTTP 请求裸露为无边界工具。
4. Agent 循环、状态和记忆
Agent 是模型和 harness(运行框架)的循环:模型根据当前消息和工具清单选择回答或工具;工具执行结果进入状态;循环直到停止条件或预算耗尽。create_agent 允许配置模型、工具、系统提示和 middleware;常见状态是消息历史,也可以通过状态 Schema 扩展业务字段。
如果要跨调用延续同一个对话,需要配置 checkpointer(检查点保存器)并复用 thread_id。仅传同一个 thread_id 而没有持久化保存器,不会神奇地保存历史。内存检查点适合示例或单进程调试;生产应使用持久后端,并由服务端验证线程归属、租户访问和数据保留策略。
“记忆”不是无限保存聊天记录。先定义要记住的事实、有效期、用户控制方式、删除流程和来源;短期工作状态适合对话状态,跨会话业务事实通常应由有授权和审计的业务数据库承担。
5. 结构化输出与 Middleware
当下游代码要求 JSON、分类标签或固定字段,使用 Schema(例如 Pydantic 模型)约束输出,并在服务端校验和处理失败;不要仅在提示里写“必须输出合法 JSON”。结构化输出的成功也不代表字段事实正确,需要业务验证。
Middleware 可在模型调用前后或工具前后检查、改写状态、注入动态提示、做安全过滤或观测。把共通策略做成小而可测的中间件;不要把核心业务决策藏在不透明的钩子里。高风险授权仍由服务端业务规则掌控,而不是模型判断或 Middleware 文案。
6. 旧课件术语到现代架构的理解方式
| 旧资料常见写法 | 学习时保留的概念 | 新项目的处理原则 |
|---|---|---|
LLMChain、ConversationChain | 可组合的输入—模型—输出流程 | 查看当前 Runnable/API 与维护状态;复杂状态循环看 create_agent 或 LangGraph |
ConversationBufferMemory | 对话历史如何保存与裁剪 | 对话状态与持久化明确分开;检查点/Store/业务库按生命周期选型 |
| 旧式 Retriever / RetrievalQA | 检索器、提示和生成的责任边界 | RAG 先单测解析/召回/重排,再接现代 Agent 或自建流程 |
initialize_agent、旧 AgentExecutor 示例 | 模型选择工具—工具执行—返回结果的控制循环 | 新建 Agent 优先核对 create_agent 和当前官方 Agent API |
| 各种兼容包里的旧导入路径 | 生态曾有模块重组 | 以当前安装版本文档和类型检查为准,锁版本并逐项迁移 |
旧抽象不是“原理错误”,但可能已经搬到 langchain-classic、更换导入路径或不再是官方主推入口。先识别它试图解决的问题,再选择现代构件;不要为了消除弃用警告而机械替换而不跑用例。
7. 何时用什么
- 单次结构化模型调用:直接用 Provider SDK 或 LangChain ChatModel,选择团队最熟悉、可测试的接口。
- 有少量工具且标准 Agent 循环即可:从
create_agent开始。 - 明确分支、并行、长流程、检查点恢复和人工审批:用 LangGraph(资料整编) 建显式状态图。
- 检索问答:先做可独立评估的 RAG 检索与答案链,只有确实要在流程中自主选工具时才叠加 Agent。
8. 排错顺序
- 记录并确认
langchain、provider integration、langgraph版本,查看锁文件和导入路径。 - 先单独验证模型调用、消息格式和 Provider 支持的 tool calling / structured output 能力。
- 把工具函数单测,确认输入 Schema、权限、超时和结果编码。
- 检查 Agent 的消息序列:AI tool call 和 ToolMessage 的调用 ID 是否匹配、结果是否正确追加。
- 检查循环退出条件、最大步数、网络超时和模型重试,避免无限调用或成本放大。
- 用 trace 区分模型没有发调用、框架没有路由、工具报错、结果格式错误和最终回答错误。
来源依据与官方核对
Raw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-01-LangChain概述.pdfRaw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-05-Tools.pdfRaw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-07-智能体.pdf- LangChain Agents 官方文档
- LangChain Tools 官方文档
- LangGraph Persistence 官方文档
相关笔记
- LangChain(资料整编)
- LangGraph(资料整编)
- Agent、MCP与Skill
- RAG检索增强生成
- Prompt与编排框架面试题库
原始来源文件
以下列出本篇整理所依据的代表性原件;同主题重复版本与完整状态请查阅 source-manifest.csv。
Raw sources/大模型官方课程-视频资料/AI应用开发学习路线/13-基于langchain RAG问答应用实战.pdfRaw sources/尚硅谷LangChain从入门到实战(2026版)/1、课件/01-课件/01-课件/尚硅谷-04-Message与提示词模板.pdf