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

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 的关系

简单理解：

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

3.3 LangChain 常见核心组件

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

基础安装可以这样写：

pipinstall-Ulangchain pipinstall-Ulangchain-openai pipinstall-Ulangchain-community

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

pipinstall-Uchromadb

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

pipinstall-Upython-dotenv

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

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

fromlangchain_openaiimportChatOpenAI llm=ChatOpenAI(model="gpt-4o-mini",temperature=0)response=llm.invoke("请用三句话解释 LangChain 是什么")print(response.content)

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

5.3 Prompt Template：让提示词可维护

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

fromlangchain_core.promptsimportChatPromptTemplatefromlangchain_openaiimportChatOpenAI 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、字段、分类标签。

fromlangchain_core.output_parsersimportStrOutputParserfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_openaiimportChatOpenAI prompt=ChatPromptTemplate.from_template("请判断下面的问题属于哪类：技术问题、业务问题、闲聊。只输出类别。\n问题：{question}")llm=ChatOpenAI(model="gpt-4o-mini",temperature=0)parser=StrOutputParser()chain=prompt|llm|parserprint(chain.invoke({"question":"向量数据库召回不准怎么办？"}))

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

5.5 构建一个简化 RAG

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

fromlangchain_openaiimportChatOpenAI,OpenAIEmbeddingsfromlangchain_core.documentsimportDocumentfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_chromaimportChromafromlangchain_core.output_parsersimportStrOutputParser 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})defformat_docs(docs):return"\n\n".join(doc.page_contentfordocindocs)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。下面给一个简化示例：

fromlangchain.agentsimportcreate_agentdefget_order_status(order_id:str)->str:"""查询订单状态。"""fake_db={"A001":"已发货，预计明天送达","A002":"待付款","A003":"已取消"}returnfake_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 系统评估指标

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，但真正能不能落地，取决于你是否理解底层链路、数据质量、检索策略、权限控制和评估体系。