LangChain 是什么从零开始学会 LangChain 的工程实践指南1. 文章背景为什么这个主题重要在大模型应用开发中很多人第一次接触 LangChain是因为想快速做一个“基于大模型的应用”例如知识库问答、RAG 检索增强生成、智能客服、Agent 工具调用、文档总结、SQL 问答、企业内部助手等。如果只调用一次大模型 API代码并不复杂responsellm.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]{index0}但需要注意LangChain 不是“万能框架”。它适合快速搭建和组织大模型应用链路但如果不了解底层流程盲目套组件很容易出现代码复杂、调试困难、性能差、版本变动带来的兼容问题。本文从工程实践角度围绕“LangChain 是什么、怎么学、怎么用、怎么落地”展开适合作为入门到项目实践的路线指南。2. 核心问题实际开发中会遇到什么问题2.1 单次 API 调用无法支撑复杂应用单纯调用大模型 API 只能解决简单问答。实际业务中常见需求是用户问题 ↓ 意图识别 ↓ 查询知识库 ↓ 拼接 Prompt ↓ 调用大模型 ↓ 解析结构化输出 ↓ 调用工具或数据库 ↓ 返回结果 ↓ 记录日志和评估如果全部手写早期可以跑通但后期很难维护。2.2 RAG 链路涉及多个模块一个完整 RAG 系统至少包含文档加载文档清洗文本切分Embedding向量数据库RetrieverQuery 改写rerankPrompt 构造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 应用和 AgentRAG、工具调用、简单 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文本切分器将长文档拆成 chunkEmbedding将文本转成向量Vector Store向量数据库或向量索引Retriever检索器输入 query返回相关文档Tool工具函数供 Agent 调用Agent能根据任务选择工具和行动的大模型应用Callback / Tracing记录链路执行过程便于调试和评估3.4 Chain 和 RunnableLangChain 早期大量使用 Chain 概念现在更推荐使用 Runnable 风格组合组件。Runnable 可以理解为一个“可调用模块”支持invoke单次调用batch批量调用stream流式输出pipe管道式组合parallel并行执行。一个典型链路可以理解为Prompt → Model → OutputParser或者Retriever → Prompt → Model → Parser4. 系统设计如何搭建完整流程或架构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 Keypipinstall-Upython-dotenv5.2 第一个最小示例调用模型下面是一个简化示例实际模型名称和 provider 需要根据你的账号和模型服务调整。fromlangchain_openaiimportChatOpenAI llmChatOpenAI(modelgpt-4o-mini,temperature0)responsellm.invoke(请用三句话解释 LangChain 是什么)print(response.content)这个示例只完成了最基本的模型调用还没有体现 LangChain 的编排价值。5.3 Prompt Template让提示词可维护不要在代码里到处拼字符串。Prompt 应该模板化。fromlangchain_core.promptsimportChatPromptTemplatefromlangchain_openaiimportChatOpenAI promptChatPromptTemplate.from_messages([(system,你是一名企业级 AI 应用架构师回答要简洁、准确、可落地。),(user,请解释这个概念{topic})])llmChatOpenAI(modelgpt-4o-mini,temperature0)chainprompt|llm resultchain.invoke({topic:RAG 检索增强生成})print(result.content)这里的|可以理解为管道Prompt 输入变量 → 生成模型输入 → 调用 LLM → 返回结果5.4 Output Parser让输出结构化企业应用不能只依赖自然语言结果。很多时候需要 JSON、字段、分类标签。fromlangchain_core.output_parsersimportStrOutputParserfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_openaiimportChatOpenAI promptChatPromptTemplate.from_template(请判断下面的问题属于哪类技术问题、业务问题、闲聊。只输出类别。\n问题{question})llmChatOpenAI(modelgpt-4o-mini,temperature0)parserStrOutputParser()chainprompt|llm|parserprint(chain.invoke({question:向量数据库召回不准怎么办}))工程建议只要结果要进入后续程序逻辑就尽量使用结构化输出而不是让后端去猜模型文本。5.5 构建一个简化 RAG下面是一个简化版 RAG 示例用少量文本模拟知识库。fromlangchain_openaiimportChatOpenAI,OpenAIEmbeddingsfromlangchain_core.documentsimportDocumentfromlangchain_core.promptsimportChatPromptTemplatefromlangchain_chromaimportChromafromlangchain_core.output_parsersimportStrOutputParser docs[Document(page_contentLangChain 是用于构建大模型应用的开源框架支持模型、Prompt、检索器和工具集成。),Document(page_contentRAG 的核心流程是先检索相关知识再将知识作为上下文交给大模型生成答案。),Document(page_contentAgent 可以根据用户任务选择工具并根据工具执行结果继续推理。)]embeddingOpenAIEmbeddings()vectorstoreChroma.from_documents(docs,embedding)retrievervectorstore.as_retriever(search_kwargs{k:2})defformat_docs(docs):return\n\n.join(doc.page_contentfordocindocs)promptChatPromptTemplate.from_template( 请基于下面的上下文回答问题。 如果上下文中没有答案请说明不知道不要编造。 上下文 {context} 问题 {question} )llmChatOpenAI(modelgpt-4o-mini,temperature0)parserStrOutputParser()questionLangChain 和 RAG 有什么关系retrieved_docsretriever.invoke(question)chainprompt|llm|parser answerchain.invoke({context:format_docs(retrieved_docs),question:question})print(answer)这个例子展示的是 RAG 的主干流程文档 → Embedding → 向量库 → 检索 → Prompt → LLM → 答案真实项目还需要加上文档清洗chunk 策略metadata权限过滤rerank引用来源日志追踪效果评估。5.6 创建一个简单 AgentLangChain 当前官方文档中提供了create_agent的方式可以用少量代码创建带工具的 Agent。下面给一个简化示例fromlangchain.agentsimportcreate_agentdefget_order_status(order_id:str)-str:查询订单状态。fake_db{A001:已发货预计明天送达,A002:待付款,A003:已取消}returnfake_db.get(order_id,未找到该订单)agentcreate_agent(modelopenai:gpt-4o-mini,tools[get_order_status],system_prompt你是一个客服助手只能基于工具返回的信息回答订单问题。)resultagent.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 不合理没有 rerankPrompt 没有约束模型基于上下文回答原始文档质量差用户问题没有做 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 系统评估指标维度指标说明检索效果RecallK正确文档是否被召回检索排序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输出 tokenEmbedding 调用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 → OutputRAG 只是中间多了 RetrieverAgent 只是中间多了 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但真正能不能落地取决于你是否理解底层链路、数据质量、检索策略、权限控制和评估体系。