拾光拾光集Search · AI · Life

LangChain 1.0 之后：为什么我劝你把旧教程删了

2026-09-01 03:190 条评论202 次阅读
#LangChain

LangChain 1.0 之后：为什么我劝你把旧教程删了

系列：《代码的江湖》LangChain 系列 · 第 1 篇
建议阅读时间：12 分钟

一、一段跑不通的代码

如果 2026 年你还在学 LangChain，有一件事必须先知道：市面上大量的 LangChain 教程，正在教你一个已经废弃的 API。

前几天我在 GitHub 上看到一个刚开源的项目，README 里贴的代码是这样的：

from langchain.agents import initialize_agent, AgentType

agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)

这段代码在三年前是对的。现在运行，你会看到一屏幕的 DeprecationWarning，或者直接 ImportError。

作者不是不懂技术，他只是照着 2023 年的教程学了一遍。而 2023 年的 LangChain，和 2026 年的 LangChain，已经是两个东西。

二、版本断层：1.0 到底改了什么

2025 年 10 月，LangChain 和 LangGraph 同时发布了 1.0 版本。这次重构对整个代码库做了彻底重组，官方在同月完成 1.2 亿美元融资，估值超 12 亿美元。

LangChain 官方首次给出 API 稳定承诺：在 2.0 版本之前，不会再有破坏性变更。这对企业级项目来说，是决定性的信号。

2.1 最直观的变化：Agent 构建方式

维度 v0.3（旧） v1.x（新）
Agent 入口 initialize_agent + AgentExecutor create_agent（底层 LangGraph）
结构化输出 JSON Parser + 正则，不稳定 Structured Output 一等公民，绑定 Pydantic 类
输出解析 纯文本手动解析 标准化的 content_blocks
工具定义 Tool 类，类型校验弱 Pydantic Schema，类型安全
扩展机制 改源码或提示词 Middleware 中间件系统
异步性能 一般 优化后提升 30%+

老教程里教的那套 AgentExecutor 心智，已经被官方废弃，维护到 2026 年 12 月就停止。现在学它，等于学一个即将下架的东西。

2.2 更深的变化：包结构和心智模型

v1.x 把包结构重新梳理了一遍：

  • langchain-core：核心 API，比如 Runnable、BaseMessage
  • langchain-classic：0.x 时代的经典 API 迁移到这里，v1 不再直接支持
  • langchain-community：第三方集成，按需安装，避免全家桶臃肿
  • langgraph：图式编排引擎，1.0 深度整合

比包结构更重要的是心智模型：从链式拼装，到图式编排。

旧时代的写法是把组件一个个串成 chain，prompt 进、结果出，线性执行。流程一旦需要循环、分支、回退，chain 就会变得非常别扭。

LangGraph 的做法是把执行过程建模成一张有向图。节点是你要执行的步骤，边是流转条件，流程怎么走、状态怎么变一目了然。

1.0 还有一个更底层的设计变化：执行状态可以被持久化。LangGraph 会在每一步自动做 checkpoint，进程中断、等待人工审核、服务商故障重试，都会从断点继续，而不是从头再来。

这套心智现在也成了 Agent 框架的共同语言。Google 的 ADK 在 2026 年也收敛到了同样的抽象。

三、组件地图：LangChain 生态的四大支柱

搞清楚 1.0 改了什么，再看 2026 年的 LangChain 到底由哪些部分组成。截至 2026 年，它已经从一个开发框架，长成一个覆盖智能体全生命周期的技术生态，核心是四大支柱：

支柱 定位 一句话理解
LangChain 能力抽象层 统一模型、工具、消息的接口，负责"有什么能力"
LangGraph 执行编排层 有向图编排工作流，负责"怎么跑"
Deep Agent 智能体抽象层 Agent Harness，规划、子 Agent、虚拟文件系统
LangSmith 监控评估层 全链路追踪、评测，让 Agent 可观测

3.1 LangChain：智能体开发的基石

LangChain 是整个生态的起点，提供三块核心能力：

  • 统一的模型抽象层：屏蔽不同模型提供商（OpenAI、Anthropic、DeepSeek、Ollama）的接口差异，一套 API 调用所有模型
  • 高度模块化：Message、Tool、Agent、Middleware 等组件灵活组合
  • 丰富的集成生态：预置大量数据源和 API 集成

官方文档有一句话说得直接：快速起步用 LangChain，复杂控制用 LangGraph，二者并行协同。

3.2 LangGraph：复杂工作流的编排引擎

