LangChain 是什么？从零开始学会 LangChain 的工程实践指南

1. 文章背景：为什么这个主题重要

在大模型应用开发中，很多人第一次接触 LangChain，是因为想快速做一个“基于大模型的应用”：例如知识库问答、RAG 检索增强生成、智能客服、Agent 工具调用、文档总结、SQL 问答、企业内部助手等。

如果只调用一次大模型 API，代码并不复杂：

response = llm.invoke("请解释一下 RAG 是什么")

但真实项目很快会变复杂：

• Prompt 需要动态拼接；
• 用户问题需要改写；
• 需要接入向量数据库；
• 需要加载 PDF、Word、网页、数据库内容；
• 需要做 Embedding、切分、检索、rerank；
• 需要支持多轮对话记忆；
• 需要让模型调用工具；
• 需要记录链路日志、评估效果、排查问题；
• 需要把应用部署成稳定服务。

这时就会发现，大模型应用不是“调一个接口”这么简单，而是一套完整的工程链路。LangChain 的价值就在这里：它把模型、Prompt、工具、检索器、链式调用、Agent、记忆、回调、观测等模块抽象出来，让开发者可以更快搭建大模型应用。

根据 LangChain 官方文档，LangChain 是一个开源框架，提供预构建的 Agent 架构以及模型、工具集成能力，用于构建基于大模型的 Agent 和应用。官方文档也说明，LangChain agents 构建在 LangGraph 之上，因此可以利用 LangGraph 的持久执行、流式输出、human-in-the-loop 和持久化等能力。:contentReference[oaicite:0]{index=0}

但需要注意，LangChain 不是“万能框架”。它适合快速搭建和组织大模型应用链路，但如果不了解底层流程，盲目套组件，很容易出现代码复杂、调试困难、性能差、版本变动带来的兼容问题。

本文从工程实践角度，围绕“LangChain 是什么、怎么学、怎么用、怎么落地”展开，适合作为入门到项目实践的路线指南。

2. 核心问题：实际开发中会遇到什么问题

2.1 单次 API 调用无法支撑复杂应用

单纯调用大模型 API 只能解决简单问答。实际业务中常见需求是：

用户问题
  ↓
意图识别
  ↓
查询知识库
  ↓
拼接 Prompt
  ↓
调用大模型
  ↓
解析结构化输出
  ↓
调用工具或数据库
  ↓
返回结果
  ↓
记录日志和评估

如果全部手写，早期可以跑通，但后期很难维护。

2.2 RAG 链路涉及多个模块

一个完整 RAG 系统至少包含：

• 文档加载；
• 文档清洗；
• 文本切分；
• Embedding；
• 向量数据库；
• Retriever；
• Query 改写；
• rerank；
• Prompt 构造；
• LLM 生成；
• 引用溯源；
• 效果评估。

LangChain 提供了这些模块的抽象接口，方便开发者组合。

2.3 Agent 工具调用需要流程控制

Agent 不是简单让模型“自己想”。真正的 Agent 需要：

• 工具定义；
• 工具参数 schema；
• 工具调用权限；
• 工具执行结果回传；
• 多轮推理状态管理；
• 失败重试；
• 人工确认；
• 执行轨迹记录。

LangChain 可以快速做基础 Agent，但复杂 Agent 更适合结合 LangGraph 做流程编排。

2.4 框架版本变化带来学习成本

LangChain 发展很快，过去很多教程使用旧版 Chain、AgentExecutor、Memory 写法，现在官方更强调 Agent、Runnable、LangGraph、LangSmith 等体系。学习时不能只复制旧教程代码，要理解组件背后的设计思想。

工程上建议：先学核心抽象和链路，再看当前版本 API，而不是死记某个旧写法。

3. 基础概念：用工程视角解释关键概念

3.1 LangChain 到底是什么

从工程角度看，LangChain 不是一个大模型，也不是一个向量数据库，而是一个大模型应用开发框架。

它主要解决三个问题：

• 统一不同模型和工具的调用方式；
• 将 Prompt、模型、检索、工具、输出解析等模块串起来；
• 支持 Agent、RAG、多轮对话、观测和评估等应用形态。

可以把 LangChain 理解为：

LangChain = 大模型应用的组件库 + 编排框架 + 集成生态

3.2 LangChain、LangGraph、LangSmith 的关系

