KNOWLEDGE NOTE / AI · LangChain

LangChain 现代 API 与旧课件迁移

把 LangChain 的模型、工具、Agent、结构化输出和状态串起来,并辨认旧版 API。

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

LangChain 现代 API 与旧课件迁移

1. 先定位 LangChain 在应用中的层次

LangChain 把模型、消息、提示、工具和 Agent 组成应用级抽象;LangGraph 提供图式控制流与持久运行时。如今 LangChain 的高层 Agent 入口是 create_agent;需要显式循环、复杂分支、恢复、人工审批或自定义状态时,可以下沉到 LangGraph(资料整编)。简单调用不需要为了使用框架而强行建一个 Agent。

框架的价值是统一常见操作和组合接口,不会自动提高模型准确率,也不会替应用完成权限校验、事务、幂等或评测。

2. 消息、模型和提示

对话不是单个字符串,而是有角色和内容的消息序列:系统/开发者指令、用户消息、AI 消息,以及与工具调用对应的工具结果消息。多模态模型的消息内容还可能是文本、图像、音频或其他块。

提示模板负责把可变输入安全、清楚地注入指令结构。格式化输入时要避免把用户内容拼接成高优先级指令;检索文本、网页和工具结果都视为不可信输入。稳定提示应有可测试的输入 Schema、版本记录和回归用例。

3. 工具调用是“模型提议 + 应用执行”

python
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. 排错顺序

  1. 记录并确认 langchain、provider integration、langgraph 版本,查看锁文件和导入路径。
  2. 先单独验证模型调用、消息格式和 Provider 支持的 tool calling / structured output 能力。
  3. 把工具函数单测,确认输入 Schema、权限、超时和结果编码。
  4. 检查 Agent 的消息序列:AI tool call 和 ToolMessage 的调用 ID 是否匹配、结果是否正确追加。
  5. 检查循环退出条件、最大步数、网络超时和模型重试,避免无限调用或成本放大。
  6. 用 trace 区分模型没有发调用、框架没有路由、工具报错、结果格式错误和最终回答错误。

来源依据与官方核对

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

放弃未保存的修改?

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