1. LangChain要解决什么问题 #

直接调用某个大模型厂商的 HTTP API，也能做出「一问一答」。但真实业务很快会碰到：

LangChain 要解决的，就是把这些能力拆成可组合的积木，再用统一的 Agent 驾驭层把它们拼成可上线的应用。

本文目标：带你从零搭出能跑通的 Agent 与 RAG 实战应用。

2. LangChain 是什么 #

LangChain 的核心定位浓缩成一句话：

Agent = Model + Harness（智能体 = 模型 + 驾驭层）

部分 含义 例子
Model（模型） 负责推理与决策 选不选工具、理解工具结果、给出最终回答
Harness（驾驭层） 围绕模型循环的一切 提示词、工具、塑造行为的 middleware（中间件）

LangChain 提供高度可配置的入口 create_agent：从一个最小 harness 起步，再按需叠加能力。模型侧支持 OpenAI、Anthropic、Google 等大量供应商。

可以把它理解成：

你要做的应用
    │
    ▼
create_agent（标准「模型 ↔ 工具」循环 + 可扩展中间件）
    │
    ├── Model：openai / deepseek / anthropic / ollama …
    ├── Tools：查库、调 API、算数、检索知识库 …
    ├── Prompt：系统人设、业务约束
    └── Middleware：护栏、重试、限流、人机协同 …

3. 为什么需要 LangChain #

痛点 LangChain 怎么帮你
换模型要改一大堆调用代码 统一聊天模型 / 嵌入接口，供应商可切换
工具调用、多轮循环手写易错 create_agent 提供标准「模型 ↔ 工具」循环
需要护栏、重试、路由、权限 用 middleware 渐进增强 harness
要可观测、评测、上线排错 与 LangSmith 深度集成
要持久化、人机协同、长任务 Agent 构建在 LangGraph 之上

官方强调的四大核心收益（见 Overview · Core benefits）：

  1. 标准模型接口 — 聊天模型、嵌入等跨供应商统一；改模型时业务代码改动最小。
  2. 高度可配置的 harness — 从最小的 create_agent 开始，用 middleware 按需加护栏、重试、路由、工具策略等。
  3. 构建在 LangGraph 之上 — 可享受持久执行、人机协同（human-in-the-loop）、状态持久化等编排能力。
  4. 用 LangSmith 调试 — 在一处查看轨迹、工具调用、状态迁移与延迟，定位失败模式并改进质量。

4. 产品族谱：LangChain / LangGraph / Deep Agents / LangSmith #

LangChain 很少单独出现。产品线分工如下：

产品 角色 什么时候选
Deep Agents 「开箱即用」的 agent 要规划、子 Agent、虚拟文件系统、上下文压缩等现成能力
LangChain（create_agent） 可高度定制的 Agent 框架 要按业务精确组装模型 / 工具 / 提示 / 中间件
LangGraph 底层编排运行时 要在同一图里混合「确定性步骤 + 智能体步骤」
LangSmith 观测、评测与部署配套 追踪、调试、评估任意上述框架构建的 Agent

选型直觉：

想要最快上手、功能齐      → Deep Agents
想要可控、可裁剪的 Agent  → LangChain create_agent
想要图编排与生产级状态机  → LangGraph
想要看清每次调用发生了什么 → LangSmith

关系可以记成「由上到下抽象变高、开箱能力变多；由下到上控制力变强」：

Deep Agents
    ↑ 建在之上
LangChain Agents（create_agent）
    ↑ 建在之上
LangGraph（图编排 / 持久化 / HITL）
    ↑ 搭配使用
LangSmith（追踪 / 评测 / 排障）

本文以 LangChain create_agent + 核心积木 为主线，后期会自然衔接到 RAG、LangGraph 与 LangSmith。

5. Agent 怎么工作 #

官方定义（Agents）：

Agent 是一个在循环中不断调用工具、直到完成任务的模型。
Harness 是这个循环周围的一切：提示、工具、以及塑造模型行为的中间件。
Harness 的职责：在正确的时间，给模型正确的上下文。