名称	作用	适合场景
LangChain	快速构建 LLM 应用和 Agent	RAG、工具调用、简单 Agent、模型集成
LangGraph	更底层的 Agent 和工作流编排框架	多步骤 Agent、状态机、持久执行、人工审批
LangSmith	调试、追踪、评估和观测平台	线上排查、效果评估、链路分析

简单理解：

• 做普通 RAG 或简单工具调用：先用 LangChain；
• 做复杂多步骤 Agent：考虑 LangGraph；
• 做生产环境调试和评估：接入 LangSmith。

3.3 LangChain 常见核心组件

组件	工程含义
Model	大模型接口，例如 OpenAI、Anthropic、本地模型
Prompt	提示词模板，负责将变量转换成模型输入
Output Parser	输出解析器，将模型文本转为 JSON、对象或结构化结果
Document Loader	文档加载器，用于读取 PDF、网页、数据库等
Text Splitter	文本切分器，将长文档拆成 chunk
Embedding	将文本转成向量
Vector Store	向量数据库或向量索引
Retriever	检索器，输入 query，返回相关文档
Tool	工具函数，供 Agent 调用
Agent	能根据任务选择工具和行动的大模型应用
Callback / Tracing	记录链路执行过程，便于调试和评估

3.4 Chain 和 Runnable

LangChain 早期大量使用 Chain 概念，现在更推荐使用 Runnable 风格组合组件。Runnable 可以理解为一个“可调用模块”，支持：

• invoke：单次调用；
• batch：批量调用；
• stream：流式输出；
• pipe：管道式组合；
• parallel：并行执行。

一个典型链路可以理解为：

Prompt → Model → OutputParser

或者：

Retriever → Prompt → Model → Parser

4. 系统设计：如何搭建完整流程或架构

4.1 一个最小 LangChain 应用架构

最小应用可以这样设计：

用户输入
  ↓
Prompt Template
  ↓
LLM / ChatModel
  ↓
Output Parser
  ↓
返回答案

适合：

• 简单问答；
• 文本改写；
• 标题生成；
• 分类判断；
• 信息抽取。

4.2 一个 RAG 应用架构

RAG 系统通常包含离线索引和在线问答两条链路。

离线索引链路：

原始文档
  ↓
Document Loader
  ↓
文本清洗
  ↓
Text Splitter
  ↓
Embedding
  ↓
Vector Store

在线问答链路：

用户问题
  ↓
Query Rewrite
  ↓
Retriever
  ↓
Rerank / Filter
  ↓
Prompt 构造
  ↓
LLM 生成
  ↓
答案 + 引用来源

LangChain 可以负责其中的 loader、splitter、embedding、retriever、prompt、model、parser 等模块。

4.3 一个 Agent 应用架构

Agent 应用通常是：

用户任务
  ↓
LLM 判断下一步
  ↓
选择工具
  ↓
执行工具
  ↓
观察工具结果
  ↓
继续推理或返回最终答案

适合：

• 查询数据库；
• 调用业务 API；
• 发送邮件；
• 查询天气；
• 生成报表；
• 多步骤任务自动化。

但在企业落地中，不建议一开始就做完全开放 Agent。更稳妥的是：

固定流程 + 少量可控工具 + 明确权限 + 可观测日志

5. 关键实现：核心模块、技术选型和实现细节

5.1 安装 LangChain

基础安装可以这样写：

pip install -U langchain
pip install -U langchain-openai
pip install -U langchain-community

如果要做本地向量库，可以再安装：

pip install -U chromadb

如果使用环境变量管理 API Key：

pip install -U python-dotenv

5.2 第一个最小示例：调用模型

下面是一个简化示例，实际模型名称和 provider 需要根据你的账号和模型服务调整。

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0
)

response = llm.invoke("请用三句话解释 LangChain 是什么")
print(response.content)

这个示例只完成了最基本的模型调用，还没有体现 LangChain 的编排价值。

5.3 Prompt Template：让提示词可维护

不要在代码里到处拼字符串。Prompt 应该模板化。

from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一名企业级 AI 应用架构师，回答要简洁、准确、可落地。"),
    ("user", "请解释这个概念：{topic}")
])

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

chain = prompt | llm

result = chain.invoke({"topic": "RAG 检索增强生成"})
print(result.content)

这里的 | 可以理解为管道：

