LangChain 框架指南

说实话，我第一次看到 LangChain 时觉得没必要——直接调 OpenAI SDK 不就行了，干嘛多一层封装？

然后一个客户找我，他们有个 GPT-4 客服机器人，跑了三个月后说要"顺便也接入 Claude 试试"。我打开代码一看：OpenAI 的 client.chat.completions.create()、消息格式、错误处理散落在 18 个地方。换模型意味着改 18 处代码，每处都要测。那天我花了整整半天，当场决定下个项目用 LangChain。

所以 LangChain 解决的核心问题不是"让 AI 调用变简单"——直接调 SDK 其实一点不麻烦。它解决的是当你的 AI 代码变复杂之后，怎么不让自己陷入维护地狱。

LangChain 能帮你避免什么

先说不用它会发生什么：

你的 Prompt 开始是一个字符串，然后变成 f-string，然后变成一个函数，然后有人想"这里要支持中英文"于是 if/else 进来了，然后另一个人想"这里加个示例"……三个月后那段代码没人敢动。

输出解析更糟。模型今天返回 {"status": "ok"}，明天心情不好返回 {"Status": "OK"}，后天加了个解释性文字在 JSON 前面导致 json.loads() 直接崩。你写了一堆正则表达式来"修复"这个，然后 GPT-4o 出了个新版本又换输出格式了。

LangChain 的 PromptTemplate 和 OutputParser 就是专门管这两件事的。不神奇，但省心。

架构：三层一看就懂

整个 LangChain 生态可以理解为三层：

┌─────────────────────────────────────────────────────┐
│                  你的业务代码                          │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│               LangGraph（需要循环/多Agent时）          │
│   状态管理 · 条件分支 · 多节点协作 · 断点恢复           │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│               LangChain（日常使用这层）                │
│                                                     │
│  Prompts     Models      Parsers      Memory        │
│  提示词模板   模型调用     输出解析     对话记忆        │
│                                                     │
│  Tools       Chains      Agents    VectorStores     │
│  工具集成     链式调用     自主代理    向量数据库        │
│                                                     │
│  LCEL：用 | 把这些组件串联起来                         │
└─────────────────────────────────────────────────────┘
                       │
            ┌──────────┴───────────┐
            ▼                     ▼
    LangSmith（调试追踪）    LangServe（部署API）

大多数时候你只用中间这层。LangGraph 是等你真的需要"循环"或"多个 AI 互相协作"时才引入的东西——不需要提前学。

LCEL：理解这一个概念，其余都水到渠成

LangChain 0.2 引入了 LCEL（LangChain Expression Language），用 | 把组件串起来：

chain = prompt | llm | parser

这不只是好看的语法糖。用 | 连起来的 chain，自动获得这些能力：

# 同步调用，等完整结果
result = chain.invoke({"question": "..."})

# 流式输出，边生成边推给前端
for chunk in chain.stream({"question": "..."}):
    print(chunk, end="", flush=True)

# 异步，配合 FastAPI
result = await chain.ainvoke({"question": "..."})

# 批量并发
results = chain.batch([{"question": q} for q in questions])

我一开始觉得流式输出要另外搞一套逻辑，后来发现只要改 .invoke() 为 .stream() 就行了。这才体会到 LCEL 统一接口的价值。

5 分钟跑通第一个 Chain

pip install langchain langchain-openai python-dotenv

from dotenv import load_dotenv
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

load_dotenv()  # 从 .env 读 OPENAI_API_KEY

chain = (
    ChatPromptTemplate.from_messages([
        ("system", "你是一个{role}，回答简洁，不超过 100 字。"),
        ("user", "{question}"),
    ])
    | ChatOpenAI(model="gpt-4o-mini")
    | StrOutputParser()
)

print(chain.invoke({"role": "Python 专家", "question": "什么是列表推导式？"}))

就这些。能跑通这个，LangChain 的核心用法你已经掌握了 80%。