简化循环：

用户输入
   ↓
模型推理（要不要调工具？调哪个？参数是什么？）
   ↓
若需要 → 执行工具 → 把结果塞回消息 → 再推理
   ↓
否则 → 输出最终回答

对应官方组件架构里的「Agent with tools」模式（见 Component architecture）：

User request → Agent → 需要工具? ──Yes→ Call tool → 结果回传 Agent
                      └─No→ Final answer

5.1. 运行示例 #

5.1.1 安装依赖 #

安装（Windows PowerShell）：

# 建议 Python 3.10+
pip install -U langchain langchain-deepseek python-dotenv
# 或使用 uv
# uv add langchain langchain-deepseek python-dotenv

5.1.2 .env # 

DEEPSEEK_API_KEY="sk-xxx"

5.1.3 1.create_agent.py # 

# 从 langchain.agents 模块导入 create_agent 函数，用于创建智能体
from langchain.agents import create_agent

# 从 dotenv 模块导入 load_dotenv 函数，用于加载环境变量
from dotenv import load_dotenv

# 加载 .env 文件中的环境变量，override=True 表示覆盖已存在的同名环境变量
load_dotenv(override=True)


# 定义获取天气信息的工具函数，参数 city 为城市名称，返回值为字符串
def get_weather(city: str) -> str:
    # 函数文档字符串：说明该函数用于获取指定城市的天气信息
    """获取指定城市的天气信息。"""
    # 返回模拟的天气信息字符串
    return f"{city} 今天晴，气温 25°C。"


# 调用 create_agent 创建智能体实例
agent = create_agent(
    # 指定使用的模型为 deepseek 提供商的 deepseek-v4-flash 模型
    model="deepseek:deepseek-v4-flash",
    # 将 get_weather 普通 Python 函数注册为智能体可调用的工具
    tools=[get_weather],
    # 设置系统提示词，定义助手简洁、可靠的行为风格
    system_prompt="你是一个简洁、可靠的助手。",
    # 结束 create_agent 函数调用
)

# 调用智能体处理用户请求，并获取执行结果
result = agent.invoke(
    # 构造包含用户问题的消息字典，询问北京今天的天气
    {"messages": [{"role": "user", "content": "北京今天天气怎么样？"}]}
    # 结束 agent.invoke 函数调用
)

# 打印结果中最后一条消息的内容（即助手的回复）
print(result["messages"][-1].content)

要点：

同一套 API 换成 DeepSeek / Anthropic / Ollama，通常只需改 model 与对应集成包。

5.2. 换供应商只改一行 # 

# OpenAI（需先：pip install -U "langchain[openai]"）
agent = create_agent(model="openai:gpt-4o-mini", tools=[get_weather])

# DeepSeek（需先：pip install -U langchain-deepseek）
agent = create_agent(model="deepseek:deepseek-v4-flash", tools=[get_weather])

# Anthropic（需先：pip install -U langchain-anthropic）
agent = create_agent(model="anthropic:claude-sonnet-4-6", tools=[get_weather])

# 本地 Ollama（需先：pip install -U langchain-ollama，且本机 Ollama 已启动）
agent = create_agent(model="ollama:llama3.2", tools=[get_weather])

6. 核心积木 #

即便最终目标是 Agent，LangChain 仍由一组可组合积木构成。官方把它们分成几大类（Component architecture）：

类别 作用 典型用途
Models AI 推理与生成 聊天、结构化输出、嵌入
Tools 外部能力 查库、调 API、计算、检索
Agents 编排与决策 工具循环、非确定性工作流
Memory 上下文保持 多轮对话、自定义状态
Retrievers 信息获取 RAG、知识库搜索
Document processing 数据摄入 PDF / 网页加载与切分
Vector Stores 语义检索存储 Chroma、FAISS、Pinecone 等

数据在应用里大致这样流动：

① 输入处理：加载文档 → 切分 → Documents
② 嵌入存储：Embedding → Vectors → Vector Store
③ 检索：用户问题 → 向量化 → Retriever → 相关上下文
④ 生成：Chat Model（± Tools）→ 回答
⑤ 编排：Agent + Memory 把以上环节串起来