Prompt 输入变量 → 生成模型输入 → 调用 LLM → 返回结果

5.4 Output Parser：让输出结构化

企业应用不能只依赖自然语言结果。很多时候需要 JSON、字段、分类标签。

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

prompt = ChatPromptTemplate.from_template(
    "请判断下面的问题属于哪类：技术问题、业务问题、闲聊。只输出类别。\n问题：{question}"
)

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
parser = StrOutputParser()

chain = prompt | llm | parser

print(chain.invoke({"question": "向量数据库召回不准怎么办？"}))

工程建议：只要结果要进入后续程序逻辑，就尽量使用结构化输出，而不是让后端去猜模型文本。

5.5 构建一个简化 RAG

下面是一个简化版 RAG 示例，用少量文本模拟知识库。

from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_core.documents import Document
from langchain_core.prompts import ChatPromptTemplate
from langchain_chroma import Chroma
from langchain_core.output_parsers import StrOutputParser

docs = [
    Document(page_content="LangChain 是用于构建大模型应用的开源框架，支持模型、Prompt、检索器和工具集成。"),
    Document(page_content="RAG 的核心流程是先检索相关知识，再将知识作为上下文交给大模型生成答案。"),
    Document(page_content="Agent 可以根据用户任务选择工具，并根据工具执行结果继续推理。")
]

embedding = OpenAIEmbeddings()
vectorstore = Chroma.from_documents(docs, embedding)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)

prompt = ChatPromptTemplate.from_template("""
请基于下面的上下文回答问题。
如果上下文中没有答案，请说明不知道，不要编造。

上下文：
{context}

问题：
{question}
""")

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
parser = StrOutputParser()

question = "LangChain 和 RAG 有什么关系？"
retrieved_docs = retriever.invoke(question)

chain = prompt | llm | parser

answer = chain.invoke({
    "context": format_docs(retrieved_docs),
    "question": question
})

print(answer)

这个例子展示的是 RAG 的主干流程：

文档 → Embedding → 向量库 → 检索 → Prompt → LLM → 答案

真实项目还需要加上：

• 文档清洗；
• chunk 策略；
• metadata；
• 权限过滤；
• rerank；
• 引用来源；
• 日志追踪；
• 效果评估。

5.6 创建一个简单 Agent

LangChain 当前官方文档中提供了 create_agent 的方式，可以用少量代码创建带工具的 Agent。下面给一个简化示例：

from langchain.agents import create_agent

def get_order_status(order_id: str) -> str:
    """查询订单状态。"""
    fake_db = {
        "A001": "已发货，预计明天送达",
        "A002": "待付款",
        "A003": "已取消"
    }
    return fake_db.get(order_id, "未找到该订单")

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[get_order_status],
    system_prompt="你是一个客服助手，只能基于工具返回的信息回答订单问题。"
)

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "帮我查一下订单 A001 的状态"}
    ]
})

print(result["messages"][-1].content)

企业落地中要注意，工具不能随便开放。每个工具都要定义：

• 参数 schema；
• 权限校验；
• 超时控制；
• 错误处理；
• 审计日志；
• 是否需要人工确认。

6. 常见问题：实际落地中的坑和解决方案

6.1 旧教程代码跑不起来

LangChain 版本变化较快，很多旧教程中的 import 路径、Chain 写法、Agent 写法已经变化。

解决方案：

• 优先查看官方文档；
• 固定项目依赖版本；
• 不要在生产环境随意升级大版本；
• 用 requirements.txt 或 uv/poetry 锁定依赖；
• 学习 Runnable、Prompt、Retriever、Tool 等稳定抽象。

6.2 RAG 效果差，不是 LangChain 的问题

很多人搭完 LangChain RAG 后发现回答不准，就认为框架不好。实际上问题通常出在数据和检索链路：

• 文档切分太粗或太碎；
• Embedding 模型不适合中文或业务领域；
• 检索 top_k 不合理；
• 没有 rerank；
• Prompt 没有约束模型基于上下文回答；
• 原始文档质量差；
• 用户问题没有做 query rewrite；
• 没有权限过滤和 metadata 过滤。

LangChain 只是帮你搭链路，不会自动保证 RAG 效果。

6.3 Agent 容易乱调用工具

Agent 常见问题：

• 调错工具；
• 参数填错；
• 工具结果理解错；
• 循环调用；
• 编造工具返回；
• 执行高风险操作没有确认。