什么时候用，什么时候不用

这个问题很多人纠结，我直接给结论：

不需要 LangChain 的情况：你的项目只有一两个 AI 调用点，逻辑简单，不打算换模型。直接用 openai 包，代码更少，依赖更轻。

值得引入 LangChain 的情况：

有 5 个以上的 AI 调用点，Prompt 散落各处 → PromptTemplate 统一管理
需要解析结构化 JSON 输出，并且模型有时会输出格式错误 → OutputParser 自动处理
要接 RAG，需要向量数据库 → 统一的 VectorStore 接口
需要多轮对话记忆 → RunnableWithMessageHistory
可能在不同模型间切换（OpenAI ↔ Claude ↔ Gemini）→ 改一行代码就行

场景	直接用 SDK	用 LangChain	我的建议
单次问答	✅ 5 行搞定	杀鸡用牛刀	SDK
5+ 个 Prompt 需要维护	字符串拼接地狱	PromptTemplate	LangChain
需要解析 JSON 输出	手写正则/重试	OutputParser	LangChain
RAG 接向量库	手写每个库的适配	统一接口	LangChain
需要换模型	改 N 处代码	改一行	LangChain
循环/自主决策 Agent	手写状态机	LangGraph	LangChain

学习路径：按需选，不用全学

目标：快速上线一个 AI 功能（1-2 小时）

安装与配置 — 装好环境，配 API Key
Model I/O — PromptTemplate + 模型调用 + OutputParser

目标：做一个有记忆的对话机器人（再加 1 小时）

Memory 记忆系统 — 多轮对话，session 管理

目标：做企业内部知识库问答（再加 2-3 小时）

Chains — 把多步逻辑串起来
RAG 检索增强 — 文档加载、向量化、检索

目标：做一个能自主调用工具的 Agent（再加 2 小时）

Agents 代理系统 — 工具定义、自主决策
LangGraph 进阶 — 需要循环逻辑时才看这个

关于版本升级这件事

必须提前说：LangChain 的版本升级是我用过的开源库里最让人头疼的之一。

0.1 到 0.2，ConversationChain、LLMChain 全部被推荐改成 LCEL 写法。0.2 到 0.3，Pydantic v1 的代码要迁移到 v2，部分 import 路径改了。如果你在 Stack Overflow 或某个 CSDN 文章上找到代码，跑不通的概率很高，因为那文章可能是一年前写的。

辨别方法很简单：看到 from langchain.llms import OpenAI（注意不是 langchain_openai）或者 LLMChain，八成是旧代码。现代写法是 from langchain_openai import ChatOpenAI 加 LCEL。

我建议在 requirements.txt 里锁定版本：

langchain>=0.3.0,<0.4.0
langchain-openai>=0.2.0
langchain-community>=0.3.0

不锁版本的话，哪天 pip install -r requirements.txt 一跑，线上可能突然有什么东西不工作了。

有一个工具从第一天就应该开启

LangSmith。

不开 LangSmith 调试 LangChain 就像闭着眼睛开车——你不知道每一步传了什么 Prompt、收到了什么响应、用了多少 Token、哪一步卡了多久。

接入方式非常简单，在 .env 里加三行：

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY="ls__..."
LANGCHAIN_PROJECT="my-project"

不改一行业务代码，自动追踪所有 Chain 调用。免费额度对个人项目完全够用。

这不是什么可选的"后期优化"，是应该在写第一行 LangChain 代码的同一天就配好的东西。

小结

几个值得记住的点：

LangChain 的核心价值是统一接口和减少胶水代码，不是让 AI 变聪明。当项目只有一两个 AI 调用，不值得引入。
LCEL 的 | 语法是整个框架的核心——prompt | llm | parser 就是最小完整应用，自动支持同步/流式/异步/批量四种调用方式。
选型逻辑：固定流程用 Chain，有条件判断/循环用 LangGraph，需要 AI 自主决定下一步才用 Agent。不要一开始就设计最复杂的。
LangSmith 从第一天就接——遇到 Bug 时你会庆幸自己早开了它。
版本要锁定——LangChain 更新频繁，不锁版本某天会出现莫名其妙的兼容性问题。