整体关系可以记成：

┌─────────────────────────────────────────────┐
│                 create_agent                 │
│  model + tools + system_prompt + middleware │
└──────────────────────▲──────────────────────┘
                       │ 由积木拼装 / 扩展
     messages · prompts · tools · runnable
     loaders · splitters · embeddings · retrievers

6.1. Model（模型） #

见 Models。模型是 Agent 的「大脑」，也可单独使用（分类、抽取、生成）。

常见能力：

两种常见初始化方式：

# 导入 os 模块，用于读取环境变量
import os

# 从 dotenv 模块导入 load_dotenv 函数，用于加载环境变量
from dotenv import load_dotenv

# 加载 .env 文件中的环境变量，override=True 表示覆盖已存在的同名环境变量
load_dotenv(override=True)

# 方式 A：统一工厂（推荐，切换供应商方便）
# 从 langchain.chat_models 模块导入 init_chat_model 函数，用于初始化聊天模型
from langchain.chat_models import init_chat_model

# 使用统一工厂创建 DeepSeek 的 deepseek-v4-flash 聊天模型实例
model = init_chat_model("deepseek:deepseek-v4-flash")
# 调用模型生成回复，并打印返回消息的文本内容
print(model.invoke("用一句话介绍 LangChain").content)

# 方式 B：OpenAI 兼容接口（DeepSeek 需显式传入 key 与 base_url）
# 从 langchain_openai 模块导入 ChatOpenAI 类，用于通过 OpenAI 兼容接口调用模型
from langchain_openai import ChatOpenAI

# 创建 ChatOpenAI 模型实例，显式配置 DeepSeek 的模型名、密钥与接口地址
model = ChatOpenAI(
    # 指定要使用的模型名称为 deepseek-v4-flash
    model="deepseek-v4-flash",
    # 从环境变量中读取 DeepSeek API 密钥
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    # 从环境变量读取 API 基础地址，若未设置则默认使用 DeepSeek 官方地址
    base_url=os.getenv("OPENAI_API_BASE", "https://api.deepseek.com"),
)
# 调用模型生成回复，并打印返回消息的文本内容
print(model.invoke("用一句话介绍 LangChain").content)

6.2. Messages（消息） #

见 Messages。消息是模型交互的基本状态单元，常见角色：

类型 角色 含义
SystemMessage system 人设与全局约束
HumanMessage user 用户输入
AIMessage assistant 模型输出（可含 tool_calls）
ToolMessage tool 工具执行结果回传给模型 
# 从 langchain.chat_models 模块导入 init_chat_model 函数，用于初始化聊天模型
from langchain.chat_models import init_chat_model
# 从 langchain_core.messages 模块导入 SystemMessage 与 HumanMessage 消息类型
from langchain_core.messages import SystemMessage, HumanMessage

# 从 dotenv 模块导入 load_dotenv 函数，用于加载环境变量
from dotenv import load_dotenv

# 加载 .env 文件中的环境变量，override=True 表示覆盖已存在的同名环境变量
load_dotenv(override=True)
# 使用统一工厂创建 DeepSeek 的 deepseek-v4-flash 聊天模型实例
model = init_chat_model("deepseek:deepseek-v4-flash")

# 构建发送给模型的消息列表，包含系统提示与用户问题
messages = [
    # 系统消息：设定模型扮演耐心导师的角色
    SystemMessage("你是一位耐心的导师"),
    # 用户消息：请求用一句话解释什么是 LangChain
    HumanMessage("请用一句话解释什么是 LangChain"),
]
# 调用模型生成回复，并打印返回消息的文本内容
print(model.invoke(messages).content)

6.3. Tools（工具） #

把检索、数据库、HTTP、业务函数暴露给模型。Agent 循环里，工具是「手脚」。

# 从 langchain.tools 模块导入 tool 装饰器，用于将普通函数转换为智能体可调用的工具
from langchain.tools import tool

