LangChain 中文完全指南 (v1.2.10)
📖 预计阅读时长：45-60 分钟 🎯 目标：从零基础到能够独立构建 AI 应用 📦 版本：LangChain 1.2.10 + Deep Agents
目录
- 先导：AI 应用开发简史
- 第一章： LangChain 是什么？
- 第二章：核心概念详解
- 第三章：模型层（Models）
- 第四章：提示词模板
- 第五章：LCEL 表达式语言
- 第六章：记忆系统（Memory）
- 第七章：工具系统（Tools）
- 第八章：Agent 体系
- 第九章：LangGraph 深入
- 第十章：RAG 检索增强生成
- 第十一章：生产环境实践
- 附录
1. 先导：AI 应用开发简史
1.1 原始时代：直接调用 API
最早的 AI 应用是这样的：
import openai
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[
{"role": "user", "content": "用Python实现快速排序"}
]
)
print(response.choices[0].message.content)
问题：
- 每 次都要手写完整的 messages 格式
- 无法保存对话历史
- 无法让 AI 使用工具（计算器、搜索等）
- 代码难以复用
1.2 LangChain 时代：组件化
┌─────────────────────────────────────────────────────────────┐
│ LangChain 的价值 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 以前（裸调用） 现在（LangChain） │
│ ┌─────────┐ ┌─────────────────────┐ │
│ │ 直接 │ │ Prompt Template │ │
│ │ 调API │ ───────► │ │ │ │
│ └─────────┘ │ ▼ │ │
│ │ LLM │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Output Parser │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Chain │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ Agent │ │
│ └─────────────────────┘ │
│ │
│ 优势： │
│ ✓ 组件可复用 │
│ ✓ 天然支持 Memory │
│ ✓ 轻松绑定 Tools │
│ ✓ 管道式调用，代码简洁 │
└─────────────────────────────────────────────────────────────┘
1.3 当前格局：LangChain → Deep Agents → LangGraph
┌──────────────────────────────────────────────────────────────────────┐
│ LangChain 生态全景图 │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ Deep Agents │ ⭐ 官方推荐 │
│ │ (开箱即用型) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌─────────────────────┼─────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ LangChain │ │ LangGraph │ │ LangSmith │ │
│ │ Agent │ │ (编排框架) │ │ (监控调试) │ │
│ │ (简单场景) │ │ (复杂场景) │ │ │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ langchain-core │ ← 核心基础库 │
│ │ (所有组件的基座) │ │
│ └─────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
第一章：LangChain 是什么？
1.1 一句话定义
LangChain = AI 应用的"乐高积木"
它把 AI 应用开发中常用的功能拆成一个个标准组件，你只需要像搭积木一样把它们拼起来。
1.2 官方定义
LangChain is an open source framework with a pre-built agent architecture and integrations for any model or tool — so you can build agents that adapt as fast as the ecosystem evolves.
翻译：LangChain 是一个开源框架，提供预置的 Agent 架构和任意模型/工具的集成，让你能构建适应能力像生态进化一样快的 Agent。
1.3 为什么用 LangChain？
| 能力 | 没有 LangChain | 有 LangChain |
|---|---|---|
| 模型切换 | 每换一个模型改一堆代码 | 换一个字符串就行 |
| 对话历史 | 自己存、自己拼接 | 自动 Memory |
| 工具调用 | 手动写 API 调用逻辑 | 装饰器 @tool 搞定 |
| 复杂流程 | 嵌套 if-else | LangGraph 可视化 |
| 调试 | print 大法 | LangSmith 全链路追踪 |
1.4 安装与环境
# 基础安装
pip install -U langchain
# 推荐：安装 Anthropic 集成（Claude 模型效果好）
pip install -U "langchain[anthropic]"
# 或 OpenAI
pip install -U langchain-openai
# 检查版本
python -c "import langchain; print(langchain.__version__)"
# 输出: 1.2.10
Python 版本：必须 3.10+
# 配置 API Key
import os
# OpenAI
os.environ["OPENAI_API_KEY"] = "sk-..."
# Anthropic (Claude)
os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..."
# 调试模式（可选）
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANCHAIN_TRACING_V2"] = "true"
第二章：核心概念详解
2.1 六大核心概念
┌─────────────────────────────────────────────────────────────────────┐
│ LangChain 核心概念 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Model │ │ Prompt │ │ Chain │ │ Tool │ │
│ │ 🤖 │ │ 📝 │ │ 🔗 │ │ 🔧 │ │
│ │ 大脑/推理│ │ 模板/格式│ │ 流水线 │ │ 能力扩展│ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └───────────────┴───────┬───────┴───────────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Agent │ ⭐ 核心概念 │
│ │ 🧠 │ │
│ │ 自主决策+工具 │ │
│ └────────┬───────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Memory │ │
│ │ 💾 │ │
│ │ 对话历史/状态 │ │
│ └────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
2.2 概念详解
Model（大语言模型）
AI 的"大脑"，负责理解和生成文本。
# 方式一：初始化模型
from langchain.chat_models import init_chat_model
llm = init_chat_model(model="gpt-4o-mini", temperature=0.7)
# 方式二：直接创建 Agent 时指定（更简洁）
agent = create_agent(model="gpt-4o-mini", tools=[...])
Prompt（提示词模板）
告诉 AI 怎么回答的"模板"，类似填空题：
┌─────────────────────────────────────┐
│ Prompt Template 结构 │
├─────────────────────────────────────┤
│ │
│ System: 你是一个[角色] │
│ 擅长[领域] │
│ 回答风格是[风格] │
│ │
│ Human: {input} │
│ │
│ [placeholder]: {history} │
│ │
└─────────────────────────────────────┘
Chain（链）
把多个组件"串"起来，像生产线：
输入 → Prompt → LLM → Output Parser → 输出
│ │ │ │
└────────┴───────┴─────────┘
用 | 管道符连接
Tool（工具）
让 AI 能执行特定操作：
- 搜索互联网
- 执行代码
- 读写文件
- 调用 API
Agent（代理）
最强大的概念：不只是执行固定流程，而是能自主思考：
- 分析用户意图
- 决定使用哪些工具
- 按需调用工具
- 根据结果调整下一步
┌─────────────────────────────────────────────────────────────┐
│ Agent 工作流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 用户问题 │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ LLM 分析意图 │ ◄── "用户想要什么？" │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 需要调用工具？ │ ◄── "我需要计算器/搜索？" │
│ └────────┬─────────┘ │
│ │ │ │
│ 是 ▼ │ 否 ▼ │ │
│ ┌─────┴────┐ ┌────┴─────┐ │
│ │ 执行工具 │ │ 直接回答 │ │
│ └─────┬────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ LLM 根据结果 │ ◄── "工具返回了结果，我可以回答了" │
│ │ 生成最终回答 │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ 最终回答 │
│ │
└─────────────────────────────────────────────────────────────┘
Memory（记忆）
让 AI 记住对话历史：
- 短期记忆：当前对话
- 长期记忆：跨会话持久化
第三章：模型层（Models）
3.1 init_chat_model 详解
新版本统一用 init_chat_model 初始化模型：
from langchain.chat_models import init_chat_model
# 基本用法
llm = init_chat_model(
model="gpt-4o-mini", # 模型名称
temperature=0.7, # 创造性 0-2
max_tokens=1000, # 最大输出 tokens
streaming=True, # 是否支持流式
)
3.2 支持的模型
# OpenAI 模型
llm = init_chat_model(model="gpt-4o") # 最新旗舰
llm = init_chat_model(model="gpt-4o-mini") # 便宜快速
llm = init_chat_model(model="gpt-3.5-turbo") # 老牌
# Anthropic 模型
llm = init_chat_model(model="claude-sonnet-4-6-20251902")
llm = init_chat_model(model="claude-3-5-sonnet-20240620")
# Google 模型
llm = init_chat_model(model="gemini-2.0-flash")
# 本地模型
llm = init_chat_model(model="llama3", model_provider="ollama")
3.3 调用方式
# 1. 普通调用
response = llm.invoke("你好")
print(response.content)
# 2. 流式调用（实时显示）
for chunk in llm.stream("讲个故事"):
print(chunk.content, end="", flush=True)
# 3. 批量调用
responses = llm.batch(["你好", "今天怎么样", "晚安"])
3.4 模型响应结构
response = llm.invoke("你好")
# AIMessage 对象
print(type(response))
# <class 'langchain_core.messages.AIMessage'>
# 常用属性
print(response.content) # 文本内容
print(response.response_metadata) # 响应元数据（token 用量等）
print(response.tool_calls) # 工具调用列表
print(response.id) # 消息 ID
第四章：提示词模板
4.1 为什么需要模板？
痛点场景：
# ❌ 不好：每次手动拼接
user_input = "北京天气"
system_prompt = "你是一个天气助手"
full_prompt = f"{system_prompt}，请告诉我{user_input}的天气"
# ✅ 好：使用模板
prompt = ChatPromptTemplate.from_template("你是一个天气助手，请告诉我{city}的天气")
formatted = prompt.invoke({"city": "北京"})
# 自动拼接，易于维护和复用
4.2 ChatPromptTemplate 详解
基础用法
from langchain_core.prompts import ChatPromptTemplate
# 方式一：从字符串模板创建
prompt = ChatPromptTemplate.from_template("翻译成中文：{text}")
# 方式二：从消息列表创建（更灵活）
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个{role}，擅长{skill}"),
("human", "{question}")
])
# 使用
result = prompt.invoke({
"role": "翻译官",
"skill": "中英互译",
"question": "Hello world"
})
print(result.to_messages())
输出：
[SystemMessage(content='你是一个翻译官，擅长中英互译'), HumanMessage(content='Hello world')]
消息类型
┌─────────────────────────────────────────────────────────────┐
│ 消息类型说明 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ("system", "系统提示") │ 设置 AI 的身份和行为规则 │
│ ──────────────────────────┼──────────────────────────── │
│ ("human", "用户问题") │ 用户说的话 │
│ ──────────────────────────┼──────────────────────────── │
│ ("ai", "AI回复") │ 可以预设 AI 的回复 │
│ ──────────────────────────┼──────────────────────────── │
│ ("tool", "工具结果") │ 工具返回的内容 │
│ ──────────────────────────┼──────────────────────────── │
│ MessagesPlaceholder(...) │ 动态插入消息列表 │
│ │
└─────────────────────────────────────────────────────────────┘
MessagesPlaceholder（动态消息）
用于 Memory 等动态内容：
from langchain_core.prompts import MessagesPlaceholder
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个有帮助的助手"),
MessagesPlaceholder(variable_name="history"), # ← 动态插入
("human", "{input}")
])
# 使用
history = [
("human", "我叫小明"),
("ai", "你好小明，很高兴认识你！")
]
result = prompt.invoke({
"history": history,
"input": "你还记得我叫什么吗？"
})
4.3 完整示例：多语言翻译助手
from langchain_core.prompts import ChatPromptTemplate
from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
# 1. 创建翻译模板
translate_prompt = ChatPromptTemplate.from_messages([
("system", """你是一个专业翻译助手。
翻译原则：
- 保持原文风格
- 意译优先于直译
- 符合目标语言习惯"""),
("human", """请将以下{source_lang}翻译成{target_lang}：
{text}""")
])
# 2. 创建链
llm = init_chat_model(model="gpt-4o-mini", temperature=0)
translator = translate_prompt | llm | StrOutputParser()
# 3. 使用
result = translator.invoke({
"source_lang": "英文",
"target_lang": "中文",
"text": "The early bird catches the worm."
})
print(result)
# 早起的鸟儿有虫吃。
4.4 Few-shot Prompting（示例提示）
给 AI 举例子，效果更好：
from langchain_core.prompts import PromptTemplate
prompt = PromptTemplate.from_template("""
下面是对话摘要示例：
原文：小明说"你好"，AI回复"你好，很高兴见到你"
摘要：小明和AI互相打招呼
原文：{input}
摘要：
""")
llm = init_chat_model(model="gpt-4o-mini")
chain = prompt | llm
result = chain.invoke({"input": "用户问今天天气，AI说晴天"})
print(result.content)
第五章：LCEL 表达式语言
5.1 什么是 LCEL？
LCEL (LangChain Expression Language) = 管道操作符 |
它的思想来自 Unix 管道：每个程序做好一件事，结果传给下一个。
# Unix 管道
cat file.txt | grep "error" | sort
# LCEL 管道
prompt | llm | parser
# │ │
# │ └─ 解析输出
# └──────── LLM 处理
5.2 基础管道
from langchain_core.prompts import ChatPromptTemplate
from langchain.chat_models import init_chat_model
from langchain_core.output_parsers import StrOutputParser
# 标准三段式
chain = (
ChatPromptTemplate.from_template("用一句话解释{topic}")
| init_chat_model(model="gpt-4o-mini")
| StrOutputParser()
)
result = chain.invoke({"topic": "量子计算"})
┌─────────────────────────────────────────────────────────────┐
│ 管道数据流向 │
├─────────────────────────────────────────────────────────────┤
│ │
│ {"topic": "量子计算"} │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ ChatPromptTemplate │ │
│ │ 输入: {"topic": "量子计算"} │ │
│ │ 输出: ChatPromptValue(... "用一句...") │ │
│ └──────────────────┬──────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ init_chat_model │ │
│ │ 输入: ChatPromptValue │ │
│ │ 输出: AIMessage("量子计算是一种...") │ │
│ └──────────────────┬──────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ StrOutputParser │ │
│ │ 输入: AIMessage │ │
│ │ 输出: "量子计算是一种..." (纯文本) │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
5.3 组件类型
LCEL 支持的组件：
| 类型 | 说明 | 示例 |
|---|---|---|
| Runnable | 可运行对象 | LLM, Prompt, Parser |
| Function | 普通函数 | lambda x: x.upper() |
| RunnableLambda | 包装函数 | RunnableLambda(func) |
from langchain_core.runnables import RunnableLambda
# 添加自定义处理
chain = (
ChatPromptTemplate.from_template("解释{word}")
| init_chat_model(model="gpt-4o-mini")
| StrOutputParser()
| RunnableLambda(lambda x: f"【回答】{x}") # 后处理
)
5.4 并行处理
from langchain_core.runnables import RunnableParallel
# 并行执行多个任务
parallel_chain = RunnableParallel(
translation=translate_prompt | llm | StrOutputParser(),
summary=summarize_prompt | llm | StrOutputParser()
)
result = parallel_chain.invoke({
"text": "人工智能正在改变世界"
})
# result = {"translation": "...", "summary": "..."}
5.5 条件分支
from langchain_core.runnables import RunnableBranch
# 根据输入条件选择不同的处理路径
chain = RunnableBranch(
(lambda x: "翻译" in x.get("task", ""), translate_chain),
(lambda x: "总结" in x.get("task", ""), summarize_chain),
default_chain # 默认
)
5.6 配置与上下文
# 添加配置
chain = prompt | llm
# 运行时传递配置
result = chain.invoke(
{"question": "你好"},
config={"configurable": {"session_id": "user123"}}
)
第六章：记忆系统（Memory）
6.1 为什么需要 Memory？
┌─────────────────────────────────────────────────────────────┐
│ 无 Memory vs 有 Memory │
├─────────────────────────────────────────────────────────────┤
│ │
│ 无 Memory: 有 Memory: │
│ ┌─────────┐ ┌─────────┐ │
│ │ 用户:你好 │ │ 用户:你好 │ │
│ │ AI:你好 │ │ AI:你好 │ │
│ └─────────┘ └─────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │ 用户:我叫 │ │ 用户:我叫小明 │ │
│ │ AI:好的 │ │ AI:你好小明│ │
│ └─────────┘ └─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │ 用户:你还记得│ │ 用户:你还记得│ │
│ │ 我叫什么？ │ │ 我叫什么？ │ │
│ │ AI:抱歉 │ ◄── 不记得！ │ AI:你叫小明│ ◄── 记得！ │
│ └─────────┘ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
6.2 聊天消息历史
from langchain_core.chat_history import InMemoryChatMessageHistory
# 创建内存存储
history = InMemoryChatMessageHistory()
# 添加消息
history.add_user_message("你好，我叫小明")
history.add_ai_message("你好小明，很高兴认识你！")
# 查看历史
for msg in history.messages:
print(f"{msg.type}: {msg.content}")
6.3 RunnableWithMessageHistory
把 Memory 接入 LCEL 链：
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain.chat_models import init_chat_model
# 1. 创建基础链
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个有帮助的助手"),
MessagesPlaceholder(variable_name="history"),
("human", "{input}")
])
llm = init_chat_model(model="gpt-4o-mini")
chain = prompt | llm
# 2. 添加记忆
history = ChatMessageHistory()
chat_with_memory = RunnableWithMessageHistory(
chain,
lambda session_id: history,
input_messages_key="input",
history_messages_key="history"
)
# 3. 使用
config = {"configurable": {"session_id": "user123"}}
# 第一轮
r1 = chat_with_memory.invoke({"input": "你好，我叫小明"}, config)
print(r1.content)
# 第二轮
r2 = chat_with_memory.invoke({"input": "你还记得我叫什么吗？"}, config)
print(r2.content)
6.4 持久化存储
# SQLite 存储
from langchain_community.chat_message_histories import SQLChatMessageHistory
history = SQLChatMessageHistory(
session_id="user123",
connection_string="sqlite:///chat_history.db"
)
# Redis 存储（生产环境推荐）
from langchain_community.chat_message_histories import RedisChatMessageHistory
history = RedisChatMessageHistory(
session_id="user123",
url="redis://localhost:6379"
)
6.5 Memory 类型对比
| 类型 | 存储 | 适用场景 |
|---|---|---|
| InMemoryChatMessageHistory | 内存 | 开发/测试 |
| SQLChatMessageHistory | SQLite | 简单生产 |
| RedisChatMessageHistory | Redis | 高并发生产 |
| DynamoDBChatMessageHistory | AWS DynamoDB | AWS 环境 |
第七章：工具系统（Tools）
7.1 什么是 Tool？
Tool = 让 AI 具备"执行力"。
没有 Tool 的 AI 只能"纸上谈兵"，有了 Tool 就能实际操作：
┌─────────────────────────────────────────────────────────────┐
│ Tool 能力图谱 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Tool │
│ ├── 🌐 搜索工具 │
│ │ ├── Tavily, DuckDuckGo, Google │
│ │ └── 获取实时信息 │
│ ├── 💻 代码执行 │
│ │ ├── Python REPL, Shell │
│ │ └── 执行计算、分析数据 │
│ ├── 📊 数据处理 │
│ │ ├── CSV, JSON, SQL │
│ │ └── 文件读写、数据分析 │
│ ├── 🔌 API 调用 │
│ │ ├── HTTP 请求 │
│ │ └── 第三方服务集成 │
│ └── 📁 向量搜索 │
│ ├── 文档检索 │
│ └── RAG 核心组件 │
│ │
└─────────────────────────────────────────────────────────────┘
7.2 定义工具
方式一：@tool 装饰器（推荐）
from langchain_core.tools import tool
@tool
def get_weather(city: str) -> str:
"""获取指定城市的天气
Args:
city: 城市名称，如"北京"、"上海"
Returns:
天气描述字符串
"""
weather_data = {
"北京": "晴天，25°C",
"上海": "多云，28°C",
"广州": "雨天，30°C"
}
return weather_data.get(city, f"{city}天气未知")
@tool
def calculate(expression: str) -> str:
"""数学计算器，支持基本运算
Args:
expression: 数学表达式，如 "2+3*4"
Returns:
计算结果
"""
try:
result = eval(expression)
return str(result)
except Exception as e:
return f"计算错误: {e}"
方式二：StructuredTool（更灵活）
from langchain_core.tools import StructuredTool
def get_time() -> str:
"""获取当前时间"""
from datetime import datetime
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
time_tool = StructuredTool.from_function(
func=get_time,
name="get_time",
description="获取当前日期和时间"
)
7.3 工具的组成
┌─────────────────────────────────────────────────────────────┐
│ Tool 结构详解 │
├─────────────────────────────────────────────────────────────┤
│ │
│ @tool │
│ def get_weather(city: str) -> str: │
│ """获取城市天气（这是 description） │
│ │
│ Args: │
│ city: 城市名 │
│ │
│ Returns: │
│ 天气描述 │
│ """ │
│ return "晴天" │
│ │
│ ├── name: "get_weather" ← 工具名 │
│ ├── description: "获取城市..." ← 描述（LLM 靠它选工具） │
│ └── args_schema ← 参数定义 │
│ │
│ LLM 通过 description 决定何时调用这个工具！ │
└─────────────────────────────────────────────────────────────┘
7.4 绑定工具到模型
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
@tool
def add(a: int, b: int) -> int:
"""两个数相加"""
return a + b
@tool
def multiply(a: int, b: int) -> int:
"""两个数相乘"""
return a * b
# 初始化模型
llm = init_chat_model(model="gpt-4o-mini")
# 绑定工具
llm_with_tools = llm.bind_tools([add, multiply])
# 调用
response = llm_with_tools.invoke("计算 3 乘以 5")
# 查看是否有工具调用
if response.tool_calls:
print("需要调用工具:")
for call in response.tool_calls:
print(f" - {call['name']}: {call['args']}")
7.5 工具调用流程
┌─────────────────────────────────────────────────────────────┐
│ Tool Calling 完整流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 用户问题 │
│ "北京天气怎么样？顺便帮我算一下 2+3" │
│ │ │
│ ▼ │
│ 2. LLM 分析 │
│ ├── 需要调用 get_weather(city="北京") │
│ └── 需要调用 add(a=2, b=3) │
│ │ │
│ ▼ │
│ 3. 执行工具（自动或手动） │
│ ├── get_weather 返回: "晴天，25°C" │
│ └── add 返回: 5 │
│ │ │
│ ▼ │
│ 4. 把工具结果返回给 LLM │
│ ┌────────────────────────────────────────┐ │
│ │ ToolMessage: "北京晴天，25°C" │ │
│ │ ToolMessage: "5" │ │
│ └────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 5. LLM 生成最终回答 │
│ "北京今天晴天，25°C。2+3=5" │
│ │
└─────────────────────────────────────────────────────────────┘
7.6 内置工具
LangChain 提供了大量内置工具：
# 搜索工具
from langchain_community.tools import TavilySearchResults
search = TavilySearchResults(max_results=2)
result = search.invoke("LangChain 是什么")
# 文件操作
from langchain_community.tools import FileManagementTools
# Python REPL
from langchain_experimental.tools import PythonREPLTool
第八章：Agent 体系
8.1 Agent vs Chain
┌─────────────────────────────────────────────────────────────┐
│ Chain vs Agent │
├─────────────────────────────────────────────────────────────┤
│ │
│ Chain (固定流程): │
│ ┌─────────────────────────────────────────┐ │
│ │ 输入 → Prompt → LLM → Parser → 输出 │ │
│ └─────────────────────────────────────────┘ │
│ 特点：线性执行，步骤固定 │
│ │
│ Agent (智能决策): │
│ ┌─────────────────────────────────────────┐ │
│ │ ┌─────────────┐ │ │
│ │ ┌───►│ LLM 思考 │ │ │
│ │ │ └──────┬──────┘ │ │
│ │ │ │ │ │
│ │ │ ┌──────▼──────┐ │ │
│ │ │ │ 需要工具？ │ │ │
│ │ │ └──────┬──────┘ │ │
│ │ │ │ │ │ │
│ │ │ 是 ▼ ▼ 否 │ │
│ │ │ ┌────┐ ┌────────┐ │ │
│ │ │ │工具│ │生成回答 │ │ │
│ │ │ └──┬─┘ └────────┘ │ │
│ │ │ │ │ │
│ │ └─────┴─────────────────► 输出 │ │
│ └─────────────────────────────────────────┘ │
│ 特点：自主决策，循环执行，按需调用工具 │
│ │
└─────────────────────────────────────────────────────────────┘
8.2 Deep Agents（官方推荐⭐）
官方现在主推 Deep Agents，开箱即用：
from langchain.agents import create_agent
from langchain_core.tools import tool
# 定义工具
@tool
def get_weather(city: str) -> str:
"""获取城市天气"""
return f"{city}今天晴天，25度"
@tool
def get_time() -> str:
"""获取当前时间"""
from datetime import datetime
return datetime.now().strftime("%H:%M:%S")
# 创建 Agent（超级简单！）
agent = create_agent(
model="claude-sonnet-4-6", # 直接指定模型
tools=[get_weather, get_time],
system_prompt="你是一个乐于助人的助手，善于使用工具解决问题"
)
# 使用
result = agent.invoke({
"messages": [{"role": "user", "content": "现在几点了？北京天气如何？"}]
})
print(result["messages"][-1].content)
Deep Agents 特性：
| 特性 | 说明 |
|---|---|
| 🔄 自动压缩长对话 | 不再受 128K 上下文限制 |
| 📁 虚拟文件系统 | 可以读写文件 |
| 👥 子 Agent 调度 | 自动拆分复杂任务 |
| 💾 持久化 | 内置 checkpoint |
| 🎯 开箱即用 | 几行代码搞定 |
8.3 带记忆的 Agent
from langchain.agents import create_agent
from langchain_core.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
@tool
def get_weather(city: str) -> str:
return f"{city}晴天"
# 添加记忆
checkpointer = InMemorySaver()
agent = create_agent(
model="gpt-4o-mini",
tools=[get_weather],
system_prompt="你是天气助手",
checkpointer=checkpointer # 开启持久化
)
config = {"configurable": {"thread_id": "user1"}}
# 多轮对话
agent.invoke({"messages": [{"role": "user", "content": "北京天气"}]}, config)
agent.invoke({"messages": [{"role": "user", "content": "上海呢？"}]}, config)
# Agent 会记得之前问过北京
8.4 自定义 Agent
from langchain.agents import create_agent
from langchain.agents import AgentExecutor
from langchain_core.tools import tool
from pydantic import BaseModel
# 定义输出格式
class WeatherResponse(BaseModel):
city: str
weather: str
suggestion: str
# 自定义 Agent
agent = create_agent(
model="claude-sonnet-4-6",
tools=[get_weather],
system_prompt="你是天气预报员，回答要包含建议",
response_format=WeatherResponse # 强制结构化输出
)
result = agent.invoke({
"messages": [{"role": "user", "content": "北京天气怎么样？"}]
})
8.5 Tool Calling Agent 原理
┌─────────────────────────────────────────────────────────────┐
│ Tool Calling Agent 完整流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Step 1: 用户输入 │
│ ┌─────────────────────────────────────┐ │
│ │ "帮我查北京天气，然后告诉我要不要带伞" │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Step 2: LLM 分析意图 │
│ ┌─────────────────────────────────────┐ │
│ │ Tool Calls: │ │
│ │ - get_weather(city="北京") │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Step 3: AgentExecutor 执行工具 │
│ ┌─────────────────────────────────────┐ │
│ │ ToolMessage: "北京晴天，25度" │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Step 4: 再次调用 LLM │
│ ┌─────────────────────────────────────┐ │
│ │ "北京今天晴天，25度。天气很好，不需 │ │
│ │ 要带伞，记得带墨镜防晒！" │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Step 5: 返回最终结果 │
│ │
└─────────────────────────────────────────────────────────────┘
第九章：LangGraph 深入
9.1 什么时候用 LangGraph？
┌─────────────────────────────────────────────────────────────┐
│ 选择决策树 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 你需要构建什么？ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 简单 Q&A 或翻译 │ ──► LangChain LCEL │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 需要工具调用的 │ ──► Deep Agents ⭐ │
│ │ 自动化 Agent │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 复杂工作流？ │ │
│ │ - 多步骤审批 │ ──► LangGraph │
│ │ - 条件分支 │ │
│ │ - 循环处理 │ │
│ │ - 状态机 │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
9.2 LangGraph 核心概念
┌─────────────────────────────────────────────────────────────┐
│ LangGraph 核心概念 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. State (状态) │
│ ┌─────────────────────────────────────┐ │
│ │ {"messages": [...], "result": ""} │ │
│ │ 贯穿整个图的数据流 │ │
│ └─────────────────────────────────────┘ │
│ │
│ 2. Node (节点) │
│ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ node1 │ │ node2 │ │ node3 │ ← 一个函数 │
│ └───────┘ └───────┘ └───────┘ │
│ │
│ 3. Edge (边) │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │ A │───►│ B │───►│ C │ ← 数据流向 │
│ └───┘ └───┘ └───┘ │
│ │
│ 4. Conditional Edge (条件边) │
│ ┌───┐ │
│ │ A │───► B (条件1) │
│ │ │───► C (条件2) │
│ └───┘ │
│ │
└─────────────────────────────────────────────────────────────┘
9.3 简单示例：计算器 Agent
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
from langgraph.graph import StateGraph, START, END
from typing import TypedDict, Annotated
import operator
# 1. 定义工具
@tool
def add(a: int, b: int) -> int:
return a + b
@tool
def multiply(a: int, b: int) -> int:
return a * b
tools = {"add": add, "multiply": multiply}
# 2. 定义状态
class AgentState(TypedDict):
messages: Annotated[list, operator.add]
final_result: str
# 3. 创建模型
llm = init_chat_model(model="gpt-4o-mini")
llm_with_tools = llm.bind_tools(list(tools.values()))
# 4. 定义节点
def llm_node(state: AgentState):
"""LLM 决定是否调用工具"""
response = llm_with_tools.invoke(state["messages"])
return {"messages": [response]}
def tool_node(state: AgentState):
"""执行工具"""
last_msg = state["messages"][-1]
results = []
for call in last_msg.tool_calls:
tool = tools[call["name"]]
result = tool.invoke(call["args"])
results.append(f"{call['name']}: {result}")
return {"final_result": "\n".join(results)}
# 5. 判断是否继续
def should_continue(state: AgentState):
"""如果 LLM 调用了工具，就继续；否则结束"""
if state["messages"][-1].tool_calls:
return "tool_node"
return END
# 6. 构建图
graph = StateGraph(AgentState)
graph.add_node("llm_node", llm_node)
graph.add_node("tool_node", tool_node)
graph.add_edge(START, "llm_node")
graph.add_conditional_edges("llm_node", should_continue, ["tool_node", END])
graph.add_edge("tool_node", "llm_node")
# 7. 编译
agent = graph.compile()
# 8. 运行
result = agent.invoke({
"messages": [{"role": "user", "content": "计算 5 * 3"}]
})
print(result["messages"][-1].content)
9.4 状态管理
# 持久化 checkpoint
from langgraph.checkpoint.sqlite import SqliteSaver
# SQLite 持久化
checkpointer = SqliteSaver.from_conn_string(":memory:")
agent = graph.compile(checkpointer=checkpointer)
# 后续可以恢复状态
config = {"configurable": {"thread_id": "user123"}}
result = agent.invoke({"messages": [...]}, config=config)
9.5 条件分支示例
# 根据 LLM 输出决定流程
def route_based_on_intent(state: AgentState) -> str:
last_message = state["messages"][-1].content.lower()
if "weather" in last_message:
return "weather_node"
elif "news" in last_message:
return "news_node"
else:
return "general_node"
graph.add_conditional_edges(
"llm_node",
route_based_on_intent,
{"weather_node": "...", "news_node": "...", "general_node": "..."}
)
第十章：RAG 检索增强生成
10.1 什么是 RAG？
┌─────────────────────────────────────────────────────────────┐
│ RAG 工作流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 传统 LLM: │
│ ┌─────────┐ ┌──────┐ ┌─────────┐ │
│ │ 用户问题 │ ──► │ LLM │ ──► │ 生成回答 │ │
│ └─────────┘ └──────┘ └─────────┘ │
│ │ │
│ 知识有限，可能 │
│ 产生"幻觉" │
│ │
│ RAG: │
│ ┌─────────┐ ┌───────┐ ┌─────────┐ │
│ │ 用户问题 │ ──► │检索器 │ ──► │ 找到相关 │ │
│ └─────────┘ └───────┘ │ 文档 │ │
│ └────┬────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ LLM + │ │
│ │ 文档 │ │
│ └────┬────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ │
│ │ 生成回答 │ │
│ │ (基于 │ │
│ │ 事实) │ │
│ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
RAG 的价值：
- 📚 让 AI 知道最新信息
- 🎯 减少"幻觉"
- 🔒 可以使用私有数据
- 📝 引用来源可追溯
10.2 RAG 核心组件
┌─────────────────────────────────────────────────────────────┐
│ RAG 组件图 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 文档 ──► 加载器 ──► 分割器 ──► 向量存储 ◄── 嵌入模型 │
│ │ │
│ ▼ │
│ 检索器 ◄── 用户问题 │
│ │ │
│ ▼ │
│ 问答链 ◄── LLM │
│ │ │
│ ▼ │
│ 最终答案 │
│ │
└─────────────────────────────────────────────────────────────┘
10.3 完整 RAG 示例
from langchain_core.documents import Document
from langchain.text_splitter import CharacterTextSplitter
from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import FAISS
from langchain_core.prompts import ChatPromptTemplate
from langchain.chat_models import init_chat_model
from langchain.chains.combine_documents import create_stuff_documents_chain
from langchain.chains import create_retrieval_chain
# ============ 第一步：准备文档 ============
docs = [
Document(
page_content="""
LangChain 是一个用于构建 AI 应用的框架。它于 2023 年发布，
迅速成为最流行的 LLM 应用开发工具之一。
""",
metadata={"source": "langchain_intro", "page": 1}
),
Document(
page_content="""
LangChain 的核心概念包括：
1. Models - 各种 LLM 的统一接口
2. Prompts - 提示词模板
3. Chains - 将多个组件串联
4. Agents - 自主决策系统
5. Memory - 对话历史管理
""",
metadata={"source": "concepts", "page": 1}
),
Document(
page_content="""
Deep Agents 是 LangChain 官方推荐的构建方式，
它内置了长对话压缩、虚拟文件系统等生产级功能。
""",
metadata={"source": "deep_agents", "page": 1}
)
]
# ============ 第二步：文档分割 ============
splitter = CharacterTextSplitter(
chunk_size=200, # 每个块的大小
chunk_overlap=20, # 块之间重叠
separator="\n" # 分割符
)
split_docs = splitter.split_documents(docs)
# ============ 第三步：创建向量存储 ============
embeddings = OpenAIEmbeddings()
vectorstore = FAISS.from_documents(split_docs, embeddings)
# 第四步：创建检索器
retriever = vectorstore.as_retriever(
search_type="similarity", # 相似度搜索
search_kwargs={"k": 2} # 返回前2个结果
)
# ============ 第五步：创建问答链 ============
# 5.1 文档处理链
prompt = ChatPromptTemplate.from_template("""基于以下文档回答问题。
如果文档中没有相关信息，请说明"文档中没有提供相关信息"。
文档:
{context}
问题: {input}""")
llm = init_chat_model(model="gpt-4o-mini")
doc_chain = create_stuff_documents_chain(llm, prompt)
# 5.2 检索+问答链
retrieval_chain = create_retrieval_chain(retriever, doc_chain)
# ============ 第六步：查询 ============
result = retrieval_chain.invoke({
"input": "LangChain 的核心概念有哪些？"
})
print("答案:", result["answer"])
print("\n来源:")
for doc in result["context"]:
print(f" - {doc.metadata['source']}")
10.4 向量数据库选择
| 数据库 | 特点 | 适用场景 |
|---|---|---|
| FAISS | Facebook 出品，本地快速 | 中小规模 |
| Pinecone | 云服务，易扩展 | 生产环境 |
| Weaviate | 开源，多模态 | 需要开源方案 |
| Milvus | 国产，大规模 | 大规模数据 |
| Chroma | 轻量，易上手 | 快速原型 |
10.5 高级 RAG 技术
# 1. 父文档检索
from langchain.retrievers import ParentDocumentRetriever
# 2. 上下文压缩
from langchain.retrievers.contextual_compression import ContextualCompressionRetriever
from langchain.retrievers.document_compressors import LLMChainExtractor
# 3. 混合搜索
from langchain.retrievers import EnsembleRetriever
第十一章：生产环境实践
11.1 错误处理
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
@tool
def risky_operation(text: str) -> str:
"""可能失败的操作"""
if "error" in text.lower():
raise ValueError("检测到错误")
return f"成功: {text}"
# 使用 try-except
llm = init_chat_model(model="gpt-4o-mini")
try:
result = llm.invoke("你好")
except Exception as e:
print(f"错误类型: {type(e).__name__}")
print(f"错误信息: {e}")
11.2 重试机制
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10))
def call_with_retry(prompt: str) -> str:
llm = init_chat_model(model="gpt-4o-mini")
return llm.invoke(prompt).content
11.3 LangSmith 监控
# 安装
pip install langchain langsmith
# 设置环境变量
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=your_api_key
# 自动追踪所有调用
from langchain import langsmith
# 所有 LangChain 操作都会被记录到 LangSmith
chain = prompt | llm | parser
result = chain.invoke({"input": "你好"})
# 打开 https://smith.langchain.com 查看追踪
11.4 性能优化
# 1. 批量处理
results = chain.batch([
{"input": "问题1"},
{"input": "问题2"},
{"input": "问题3"},
])
# 2. 异步调用
import asyncio
from langchain.chat_models import init_chat_model
llm = init_chat_model(model="gpt-4o-mini")
async def main():
tasks = [
llm.ainvoke("问题1"),
llm.ainvoke("问题2"),
llm.ainvoke("问题3"),
]
results = await asyncio.gather(*tasks)
asyncio.run(main())
# 3. 缓存
from langchain.cache import InMemoryCache
import langchain
langchain.llm_cache = InMemoryCache()
11.5 部署建议
# 1. 使用 LangGraph 的持久化
from langgraph.checkpoint.sqlite import SqliteSaver
checkpointer = SqliteSaver.from_conn_string("production.db")
# 2. 配置超时
result = agent.invoke(
{"messages": [...]},
config={"configurable": {"thread_id": "..."}, "timeout": 60}
)
# 3. 限流
from langchain.rate_limiters import InMemoryRateLimiter
rate_limiter = InMemoryRateLimiter(
requests_per_second=10,
bucket_size=20
)
附录
A. 版本迁移指南
| 旧版本 (0.2) | 新版本 (1.x) |
|---|---|
ChatOpenAI(model="gpt-3.5") | init_chat_model(model="gpt-4o-mini") |
create_tool_calling_agent | create_agent |
prompt.format(**data) | prompt.invoke(data) |
LLMChain(llm, prompt) | prompt | llm |
B. 常用 API 参考
# 模型
from langchain.chat_models import init_chat_model
# 提示词
from langchain_core.prompts import ChatPromptTemplate, PromptTemplate, MessagesPlaceholder
# 输出解析
from langchain_core.output_parsers import StrOutputParser, JsonOutputParser
# 工具
from langchain_core.tools import tool, StructuredTool
# Agent
from langchain.agents import create_agent
# 记忆
from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.runnables.history import RunnableWithMessageHistory
# LangGraph
from langgraph.graph import StateGraph, START, END
# RAG
from langchain.vectorstores import FAISS
from langchain.embeddings import OpenAIEmbeddings
from langchain.text_splitter import CharacterTextSplitter
C. 学习资源
D. 快速开始代码模板
"""
LangChain 快速开始模板
"""
from langchain.agents import create_agent
from langchain_core.tools import tool
# 1. 定义工具
@tool
def your_tool(param: str) -> str:
"""工具描述"""
return "结果"
# 2. 创建 Agent
agent = create_agent(
model="gpt-4o-mini",
tools=[your_tool],
system_prompt="你的 Agent 提示词"
)
# 3. 使用
result = agent.invoke({
"messages": [{"role": "user", "content": "你的问题"}]
})
print(result["messages"][-1].content)
结语
🎉 恭喜你！ 完成了 LangChain 完整学习！
你现在应该已经掌握：
- ✅ LangChain 核心概念和组件
- ✅ 提示词模板设计
- ✅ LCEL 管道表达式
- ✅ Memory 记忆系统
- ✅ Tools 工具定义
- ✅ Agent 代理开发
- ✅ LangGraph 复杂工作流
- ✅ RAG 检索增强生成
- ✅ 生产环境最佳实践
下一步推荐：
- 动手实践：把教程代码都跑一遍
- 构建自己的项目：可以用 Deep Agents 快速原型
- 深入学习：LangGraph 高级特性
- 关注 LangSmith：学会调试和监控
祝你在 AI 应用开发之路上一路顺风！🚀