解决方案：

• 工具描述写清楚；
• 参数 schema 严格定义；
• 工具返回结构化结果；
• 高风险工具增加 human-in-the-loop；
• 设置最大调用次数；
• 对工具调用做日志审计；
• 复杂流程用 LangGraph 显式编排，而不是完全交给模型自由规划。

6.4 链路不可观测，出错难排查

大模型应用的问题经常不是“代码报错”，而是“回答质量差”。这类问题必须看完整链路：

• 用户原始问题；
• 改写后的 query；
• 检索到的文档；
• rerank 分数；
• 最终 Prompt；
• 模型输出；
• 工具调用参数；
• 工具返回结果；
• token 成本和延迟。

建议开发阶段就接入 tracing，而不是上线后再补。

6.5 过度封装导致失控

LangChain 提供很多高级组件，但过度封装会让开发者不知道实际发生了什么。企业项目建议保留关键链路的可控性：

• RAG 检索逻辑自己显式写；
• Prompt 模板自己维护；
• 工具调用权限自己控制；
• 输出解析失败要有兜底；
• 不要把所有东西塞进一个黑盒 Agent。

7. 效果评估：如何判断系统是否有效

7.1 RAG 系统评估指标

维度	指标	说明
检索效果	Recall@K	正确文档是否被召回
检索排序	MRR / NDCG	正确文档是否排在前面
生成质量	答案准确率	是否回答正确
忠实性	Faithfulness	是否基于上下文回答
引用质量	Citation Accuracy	引用是否对应答案内容
稳定性	多次回答一致性	同样问题是否稳定
性能	TTFT / 总延迟	首 token 和完整响应时间
成本	token 消耗	每次请求花费

7.2 Agent 系统评估指标

维度	指标
任务完成率	用户任务是否成功完成
工具调用准确率	是否选择正确工具
参数正确率	工具参数是否正确
平均调用步数	是否存在无效推理
失败恢复能力	工具失败后能否兜底
人工介入率	需要人工确认或修复的比例
安全性	是否出现越权或危险操作

7.3 LangChain 项目如何做评估集

建议维护一份测试集：

[
  {
    "question": "LangChain 如何接入向量数据库？",
    "expected_keywords": ["Embedding", "Vector Store", "Retriever"],
    "gold_docs": ["doc_001", "doc_003"]
  },
  {
    "question": "Agent 调用工具失败怎么办？",
    "expected_keywords": ["重试", "超时", "错误处理", "人工确认"],
    "gold_docs": ["doc_010"]
  }
]

每次改 Prompt、换 Embedding、改 chunk、升级模型，都跑一遍评估，避免“感觉变好了”。

8. 工程优化：性能、成本、稳定性和可维护性

8.1 性能优化

LangChain 应用的性能瓶颈通常在：

• LLM 调用；
• Embedding；
• 向量检索；
• rerank；
• 工具 API；
• 长 Prompt；
• 多轮 Agent 循环。

优化建议：

• 能并行的检索和工具调用尽量并行；
• 控制 Prompt 长度；
• 对固定内容做缓存；
• 对高频问题做结果缓存；
• 使用流式输出降低感知延迟；
• 对 Agent 设置最大迭代次数；
• 对外部工具设置超时。

8.2 成本优化

大模型应用成本主要来自：

• 输入 token；
• 输出 token；
• Embedding 调用；
• rerank 模型；
• 向量数据库；
• Agent 多轮调用。

建议：

• 文档入库时离线计算 Embedding；
• 不要每次请求重复 embedding 大段文本；
• 控制 RAG top_k；
• 使用 query rewrite 但不要滥用；
• 高频固定 Prompt 做缓存；
• 简单任务使用小模型；
• 复杂任务再路由到大模型。

8.3 稳定性设计

生产环境必须有兜底：

LLM 调用失败 → 重试或返回降级回答
Retriever 失败 → 返回无检索回答或提示稍后再试
Parser 失败 → 重新格式化或走兜底解析
工具超时 → 终止工具调用并提示用户
Agent 循环 → 达到最大步数后停止

不要让 LangChain 链路中的任意一个组件失败导致整个服务不可用。

8.4 数据安全和权限控制

企业 RAG 特别要关注权限：