LangGraph 的核心思想是把智能体内部抽象成一张有向图：

  • 节点（Node）：独立的功能单元或决策点
  • 边（Edge）：节点间的流转条件与路径
  • 状态（State）：共享上下文，在节点间传递并持久化

需要多步、有状态、带人工审核的复杂工作流，就是 LangGraph 的舞台。

3.3 Deep Agent：智能体的执行框架

Deep Agent 是 2026 年推出的新组件，定位是 Agent Harness（智能体执行框架）。它构建在 LangChain 和 LangGraph 之上，增加了显式规划、虚拟文件系统、子智能体、长期记忆等能力，让开发者可以快速构建具备深度规划的复杂智能体。

3.4 LangSmith：可视化监控与测试

当智能体越来越复杂，靠 print 调试已经不现实。LangSmith 提供全链路追踪、调试优化、评测质控和团队协作，让 Agent 的运行过程透明、可评估。

四个支柱合在一起，正好覆盖从技术验证到生产部署的完整闭环。后面整个系列，都会沿着这条线展开。

四、何时上框架：裸调 API 与 LangChain 的边界

理解了生态全貌，一个现实的问题摆在面前：我到底要不要用 LangChain？

这个问题值得认真回答，因为 LangChain 一直有"过度封装"的争议。我的判断标准很简单：看你的应用复杂度到了哪一档。

4.1 复杂度分级

场景 推荐方案 理由
单次问答、一个 prompt 直接调 SDK 裸写几行代码，无框架开销
多轮对话 + 系统提示 裸写 + 手动管理 messages 可控，心智负担小
需要多模型切换、结构化输出 init_chat_model + LangChain 统一接口的价值开始体现
工具调用、Agent 循环 LangChain + create_agent 复用成熟实现，别重复造轮子
多步、分支、人工审核、持久化 LangGraph StateGraph 图式编排是唯一合理选择

4.2 一个算账式的判断

裸调 API 的成本是显性的：每一行胶水代码（重试、日志、token 统计、模型切换）都要自己写，写多了就是重复劳动。

LangChain 的成本是隐性的：抽象层学习曲线、版本演进、依赖管理。你花时间学它的抽象，换来的是不需要自己维护胶水代码。

我的经验是：从第三个场景开始，LangChain 的价值就超过了它的成本。一旦你的应用要接多个模型、要做结构化输出、要接工具，裸写的维护成本会快速超过框架的抽象成本。

五、动手：从第一个模型调用开始

纸上谈兵结束，开始写代码。这个系列全程使用 LangChain 1.x 的新 API，不碰任何旧写法。

5.1 环境准备

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate   # Windows 用 .venv\Scripts\activate

# 安装依赖
pip install langchain langchain-openai python-dotenv

5.2 配置密钥

在项目根目录创建 .env 文件，把 API Key 放进去。这里以 DeepSeek 为例（国产模型，注册送额度，国内直连）：

# .env
DEEPSEEK_API_KEY=sk-你的密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com

密钥放 .env，而不是硬编码在代码里。加进 .gitignore，避免泄露。

5.3 用 init_chat_model 创建模型

init_chat_model 是 LangChain 1.x 推出的统一模型入口。只要改一行模型名，就能切换不同的模型提供商：

from langchain.chat_models import init_chat_model
from dotenv import load_dotenv

load_dotenv(override=True)

model = init_chat_model(
    model="deepseek:deepseek-chat",   # 提供商:模型名
    temperature=0.7,
)

对比一下，如果你不用 init_chat_model，切换模型要写完全不同的类：

# 不用 init_chat_model 的写法：每家模型一个类
from langchain_deepseek import ChatDeepSeek
deepseek_llm = ChatDeepSeek(model="deepseek-chat")

from langchain_openai import ChatOpenAI
openai_llm = ChatOpenAI(model="gpt-4o")

from langchain_ollama import ChatOllama
ollama_llm = ChatOllama(model="qwen3:14b")

init_chat_model 的好处就是统一：改一行字符串，模型随便换。

5.4 调用模型：invoke

response = model.invoke("用一句话解释什么是 Agent")

print(response.content)
# 输出：Agent 是一个能自主规划并调用工具完成复杂任务的大模型应用。

invoke 返回的不只是文本，而是一个 AIMessage 对象，里面带着 token 消耗和元数据：

print(response.content)                     # 模型生成的文本
print(response.usage_metadata)              # token 统计（input/output/total）
print(response.response_metadata)           # 模型名、结束原因等原始元数据