下一步：安装与配置 — 5 分钟装好环境，跑通第一个 Chain

调试工具：LangSmith | 官方文档 | LangGraph

LangChain 框架指南

说实话，我第一次看到 LangChain 时觉得没必要——直接调 OpenAI SDK 不就行了，干嘛多一层封装？

#LangChain 能帮你避免什么

先说不用它会发生什么：

LangChain 的 PromptTemplate 和 OutputParser 就是专门管这两件事的。不神奇，但省心。

#架构：三层一看就懂

整个 LangChain 生态可以理解为三层：

┌─────────────────────────────────────────────────────┐
│                  你的业务代码                          │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│               LangGraph（需要循环/多Agent时）          │
│   状态管理 · 条件分支 · 多节点协作 · 断点恢复           │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│               LangChain（日常使用这层）                │
│                                                     │
│  Prompts     Models      Parsers      Memory        │
│  提示词模板   模型调用     输出解析     对话记忆        │
│                                                     │
│  Tools       Chains      Agents    VectorStores     │
│  工具集成     链式调用     自主代理    向量数据库        │
│                                                     │
│  LCEL：用 | 把这些组件串联起来                         │
└─────────────────────────────────────────────────────┘
                       │
            ┌──────────┴───────────┐
            ▼                     ▼
    LangSmith（调试追踪）    LangServe（部署API）

大多数时候你只用中间这层。LangGraph 是等你真的需要"循环"或"多个 AI 互相协作"时才引入的东西——不需要提前学。

#LCEL：理解这一个概念，其余都水到渠成

LangChain 0.2 引入了 LCEL（LangChain Expression Language），用 | 把组件串起来：

python
chain = prompt | llm | parser

这不只是好看的语法糖。用 | 连起来的 chain，自动获得这些能力：

python
# 同步调用，等完整结果
result = chain.invoke({"question": "..."})

# 流式输出，边生成边推给前端
for chunk in chain.stream({"question": "..."}):
    print(chunk, end="", flush=True)

# 异步，配合 FastAPI
result = await chain.ainvoke({"question": "..."})

# 批量并发
results = chain.batch([{"question": q} for q in questions])

我一开始觉得流式输出要另外搞一套逻辑，后来发现只要改 .invoke() 为 .stream() 就行了。这才体会到 LCEL 统一接口的价值。

#5 分钟跑通第一个 Chain

bash
pip install langchain langchain-openai python-dotenv

python
from dotenv import load_dotenv
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

load_dotenv()  # 从 .env 读 OPENAI_API_KEY

chain = (
    ChatPromptTemplate.from_messages([
        ("system", "你是一个{role}，回答简洁，不超过 100 字。"),
        ("user", "{question}"),
    ])
    | ChatOpenAI(model="gpt-4o-mini")
    | StrOutputParser()
)

print(chain.invoke({"role": "Python 专家", "question": "什么是列表推导式？"}))

就这些。能跑通这个，LangChain 的核心用法你已经掌握了 80%。

#什么时候用，什么时候不用

这个问题很多人纠结，我直接给结论：

不需要 LangChain 的情况：你的项目只有一两个 AI 调用点，逻辑简单，不打算换模型。直接用 openai 包，代码更少，依赖更轻。

值得引入 LangChain 的情况：

有 5 个以上的 AI 调用点，Prompt 散落各处 → PromptTemplate 统一管理
需要解析结构化 JSON 输出，并且模型有时会输出格式错误 → OutputParser 自动处理
要接 RAG，需要向量数据库 → 统一的 VectorStore 接口
需要多轮对话记忆 → RunnableWithMessageHistory
可能在不同模型间切换（OpenAI ↔ Claude ↔ Gemini）→ 改一行代码就行