# 从 langchain.agents 模块导入 create_agent 函数，用于创建带工具调用能力的智能体
from langchain.agents import create_agent

# 从 dotenv 模块导入 load_dotenv 函数，用于加载环境变量
from dotenv import load_dotenv

# 加载 .env 文件中的环境变量，override=True 表示覆盖已存在的同名环境变量
load_dotenv(override=True)


# 使用 @tool 装饰器将下方函数注册为 LangChain 工具
@tool
# 定义加法工具函数，接收两个整数参数 a 与 b，并返回它们的和
def add(a: int, b: int) -> int:
    # 工具的文档字符串，描述该工具的功能，供模型判断何时调用
    """计算两个整数之和。"""
    # 返回两个整数相加后的结果
    return a + b


# 创建智能体实例，并配置所用模型、可用工具与系统提示
agent = create_agent(
    # 指定使用 DeepSeek 的 deepseek-v4-flash 聊天模型
    model="deepseek:deepseek-v4-flash",
    # 将 add 工具注册到智能体，使其在需要时可被调用
    tools=[add],
    # 系统提示：要求模型在计算时调用工具，禁止心算
    system_prompt="需要计算时请调用工具，不要心算。",
    # 结束 create_agent 调用
)

# 调用智能体处理用户问题，传入包含用户消息的输入字典
result = agent.invoke(
    # 构造消息列表，角色为 user，内容为需要计算的加法问题
    {"messages": [{"role": "user", "content": "123 + 456 等于多少？"}]}
    # 结束 agent.invoke 调用
)
# 打印智能体返回结果中最后一条消息的文本内容
print(result["messages"][-1].content)

6.4. Middleware（中间件） #

在 harness 上增量加能力：护栏、重试、限流、PII 脱敏、人机协同等。详见 Middleware。

6.5. RAG 相关组件 #

文档加载 → 切分 → 嵌入 → 向量库 → 检索 →（可选压缩重排）→ 模型生成。这是企业知识库问答的标准路径。

7. 安装与生态包 #

7.1. 安装 LangChain #

需要 Python 3.10+（见 Install）：

pip install -U langchain python-dotenv
# 或
uv add langchain python-dotenv

按供应商安装集成包，例如：

pip install -U langchain-deepseek    # DeepSeek（本教程默认）
pip install -U "langchain[openai]"   # OpenAI（含常用依赖组合）
pip install -U langchain-openai      # 仅 OpenAI 集成
pip install -U langchain-anthropic   # Anthropic
pip install -U langchain-ollama      # 本地 Ollama

完整列表见 Integrations · Providers。

7.2. 常见包怎么分工 #

包 作用
langchain 主框架：Agent、init_chat_model、高层编排入口
langchain-core 核心抽象：消息、Runnable、工具协议等
langchain-openai / langchain-anthropic / … 各厂商模型与嵌入适配
langchain-community 社区维护的加载器、检索器、部分集成
langchain-text-splitters 文本切分
langchain-chroma 等 向量库集成
langgraph 底层图编排（Agent 运行时可依赖）

原则：

业务从 langchain 起步；接具体厂商装对应集成包；需要社区数据源再加 langchain-community。

7.3. API Key 与观测 #

.env 示例（请替换为你自己的密钥，勿提交真实 key）：

DEEPSEEK_API_KEY="sk-xxx"
OPENAI_API_BASE="https://api.deepseek.com"
OPENAI_API_KEY="sk-xxx"

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY="lsv2_pt_xxx"
LANGSMITH_PROJECT="langchain"

建议尽早打开 LangSmith Tracing；进一步可用 LangSmith Engine 根据轨迹发现问题并给出修复建议。

8. 典型应用场景 #

场景 常用组合
带工具的助理 create_agent + 自定义 tools
结构化信息抽取 模型 + Structured Output
多轮客服 / 会话 消息历史 + Agent / Memory
知识库问答（RAG） 加载 → 切分 → 嵌入 → 检索 → 生成
复杂业务流程 LangGraph：确定性节点 + Agent 节点
生产排障与评测 LangSmith 追踪 / 评测