生产环境里，token 统计是成本核算的基础，这个对象设计得很实用。

5.5 多轮对话：messages 列表

单次调用不需要记忆，但多轮对话需要把历史传回去。用字典列表构建消息，是生产环境推荐的做法：

messages = [
    {"role": "system", "content": "你是一个专业的搜索架构师。"},
    {"role": "user", "content": "RAG 的召回阶段要注意什么？"},
]

resp1 = model.invoke(messages)
print(resp1.content)

# 把 AI 的回答追加进对话，形成多轮
messages.append({"role": "assistant", "content": resp1.content})
messages.append({"role": "user", "content": "那精排阶段呢？"})

resp2 = model.invoke(messages)
print(resp2.content)

如果不把历史传回去，模型就会"失忆"：你上一轮刚说过的话，它这轮完全不知道。

5.6 流式输出：stream

聊天的体验要靠流式。stream 返回一个迭代器，可以逐 token 输出，用户不用等整段生成完：

for chunk in model.stream("写一段 100 字的商品文案"):
    print(chunk.text, end="", flush=True)

在聊天机器人、长文本生成场景，这个接口是提升体感的关键。

六、动手：从对话到 Agent

模型调用是地基，Agent 才是 LangChain 真正发力的地方。1.x 里构建 Agent 的标准入口是 create_agent。

6.1 定义一个工具

先用 @tool 装饰器定义一个工具。1.x 支持 Pydantic Schema 定义参数，类型安全：

from langchain.tools import tool

@tool
def get_stock_price(symbol: str) -> str:
    """查询股票的实时价格。"""
    # 这里接你的行情 API
    return f"{symbol} 当前价格: 128.5 元"

6.2 创建 Agent

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

model = init_chat_model("deepseek:deepseek-chat")

agent = create_agent(
    model=model,
    tools=[get_stock_price],
    system_prompt="你是一个专业的金融助手，回答要简洁准确。",
)

response = agent.invoke({"messages": [{"role": "user", "content": "帮我查一下宁德时代的价格"}]})

for message in response["messages"]:
    print(f"{message.type}: {message.content}")

注意这里的 Agent 和旧版 AgentExecutor 的关键区别：底层是 LangGraph 驱动的，工具调用、多轮推理、状态流转都是显式的。想看到 Agent 内部怎么思考，response["messages"] 里每一步都有记录。

6.3 什么时候升级到 LangGraph

create_agent 解决的是"够用"的问题。当你的流程出现这些需求时，就该上 LangGraph 的 StateGraph 自己画图了：

  • 需要人工审核节点（human-in-the-loop）
  • 需要条件分支和循环
  • 需要跨进程的状态持久化（checkpoint）
  • 需要多个 Agent 协作

这些是后续系列第 7 篇的重点，这里先留个印象：从 create_agent 到 StateGraph，是 LangChain 学习路径上的第二道分水岭。

七、过期教程鉴别清单

最后给你一个判断标准，帮你避开市面上的坑：

判断线索 结论
出现 AgentExecutor 或 initialize_agent 旧内容，跳过
出现 LLMChain、PromptTemplate 链式写法 0.x 时代的写法，对照官方文档甄别
import 来自 langchain.agents 旧式入口 1.0 前的写法
文章发布于 2025 年 10 月之前 需要对照新文档甄别
教你 init_chat_model、create_agent、StateGraph 新内容，放心学

八、系列地图与结语

回到开头那段报错。那个作者后来把代码换成了 create_agent，半小时就通了。其实把代码换成新 API 就好，真正拦人的，是压根不知道旧路已经废弃。

2026 年学 LangChain，先忘掉旧教程。这种变化恰恰说明框架还在快速进化，值得投入时间。

这个系列会沿着四大支柱展开，排成 12 篇 4 个阶段：筑基、核心功、进阶、产线。每篇一张架构图、一张决策表、一段能跑的代码。

筑基：组件地图（本篇）→ 模型 I/O → 结构化输出
核心功：RAG 实战 → Agent 循环 → 工具定义
进阶：LangGraph 状态机 → MCP 接入 → 多 Agent 演进
产线：LangSmith 评测 → 生产部署 → 收官 Demo

下一篇，我们来拆模型 I/O 和结构化输出：怎么让 AI 稳定返回你想要的 JSON，而不是一段自由发挥的文字。

关注我，跟着一个在产线上跑过 Search Agent 的老后端，把 LangChain 学明白。

本站笔记除注明转载/出处外，皆为作者原创；转载时请保留来源说明。