场景	直接用 SDK	用 LangChain	我的建议
单次问答	✅ 5 行搞定	杀鸡用牛刀	SDK
5+ 个 Prompt 需要维护	字符串拼接地狱	PromptTemplate	LangChain
需要解析 JSON 输出	手写正则/重试	OutputParser	LangChain
RAG 接向量库	手写每个库的适配	统一接口	LangChain
需要换模型	改 N 处代码	改一行	LangChain
循环/自主决策 Agent	手写状态机	LangGraph	LangChain

#学习路径：按需选，不用全学

目标：快速上线一个 AI 功能（1-2 小时）

安装与配置 — 装好环境，配 API Key
Model I/O — PromptTemplate + 模型调用 + OutputParser

目标：做一个有记忆的对话机器人（再加 1 小时）

Memory 记忆系统 — 多轮对话，session 管理

目标：做企业内部知识库问答（再加 2-3 小时）

Chains — 把多步逻辑串起来
RAG 检索增强 — 文档加载、向量化、检索

目标：做一个能自主调用工具的 Agent（再加 2 小时）

Agents 代理系统 — 工具定义、自主决策
LangGraph 进阶 — 需要循环逻辑时才看这个

#关于版本升级这件事

必须提前说：LangChain 的版本升级是我用过的开源库里最让人头疼的之一。

我建议在 requirements.txt 里锁定版本：

langchain>=0.3.0,<0.4.0
langchain-openai>=0.2.0
langchain-community>=0.3.0

不锁版本的话，哪天 pip install -r requirements.txt 一跑，线上可能突然有什么东西不工作了。

#有一个工具从第一天就应该开启

LangSmith。

不开 LangSmith 调试 LangChain 就像闭着眼睛开车——你不知道每一步传了什么 Prompt、收到了什么响应、用了多少 Token、哪一步卡了多久。

接入方式非常简单，在 .env 里加三行：

bash
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY="ls__..."
LANGCHAIN_PROJECT="my-project"

不改一行业务代码，自动追踪所有 Chain 调用。免费额度对个人项目完全够用。

这不是什么可选的"后期优化"，是应该在写第一行 LangChain 代码的同一天就配好的东西。

#小结

几个值得记住的点：

LangChain 的核心价值是统一接口和减少胶水代码，不是让 AI 变聪明。当项目只有一两个 AI 调用，不值得引入。
LCEL 的 | 语法是整个框架的核心——prompt | llm | parser 就是最小完整应用，自动支持同步/流式/异步/批量四种调用方式。
选型逻辑：固定流程用 Chain，有条件判断/循环用 LangGraph，需要 AI 自主决定下一步才用 Agent。不要一开始就设计最复杂的。
LangSmith 从第一天就接——遇到 Bug 时你会庆幸自己早开了它。
版本要锁定——LangChain 更新频繁，不锁版本某天会出现莫名其妙的兼容性问题。

下一步：安装与配置 — 5 分钟装好环境，跑通第一个 Chain

调试工具：LangSmith↗ | 官方文档↗ | LangGraph↗

LangChain 框架指南

LangChain 能帮你避免什么

架构：三层一看就懂

LCEL：理解这一个概念，其余都水到渠成

5 分钟跑通第一个 Chain

什么时候用，什么时候不用

学习路径：按需选，不用全学

关于版本升级这件事

有一个工具从第一天就应该开启

小结

LangChain 框架指南

LangChain 框架指南

#LangChain 能帮你避免什么

#架构：三层一看就懂

#LCEL：理解这一个概念，其余都水到渠成

#5 分钟跑通第一个 Chain

#什么时候用，什么时候不用

#学习路径：按需选，不用全学

#关于版本升级这件事

#有一个工具从第一天就应该开启

#小结

系统设计必备：核心概念 + 经典案例

相关指南

相关路线图