9. 大纲 #

9.1 阶段一：打底（认识积木） #

章 标题 你将学会 产出物
1 LangChain 介绍与课程大纲 定位、产品族谱、Agent 循环、整体地图 心智模型 + 学习路线
2 第一个 Agent create_agent、消息轨迹、多工具、流式 可运行的天气助手
3 Chat Models 聊天模型 init_chat_model、多供应商切换、流式输出、参数调优 统一模型调用层
4 Messages 消息体系 System / Human / AI / Tool 消息、多模态入门 正确的对话状态表示
5 Prompts 提示词工程 提示模板、变量填充、少样本、系统提示设计 可维护的 prompt 层

9.2 阶段二：组合（从链到 Agent） #

章 标题 你将学会 产出物
6 结构化输出 Structured Output、Pydantic、解析失败处理 订单 / 工单抽取器
7 Runnable 与 LCEL 管道组合 ` `、并行、分支、流式 可组合的处理链
8 Tools 工具定义与调用 @tool、参数 schema、错误处理、bind_tools 业务工具包
9 create_agent 深入 系统提示、多工具协作、动态选模型/工具 多工具办公助理
10 Middleware 与安全护栏 重试、限流、PII、人机协同（HITL） 带护栏的生产向 Agent

9.3 阶段三：记忆与知识库（RAG 主线） #

章 标题 你将学会 产出物
11 Memory 短期记忆与会话 线程、checkpoint、多轮上下文 带记忆的客服 Agent
12 Document Loaders 文档加载 PDF / 网页 / 文本等加载器 企业文档摄入脚本
13 Text Splitters 文本切分 chunk 策略、重叠、按结构切分 高质量切片流水线
14 Embeddings 与向量库 嵌入模型、Chroma / FAISS、相似度检索 本地向量知识库
15 Retrievers 与 RAG 实战 检索增强生成、重排、Agentic RAG 企业知识库问答系统

9.4 阶段四：进阶与上线 #

章 标题 你将学会 产出物
16 LangGraph 入门 状态图、确定性节点 + Agent 节点、分支与循环 审批流 / 多步业务图
17 LangSmith 观测与评测 Tracing、数据集、评测器、回归对比 可度量的质量闭环
18 综合实战项目 把 Agent + RAG + 护栏 + 观测拼成一个完整应用 可演示的毕业项目

9.5. 学习路径图 # 

第1章 总览与大纲
   │
   ▼
第2章 第一个 Agent ──────────────► 建立「跑通」信心
   │
   ├─► 第3–5章  模型 / 消息 / 提示
   │
   ├─► 第6–7章  结构化输出 / Runnable
   │
   ├─► 第8–10章 工具 / Agent / Middleware   ◄── 应用核心
   │
   ├─► 第11章   会话记忆
   │
   ├─► 第12–15章 RAG 全链路               ◄── 企业知识库主线
   │
   └─► 第16–18章 LangGraph / LangSmith / 综合项目

9.6 文档 #

主题 链接
Overview https://docs.langchain.com/oss/python/langchain/overview
Install https://docs.langchain.com/oss/python/langchain/install
Quickstart https://docs.langchain.com/oss/python/langchain/quickstart
Agents https://docs.langchain.com/oss/python/langchain/agents
Models https://docs.langchain.com/oss/python/langchain/models
Messages https://docs.langchain.com/oss/python/langchain/messages
Tools https://docs.langchain.com/oss/python/langchain/tools
Middleware https://docs.langchain.com/oss/python/langchain/middleware/overview
Component architecture https://docs.langchain.com/oss/python/langchain/component-architecture
LangGraph https://docs.langchain.com/oss/python/langgraph/overview
LangSmith https://docs.langchain.com/langsmith/observability
Providers https://docs.langchain.com/oss/python/integrations/providers/overview
文档索引（llms.txt） https://docs.langchain.com/llms.txt
← 上一节 没有上一节
下一节 2.第一个Agent →