• 检索前根据用户身份过滤文档；
• 文档 metadata 中存储部门、角色、密级；
• 不同租户向量库隔离；
• Prompt 中不要拼接用户无权限内容；
• 工具调用前做权限校验；
• 日志中脱敏敏感信息；
• 高风险操作必须人工确认。

权限控制不能只靠 Prompt 约束，必须在检索层、工具层和数据层做硬控制。

8.5 可维护性

建议项目结构清晰拆分：

app/
  chains/
    rag_chain.py
    classify_chain.py
  prompts/
    rag_prompt.py
    agent_prompt.py
  retrievers/
    vector_retriever.py
  tools/
    order_tool.py
    database_tool.py
  loaders/
    pdf_loader.py
  configs/
    model_config.yaml
  eval/
    rag_eval.py

不要把所有 LangChain 代码写在一个 notebook 或一个 Python 文件里。早期 Demo 可以这样做，生产项目不建议。

9. 实践建议：给开发者的落地建议

9.1 学 LangChain 的正确路线

建议按这个顺序学习：

模型调用
  ↓
Prompt Template
  ↓
Output Parser
  ↓
Runnable / LCEL
  ↓
Document Loader
  ↓
Text Splitter
  ↓
Embedding / Vector Store
  ↓
Retriever
  ↓
RAG
  ↓
Tool
  ↓
Agent
  ↓
Tracing / Evaluation
  ↓
LangGraph

不要一开始就学复杂 Agent。先把 RAG 和基础链路跑通，再进入 Agent 编排。

9.2 初学者不要被概念吓到

LangChain 名词很多，但本质就三件事：

• 输入怎么组织；
• 中间怎么调用；
• 输出怎么解析。

任何 LangChain 应用都可以拆成：

Input → Prompt → Model → Parser → Output

RAG 只是中间多了 Retriever，Agent 只是中间多了 Tool 和循环决策。

9.3 Demo 和生产要分开看

Demo 目标是跑通，生产目标是稳定。

Demo 可以：

• 用内存向量库；
• 用简单 Prompt；
• 不做权限；
• 不做评估；
• 不做日志。

生产必须考虑：

• 数据清洗；
• 权限控制；
• 模型成本；
• 延迟；
• 失败兜底；
• 日志追踪；
• 自动评估；
• 版本管理；
• 安全审计。

9.4 不要迷信框架

LangChain 可以提高开发效率，但不能代替系统设计。真正决定效果的是：

• 文档质量；
• Prompt 设计；
• 检索策略；
• 模型选择；
• 工具设计；
• 评估体系；
• 工程稳定性。

框架只是工具，不是答案。

9.5 企业项目建议先做可控 RAG，再做 Agent

很多团队一上来就想做 Agent，但 Agent 的不确定性更强。更稳的路线是：

第一阶段：单轮 RAG 问答
第二阶段：多轮 RAG 问答
第三阶段：结构化输出和业务 API 查询
第四阶段：受控工具调用
第五阶段：复杂 Agent 工作流

这样更容易交付，也更容易排查问题。

10. 总结：提炼核心观点

LangChain 是一个用于构建大模型应用的开源框架，它提供了模型、Prompt、检索器、工具、Agent、输出解析、链路追踪等组件，让开发者可以更快搭建 RAG、Agent、知识库问答和自动化应用。

从工程角度看，LangChain 的核心价值不是“帮你调用大模型”，而是帮助你组织复杂的大模型应用链路：

Prompt 编排
模型调用
文档检索
工具调用
结构化输出
链路追踪
效果评估

学习 LangChain 时，要抓住几个核心概念：

• Model：模型接口；
• Prompt：输入模板；
• Parser：输出解析；
• Retriever：检索器；
• Tool：工具；
• Agent：带工具调用能力的应用；
• Runnable：可组合的执行单元；
• LangGraph：复杂 Agent 编排；
• LangSmith：调试和评估。

实际落地时，不要只关注代码能否跑通，更要关注：

• RAG 效果是否可评估；
• Agent 行为是否可控；
• 工具调用是否安全；
• Prompt 是否可维护；
• 成本和延迟是否可接受；
• 数据权限是否严格隔离；
• 日志和链路是否可观测。

一句话总结：

LangChain 是大模型应用开发的工程脚手架，适合快速搭建 RAG 和 Agent，但真正能不能落地，取决于你是否理解底层链路、数据质量、检索策略、权限控制和评估体系。