🦜🔗 LangChain 零基础详解教程
从"大模型是什么"讲到"能自己干活、能查资料、能记住对话的智能体"。每一行代码都有解释、有预期运行结果,跟着抄一遍就能跑。
本教程基于 官方一手资料 编写:LangChain 官方 GitHub 仓库、docs.langchain.com 官方文档(1.0 版)、官方 v1.0 发布公告、arXiv 原始论文(ReAct、RAG)等,全部来源见文末"参考资料"。
第 0 章开始之前
0.1 为什么需要这本教程
网上关于 LangChain 的教程有一个普遍问题:版本太旧或太碎。LangChain 在 2025 年 10 月 22 日发布了划时代的 1.0 正式版(与 LangGraph 1.0 同日发布),大量旧教程里的写法(比如 LLMChain、AgentExecutor)在 1.0 里已经被移走或删除,照着旧教程抄代码会满屏报错。
本教程的三个承诺:
- 只讲官方 1.0 的新写法:所有核心代码都对照官方文档(docs.langchain.com)和官方 GitHub 仓库核对过。
- 假设你什么都不会:每个概念先讲"人话版"解释和生活化比喻,再讲代码;每段代码都告诉你它做了什么、运行后会看到什么。
- 可以完全跟着做:环境安装、报错排查、常见坑都写清楚了,遇到问题先翻第 12 章 FAQ。
0.2 如何使用本教程
- 先通读第 1 章(不用电脑),搞懂大模型和 LangChain 的基本概念,这一章决定了后面所有内容你能不能"看得懂"。
- 跟着第 2 章把环境搭好,并成功运行第一个程序。这是最重要的一步,环境通了,后面就顺了。
- 按章节顺序学第 3~9 章,每章都动手把代码抄一遍、跑一遍。第 3~6 章是地基(模型、提示词、结构化输出、链),第 7~9 章是三栋大楼(智能体、记忆、RAG)。
- 第 10~13 章按需选学,做完第 13 章的三个实战项目,你就超过 90% 的入门者了。
- 卡住了就查第 12 章 FAQ 和附录术语表。
☰ 按钮或按键盘 S 键;每个章节目录也可以点章节名展开 / 折叠;目录顶部还有搜索框可以快速过滤章节。代码块右上角有"复制"按钮。右上角 🌙 可切换深色模式。0.3 开始前你要准备什么
- 一台电脑(Windows / macOS / Linux 都行,本教程对 Windows 用户格外照顾)。
- 能上网(安装软件包和调用模型 API 都需要)。
- 一个模型服务的 API Key(第 2 章会手把手教申请;也有完全免费不联网的本地方案,见 2.6 节)。
- 初中级 Python 基础:会变量、函数、字典、import 就够了。不会也没关系,代码里的注释非常详细。
📝 第 0 章自测(点击展开答案)
LLMChain 写法在本教程里还能用吗?答:不能直接用。LangChain 1.0 把旧的链和 Agent 类移到了兼容包
langchain-classic 中,官方推荐新代码一律使用本教程讲的新写法(create_agent、LCEL 管道等)。第 1 章初识 LangChain
1.1 先搞懂:大模型到底是个啥
几个关键事实(后面每一条都对应 LangChain 的一个功能模块):
| 大模型的事实 | 人话解释 | LangChain 对应的解决方案 |
|---|---|---|
| 只输出纯文字 | 它回的是一段话,不是能直接被程序用的数据 | 第 5 章 结构化输出 |
| 没有记忆 | 每次调用都是"失忆"的,上一轮说过什么它不知道 | 第 8 章 记忆 |
| 知识有截止日期 | 训练完之后发生的事它一概不知 | 第 9 章 RAG(让它现查资料) |
| 不能动手 | 它不能帮你查天气、发邮件、算数 | 第 7 章 工具与智能体 |
| 不同家模型 API 完全不同 | OpenAI、Anthropic、DeepSeek…每家接口格式都不一样 | 第 3 章 统一模型接口 |
1.2 直接调 API 的痛点
假设你想做一个"能查询公司文档的客服机器人",直接用模型 API 的话,你要自己解决:
- 不同厂商 API 格式不同,换模型 = 重写一遍调用代码;
- 想让它输出 JSON?要自己写提示词约束 + 自己解析 + 自己处理解析失败;
- 想让它查资料?要自己实现文档解析、切分、向量化、相似度检索整套流程;
- 想让它"先想后做、调用工具、再继续想"?要自己写循环逻辑(这就是"智能体");
- 多轮对话的记忆、出错重试、调试时看不到模型内部发生了什么……全是自己写。
这些"脏活累活",就是 LangChain 帮你干的。
1.3 LangChain 是什么
官方定义(来自官方文档 docs.langchain.com):LangChain 提供 create_agent —— 一个"极简但高度可配置的智能体框架(a minimal, highly configurable agent harness)"。官方给出的核心公式是:
其中 harness(挽具,原意是套在马身上让马拉车的那套装备)= 提示词(prompt)+ 工具(tools)+ 中间件(middleware)——也就是"围着模型转的那一圈基础设施"。
它是一个开源项目(MIT 协议),主仓库 langchain-ai/langchain 在 GitHub 上已有约 14.7 万颗 star,是 LLM 应用领域事实上的标准框架之一。
1.4 LangChain 不是什么
- 不是模型:它本身不是大模型,不提供智能;它是"使用模型的框架"。没有模型 API Key,LangChain 什么都干不了。
- 并非只有 Python 版:它同时提供 JavaScript/TypeScript 版本(仓库 langchain-ai/langchain-js),本教程讲 Python 版。
- 不是万能药:简单场景(比如就调一次 API)不需要 LangChain;但它能在你项目长大后省下大量工程化时间。
1.5 发展史与 1.0 时代
| 时间 | 事件 | 对你的影响 |
|---|---|---|
| 2022 年 10 月 | Harrison Chase 发布 LangChain 首个版本(ChatGPT 发布前两周,堪称先行者) | — |
| 2023 年 | 伴随 ChatGPT 热潮爆发式增长;LangChain 公司成立并获红杉等投资;推出 LangSmith(观测评估平台) | 旧教程大多是这个时代的(已过时) |
| 2024 年 | v0.1 → v0.2(拆分出 langchain-core)→ v0.3(适配 Pydantic v2);推出 LangGraph(图式编排) | 网上教程 0.x 写法混杂 |
| 2025 年 10 月 22 日 | LangChain 1.0 与 LangGraph 1.0 同日发布正式版,官方称之为"第一个大版本",API 承诺长期稳定 | 本教程所讲版本 |
- 旧的
LLMChain、ConversationChain、AgentExecutor、create_react_agent等已从主包移除,整体搬进了兼容包langchain-classic; - 1.0 的主包聚焦于:智能体(create_agent)+ 标准模型接口 + LCEL;
- 新建智能体的官方标准写法是
from langchain.agents import create_agent。
1.6 生态全景图
LangChain 官方生态由几部分组成(都是官方出品,不是第三方):
| 成员 | 是什么(人话) | 什么时候用 |
|---|---|---|
langchain | 主角:智能体框架 + 标准接口(本教程主角) | 几乎所有项目 |
langchain-core | 地基:基础抽象(消息、提示词、Runnable 接口),其他包都基于它 | 被动安装,import 常用 |
langchain-*(伙伴包) | 各家模型的适配器,如 langchain-openai、langchain-anthropic、langchain-deepseek、langchain-ollama | 用哪家装哪家 |
langchain-community | 社区贡献的第三方集成大集合(各类文档加载器、向量库等) | 用到再装 |
| LangGraph | 底层编排框架:用"图"精确控制流程,支持持久化、断点恢复、人工介入;LangChain 1.0 的智能体就构建在它之上 | 复杂流程、生产级智能体(第 10 章) |
Deep Agents(deepagents) | "全家桶"高级智能体:自带规划、子智能体、虚拟文件系统 | 复杂任务想开箱即用 |
| LangSmith | 官方"监控摄像头 + 阅卷老师":追踪每次调用细节、做评估 | 调试与上线(第 11 章) |
1.7 官方一手资料汇总(本教程的信息来源)
| 资料 | 地址 | 说明 |
|---|---|---|
| 官方 GitHub 主仓库 | github.com/langchain-ai/langchain | 源码、README、发版记录(MIT 开源) |
| 官方文档(Python) | docs.langchain.com | 教程、概念、操作指南(1.0 统一文档站) |
| API 参考手册 | reference.langchain.com/python | 每个类和函数的详细签名 |
| 官方博客 / 发布公告 | langchain.com/blog | LangChain & LangGraph 1.0 发布公告(2025-10-22) |
| LangChain Academy | academy.langchain.com | 官方免费课程 |
| ReAct 原始论文 | arxiv.org/abs/2210.03629 | 智能体"边想边做"模式的理论源头(第 7 章详解) |
| RAG 原始论文 | arxiv.org/abs/2005.11401 | 检索增强生成的开山之作(第 9 章详解) |
| 社区论坛 | forum.langchain.com | 官方论坛,提问好去处 |
📝 第 1 章自测(点击展开答案)
② Agent = 什么 + 什么?——官方公式:Agent = Model + Harness(模型 + 挽具;挽具 = 提示词 + 工具 + 中间件)。
③ 1.0 正式版什么时候发布?——2025 年 10 月 22 日,与 LangGraph 1.0 同日。
第 2 章动手前的准备
2.1 安装 Python
LangChain 1.0 要求 Python 3.10 或更高版本(建议 3.10~3.13)。
- 先检查有没有装过:打开终端(Windows 按
Win+R输入powershell回车;macOS 打开"终端"),输入:终端命令python --version如果显示
Python 3.10以上(比如本教程作者的机器显示Python 3.13.12),直接跳到 2.2 节。 - 没有就去官网下载:python.org/downloads,下载 3.12.x 安装包。
- Windows 用户务必勾选:安装第一步界面底部的 "Add python.exe to PATH"(把 Python 加入环境变量),再点 Install Now。这是新手第一大坑!
- 装完关掉终端重新打开,再执行
python --version验证。
2.2 创建虚拟环境(为什么需要 & 怎么做)
选一个你放代码的目录(例如 Windows 下 D:\code),执行:
# 1. 建一个项目文件夹(名字随便,这里叫 langchain-tutorial)
mkdir langchain-tutorial
cd langchain-tutorial
# 2. 创建名为 .venv 的虚拟环境(只需做一次)
python -m venv .venv
# 3. 激活虚拟环境(每次开新终端都要做!)
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Windows (cmd):
.venv\Scripts\activate.bat
# macOS / Linux:
source .venv/bin/activate(.venv) 字样。以后每次打开新终端写这个项目的代码,都要先执行第 3 步的激活命令。如果 PowerShell 提示"禁止运行脚本",以管理员打开 PowerShell 执行一次:Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。2.3 安装 LangChain
在激活了虚拟环境的终端里执行(官方文档给出的安装命令):
# 官方推荐安装命令(-U 表示升级到最新)
pip install -qU langchain "langchain[openai]"
# 国内网络慢可换清华镜像源:
pip install -qU langchain "langchain[openai]" -i https://pypi.tuna.tsinghua.edu.cn/simple
# 如果用 uv(更快的现代包管理器,官方 GitHub README 同样给出):
# pip install uv 然后执行 uv add langchain这条命令会装上:langchain 主包、langchain-core 地基包、langchain-openai 模型适配包,以及依赖的 langgraph、langsmith 等。
验证安装:
pip show langchain
# 应显示 Version: 1.x.x(1.0 以上即为 1.0 正式版)
pip list | findstr langchain # Windows;macOS/Linux 用 pip list | grep langchain2.4 包结构解密(装的是什么、import 该从哪来)
| 包名 | 角色 | 常用 import 举例 |
|---|---|---|
langchain-core | 地基:消息、提示词模板、Runnable 接口、结构化输出 | from langchain_core.messages import HumanMessage(1.0 也可写 from langchain.messages import ...) |
langchain | 主角:create_agent、init_chat_model、中间件 | from langchain.agents import create_agent |
langchain-openai 等 | 各家模型适配器(伙伴包) | from langchain_openai import ChatOpenAI |
langchain-community | 社区集成(部分文档加载器等) | from langchain_community.document_loaders import TextLoader |
langchain-text-splitters | 文本切分(RAG 用) | from langchain_text_splitters import RecursiveCharacterTextSplitter |
langgraph | 图编排(create_agent 的底层、第 10 章主角) | from langgraph.checkpoint.memory import InMemorySaver |
langsmith | 追踪与评估(第 11 章) | 一般只需环境变量,无需 import |
langchain-classic | 1.0 移出的旧版功能(单独安装) | 只用于跑旧代码,新项目别用 |
2.5 配置模型 API Key(三种方案任选其一)
LangChain 不是模型,你需要一个"模型服务商"。就像打印机需要接墨盒,选一个:
方案 A:OpenAI(国际主流)
- 到 platform.openai.com 注册并创建 API Key(以
sk-开头)。 - 设置环境变量(LangChain 会自动读取):
终端命令
# PowerShell(当前窗口有效): $env:OPENAI_API_KEY = "sk-你的密钥" # macOS / Linux: export OPENAI_API_KEY="sk-你的密钥" - 更推荐写进项目根目录的
.env文件(一劳永逸):文件:.env(放在项目根目录)OPENAI_API_KEY=sk-你的密钥然后在代码开头加载它(需先
pip install python-dotenv):Pythonfrom dotenv import load_dotenv load_dotenv() # 读取 .env 文件,把里面的键值注入环境变量。必须在最前面调用
方案 B:DeepSeek 等国产模型(国内用户友好)
到 platform.deepseek.com 注册获取 Key,安装适配包并配置:
# 终端安装:pip install -qU langchain-deepseek
# .env 文件里写:DEEPSEEK_API_KEY=sk-你的密钥
from langchain_deepseek import ChatDeepSeek
llm = ChatDeepSeek(model="deepseek-chat") # 自动读取 DEEPSEEK_API_KEY 环境变量方案 C:本地开源模型(完全免费、断网可用,见 2.6)
2.6 不花钱的本地方案:Ollama
- 到 ollama.com 下载安装 Ollama。
- 终端执行:
ollama pull qwen3:4b(下载通义千问 4B 小模型,约 3GB;配置好的机器可下qwen3:8b)。 - 安装适配包:
pip install -qU langchain-ollama。
from langchain_ollama import ChatOllama
llm = ChatOllama(model="qwen3:4b") # 使用本地已下载的模型,无需任何 Key2.7 第一个程序:跟大模型说 Hello
官方文档与 GitHub README 的第一个示例使用 init_chat_model(一个"万能初始化器",按 厂商:模型名 字符串自动加载对应适配器):
# -*- coding: utf-8 -*-
"""我的第一个 LangChain 程序:向大模型问好"""
from dotenv import load_dotenv
load_dotenv() # 从 .env 加载 API Key(用 Ollama 的可删掉这行)
from langchain.chat_models import init_chat_model
# ① 创建模型:字符串格式为 "厂商:模型名"
# 用 OpenAI 就写 "openai:gpt-4o-mini"(便宜快速)
# 用 DeepSeek 就写 "deepseek:deepseek-chat"
# 用本地 Ollama 就写 "ollama:qwen3:4b"
llm = init_chat_model("openai:gpt-4o-mini")
# ② 调用:把一句话发给模型,返回结果
result = llm.invoke("用一句话向一位刚装好 LangChain 的初学者表示祝贺")
# ③ 打印模型回复的文字内容
print(result.text) # 1.0 推荐用 .text;旧写法 result.content 依然可用python hello_langchain.pyopenai: / anthropic:(Claude)/ google_genai:(Gemini)/ deepseek: / ollama: / bedrock_converse:(AWS)等。前提是对应伙伴包已安装(langchain[openai] 已含 openai)。2.8 安装报错急救室
| 症状 | 原因 | 解法 |
|---|---|---|
'python' 不是内部或外部命令 | 装 Python 时没勾 Add to PATH | 重装并勾选;或用 py --version 试试 |
ModuleNotFoundError: No module named 'langchain' | 没激活虚拟环境,或装到了别的环境 | 先激活 .venv 再 pip install(见 2.2) |
| pip 下载超时 / 反复重试 | 网络问题 | 加清华镜像参数(见 2.3) |
pip install 报权限错误 | 往系统 Python 硬装 | 务必在虚拟环境内安装 |
| Jupyter 里 import 失败 | Jupyter 内核用的不是这个环境 | 在虚拟环境里:pip install ipykernel 然后 python -m ipykernel install --user --name=lc,并在 Jupyter 中切换内核为 lc |
| 装出来的 langchain 是 0.x | pip 源缓存太旧 | pip install -U langchain 强制升级;检查 pip show langchain |
📝 第 2 章自测(点击展开答案)
init_chat_model("openai:gpt-4o-mini") 里的 "openai" 是什么意思?——厂商前缀,告诉 LangChain 用哪个适配包来连接模型。② 为什么推荐虚拟环境?——项目间依赖隔离,避免包版本互相打架。
③ API Key 应该写在哪?——环境变量或 .env 文件,绝不要硬编码进代码上传到 Git。
第 3 章与大模型对话:Chat Model
3.1 统一模型接口:换模型不改代码
第 2 章你已经用 init_chat_model 跑通了第一次对话。它的意义在于统一:不管底层是 OpenAI、DeepSeek 还是本地 Ollama,调用方式完全一样。今天用 A 家,明天想试 B 家,改一个字符串就行:
from langchain.chat_models import init_chat_model
# 三种模型,同一套用法(选你有 Key 的那个运行)
llm = init_chat_model("openai:gpt-4o-mini")
# llm = init_chat_model("deepseek:deepseek-chat")
# llm = init_chat_model("ollama:qwen3:4b")也可以直接使用具体适配器的类(效果等价,好处是能用该厂商特有参数):
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini") # 自动读取 OPENAI_API_KEYllm 只是习惯。3.2 三种消息类型:对话的"角色剧本"
from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
from langchain.messages import SystemMessage, HumanMessage
# 若提示找不到,可改为:from langchain_core.messages import SystemMessage, HumanMessage
llm = init_chat_model("openai:gpt-4o-mini")
# 剧本:一条导演指令 + 一条观众提词
messages = [
SystemMessage(content="你是一位说话简短、风趣的编程老师。"), # 设定人设,只出现一次
HumanMessage(content="什么是 RAG?"), # 用户的问题
]
response = llm.invoke(messages) # 把整个剧本递给模型
print(response.text) # .text 取出回复的纯文字消息对象常用属性:.content(文字内容)、.response_metadata(厂商返回的元信息)、.usage_metadata(token 消耗)。回复对象(AIMessage)还有 .tool_calls(第 7 章的主角)和 1.0 新增的 .content_blocks(统一格式的内容块)。
3.3 常用参数:温度、上限等
llm = init_chat_model("openai:gpt-4o-mini", temperature=0)
# temperature(温度):"随机度"旋钮,范围 0~2
# 0 → 最稳定,适合抽取、分类、写代码(生产环境常用)
# 0.7 → 默认,日常对话
# 1.5+ → 天马行空,适合头脑风暴,也更容易胡说
# max_tokens:限制回复的最大长度(省钱的直接手段)
llm2 = init_chat_model("openai:gpt-4o-mini", temperature=0, max_tokens=200)3.4 流式输出:打字机效果
网页上 ChatGPT 那种"一个字一个字往外蹦"的效果就是流式。把 invoke 换成 stream,逐段打印:
from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
llm = init_chat_model("openai:gpt-4o-mini")
# stream 返回一个"生成器":每次循环给一小块文字
for chunk in llm.stream("用 100 字讲讲为什么程序员工资高"):
print(chunk.text, end="", flush=True) # end="" 不换行、flush=True 立即显示
print() # 最后补一个换行3.5 批量处理:一次问一百个问题
questions = ["一句话介绍 Python", "一句话介绍 Java", "一句话介绍 Go"]
answers = llm.batch(questions) # 底层自动并发,比 for 循环逐个 invoke 快
for q, a in zip(questions, answers):
print(q, "→", a.text[:30], "…")llm.invoke(输入) 同步问一次;llm.stream(输入) 流式;llm.batch(列表) 批量。第 6 章会看到:这套三件套是 LangChain 所有组件(提示词、链、智能体)通用的标准接口。📝 第 3 章自测(点击展开答案)
② temperature=0 适合什么场景?——需要稳定输出的场景:信息抽取、分类、结构化生成。
③ 想要打字机效果用哪个方法?——stream(),逐块接收并打印。
第 4 章提示词模板:Prompt Template
4.1 为什么需要模板
假设你要做一个"公司名起名器",用户输入产品描述,你生成名字。不用模板的写法:
product = "会自动浇花的花盆"
prompt = "你是一位起名大师。请给这个产品起 3 个好名字:" + product
result = llm.invoke(prompt)能跑,但问题很多:拼接容易漏空格、没有类型检查、换个地方写又是一遍、没法复用。模板的思路是——把提示词做成"带填空的试卷",运行时只填空:
4.2 ChatPromptTemplate:最常用的模板
from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
from langchain_core.prompts import ChatPromptTemplate
llm = init_chat_model("openai:gpt-4o-mini")
# ① 定义模板:消息列表,每条是 (角色, 内容);{花括号} 里是变量名
prompt = ChatPromptTemplate.from_messages([
("system", "你是一位资深品牌起名专家,起的名字要朗朗上口、便于注册商标。"),
("human", "请给产品「{product}」起 3 个中文名字,目标人群是{audience}。"),
])
# ② 填空:传入变量的值,得到真正的消息列表
filled = prompt.invoke({"product": "会自动浇花的花盆", "audience": "忙碌的上班族"})
print(filled.to_messages()) # 先看看填好后的"剧本"长什么样
# ③ 交给模型
response = llm.invoke(filled)
print(response.text)prompt.invoke() 时若忘了传某个变量,会直接抛出 KeyError 并明确告诉你是哪个变量没传,比手写拼接可靠得多——这正是模板的价值之一。若提示词里需要输出字面花括号(如 JSON 示例),写成双花括号 {{ }}。4.3 MessagesPlaceholder:给聊天历史留个座位
做多轮对话时,历史消息数量不定,没法写死在模板里。占位符 MessagesPlaceholder 就是"这里插入一段消息列表,具体几条运行时再定":
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.messages import HumanMessage, AIMessage
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个耐心的数学老师。"),
MessagesPlaceholder("chat_history"), # ← 历史消息将插入这里,可为空列表
("human", "{question}"),
])
filled = prompt.invoke({
"chat_history": [
HumanMessage(content="1+1 等于几?"),
AIMessage(content="等于 2。"),
],
"question": "那再加 3 呢?", # 模型结合历史能明白"再加"指 2+3
})
print(filled.to_messages())chat_history 适合小脚本;做正经应用时用第 8 章的 checkpointer 自动管理记忆,原理相同但更省心。4.4 Few-shot:给模型"看例题"
from langchain_core.prompts import FewShotChatMessagePromptTemplate, ChatPromptTemplate
# 每道"例题"的格式
example_prompt = ChatPromptTemplate.from_messages([
("human", "{input}"),
("ai", "{output}"),
])
examples = [
{"input": "今天天气真好", "output": "正面"},
{"input": "这服务太差劲了", "output": "负面"},
{"input": "还行吧,一般般", "output": "中性"},
]
few_shot = FewShotChatMessagePromptTemplate(
example_prompt=example_prompt,
examples=examples,
)
prompt = ChatPromptTemplate.from_messages([
("system", "你是情感标注员,只输出:正面/负面/中性 三个词之一。"),
few_shot, # 例题统一插入这里
("human", "{text}"), # 新题
])
chain = prompt | llm # llm 沿用 3.1 节的定义;管道符先混个脸熟,第 6 章详解
print(chain.invoke({"text": "快递员小哥人超好!"}).text)4.5 提示词最佳实践(官方与实战共识)
- System 设人设和规则,Human 放具体输入——分工清晰;
- 规则越具体越好:"要简洁"不如"用不超过 50 字回答";
- 要结构就给样例:想要 JSON/表格,直接在提示词里给一个范例;
- 复杂任务拆步骤:"先列要点,再总结"比"总结一下"效果好;
- 把提示词当代码管理:改动要记录版本,效果差异要测试(第 11 章 LangSmith 评估)。
📝 第 4 章自测(点击展开答案)
{变量名},调用 invoke 时用字典传值。② 聊天历史数量不定怎么办?——用 MessagesPlaceholder 占位。
③ few-shot 是什么?——在提示词里附上少量"例题+答案",让模型模仿格式与思路。
第 5 章结构化输出:让模型吐出能用
5.1 为什么不能只要字符串
真实业务里,模型的回答往往要喂给程序继续处理:提取出的邮箱要存数据库、分类结果要走 if 判断、评价要画图表。如果只拿到一段"人话",你就得写一堆脆弱的正则去抠字段。结构化输出让模型直接"按表格交作业"。
5.2 用 Pydantic 定义"表格格式"
Pydantic 是 Python 生态标准的数据校验库(LangChain 依赖它),用"类 + 字段类型 + 说明"描述你想要的输出格式:
from pydantic import BaseModel, Field
class MovieReview(BaseModel):
"""一部电影的影评分析结果""" # ← 类的 docstring 会成为给模型的整体说明
movie_name: str = Field(description="电影名称")
score: int = Field(description="评分,1 到 10 的整数")
verdict: str = Field(description="一句话总结,不超过 20 字")
tags: list[str] = Field(description="标签列表,2 到 4 个,如 ['科幻','烧脑']")5.3 with_structured_output:一行开启结构化模式
from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
from pydantic import BaseModel, Field
class MovieReview(BaseModel):
movie_name: str = Field(description="电影名称")
score: int = Field(description="评分,1 到 10 的整数")
verdict: str = Field(description="一句话总结")
tags: list[str] = Field(description="2 到 4 个标签")
llm = init_chat_model("openai:gpt-4o-mini")
# 关键一行:给模型"戴上格式眼镜"
structured_llm = llm.with_structured_output(MovieReview)
result = structured_llm.invoke("帮我分析电影《流浪地球 2》:口碑不错,特效震撼,剧情略长")
print(type(result)) # <class 'MovieReview'> —— 不再是字符串!
print(result.movie_name) # 流浪地球2 —— 直接当对象属性用
print(result.score) # 9
print(result.tags) # ['科幻', '特效', '史诗']
print(result.score >= 8) # True —— 可以直接参与程序逻辑判断背后发生的事:LangChain 把你的 Pydantic 类转换成"工具定义"(或 JSON Schema)发给模型,模型按格式返回 JSON,LangChain 再校验并转换成 Python 对象。解析失败会自动抛错,你可以捕获后重试。
with_structured_output 需要模型支持"函数/工具调用"或 JSON 模式——主流商用模型都支持;非常小的本地模型可能支持不佳。老教程里的 PydanticOutputParser 组合已随旧链移入 langchain-classic,新代码请一律用本节写法。5.4 智能体里的结构化输出:response_format
第 7 章的智能体同样支持结构化,但参数位置不同——传给 create_agent 的 response_format,结果从返回值的 structured_response 字段取:
from langchain.agents import create_agent
agent = create_agent(
model="openai:gpt-4o-mini",
tools=[...], # 智能体可以先用工具干活
response_format=MovieReview, # 最后按这个格式"交作业"
)
result = agent.invoke({"messages": [{"role": "user", "content": "分析电影《奥本海默》"}]})
result["structured_response"] # ← 结构化结果在这里📝 第 5 章自测(点击展开答案)
② 普通模型与智能体取结构化结果的位置?——普通模型:
with_structured_output 的返回值直接是对象;智能体:result["structured_response"]。③ Field(description=...) 的作用?——告诉模型每个字段怎么填,直接提升准确率。
第 6 章LCEL 与链:把组件串成流水线
|,掌握 Runnable 标准接口,理解"链"为什么是 LangChain 的灵魂设计。6.1 一切皆 Runnable
LangChain 里所有组件——提示词模板、模型、输出解析器、检索器、智能体——都实现同一套接口 Runnable,统一暴露三个方法:
| 方法 | 作用 | 类比 |
|---|---|---|
invoke(x) | 喂一个输入,拿一个输出 | 洗衣机洗一件 |
batch([x1,x2]) | 喂一批,拿一批(自动并发) | 一次洗一筐 |
stream(x) | 边干边吐结果 | 洗的过程中随时看进度 |
因为接口统一,任何组件都能互相拼接——这就是"链"(Chain)这个名字的由来。
6.2 管道符 | :把组件串成流水线
A | B 读作"A 干完的活交给 B",就像工厂流水线:原料(用户输入)→ 工位 A(模板填空)→ 工位 B(模型生成)→ 工位 C(加工包装)。from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
from langchain_core.prompts import ChatPromptTemplate
llm = init_chat_model("openai:gpt-4o-mini")
# 用模板 + 模型拼一条最经典的流水线
prompt = ChatPromptTemplate.from_messages([
("system", "你是一位爱用比喻的科普作者。"),
("human", "用 100 字向{audience}解释什么是{concept}。"),
])
chain = prompt | llm # ← 流水线:先填空,再生成
# 调用整条链:传的是模板需要的变量
result = chain.invoke({"audience": "小学生", "concept": "人工智能"})
print(result.text)可以继续往后接工位。常见的是接一个"加工函数",用 RunnableLambda 把普通函数变成流水线工位:
from langchain_core.runnables import RunnableLambda
def shout(text_obj):
return text_obj.text.upper() + "!!!"
chain = prompt | llm | RunnableLambda(shout) # 三段流水线
chain.invoke({"audience": "小学生", "concept": "云计算"})6.3 invoke / stream / batch:整条链通用
美妙之处来了:链本身也是 Runnable,所以三件套对整条链直接可用:
chain = prompt | llm
chain.invoke({"audience": "程序员", "concept": "RAG"}) # 一次性拿结果
for chunk in chain.stream({"audience": "程序员", "concept": "RAG"}):
print(chunk.text, end="", flush=True) # 流式
chain.batch([{"audience": "小学生", "concept": "引力"},
{"audience": "老人", "concept": "疫苗"}]) # 批量a —— ainvoke / astream / abatch。写 FastAPI 网络服务或并发脚本时用它们,避免阻塞。本教程只演示同步版,概念完全一致。6.4 并行与编排:RunnableParallel / RunnablePassthrough
想同时从不同角度提问再汇总?RunnableParallel 让多条支线并行执行:
from langchain_core.runnables import RunnableParallel, RunnableLambda
double = RunnableLambda(lambda x: x * 2)
plus1 = RunnableLambda(lambda x: x + 1)
# 名为 a、b 的两条支线同时跑,结果按名字汇总成字典
para = RunnableParallel(a=double, b=plus1)
print(para.invoke(5)) # {'a': 10, 'b': 6}RunnablePassthrough 则是"直通管道"——原样把输入传下去,常用来在并行时保留原始输入(RAG 里极常用,第 9 章会再见到它):
from langchain_core.runnables import RunnablePassthrough
p = RunnableParallel(原文=RunnablePassthrough(), 处理过=RunnableLambda(lambda x: x + "!"))
print(p.invoke("hi")) # {'原文': 'hi', '处理过': 'hi!'}6.5 重试与降级:生产环境的保命符
# with_retry:失败自动重试(网络抖动、限流时救命)
safe_chain = chain.with_retry(stop_after_attempt=3)
# with_fallbacks:主模型挂了自动切换备用模型
main_llm = init_chat_model("openai:gpt-4o-mini")
backup_llm = init_chat_model("deepseek:deepseek-chat")
robust_llm = main_llm.with_fallbacks([backup_llm])6.6 旧版 Chain 去哪了
你在旧教程里看到的 LLMChain、SequentialChain、ConversationChain 等类,在 1.0 中已移入兼容包 langchain-classic。对照一下:
# 旧(0.x):
from langchain.chains import LLMChain
chain = LLMChain(llm=llm, prompt=prompt)
# 新(1.0 / LCEL):功能相同,且天然获得 stream/batch/重试/异步全套能力
chain = prompt | llm| 串行、RunnableParallel 并行;③拼好的链自动拥有 invoke/stream/batch/重试/异步。此后你看到的 RAG 链、智能体,都是这套积木的组合。📝 第 6 章自测(点击展开答案)
prompt | llm 表示什么?——模板填空后的消息直接交给模型(串行流水线)。② 想同时跑两条支线用什么?——RunnableParallel。
③ 旧教程的
LLMChain 在 1.0 里怎么办?——已移到 langchain-classic 兼容包,新代码用 LCEL 写法。
第 7 章工具与智能体:Agent
create_agent 造出一个"会自己动手干活"的 AI。7.1 智能体到底是什么
前面的章节里,模型只会一件事:你问,它答。智能体则更进一步——官方文档的定义非常直白:
7.2 ReAct:智能体的工作原理(来自论文)
这个"做一步看一步"的模式有正式名字:ReAct,来自 2022 年 10 月的论文《ReAct: Synergizing Reasoning and Acting in Language Models》(Yao 等人,arXiv:2210.03629)。核心思想用论文的话说:让模型交错地生成"推理轨迹(Reasoning)"和"任务动作(Acting)":
- Thought(想):"我需要先查一下北京的天气" ——推理帮模型规划、应对意外;
- Action(做):调用工具 get_weather("北京") ——动作让模型能查询外部世界;
- Observation(看):"晴,28 度" ——工具返回的结果;
- 循环以上,直到模型认为可以给出最终答案(Final Answer)。
论文实验显示:在 HotpotQA、Fever 等任务上,ReAct 通过"简单的 Wikipedia API"显著减少幻觉;在 ALFWorld、WebShop 两个环境里,只用一两个示例就分别比 imitation/RL 方法高出 34% 和 10% 的绝对成功率。LangChain 早期的智能体就是 ReAct 的直接工程实现,今天的 create_agent 底层(LangGraph)本质仍是这个循环的升级版。
Thought: 用户问"北京适合穿什么",我得先知道天气 → 需要查天气
Action: get_weather(city="北京")
Observation: 晴,28°C,紫外线强
Thought: 有天气了,可以给出穿衣建议了
Final Answer: 北京今天晴,28 度,建议穿短袖,注意防晒。7.3 写一个工具:@tool 装饰器
工具就是一个带说明的 Python 函数。用 @tool 装饰器把普通函数变成 LangChain 工具:
from langchain.tools import tool
@tool
def get_weather(city: str) -> str:
"""查询指定城市今天的天气。当用户问到天气、气温、穿衣建议时调用。"""
# 这里可以是真实 API 调用;演示用假数据
fake_db = {"北京": "晴,28°C", "上海": "小雨,24°C", "广州": "雷阵雨,30°C"}
return fake_db.get(city, f"{city}:暂无天气数据")def 下面的三引号字符串(docstring)会被直接发给模型,模型完全靠它判断"这个工具是干嘛的、什么时候该用"。函数名、参数名、参数类型、docstring,共同构成工具的"简历"。写得含糊,模型就不知道何时用它、怎么传参——这是新手智能体"不调工具/乱调工具"的第一大原因。写完可以自己先验收一下工具的"简历":
print(get_weather.name) # get_weather
print(get_weather.description) # 查询指定城市今天的天气。当用户问到天气、气温、穿衣建议时调用。
print(get_weather.args_schema.model_json_schema())
# {'properties': {'city': {'description': ..., 'type': 'string'}}, 'required': ['city'], ...}7.4 create_agent:三行造出智能体(官方 1.0 标准写法)
下面是官方文档的完整示例,逐行讲解:
from dotenv import load_dotenv
load_dotenv()
from langchain.agents import create_agent # ← 1.0 的官方标准入口
# ① 定义工具(上一节的函数)
@tool
def get_weather(city: str) -> str:
"""查询指定城市今天的天气。当用户问到天气、气温、穿衣建议时调用。"""
fake_db = {"北京": "晴,28°C", "上海": "小雨,24°C"}
return fake_db.get(city, f"{city}:暂无天气数据")
# ② 创建智能体:模型 + 工具 + 系统提示词
agent = create_agent(
model="openai:gpt-4o-mini", # 直接用 "厂商:模型名" 字符串
tools=[get_weather], # 把工具交给它
system_prompt="你是一位贴心的生活助手,回答要简洁实用。",
)
# ③ 运行:输入是一个包含 messages 的字典
result = agent.invoke(
{"messages": [{"role": "user", "content": "北京今天适合穿什么?"}]}
)
# ④ 取出最后一条消息(模型的最终回答)
print(result["messages"][-1].text)
# 1.0 新增:content_blocks 是统一格式的内容块列表
print(result["messages"][-1].content_blocks)注意:你的代码里没有任何 for 循环。"思考→调工具→看结果"的循环是 create_agent 内部(LangGraph)自动完成的。如果用户问"1 加 1 等于几",模型会判断不需要天气工具,直接回答——用不用工具、用哪个,是模型自己决定的。
7.5 看懂运行轨迹:result 里到底有什么
把中间过程打印出来,你会看到消息列表记录了整个"思考-行动-观察"链条:
for msg in result["messages"]:
role = msg.type # human / ai / tool
if role == "ai" and msg.tool_calls:
for tc in msg.tool_calls: # 模型决定调用的工具
print("[AI 决定调用]", tc["name"], tc["args"])
elif role == "tool":
print("[工具返回]", msg.content)
else:
print(f"[{role}]", getattr(msg, 'text', msg.content))想"边跑边看"而不是等最后结果,用流式(官方文档还提供了更细粒度的 agent.stream_events(..., version="v3")):
# stream_mode="values":每走一步,吐出当前完整状态
for state in agent.stream(
{"messages": [{"role": "user", "content": "北京和上海哪个更热?"}]},
stream_mode="values",
):
state["messages"][-1].pretty_print() # 官方提供的友好打印方法7.6 中间件 Middleware:给智能体"加 buff"
1.0 的主扩展点是中间件——在模型调用前后、工具调用前后插入逻辑。官方内置了重试、PII 脱敏、人工审批等,用列表组合:
from langchain.agents import create_agent
from langchain.agents.middleware import (
ModelRetryMiddleware, # 模型调用失败自动重试
ToolRetryMiddleware, # 工具调用失败自动重试
HumanInTheLoopMiddleware, # 敏感操作先问人(见 7.7)
PIIMiddleware, # 自动识别/遮蔽个人敏感信息(邮箱等)
)
agent = create_agent(
model="openai:gpt-4o-mini",
tools=[get_weather],
middleware=[
ModelRetryMiddleware(max_retries=3),
ToolRetryMiddleware(max_retries=2),
PIIMiddleware("email"),
],
)7.7 人工审批:危险操作先问人
智能体能动工具,就可能"闯祸"(比如删除文件、转账)。HumanInTheLoopMiddleware 让指定工具在执行前暂停等人批准(需要配置持久化 checkpointer,见第 8 章):
from langgraph.checkpoint.memory import InMemorySaver # 这个导入在第 8 章详解
agent = create_agent(
model="openai:gpt-4o-mini",
tools=[send_email, delete_file], # 假设有这两个"危险"工具
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={"send_email": True, "delete_file": True}
# 字典里点名的工具:执行前必须人工确认
),
],
checkpointer=InMemorySaver(), # HITL 依赖状态持久化
)📝 第 7 章自测(点击展开答案)
② ReAct 的三要素?——Thought(想)/ Action(调工具)/ Observation(看结果),循环至 Final Answer。
③ 工具的 docstring 有什么用?——直接发给模型当使用说明书,决定模型会不会用、怎么用这个工具。
④ 1.0 创建智能体的标准函数?——
langchain.agents.create_agent。
第 8 章记忆:让智能体记住你说过的话
8.1 模型天生健忘
试试这个(不带记忆的普通调用):
llm.invoke("我叫小明,最喜欢的数字是 7")
llm.invoke("我叫什么名字?") # 模型:???你谁啊两次调用之间毫无关联——每次 invoke 对模型都是全新的一页纸。所谓"记忆",本质就是:把历史消息每次都一起发过去。历史要有人帮你存、帮你拼——这就是"记忆管理"。第 4 章的 MessagesPlaceholder 是手动方案;做应用用下面的自动方案。
8.2 Checkpointer 与 thread_id:两件套
- Checkpointer(检查点存储器):负责把每轮对话状态存下来。入门用
InMemorySaver(存内存里,程序重启就没);生产用数据库版(如 SqliteSaver / PostgresSaver,重启不丢)。 - thread_id(会话 ID):区分"和谁的哪段对话"。同一个 thread_id 的消息会被自动续上。
官方文档原话:用 thread_id 持久化对话历史,前提是智能体配置了 checkpointer。
8.3 多轮对话完整示例(可直接跑)
from dotenv import load_dotenv
load_dotenv()
from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from langchain_core.utils.uuid import uuid7
# 创建带记忆的智能体:多传一个 checkpointer
agent = create_agent(
model="openai:gpt-4o-mini",
tools=[],
system_prompt="你是一位话不多但记性很好的朋友。",
checkpointer=InMemorySaver(), # ← 记忆的本体
)
# 每个对话一个 thread_id(同一个对话全程复用)
config = {"configurable": {"thread_id": str(uuid7())}}
# 第一轮:告诉它我的信息
agent.invoke(
{"messages": [{"role": "user", "content": "我叫小明,下周要去北京出差"}]},
config=config,
)
# 第二轮:考考它记不记得(注意:消息里没再提名字)
result = agent.invoke(
{"messages": [{"role": "user", "content": "我叫什么名字?要去哪干嘛?"}]},
config=config,
)
print(result["messages"][-1].text)
# 换一个 thread_id = 开新对话,它就"失忆"了
new_config = {"configurable": {"thread_id": "另一个新对话"}}
result2 = agent.invoke(
{"messages": [{"role": "user", "content": "我叫什么名字?"}]},
config=new_config,
)
print(result2["messages"][-1].text)create_agent 传 checkpointer;② 想区分不同用户/会话,给每次调用传 thread_id;③ 记忆 = 自动帮你把历史消息拼进每轮请求。第 7 章的人工审批(HITL)之所以需要 checkpointer,就是因为"暂停等人"也要靠它保存现场。8.4 长对话怎么办:压缩与总结
历史消息越滚越长,迟早撑爆上下文窗口、还烧钱。两条主流对策(官方 Deep Agents 生态内置了对应中间件):
- 滑动窗口:只保留最近 N 条消息,老的直接丢;
- 总结压缩(Summarization):用模型把老消息压成一段摘要,摘要 + 最近原文一起发。
deepagents包的SummarizationMiddleware就是官方实现,一行装上:
# pip install deepagents
from deepagents.middleware import SummarizationMiddleware
agent = create_agent(
model="openai:gpt-4o-mini",
tools=[],
middleware=[SummarizationMiddleware(
model="openai:gpt-4o-mini", # 用哪个模型来做总结
max_tokens_before_summary=4000, # 历史超过这个量就开始压缩
)],
)📝 第 8 章自测(点击展开答案)
② 记忆两件套?——checkpointer(存储)+ thread_id(会话编号)。
③ InMemorySaver 的缺点?——程序重启记忆就没了,生产环境用数据库存储(如 Postgres/SQLite 版 checkpointer)。
第 9 章RAG:让模型现查资料再回答
9.1 为什么需要 RAG
模型的三个硬伤前面提过:知识有截止日期(不知道昨天的新政策)、不知道你的私有数据(没读过你公司的规章制度)、会编造(一本正经胡说八道,即"幻觉")。RAG(Retrieval-Augmented Generation,检索增强生成)的思路来自 2020 年论文《Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks》(Lewis 等,arXiv:2005.11401)——回答之前,先去资料库里检索相关段落,把段落塞进提示词,让模型"开卷作答"。
另一种让模型学新知识的办法是"微调训练"——贵、慢、改数据要重训。RAG 只需改资料库,便宜、实时、可溯源,所以企业文档问答、客服机器人、知识库应用几乎都选 RAG。
9.2 五步流程总览(先看懂再动手)
①~④ 是离线准备 + 在线检索(索引建一次,查询无数次);⑤ 是每次提问时执行。下面逐步拆解。
9.3 第①步:加载文档(Document Loaders)
LangChain 把一切资料统一成 Document 对象:page_content(正文)+ metadata(来源等元信息)。各类加载器把 PDF、Word、网页、Notion 等都转成它:
# 加载器多在 langchain-community 包里:pip install langchain-community pypdf
from langchain_core.documents import Document
from langchain_community.document_loaders import TextLoader, PyPDFLoader
# 加载本地 txt
docs = TextLoader("公司制度.txt", encoding="utf-8").load()
# 加载 PDF
pdf_docs = PyPDFLoader("年报.pdf").load()
print(docs[0].page_content[:100]) # 看看读到了什么
print(docs[0].metadata) # {'source': '公司制度.txt'}
# 也可以手工构造 Document(比如来自数据库或接口的数据)
doc = Document(page_content="年假规定:入职满一年 5 天。", metadata={"source": "HR 手册"})9.4 第②步:切分文本(Text Splitters)
最常用的是 RecursiveCharacterTextSplitter(官方 RAG 教程的推荐选择):按段落→句子→字符的顺序递归尝试切,尽量保持语义完整:
# pip install langchain-text-splitters
from langchain_text_splitters import RecursiveCharacterTextSplitter
splitter = RecursiveCharacterTextSplitter(
chunk_size=1000, # 每块目标长度(字符):官方教程用 1000
chunk_overlap=200, # 相邻块重叠 200 字:防止关键句恰好被切断
)
splits = splitter.split_documents(docs)
print(len(docs), "个文档 →", len(splits), "个块")chunk_size=1000 / overlap=200 起步,按效果微调。重叠(overlap)是防止"第 3 条年假规定"正好被切成两半。9.5 第③步:向量化(Embeddings)
# 用 OpenAI 的向量模型(与 langchain[openai] 一起安装)
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
v = embeddings.embed_query("如何申请年假?")
print(len(v)) # 1536 —— 一段话变成 1536 个数字组成的向量本地/免费方案:pip install langchain-huggingface 后用 HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5"),或 Ollama 的 OllamaEmbeddings。注意:建库和查询必须用同一个 embedding 模型(坐标系不同就没法比距离)。
9.6 第④步:存入向量库并检索(Vector Store / Retriever)
向量库负责"存所有块的向量 + 快速找出与问题最相似的 K 块"。教程用官方自带的内存版 InMemoryVectorStore(零安装);生产换 Chroma、FAISS、Milvus、PGVector 等,代码只需换一行构造——这正是标准接口的好处:
from langchain_core.vectorstores import InMemoryVectorStore
# 建库 + 入库(自动完成第③步:add_documents 内部会调用 embeddings)
vector_store = InMemoryVectorStore(embedding=embeddings)
vector_store.add_documents(documents=splits)
# 检索:找出与问题最相似的 4 个块
results = vector_store.similarity_search("年假有几天?", k=4)
print(results[0].page_content) # 最相关的那块内容
print(results[0].metadata["source"]) # 它来自哪个文件
# 也可以把向量库包装成"检索器"(Retriever,也是一个 Runnable!)
retriever = vector_store.as_retriever(search_kwargs={"k": 4})
retriever.invoke("年假有几天?") # 接口统一,可接进 LCEL 流水线9.7 第⑤步:完整可运行的迷你 RAG
把五步串成一条链(借鉴官方 RAG 教程的标准结构):
from dotenv import load_dotenv
load_dotenv()
from langchain.chat_models import init_chat_model
from langchain_openai import OpenAIEmbeddings
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_core.documents import Document
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
# ---------- 离线:建索引 ----------
knowledge = [
Document(page_content="年假规定:入职满一年享有 5 天带薪年假,满十年 10 天。", metadata={"source": "HR手册"}),
Document(page_content="报销规定:出差住宿每晚上限 400 元,需 5 个工作日内提交发票。", metadata={"source": "财务制度"}),
Document(page_content="考勤规定:工作日 9:00-18:00,弹性上班最晚 10:00 到岗。", metadata={"source": "HR手册"}),
]
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vector_store = InMemoryVectorStore(embedding=embeddings)
vector_store.add_documents(knowledge) # 这里块少就不切分了;真实文档要切分!
retriever = vector_store.as_retriever(search_kwargs={"k": 2})
# ---------- 在线:检索 + 生成 ----------
llm = init_chat_model("openai:gpt-4o-mini")
prompt = ChatPromptTemplate.from_messages([
("system",
"你是公司 HR 助理。只依据下面的资料回答,资料里没有的就直说不知道。\n\n资料:\n{context}"),
("human", "{question}"),
])
def format_docs(docs): # 把 Document 列表拼成一段文字
return "\n---\n".join(d.page_content for d in docs)
rag_chain = (
{"context": retriever | format_docs, # 支线1:检索并拼接资料
"question": RunnablePassthrough()} # 支线2:原样保留问题
| prompt # 两路汇合填进模板
| llm
)
# 提问!(注意传的是字符串,因为入口处 RunnablePassthrough 吃的就是它)
print(rag_chain.invoke("年假有几天?").text)
print(rag_chain.invoke("老板欠薪怎么办?").text) # 资料里没有 → 应答"不知道"拆解那条链:入口是个字典 → RunnableParallel 语义,两支线并行:retriever | format_docs 负责把"年假有几天"变成检索到的资料文本;RunnablePassthrough 原样传问题;汇合后填模板、调模型。第 6 章的积木,在这里全部用上了。
9.8 生产建议与安全提醒(来自官方)
- 换持久化向量库:InMemoryVectorStore 重启即失忆;生产用 Chroma/FAISS(本地文件)或 Milvus/PGVector(服务端)。
- 块要带出处:保留 metadata 里的 source,回答时附引用,用户才敢信。
- 进阶检索:混合检索(向量+关键词)、重排序(rerank)、按元数据过滤,都能显著提升命中率——先把基础版跑通再优化。
- 更强的形态:把"检索"包装成一个工具交给智能体(第 7 章),让模型自己决定何时查资料——官方 RAG 教程正是这样做的(
search_documentation工具 + Deep Agents)。本节的链式 RAG 适合"一问一答"的固定场景;智能体式 RAG 适合复杂任务。
📝 第 9 章自测(点击展开答案)
② 为什么要 chunk_overlap?——防止关键句恰好被切在两块边界上。
③ 建库和查询的 embedding 模型必须怎样?——必须是同一个,否则向量不在同一坐标系。
④ 检索进来的内容能全信吗?——不能,官方明确警告间接提示词注入风险,需要纵深防御。
第 10 章LangGraph 入门:自己画流程图
10.1 什么时候需要 LangGraph
create_agent 很强,但它的循环是"自动"的——模型自己决定下一步。当你需要精确控制流程时,就要 LangGraph:
- 流程必须固定:先审核 → 再生成 → 最后质检,不许模型自由发挥;
- 需要循环+条件分支:质检不过自动打回重写,最多重写 3 次;
- 需要持久化与断点恢复:任务跑了 2 小时崩了,从断点继续(LangGraph 1.0 的"durable execution"持久执行);
- 需要人工介入:流程停在某个点等人确认(human-in-the-loop)。
10.2 图的三大件:状态、节点、边
| 概念 | 人话 | 代码对应 |
|---|---|---|
| State 状态 | 全流程共享的一张"记录单",每经过一站就更新 | TypedDict / Pydantic 类 |
| Node 节点 | 一个工位/一站:读状态、干活、写回状态 | 普通 Python 函数 |
| Edge 边 | 站与站之间的轨道;条件边 = 岔路口按规则选路 | add_edge / add_conditional_edges |
| Checkpointer | 每到一站拍照存档(可恢复、可回溯) | InMemorySaver 等(第 8 章同款) |
10.3 编写第一个图:自动写文案 + 质检循环
场景:节点 A 生成文案 → 节点 B 检查是否包含"极限词"(如"最")→ 不合格打回重写(最多 3 次)。
from dotenv import load_dotenv
load_dotenv()
from typing import TypedDict
from langchain.chat_models import init_chat_model
from langgraph.graph import StateGraph, START, END
llm = init_chat_model("openai:gpt-4o-mini")
# ① 定义状态:整张"记录单"上有哪些字段
class State(TypedDict):
product: str # 输入:产品名
copy: str # 当前文案
attempts: int # 已尝试次数
review: str # 审校结论
# ② 定义节点:函数签名固定为 (state) -> 要更新的字段字典
def write_copy(state: State):
result = llm.invoke(f"给「{state['product']}」写一句 20 字内的广告语,禁止使用'最'字。")
return {"copy": result.text, "attempts": state.get("attempts", 0) + 1}
def review_copy(state: State):
result = llm.invoke(f"检查这句广告语是否含违反广告法的极限词,只回答 通过 或 不通过:{state['copy']}")
return {"review": result.text} # 写回 State 的 review 字段
# 路由函数:决定走哪条边
def route(state: State) -> str:
last_msg = state.get("copy", "")
if "最" in last_msg: # 极简版检查:含"最"就不通过
if state["attempts"] >= 3:
return "give_up" # 重写 3 次还不过 → 放弃
return "rewrite" # → 回到写作节点重写
return "finish" # → 结束
# ③ 组装图
builder = StateGraph(State)
builder.add_node("writer", write_copy) # 节点:写作
builder.add_node("reviewer", review_copy) # 节点:审校
builder.add_edge(START, "writer") # 入口 → 写作
builder.add_edge("writer", "reviewer") # 写作 → 审校
builder.add_conditional_edges( # 审校后的岔路口
"reviewer",
route,
{"rewrite": "writer", "give_up": END, "finish": END},
)
app = builder.compile() # 编译!得到一个可 invoke 的对象
# ④ 运行(它也是一个 Runnable,支持 stream/batch)
result = app.invoke({"product": "超级舒服的枕头", "attempts": 0})
print(result)give_up 直接接到 END 结束流程(小心:如果指回某个节点而条件永远不满足,图会一直循环跑不完);真实项目可加一个"放弃兜底"节点,输出"转人工处理"提示。另外 LangGraph 有一个减负神器:from langgraph.graph.message import add_messages 配合 Annotated,可让 messages 字段自动"追加"而不是"覆盖"。10.4 与 create_agent 的关系(一图看懂)
记住这句话就够了:create_agent 是 LangGraph 的"预制图"——官方替你画好了"模型↔工具循环"这张最常用的图,还预留了 middleware、checkpointer、state_schema 等定制接口。当你需要完全不同的图,就自己用 LangGraph 画。两者共用同一套持久化(第 8 章)和 LangSmith 观测(第 11 章)。
📝 第 10 章自测(点击展开答案)
② create_agent 和 LangGraph 的关系?——create_agent 是用 LangGraph 预先构建的"工具循环图",是官方推荐的默认入口;需要自定义流程时才自己画图。
③ 节点函数的签名?——入参 state,返回"要更新的字段"字典。
第 11 章LangSmith:给 AI 应用装上行车记录仪
11.1 LangSmith 是什么
AI 应用调试的三大难题:①模型内部发生了什么看不见(它为什么调了这个工具?);②出了错不知道是提示词问题还是检索问题;③改了提示词,效果是变好还是变坏全靠感觉。LangSmith(官方出品,与框架深度集成)提供:
- Tracing(追踪):每次调用的完整"行车记录"——每条消息、每次工具调用、每步耗时、每步 token 花费;
- Evaluation(评估):把"测试题集 + 评分标准"跑成自动化考试,改提示词前后对比分数;
- Monitoring(监控):上线后的错误率、延迟、成本大盘。
11.2 三行环境变量打开追踪(零代码改动)
LangSmith 与 LangChain 深度集成:只要设置环境变量,你已写好的所有代码自动开始上报。
- 到 smith.langchain.com 注册(有免费额度),在 Settings → API Keys 创建密钥。
- 在
.env里加三行:文件:.envLANGSMITH_TRACING=true LANGSMITH_API_KEY=lsv2_pt_你的密钥 LANGSMITH_PROJECT=langchain-tutorial # 项目名,随便起,用于归类 - 像平常一样运行第 7/8/9 章的任何脚本,然后打开 smith.langchain.com —— 能看到完整调用树:用户问题 → 提示词模板长什么样 → 模型原始输入输出 → 工具调用参数与结果 → 每一步的耗时和 token 数,一目了然。
11.3 评估:把"感觉变好了"变成"分数变高了"
核心做法:①准备一组测试用例(问题 + 标准答案/评分标准);②每次改动后批量跑,让"评判模型"或人工规则打分;③对比分数决定是否上线。入门可以直接在 LangSmith 网页上建 Dataset 手动体验;代码化后可结合官方 langsmith SDK 的 evaluate 接口跑批量实验。关键心法:
- 改提示词 = 改代码,必须有"回归测试",否则等于盲改;
- 测试集要包含刁钻案例(资料里没有答案的问题,检验它会不会老实说"不知道");
- 评估指标贴合业务:客服看准确率+满意度,抽取看字段级正确率,RAG 看引用是否真实存在。
📝 第 11 章自测(点击展开答案)
② LangSmith 三大能力?——Tracing 追踪 / Evaluation 评估 / Monitoring 监控。
③ 为什么改提示词要配评估?——避免凭感觉盲改,用分数对比保证改动是提升。
第 12 章常见坑与急救 FAQ
12.1 安装与导入类
❌ ImportError: cannot import name 'LLMChain' from 'langchain.chains'
病因:你在跑 0.x 时代的旧代码,而装的是 1.0。1.0 把旧链和 AgentExecutor 移到了兼容包 langchain-classic。
药方:首选按本教程新写法重写(prompt | llm、create_agent);只想跑旧代码则 pip install langchain-classic 后从 langchain_classic 导入。
❌ ModuleNotFoundError: No module named 'langchain'
病因:当前终端/IDE 没有用装了 langchain 的那个环境(最常见的版本:忘了激活 .venv)。
药方:重新激活虚拟环境;VS Code 用户右下角切换 Python 解释器到 .venv;Jupyter 用户见第 2 章 2.8 换内核。
❌ ImportError: cannot import name 'HumanMessage' from 'langchain.messages'
病因:消息类在 1.0 中主推从 langchain.messages 导入,但你装的版本较老或代码来自不同教程。
药方:用最稳的写法 from langchain_core.messages import HumanMessage, AIMessage, SystemMessage——langchain-core 在任何版本里都有它们。
❌ 装出来的 langchain 版本是 0.2.x / 0.3.x
病因:Python 版本过低(1.0 要求 Python ≥ 3.10),pip 自动降级装了旧版;或用了过旧的镜像源。
药方:升级 Python 后 pip install -U langchain;用 pip show langchain 确认 Version 是 1.x。
❌ pydantic 版本冲突 / ValidationError: ... pydantic v1 style
病因:环境里同时有依赖 Pydantic v1 和 v2 的旧包互相打架。
药方:统一升级全家桶:pip install -U langchain langchain-openai langchain-community pydantic;还不行就删掉 .venv 重建(虚拟环境的好处这时候就体现了)。
12.2 API 调用类
❌ AuthenticationError / 401 / Invalid API key
病因:环境变量没生效(最常见:忘了在代码开头 load_dotenv(),或 .env 不在项目根目录/文件名写错成 .env.txt);或 Key 复制时带了空格。
药方:代码里打印验证:import os; print(bool(os.getenv("OPENAI_API_KEY"))),为 False 就是没读到。
❌ RateLimitError / 429 Too Many Requests
病因:请求太频繁或账号额度不足(免费/新账号限制严格)。
药方:加官方重试中间件(第 7 章 ModelRetryMiddleware);batch 调用减少并发;充值或换模型。
❌ APIConnectionError / 连接超时(国内用户高发)
病因:网络无法直连境外 API。
药方:方案一:换国内可直连的服务(DeepSeek、通义等,见 2.5 方案 B);方案二:给终端设置代理环境变量 HTTPS_PROXY;方案三:本地 Ollama(2.6 节)。
❌ 模型输出乱码 / 中文变 ??(Windows)
病因:Windows 终端默认编码不是 UTF-8。
药方:PowerShell 执行 [Console]::OutputEncoding=[Text.Encoding]::UTF8;或运行前设置环境变量 PYTHONIOENCODING=utf-8;代码文件保存为 UTF-8 并在文件头写 # -*- coding: utf-8 -*-。
❌ BadRequestError: first content byte should be... role system 相关
病因:把不合法的消息列表传给了模型(比如空列表、格式不对的元组)。
药方:打印 messages 检查;模板变量用字典传齐;元组格式必须是 ("system"|"human"|"ai", 文本)。
12.3 智能体与 RAG 类
🤖 智能体不调用我给的工具
病因 1:docstring 太敷衍("""工具"""),模型不知道它是干嘛的。病因 2:参数类型注解缺失。病因 3:用户问题与工具功能确实无关(这是正确行为)。
药方:按 7.3 节标准重写 docstring(功能 + 何时调用);补全类型注解;用 print(get_weather.args_schema.model_json_schema()) 验收工具简历。
🤖 智能体死循环 / 工具来回调用停不下来
病因:工具返回的信息不足以让模型判断任务完成,或工具自身报错被反复重试。
药方:让工具返回明确、结构化的结果;加 ToolRetryMiddleware(max_retries=2) 限制重试;调试时用 LangSmith 看每一圈到底发生了什么。
🤖 记忆重启就丢 / 换个终端就"失忆"
病因:InMemorySaver 存在内存里,进程结束即清空——这是设计如此,不是 bug。
药方:生产环境换持久化 checkpointer:pip install langgraph-checkpoint-sqlite 后用 SqliteSaver.from_conn_string("memory.db")。
🤖 RAG 答非所问 / 检索不到相关内容
排查清单:① chunk_size 是否太大把无关内容混进来?(先试 1000/200)② 建库与查询是否用了同一个 embedding 模型?③ k 值是否太小?(试 k=4)④ 问题和资料的语言/措辞差异是否过大?⑤ 打印 retriever.invoke(问题) 直接看检索到了什么——90% 的问题在这一步现形。
🤖 with_structured_output 报输出格式错误
病因:模型太弱不支持函数调用;或字段 description 含糊导致模型乱填;或 demanded 字段模型填不出(如让它填不存在的日期)。
药方:换支持工具调用的模型;完善每个字段的 description;允许字段为空(Optional[str])并写明"无相关信息时填 null"。
12.4 版本与迁移总原则
pip show langchain —— 0.x 与 1.0 的 API 差异极大;② 查导入路径:报错说哪个模块没有,就去 API 参考(reference.langchain.com)搜正确路径;③ 查官方文档示例:docs.langchain.com 的示例永远是 1.0 最新写法,比三年前的博客可靠。第 13 章学习路线与实战项目
13.1 路线图:你现在在哪,接下来去哪
| 阶段 | 能力标志 | 对应章节 |
|---|---|---|
| 🟢 入门(你已在这里) | 能配置环境、调用模型、写模板与结构化输出 | 第 2~5 章 |
| 🟡 进阶 | 会用 LCEL 编排、创建带工具/记忆的智能体、搭 RAG | 第 6~9 章 |
| 🟠 熟练 | 能用 LangGraph 画自定义流程、用 LangSmith 调优评估 | 第 10~11 章 |
| 🔴 生产级 | 持久化、并发、成本控制、安全防御、自动化评估 | 第 9.8 / 12 / 11 章 + 官方文档 deep dive |
13.2 三个实战项目(难度递增,务必动手)
项目一:多轮对话记账助手(综合第 3/4/5/8 章,约 60 行)
- 需求:用户用自然语言记账("今天午饭花了 32 块"),助手确认并记住历史;
- 要点:结构化输出提取
{"item": "午饭", "amount": 32, "date": "今天"};checkpointer 保存对话;用 thread_id 区分不同用户; - 验收:连续聊 3 轮后问"我这周花了多少",它能把记过的账汇总出来(提示:把账目作为工具结果存进对话,或直接在工具里读写一个本地 JSON 文件)。
项目二:个人文档知识库(综合第 9 章,约 100 行)
- 需求:把你的笔记/PDF 丢进去,用自然语言提问,回答附出处;
- 要点:PyPDFLoader 加载 → RecursiveCharacterTextSplitter 切分 → 向量库(本地可用 Chroma 持久化)→ RAG 链 → 回答时引用 metadata.source;
- 验收:故意问一个资料里没有的问题,它应回答"资料中没有"而不是编造(用 9.7 节的提示词约束 + 测试)。
项目三:会查资料的研究助理(综合第 7/8/9/11 章)
- 需求:给它"查资料"工具(接你的项目二知识库 + 一个搜索 API),让它自主完成"调研一个主题并输出结构化报告";
- 要点:
create_agent+ 多个工具 + response_format 输出报告结构;HITL 审批外发动作;LangSmith 开着观察它的决策链; - 验收:LangSmith trace 里能清晰看到 Thought→Action→Observation 循环,报告字段完整、每个结论有来源。
13.3 综合练习题(检验真懂了没)
- 用 LCEL 把"翻译链"写出来:用户输入任意语言文本 → 输出中文。要求支持流式输出。(答案要点:
prompt | llm+.stream()) - 写一个工具
read_file(path),并给智能体加上"读文件前必须人工批准"的约束。(HumanInTheLoopMiddleware + checkpointer) - 解释:为什么 RAG 项目里建库和查询必须用同一个 embedding 模型?(不同模型生成的向量不在同一坐标系,相似度无意义)
- 把第 10 章的图改造成:审校不通过时改为"人工介入"节点(提示:checkpointer + interrupt,参考 LangGraph 官方 human-in-the-loop 教程)。
- 给你第 9 章的 RAG 链加上 LangSmith 追踪,找出检索环节的平均耗时与 token 消耗。(.env 三行变量,去后台看 trace 树)
附录术语表 / 速查表 / 参考资料
附 1 术语表(人话版)
| 术语 | 人话解释 |
|---|---|
| LLM 大语言模型 | 读过海量文本、按概率接话的 AI 模型。只接收文字、输出文字。 |
| Token | 模型处理文字的最小单位,约等于半个到一个词;计费和上下文长度都按它算。 |
| 上下文窗口 | 模型一次能"看到"的最大 token 数,超了就要靠记忆管理或 RAG。 |
| Prompt 提示词 | 你发给模型的文字输入。提示词工程 = 把这段话写得更能让模型干活。 |
| System Prompt | 幕后指令,设定角色与规则;用户看不到它。 |
| 幻觉 | 模型一本正经地编造不存在的信息。RAG 与要求"答不上就说不知道"是主要对策。 |
| Temperature | 随机度旋钮:0 最稳定,高值更有创意也更容易胡说。 |
| ChatModel | 吃消息列表、吐一条消息的标准对话模型接口,LangChain 的模型抽象。 |
| LCEL | LangChain Expression Language:用 | 把组件拼成链的声明式写法。 |
| Runnable | LangChain 万物皆可拼的统一接口:都有 invoke / batch / stream。 |
| Tool 工具 | 带说明书(docstring)的函数,交给模型在需要时调用。 |
| Agent 智能体 | 模型 + 挽具(提示词/工具/中间件),在一个循环里自主调工具直到完成任务。 |
| ReAct | 智能体的经典工作模式:想(Thought)→ 做(Action)→ 看(Observation)循环。 |
| Harness 挽具 | 官方 1.0 术语:围着模型的那套装备 = prompt + tools + middleware。 |
| Middleware 中间件 | 挂在模型/工具调用前后的可插拔逻辑:重试、审批、脱敏、总结等。 |
| Checkpointer | 状态存储器,配合 thread_id 实现对话记忆与断点恢复。 |
| Embedding 向量嵌入 | 把文字变成语义坐标(一串数字),意思越近坐标越近,是向量检索的基础。 |
| Vector Store 向量库 | 存向量并按相似度快速查找的数据库。 |
| RAG | 检索增强生成:先查资料再让模型开卷作答,解决知识过期、私有数据与幻觉。 |
| Chunk | 文档切出来的小块;检索的"知识卡片"。 |
| LangGraph | 底层编排框架:用"图"(节点+边+状态)精确控制流程,支持持久化与人工介入。 |
| LangSmith | 官方观测评估平台:追踪、评估、监控。 |
| Deep Agents | 官方"全家桶"智能体包:自带规划、文件系统、子智能体。 |
| Human-in-the-loop | 人工介入环节:危险操作暂停下来等人批准。 |
附 2 代码速查表(复制即用的骨架)
① 最小对话
from dotenv import load_dotenv; load_dotenv()
from langchain.chat_models import init_chat_model
llm = init_chat_model("openai:gpt-4o-mini", temperature=0)
print(llm.invoke("你好").text)② 结构化输出
from pydantic import BaseModel, Field
class Person(BaseModel):
name: str = Field(description="姓名")
age: int = Field(description="年龄,未知填 0")
person = llm.with_structured_output(Person).invoke("鲁迅生于1881年")
print(person.name, person.age)③ LCEL 链
from langchain_core.prompts import ChatPromptTemplate
chain = (ChatPromptTemplate.from_messages([("human", "把这句话翻译成英文:{t}")]) | llm)
print(chain.invoke({"t": "学习使我快乐"}).text)④ 智能体(工具 + 记忆)
from langchain.agents import create_agent
from langchain.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
@tool
def add(a: int, b: int) -> int:
"""计算两个整数的和。当用户需要加法运算时调用。"""
return a + b
agent = create_agent(
model="openai:gpt-4o-mini",
tools=[add],
system_prompt="你是可靠的数学助手,算数必须用工具。",
checkpointer=InMemorySaver(),
)
cfg = {"configurable": {"thread_id": "demo-1"}}
r = agent.invoke({"messages": [{"role": "user", "content": "37+85 等于几?"}]}, config=cfg)
print(r["messages"][-1].text)⑤ 常用命令
pip install -qU langchain "langchain[openai]" # 安装主包+OpenAI 适配
pip install -qU langchain-deepseek # 国产 DeepSeek 适配
pip install -qU langchain-ollama # 本地 Ollama 适配
pip install -qU langchain-community pypdf # 文档加载器
pip install -qU langchain-text-splitters # 文本切分
pip install -qU langchain-chroma # 持久化向量库
pip show langchain # 查版本(应为 1.x)附 3 官方一手参考资料(本教程信息来源,权威优先级从上到下)
| # | 资料 | 链接 | 本教程引用之处 |
|---|---|---|---|
| 1 | LangChain 官方 GitHub 主仓库(MIT 开源,源码与 README) | github.com/langchain-ai/langchain | 包结构、安装、定义("agent engineering platform") |
| 2 | 官方文档:LangChain Overview(1.0) | docs.langchain.com/oss/python/langchain/overview | "Agent = Model + Harness"、create_agent 示例、安装命令 |
| 3 | 官方文档:Agents(1.0) | docs.langchain.com/oss/python/langchain/agents | @tool、system_prompt、response_format、checkpointer、middleware |
| 4 | 官方文档:RAG 教程 | docs.langchain.com/oss/python/langchain/rag | 切分参数 1000/200、检索 k=4、提示词注入警告 |
| 5 | 官方公告:LangChain & LangGraph Reach v1.0(2025-10-22) | www.langchain.com/blog | 1.0 发布时间与内容 |
| 6 | 官方文档:LangChain v1 Migration Guide(v1 迁移指南) | docs.langchain.com(Migration 1.0) | 旧链/AgentExecutor 移入 langchain-classic |
| 7 | API 参考(Python) | reference.langchain.com/python | 类与函数签名查询 |
| 8 | 论文:ReAct: Synergizing Reasoning and Acting in Language Models(Yao et al., 2022-10) | arxiv.org/abs/2210.03629 | 第 7.2 节智能体原理(幻觉显著减少、ALFWorld +34%) |
| 9 | 论文:Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks(Lewis et al., 2020) | arxiv.org/abs/2005.11401 | 第 9 章 RAG 原理 |
| 10 | LangChain Academy 官方免费课程 | academy.langchain.com | 进阶学习 |
| 11 | 官方社区论坛 | forum.langchain.com | 提问求助 |
reference.langchain.com 为准。写作日期:2026 年 9 月。