一、LangChain 是什么？为什么重要？
LangChain 是一个开源 Python/JS 框架，用于构建基于大语言模型（LLM）的应用程序。它最初由 Harrison Chase 于 2022 年秋季作为副业项目启动，到 2025 年 10 月发布 1.0 版本时，已拥有 135,000+ GitHub Stars、22,300+ Forks、2.35 亿月下载量。背后的公司 LangChain Inc. 在 2025 年 10 月以 12.5 亿美元估值完成 B 轮融资，累计融资约 2.6 亿美元。
1.1 核心定位：解决原始 LLM API 的局限
单独使用 LLM API 有三大局限：无法保留上下文、无法访问实时数据、无法调用外部工具。LangChain 把这些"胶水代码"抽象成可复用的组件，让开发者可以像搭积木一样构建复杂应用。
LangChain 解决的三大问题：
- 无状态 → 有状态：原始 API 每次调用独立，LangChain 提供 Memory 让对话能跨轮次保留上下文
- 静态知识 → 动态知识：通过 Retriever 接入私有文档、数据库、API，让 LLM 能回答训练数据之外的问题
- 纯文本 → 工具调用：通过 Agent + Tool 让 LLM 自主决定调用搜索、计算、数据库等外部工具
1.2 2026 年的 LangChain：不只是框架，是生态
今天的 LangChain 已经不只是"一个 Python 库"，而是一个完整的 LLM 应用开发生态系统，包含四大产品：
- LangChain（框架）：核心库，提供组件和 LCEL 编排语言
- LangGraph（编排层）：基于图的低级别工作流编排，支持循环、分支、持久化
- LangSmith（可观测性）：追踪、调试、评估平台，每月近 3 万新用户注册
- LangServe（部署）：将 LCEL Chain 暴露为 REST API
35% 的 Fortune 500 公司在生产中使用 LangChain。84.7% 的使用量来自 Python SDK。State of AI 2024 报告显示：43% 的 LangSmith 组织现在发送 LangGraph 追踪，标志着从简单检索工作流向 Agentic 多步应用的转变。
二、核心架构：Runnable 与 LCEL
LangChain 1.0 最重要的架构变革是全面统一到 Runnable 接口和 LCEL（LangChain Expression Language）。旧版的 LLMChain、SequentialChain 等已被弃用。理解 Runnable 和 LCEL 是掌握现代 LangChain 的关键。
2.1 Runnable 接口：一切皆是 Runnable
Runnable 是 LangChain 的核心抽象接口。Chat Model、Prompt Template、Output Parser、Retriever、Agent——所有组件都实现 Runnable。这带来了三大好处：
- 统一调用方式：所有组件都支持 invoke()、stream()、batch() 及异步版本 ainvoke()、astream()、abatch()
- 自动并行化：用 LCEL 构建的 Chain 自动支持并行执行、流式传输、批处理
- 可组合性：任何两个 Runnable 可以组合成新的 Runnable，递归构建复杂工作流
2.2 LCEL：用管道符号编排 LLM 工作流
LCEL 使用 Unix 风格的管道符 | 来组合组件，简洁直观：
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
# 一条链 = Prompt | LLM | Parser
chain = (
ChatPromptTemplate.from_template("Summarise this: {text}")
| llm
| StrOutputParser()
)
result = chain.invoke({"text": "LangChain is a framework..."})
2.3 并行执行：RunnableParallel
当多个步骤之间没有依赖关系时，可以用 RunnableParallel 同时执行，显著降低延迟：
from langchain_core.runnables import RunnableParallel
chain = RunnableParallel(
pros=pros_prompt | llm | StrOutputParser(),
cons=cons_prompt | llm | StrOutputParser(),
summary=summary_prompt | llm | StrOutputParser(),
)
results = chain.invoke({"topic": "LangChain"})
# 三个 LLM 调用并发执行
2.4 中间结果访问
LCEL Chain 可以通过字典推导访问中间结果，实现更复杂的分支逻辑：
chain = (
{"summary": summarise_prompt | llm | parser}
| translate_prompt
| llm
| parser
)
三、七大核心组件
3.1 Chat Models（对话模型）
LangChain 将所有 LLM 提供商封装成统一接口。切换提供商只需改一行 import：
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
# OpenAI
llm = ChatOpenAI(model="gpt-4o", temperature=0)
# Anthropic —— 完全相同的接口
llm = ChatAnthropic(model="claude-opus-4-6", temperature=0)
response = llm.invoke("What is prompt engineering?")
每个 Chat Model 支持三种核心调用方式：
- invoke()：同步调用，返回完整响应（AIMessage）
- stream()：流式调用，实时返回 token 块（AIMessageChunk），适合长文本生成
- batch()：批处理，并行处理多个独立请求
3.2 Prompt Templates（提示模板）
Prompt Template 将原始输入格式化为 LLM 可理解的结构化消息。LangChain 支持多种模板类型：
# ChatPromptTemplate：多角色对话式提示
prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful {role}."),
("human", "{question}"),
])
# FewShotPromptTemplate：少样本示例
prompt = FewShotPromptTemplate(
examples=examples,
example_prompt=example_prompt,
suffix="Question: {input}",
input_variables=["input"],
)
3.3 Output Parsers（输出解析器）
LLM 输出的是原始文本，Output Parser 负责将其转换为结构化数据。三种主要类型：
from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser
class APIEndpoint(BaseModel):
path: str = Field(description="API endpoint path")
method: str = Field(description="HTTP method")
description: str = Field(description="What it does")
parser = PydanticOutputParser(pydantic_object=APIEndpoint)
chain = prompt | llm | parser
result = chain.invoke({"use_case": "user authentication"})
# result.path == "/api/auth/login"
3.4 Retrievers（检索器）
Retriever 是 RAG 的核心组件，负责从数据源中获取与用户查询相关的文档。Retriever 本身也是 Runnable，因此可以无缝集成到 LCEL Chain 中。
- Vector Store Retriever：基于向量相似度的语义检索（最常用）
- BM25 Retriever：基于关键词的传统信息检索
- Ensemble Retriever：混合检索，结合向量和关键词
- Parent Document Retriever：用小 chunk 检索，返回大 chunk
- Multi-Vector Retriever：为每个文档生成多个向量（摘要、假设问题等）
- Contextual Compression Retriever：检索后压缩，只保留相关部分
3.5 Memory（记忆）
Memory 让 LLM 应用能保留对话历史。现代 LangChain 提供多种记忆机制：
- InMemoryChatMessageHistory：内存中的对话历史（开发/原型用）
- RedisChatMessageHistory：Redis 持久化（生产用）
- RunnableWithMessageHistory：包装器，自动管理对话线程
from langchain_core.runnables.history import RunnableWithMessageHistory
chain_with_history = RunnableWithMessageHistory(
chain,
get_session_history=get_session_history,
input_messages_key="question",
history_messages_key="history",
)
3.6 Agents（智能体）
Agent 是 LLM 驱动的决策系统。模型根据任务描述和可用工具，自主决定调用哪些工具、以什么顺序调用。LangChain 1.0 简化了 Agent 创建：
from langchain.agents import create_agent
def get_weather(city: str) -> str:
"""Get weather for a given city."""
return f"It's sunny in {city}!"
agent = create_agent(
model="openai:gpt-4o",
tools=[get_weather],
system_prompt="You are a helpful assistant",
)
result = agent.invoke({
"messages": [{"role": "user", "content": "SF weather?"}]
})
3.7 Tools（工具）
Tool = Schema（名称+描述+参数定义）+ Function（执行逻辑）。LangChain 通过函数 docstring 和类型注解自动生成工具 Schema，供 LLM 理解何时调用。
from langchain.tools import tool
@tool
def search_database(query: str) -> str:
"""Search internal docs for the query. Use for product questions."""
return retriever.invoke(query)[0].page_content
四、完整实践案例一：RAG 知识库问答系统
RAG（Retrieval-Augmented Generation，检索增强生成）是 LangChain 最主流的生产场景。下面是一个从 0 到 1 的完整实现，涵盖文档加载 → 切分 → 嵌入 → 存储 → 检索 → 生成的全流程。
4.1 步骤总览
RAG 五步法
Step 1：文档加载 —— 从 PDF/网页/数据库加载原始文档
Step 2：文本切分 —— 将长文档切成适合模型上下文的小块
Step 3：嵌入+存储 —— 将文本块转为向量，存入向量数据库
Step 4：检索 —— 根据用户查询找出最相关的文本块
Step 5：生成 —— 将检索结果作为上下文，让 LLM 生成回答
4.2 Step 1：文档加载
from langchain_community.document_loaders import PyPDFLoader, DirectoryLoader
# 加载单个 PDF
loader = PyPDFLoader("document.pdf")
pages = loader.load() # 返回 List[Document]
# 批量加载目录下所有 PDF
loader = DirectoryLoader(
"./docs",
glob="**/*.pdf",
loader_cls=PyPDFLoader,
show_progress=True,
)
docs = loader.load()
4.3 Step 2：文本切分
切分策略直接影响 RAG 效果。RecursiveCharacterTextSplitter 是通用场景的首选：它会尝试在段落、句子等自然边界处切分，只有当 chunk 仍然过大时才使用更小的分隔符。
from langchain_text_splitters import RecursiveCharacterTextSplitter
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000, # 每个 chunk 约 1000 字符
chunk_overlap=200, # 相邻 chunk 重叠 200 字符，保留上下文
add_start_index=True, # 记录在原文档中的位置
)
all_splits = text_splitter.split_documents(docs)
# 42k 字符的文档可能被切分为 66 个子文档
chunk_size 和 chunk_overlap 的选择原则：
- chunk_size：取决于嵌入模型的最大输入长度（如 text-embedding-3-small 支持 8191 tokens）和 LLM 的上下文窗口
- chunk_overlap：通常为 chunk_size 的 10-20%，确保跨边界的信息不被切断
- 对于代码等技术文档，可考虑基于语义的切分策略（如按函数、类切分）
4.4 Step 3：嵌入与向量存储
from langchain_openai import OpenAIEmbeddings
from langchain_chroma import Chroma
# 1. 选择嵌入模型
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
# 2. 创建向量数据库
vector_store = Chroma.from_documents(
documents=all_splits,
embedding=embeddings,
persist_directory="./chroma_db", # 持久化到磁盘
collection_metadata={"hnsw:space": "cosine"},
)
# 3. 保存索引（避免下次重启时重新嵌入）
vector_store.persist()
向量数据库选型参考：
- Chroma：开源、轻量、本地运行，适合原型和小规模应用
- Pinecone：全托管云原生，适合生产环境，按量付费
- Weaviate：混合搜索（向量+BM25），支持 GraphQL
- Qdrant：Rust 编写，高性能，支持过滤和混合搜索
- Milvus：分布式，适合十亿级向量规模
- FAISS：Meta 开源，纯内存，速度极快
4.5 Step 4 + 5：检索与生成（完整 LCEL Chain）
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
# 1. 配置检索器
retriever = vector_store.as_retriever(
search_type="similarity",
search_kwargs={"k": 5} # 返回 top-5 最相关 chunk
)
# 2. 构建 RAG Prompt
template = """Answer the question based only on the following context:
<context>
{context}
</context>
Question: {question}
If you don't know the answer, say "I don't know"."""
prompt = ChatPromptTemplate.from_template(template)
# 3. 辅助函数：将检索结果格式化为字符串
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
# 4. 构建完整 RAG Chain
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
# 5. 执行
answer = rag_chain.invoke("What is LangChain's main purpose?")
4.6 RAG 进阶：混合检索 + 重排序
单纯向量检索有时不够精确。生产级 RAG 通常采用"混合检索 + 重排序"的两阶段策略：
from langchain.retrievers import EnsembleRetriever
from langchain_community.retrievers import BM25Retriever
from langchain.retrievers.document_compressors import LLMChainExtractor
from langchain.retrievers import ContextualCompressionRetriever
# 阶段 1：混合检索（向量 + BM25）
bm25_retriever = BM25Retriever.from_documents(all_splits)
bm25_retriever.k = 5
vector_retriever = vector_store.as_retriever(search_kwargs={"k": 5})
ensemble_retriever = EnsembleRetriever(
retrievers=[bm25_retriever, vector_retriever],
weights=[0.4, 0.6], # 向量检索权重更高
)
# 阶段 2：上下文压缩（只保留相关段落）
compressor = LLMChainExtractor.from_llm(llm)
compression_retriever = ContextualCompressionRetriever(
base_compressor=compressor,
base_retriever=ensemble_retriever,
)
# 使用压缩检索器替换原检索器
rag_chain = (
{"context": compression_retriever | format_docs, "question": RunnablePassthrough()}
| prompt | llm | StrOutputParser()
)
五、完整实践案例二：Agent 智能体
Agent 是 LangChain 最激动人心的能力——让 LLM 自主决定调用哪些工具、以什么顺序调用。下面构建一个能搜索文档、计算数据、查询天气的多工具 Agent。
5.1 定义工具
from langchain.tools import tool
@tool
def search_docs(query: str) -> str:
"""Search internal documentation for the given query.
Use this for questions about product features, APIs, or internal policies."""
return retriever.invoke(query)[0].page_content
@tool
def calculate(expression: str) -> str:
"""Evaluate a mathematical expression. Use for calculations."""
try:
return str(eval(expression))
except:
return "Invalid expression"
@tool
def get_weather(city: str) -> str:
"""Get current weather for a city."""
return f"Weather in {city}: 25C, Sunny"
5.2 创建 Agent
from langchain.agents import create_agent
agent = create_agent(
model="openai:gpt-4o",
tools=[search_docs, calculate, get_weather],
system_prompt="""You are a helpful assistant. Follow these rules:
1. Always use tools when you need external information
2. Show your reasoning process
3. If you don't know, say so""",
)
5.3 执行 Agent
result = agent.invoke({
"messages": [{
"role": "user",
"content": "What's the weather in Tokyo and what is 123 * 456?"
}]
})
5.4 Agent 执行流程解析
Agent 内部执行循环
1. 输入处理：Agent 接收用户消息，加载历史对话（如有 Memory）
2. 推理阶段：LLM 分析请求，查看可用工具列表及其描述，决定调用哪些工具
3. 工具调用：Agent 执行选中的工具，获取结果
4. 观察与迭代：LLM 处理工具结果，决定给出最终答案还是继续调用更多工具
5. 状态持久化：对话状态（消息、工具调用、结果）保存到 Checkpointer
六、LangGraph：复杂工作流的图编排
LangGraph 是 LangChain 生态的低级别编排框架，2024 年 3 月发布。它将工作流建模为有向图，节点是 Python 函数，边是状态转换。当工作流需要循环、条件分支或持久化状态时，LangGraph 是正确选择。
6.1 LangGraph 与 LangChain Agent 的区别
6.2 LangGraph 核心概念
- StateGraph：状态图，定义工作流的结构
- State（状态）：TypedDict 定义，所有节点共享的状态对象
- Node（节点）：Python 函数，接收状态、返回状态更新
- Edge（边）：节点之间的连接，包括普通边和条件边
- Checkpointer：检查点，持久化状态，支持容错和恢复
6.3 完整 LangGraph 示例：带记忆的多轮对话
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import START, MessagesState, StateGraph
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-5")
# 定义状态图
workflow = StateGraph(state_schema=MessagesState)
def call_model(state: MessagesState):
"""Process messages and generate response."""
response = model.invoke(state["messages"])
return {"messages": response}
# 添加节点和边
workflow.add_node("model", call_model)
workflow.add_edge(START, "model")
# 添加记忆检查点
memory = MemorySaver()
app = workflow.compile(checkpointer=memory)
# 使用唯一 thread_id 进行多轮对话
config = {"configurable": {"thread_id": "conversation-1"}}
# 第一轮
response1 = app.invoke(
{"messages": [{"role": "user", "content": "My name is Alice"}]},
config=config
)
# 第二轮 —— Agent 记住上下文
response2 = app.invoke(
{"messages": [{"role": "user", "content": "What's my name?"}]},
config=config
)
# 输出："Your name is Alice"
6.4 生产级持久化：PostgresSaver
from langgraph.checkpoint.postgres import PostgresSaver
from psycopg import Connection
# 连接 PostgreSQL
db_url = os.getenv("DATABASE_URL")
connection = Connection.connect(db_url)
# 初始化检查点
memory = PostgresSaver(connection)
memory.setup() # 创建检查点表
app = workflow.compile(checkpointer=memory)
# 同样的 API，但状态持久化到数据库
config = {"configurable": {"thread_id": "production-thread-1"}}
response = app.invoke(
{"messages": [{"role": "user", "content": "Store this ID: CUS-2025-001"}]},
config=config
)
6.5 人工干预：Human-in-the-Loop
from langgraph.graph import StateGraph, END
from typing import TypedDict
class AgentState(TypedDict):
messages: list
pending_approval: bool
approved_action: str | None
workflow = StateGraph(AgentState)
def process_request(state: AgentState):
last_message = state["messages"][-1]["content"]
requires_approval = any(
keyword in last_message.lower()
for keyword in ["delete", "purchase", "transfer"]
)
return {
"pending_approval": requires_approval,
"approved_action": last_message if requires_approval else None
}
workflow.add_node("process", process_request)
workflow.add_edge("process", "execute")
workflow.set_entry_point("process")
workflow.add_edge("execute", END)
# 在 execute 节点前暂停，等待人工审批
app = workflow.compile(
checkpointer=memory,
interrupt_before=["execute"]
)
七、LangSmith：可观测性平台
LangSmith 是 LangChain 生态的可观测性、调试和评估平台。它捕获每一次 LLM 调用的追踪（trace），让你可以检查输入输出、查看执行路径、评估检索质量。每月近 3 万新用户注册，15.7% 的追踪来自非 LangChain 应用。
7.1 核心功能
- 追踪（Tracing）：自动记录每个 Chain/Agent 的执行步骤、输入输出、耗时
- 调试（Debugging）：可视化执行路径，定位失败节点
- 评估（Evaluation）：内置 RAG 评估指标（faithfulness、relevancy、correctness）
- Prompt 管理：版本控制、A/B 测试不同 Prompt
- 数据集：创建测试数据集，持续回归测试
7.2 快速接入
import os
# 设置环境变量
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-api-key"
os.environ["LANGCHAIN_PROJECT"] = "production-agents"
# 所有 LangChain 调用会自动追踪
response = agent.invoke({"messages": [...]})
# 程序化访问追踪数据
from langsmith import Client
client = Client()
runs = client.list_runs(
project_name="production-agents",
execution_order=1,
error=False,
)
八、LangChain vs 替代方案
8.1 LangChain vs LlamaIndex
混合策略（推荐）：许多生产团队同时使用两者——LlamaIndex 负责数据摄取、索引和检索，LangGraph 负责编排、记忆和多步 Agent 逻辑。将 LlamaIndex Query Engine 包装为 LangChain Tool，是成熟的集成模式。
8.2 其他替代方案
- Haystack（deepset）：德国团队开发，生产级 RAG 和搜索系统，Pipeline 架构，GDPR 友好
- Semantic Kernel（Microsoft）：微软生态集成，适合 Azure -centric 组织
- CrewAI：基于角色的多 Agent 编排，定义 Agent 的角色、目标、背景故事
- DSPy（Stanford）：程序化 Prompt 优化，用编译器思维替代手工 Prompt 工程
- Instructor：轻量级结构化输出库，基于 Pydantic，最小依赖
- Mirascope：极简 Python 包装器，标准装饰器和类型提示，无框架魔法
8.3 何时不用 LangChain
直接调用 SDK 的场景：
- 只需要单轮对话，不需要上下文、工具、检索
- 对延迟极其敏感，不能承受框架开销
- 希望完全控制每一字节的数据流向（安全/合规要求）
替代方案选择：
- 简单结构化输出 → Instructor
- 极简 LLM 调用 → Mirascope 或直接 SDK
- 纯 RAG、文档检索 → LlamaIndex
- 生产级搜索 → Haystack
- Prompt 自动优化 → DSPy
九、批评、局限性与最佳实践
9.1 已知问题
1. 版本频繁破坏性变更
LangChain 0.1 → 0.2 → 0.3 之间多次发生核心 API 变更，团队报告花费在迁移上的时间超过功能开发。建议：锁定版本、阅读 changelog、编写合约测试。
2. 依赖膨胀
400+ 传递依赖，每个都是潜在 CVE。对于处理金融记录、医疗数据、专有 IP 的团队，依赖面是合规风险。
3. 调试不透明
Chain 执行中途失败时，追踪数据流向困难。必须配合 LangSmith 使用，否则 Chain 是"黑盒"。
4. 云优先默认
大多数集成假设数据发往 OpenAI、Pinecone 等 SaaS 端点。私有化部署需要额外工作。
9.2 生产环境最佳实践
开发阶段：
- 从 Day 1 接入 LangSmith，没有可观测性的 Chain 是黑盒
- 使用 PydanticOutputParser 确保结构化输出，而非依赖 LLM "听话"
- Prompt 用模板管理，避免硬编码字符串
- 为工具写详尽的 docstring——这是 Agent 决定何时调用它们的唯一依据
部署阶段：
- 启用流式响应（stream / astream_events）提升用户体验
- 添加指数退避重试（tenacity）
- 实施按用户/租户限流
- 用 PostgresSaver 替代 MemorySaver，确保状态持久化
- 监控 Token 使用量和成本
架构设计：
- 简单线性链用 LCEL，循环/分支/持久化用 LangGraph
- 从原型到生产渐进演进，不要一开始就设计最复杂的架构
- 评估工作流级别的准确性，而非单个 LLM 输出的准确性
十、核心收获与学习路径
10.1 关键认知
- LCEL 是现代 LangChain 的核心：LLMChain、SequentialChain 等旧 API 已被弃用，学习 LCEL 管道语法是首要任务
- Runnable 接口是统一抽象：Chat Model、Retriever、Parser、Agent 都是 Runnable，统一调用方式带来极大便利
- Agent 的本质是"反馈循环"：LLM 决定工具调用 → 执行工具 → 观察结果 → 再次推理，直到给出答案
- RAG 效果取决于检索质量：chunk 策略、嵌入模型、检索器选择比 LLM 生成更重要
- LangChain 是生态，不是单一库：LangGraph（编排）、LangSmith（观测）、LangServe（部署）三位一体
10.2 推荐学习路径
从入门到生产
Level 1：基础（1-2 天）
安装 langchain + langchain-openai，写一个 LCEL Chain（Prompt | LLM | Parser），理解 invoke/stream/batch
Level 2：RAG（2-3 天）
实现完整 RAG Pipeline：加载文档 → 切分 → 嵌入 → Chroma → 检索 → 生成。尝试不同 chunk_size 和检索策略
Level 3：Agent（2-3 天）
创建带工具的 Agent，理解 ReAct 循环。接入 LangSmith 观察执行轨迹
Level 4：LangGraph（3-5 天）
用 StateGraph 构建循环工作流，添加 MemorySaver/SqliteSaver，实现 Human-in-the-Loop
Level 5：生产化（持续）
流式响应、重试机制、限流、多 Agent 协作、评估指标体系
10.3 一句话总结
LangChain 的价值不是让你"更快地调用 LLM"，而是让你"用工程化的方式构建可靠的 LLM 应用"。它把 LLM 从"一个会说话的黑盒"变成了"可编排、可观测、可迭代的基础设施"。