基于LangChain的Agentic RAG智能体实战：从零构建能思考会检索的AI助手

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度如果你在2024年还在用“调用API、拼接Prompt”的老方法构建AI应用那么你很可能已经落后了。LangChain、Agent、RAG这些概念早已不是新鲜词汇但为什么很多开发者学完教程后依然无法落地一个真正“智能”的项目问题往往不在于概念本身而在于缺乏一个贯穿始终的、能体现其核心价值的实战案例。本文不是一篇简单的概念罗列。我们将直接切入一个基于Agent智能体的RAG项目实战目标是构建一个能理解复杂问题、自主调用工具、并从私有知识库中精准检索答案的智能助手。你将清晰地看到从零到一LangChain如何将大语言模型LLM、工具Tools、记忆Memory和检索Retrieval编织成一个协同工作的智能体。更重要的是我们会揭示那些官方文档里很少提及的工程化细节和常见陷阱比如Agent的思维链ReAct如何实际运作、RAG中“检索精度”的真正瓶颈在哪里、以及如何让整个系统稳定运行。无论你是想快速入门LangChain还是希望将Agentic RAG应用到实际业务中这篇文章都将提供一条清晰的路径。我们不仅会“跑通”一个Demo更会深入探讨其背后的“为什么”让你知其然更知其所以然。1. 为什么你需要关注Agent与RAG的结合在AI应用开发中我们常面临两个核心痛点LLM的“幻觉”问题和其知识的静态性与局限性。RAG通过引入外部知识源部分解决了幻觉和知识更新问题。但传统的RAG流程检索-拼接-生成是线性的、被动的它只能回答“知识库里有什么”。而Agent的引入带来了主动性和决策能力。一个Agent智能体可以理解用户意图判断问题是否需要检索、计算、或调用其他API。规划与执行将复杂问题拆解为多个步骤例如先检索背景信息再进行计算推理。使用工具超越单纯的文本生成可以执行代码、查询数据库、调用外部服务。当Agent与RAG结合时我们得到的是一个能思考、会查资料、可执行动作的智能助手。例如面对问题“我们公司Q3的销售额增长率是多少如果保持这个增速预测Q4的销售额”一个传统的RAG系统可能只能返回Q3的销售数据。而一个Agentic RAG系统则会理解这是一个需要计算和预测的问题。首先调用RAG工具从知识库中检索出Q2、Q3的销售额。然后调用计算工具或利用LLM的推理能力计算出增长率。最后再次推理基于增长率预测Q4的销售额并生成最终答案。这个“思考-行动-观察”的循环正是Agent的核心范式。学习LangChain如果只学RAG或只学Agent就像只学了汽车的发动机或方向盘而本文将教你如何组装一台能上路的车。2. 核心概念精讲LangChain、Agent与RAG在开始实战前我们需要统一语言。这些概念经常被混淆理解它们的区别和联系是成功的第一步。2.1 LangChainAI应用的“框架”与“粘合剂”LangChain不是一个具体的AI模型而是一个用于开发由语言模型驱动的应用程序的框架。你可以把它想象成Spring之于Java应用。它提供了以下核心价值模块化将LLM调用、提示模板、记忆、检索链、代理等抽象成可复用的组件。编排提供Chain和Agent两种主要模式将这些组件连接起来定义执行流程。集成预集成了大量第三方工具如搜索引擎、数据库、API和向量数据库如Chroma, Pinecone大幅降低集成复杂度。简单说LangChain让你不用从零开始造轮子能更专注于构建应用逻辑。2.2 Agent具有决策能力的“智能体”Agent是LangChain中更高级的抽象。一个Agent的核心包括LLM作为其“大脑”负责理解和规划。Tools作为其“手脚”是它可以调用的具体功能如搜索、计算、查数据库。Agent Executor作为其“运行引擎”负责驱动“大脑”根据当前状态选择工具执行工具并将结果返回给“大脑”进行下一轮决策直到任务完成。关键范式是ReAct (Reason Act)ThoughtLLM分析当前情况和目标思考下一步该做什么。ActionLLM决定调用哪个工具并生成调用参数。Observation工具执行的结果返回给LLM。重复1-3步直到LLM认为可以给出最终Answer。2.3 RAG为LLM注入“外部知识”RAG解决了LLM的两个关键问题知识过时LLM的训练数据有截止日期。幻觉与缺乏依据LLM可能编造信息。RAG的工作流程如下用户问题 - 文本嵌入Embedding- 向量检索 - 获取相关文档片段 - 与问题一起组合成增强的Prompt - 提交给LLM生成答案核心在于LLM生成的答案是基于你提供的“上下文”的这大大提高了答案的准确性和可追溯性。2.4 三者关系图用户 | v [Agent (大脑)] | (决策) v [Tools (工具集)] |--- [RAG Tool] --- [向量知识库] |--- [Calculator] |--- [Search API] | v (Agent Executor 协调循环) | v 最终答案结论在本项目中我们将使用LangChain框架构建一个以Agent为核心其关键工具之一是RAG检索工具的智能应用。3. 环境准备与项目初始化我们使用Python作为开发语言。请确保你的环境满足以下要求。3.1 基础环境Python版本3.8 或更高版本推荐3.9。包管理工具pip。代码编辑器VS Code, PyCharm等均可。3.2 创建虚拟环境强烈推荐隔离项目依赖避免版本冲突。# 在项目目录下 python -m venv venv # 激活虚拟环境 # Windows (cmd或PowerShell) venv\Scripts\activate # macOS/Linux source venv/bin/activate激活后命令行提示符前会出现(venv)标识。3.3 安装核心依赖我们将安装LangChain及其相关组件。注意LangChain社区活跃库拆分为多个包我们安装最常用的。pip install langchain langchain-community langchain-core # 安装OpenAI官方SDK我们将使用GPT模型作为LLM大脑 pip install openai # 安装用于文本嵌入和向量数据库的库 pip install chromadb sentence-transformers # 安装用于Agent工具调用的可选工具库 pip install wikipedia版本说明为避免依赖冲突建议先安装上述基础包。具体版本号可能会随时间变化如果遇到问题可以尝试固定版本如pip install langchain0.1.0请查阅官方文档获取最新稳定版。3.4 获取并设置API密钥本项目需要OpenAI的API密钥。如果你没有需要前往 OpenAI平台 注册并获取。# 在Linux/macOS上 export OPENAI_API_KEY你的-sk-...密钥 # 在Windows (PowerShell)上 $env:OPENAI_API_KEY你的-sk-...密钥 # 或者在Python代码中设置不推荐将密钥硬编码在代码中 import os os.environ[OPENAI_API_KEY] 你的-sk-...密钥安全提醒永远不要将API密钥提交到Git等版本控制系统。推荐使用环境变量或.env文件管理。4. 项目实战一构建基础RAG系统在让Agent使用RAG之前我们先建立一个独立可用的RAG系统。这是整个项目的知识基础。4.1 准备知识库文档我们在项目根目录创建一个data文件夹并放入一些文本文件作为知识库。例如创建company_faq.txt公司产品“智能助手Pro”最新版本是v2.1.0发布于2024年5月。 该版本主要特性包括多轮对话记忆、支持文件上传分析、集成第三方日历API。 我们的技术服务热线是400-123-4567工作时间是工作日9:00-18:00。 公司2023年销售额为1200万元主要客户来自科技和金融行业。 公司地址上海市浦东新区张江高科技园区。4.2 实现RAG核心流程创建一个Python脚本basic_rag.py。# basic_rag.py import os from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma from langchain_openai import ChatOpenAI from langchain.chains import RetrievalQA # 1. 加载文档 loader TextLoader(./data/company_faq.txt, encodingutf-8) documents loader.load() print(f加载了 {len(documents)} 个文档) # 2. 分割文本 # 大文档需要分割成小块以适应LLM的上下文窗口和提升检索精度 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块的最大字符数 chunk_overlap50 # 块之间的重叠字符保持上下文连贯 ) texts text_splitter.split_documents(documents) print(f将文档分割成 {len(texts)} 个文本块) # 3. 嵌入并存储到向量数据库 # 使用OpenAI的嵌入模型将文本转换为向量 embeddings OpenAIEmbeddings() # 持久化存储到本地./chroma_db目录 vectorstore Chroma.from_documents( documentstexts, embeddingembeddings, persist_directory./chroma_db ) print(向量知识库已创建并持久化。) # 4. 构建检索链 # 创建一个检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3个块 # 创建LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 最简单的方式将所有检索到的文档“塞”进prompt retrieverretriever, return_source_documentsTrue # 返回源文档便于追溯 ) # 5. 进行问答测试 query 智能助手Pro的最新版本是什么有什么新功能 result qa_chain.invoke({query: query}) print(\n 问题 ) print(query) print(\n 答案 ) print(result[result]) print(\n 参考来源 ) for doc in result[source_documents]: print(f- {doc.page_content[:200]}...) # 打印前200个字符关键点解析文本分割这是RAG的第一个关键步骤。分割的大小和重叠度需要根据文档内容调整。太小会丢失上下文太大会引入噪声。向量化OpenAIEmbeddings将文本转换为数学向量相似的文本在向量空间中也相近。向量数据库Chroma是一个轻量级、可持久化的向量数据库负责存储向量并执行相似性搜索。检索器retriever是执行搜索的组件。k3表示返回最相似的3个片段。检索问答链RetrievalQA是LangChain提供的一个高级链它封装了“检索-组合Prompt-调用LLM”的完整流程。运行脚本python basic_rag.py你应该能看到控制台输出答案以及答案所依据的文档片段。至此一个基础的RAG系统就搭建完成了。它已经可以回答关于你知识库的问题。5. 项目实战二创建具有工具调用能力的Agent现在我们赋予LLM使用工具的能力。我们将创建一个简单的Agent它可以使用计算器和搜索维基百科。5.1 定义工具创建agent_with_tools.py。# agent_with_tools.py import os from langchain_openai import ChatOpenAI from langchain.agents import Tool, AgentExecutor, create_react_agent from langchain import hub # 用于拉取预定义的Prompt # 1. 首先定义几个工具函数 from langchain_community.utilities import WikipediaAPIWrapper from langchain_community.tools import WikipediaQueryRun from langchain_community.tools import DuckDuckGoSearchRun from langchain.tools import tool import math # 自定义一个计算器工具 tool def calculator(expression: str) - str: 用于计算数学表达式。输入应该是一个有效的数学表达式字符串例如 3 5 * 2 或 sqrt(16)。 try: # 警告使用eval有安全风险仅用于演示。生产环境应使用安全库如ast.literal_eval或专用数学库。 # 这里进行了简单限制但绝非安全做法。 if any(keyword in expression.lower() for keyword in [import, os, sys, exec, eval, __]): return 错误表达式包含不安全字符。 result eval(expression, {__builtins__: None}, {sqrt: math.sqrt, sin: math.sin, cos: math.cos, pi: math.pi}) return str(result) except Exception as e: return f计算错误{e} # 2. 实例化工具 # 维基百科工具 api_wrapper WikipediaAPIWrapper(top_k_results2, doc_content_chars_max200) wiki_tool WikipediaQueryRun(api_wrapperapi_wrapper) # 网络搜索工具需要网络连接 search_tool DuckDuckGoSearchRun() # 将自定义计算器工具也包装成LangChain Tool对象 calc_tool Tool( nameCalculator, funccalculator.invoke, description用于计算数学表达式。输入是一个字符串如 3 5 * 2。 ) # 工具列表 tools [calc_tool, wiki_tool, search_tool] # 3. 初始化LLM和Agent llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 从LangChain Hub拉取一个适合ReAct范式的Prompt prompt hub.pull(hwchase17/react) # 创建ReAct Agent agent create_react_agent(llm, tools, prompt) # 创建执行器 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志可以看到Agent的“思考”过程 handle_parsing_errorsTrue, # 优雅处理解析错误 max_iterations5 # 限制最大迭代次数防止无限循环 ) # 4. 测试Agent questions [ 3的平方加上4的平方等于多少, 谁是阿尔伯特·爱因斯坦, 搜索一下今天北京天气怎么样 ] for question in questions: print(f\n{*50}) print(f问题: {question}) print(f{*50}) try: result agent_executor.invoke({input: question}) print(f答案: {result[output]}) except Exception as e: print(f执行出错: {e})关键点解析工具定义每个工具都需要有清晰的name、description和func。description至关重要LLM依靠它来决定是否以及如何使用该工具。ReAct Prompthwchase17/react是一个经过精心设计的Prompt它指导LLM按照“Thought/Action/Observation”的格式进行输出。这是Agent能进行规划的关键。Agent Executor它负责解析LLM的输出调用工具并将结果反馈给LLM循环往复。verboseTrue会让你看到完整的思考链这对调试和理解Agent行为非常有帮助。安全警告示例中的calculator工具使用了eval这在生产环境中是极其危险的因为它允许执行任意代码。此处仅用于演示最简单原理。实际应用中必须使用安全的表达式求值库。运行此脚本你会看到Agent如何一步步思考、选择工具并得出答案。例如对于第一个数学问题它可能会Thought: 用户问的是一个数学计算问题我需要使用计算器工具。 Action: Calculator Action Input: 3**2 4**2 Observation: 25 Thought: 我得到了计算结果可以回答用户了。 Final Answer: 3的平方加上4的平方等于25。6. 项目实战三构建Agentic RAG智能体这是最激动人心的部分我们将把前两步结合起来创建一个可以使用RAG知识库作为其专属工具的智能体。6.1 将RAG系统封装成Tool我们将4.2节中构建的RAG检索问答链包装成一个Agent可以调用的工具。创建agentic_rag.py。# agentic_rag.py import os from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA from langchain.agents import Tool, AgentExecutor, create_react_agent from langchain import hub from langchain_community.tools import DuckDuckGoSearchRun from langchain.tools import tool import math # --- 第一部分重新加载或创建RAG检索器 --- persist_directory ./chroma_db embeddings OpenAIEmbeddings() # 从已持久化的目录加载向量数据库 vectorstore Chroma( persist_directorypersist_directory, embedding_functionembeddings ) print(f已从 {persist_directory} 加载向量知识库。) # 创建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 创建用于RAG的LLM可以与Agent的LLM不同 rag_llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 创建RAG链 rag_chain RetrievalQA.from_chain_type( llmrag_llm, chain_typestuff, retrieverretriever ) # --- 第二部分将RAG链定义为工具 --- tool def company_knowledge_base(query: str) - str: 当问题涉及到公司内部信息、产品、政策、联系方式或销售数据时使用此工具进行查询。输入应为具体的问题。 # 直接调用RAG链 result rag_chain.invoke({query: query}) return result[result] # --- 第三部分定义其他工具计算器、搜索--- tool def calculator(expression: str) - str: 用于计算数学表达式。输入应该是一个有效的数学表达式字符串。 try: # 再次强调此eval仅用于演示不安全 if any(keyword in expression for keyword in [import, os, sys, exec, eval, __]): return 错误表达式不安全。 result eval(expression, {__builtins__: None}, {sqrt: math.sqrt, pi: math.pi}) return str(result) except Exception as e: return f计算错误{e} search_tool DuckDuckGoSearchRun() # --- 第四部分组装Agent --- tools [ Tool( nameCompany_Knowledge_Base, funccompany_knowledge_base.invoke, description专门查询公司内部知识库的工具。适用于产品版本、功能、联系方式、销售数据、公司地址等问题。 ), Tool( nameCalculator, funccalculator.invoke, description计算数学表达式例如 3 5 * 2 或 sqrt(16)。 ), Tool( nameWeb_Search, funcsearch_tool.run, description在互联网上搜索最新的、实时的或公开的信息例如新闻、天气、体育比分等。 ) ] # 初始化Agent的LLM agent_llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) prompt hub.pull(hwchase17/react) agent create_react_agent(agent_llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations6, early_stopping_methodgenerate # 当LLM连续两次输出相同内容时停止 ) # --- 第五部分测试智能体 --- complex_queries [ “智能助手Pro的最新版本是什么它比v2.0增加了哪些主要功能” # 纯知识库问题 “根据公司2023年1200万的销售额如果年增长率为20%预测2024年的销售额是多少” # 混合问题需要知识库数据计算 “今天上海的天气怎么样” # 需要网络搜索的问题 “告诉我公司的技术服务热线和工作时间然后计算一下如果我从现在开始拨打到下班还有多少小时假设现在是下午3点” # 多步骤混合问题 ] print(“\n” “”*60) print(“开始测试Agentic RAG智能体”) print(“”*60) for i, query in enumerate(complex_queries, 1): print(f”\n[测试{i}] 问题: {query}”) print(“-”*40) try: result agent_executor.invoke({“input”: query}) print(f”\n最终答案: {result[‘output’]}”) except Exception as e: print(f”执行过程中出现错误: {e}”) print(“”*60)核心创新点工具化RAGcompany_knowledge_base函数被tool装饰器包装成为了Agent工具箱中的一个正式工具。其description清晰地界定了它的使用边界——“公司内部信息”。智能路由AgentLLM大脑会根据用户问题的性质自主决定调用哪个工具。例如对于问题2它会先调用Company_Knowledge_Base获取“2023年销售额”然后调用Calculator计算预测值。多步推理对于问题4Agent会展示出完整的规划能力先查知识库获取“工作时间”再根据“现在时间”进行计算。这一切都由ReAct范式驱动无需手动编写流程。运行这个脚本观察verbose日志。你会看到一个真正的智能体在工作思考、决策、行动、再思考。7. 运行、验证与效果评估运行上述三个脚本后你如何评估系统的成功7.1 运行验证基础RAG运行python basic_rag.py。验证它能否从company_faq.txt中准确找到答案。基础Agent运行python agent_with_tools.py。观察控制台输出的Thought/Action/Observation序列验证其工具选择逻辑是否正确。Agentic RAG运行python agentic_rag.py。这是终极测试重点关注工具选择准确性对于混合问题它是否优先选择了正确的工具信息流转正确性上一个工具的输出是否被正确用作下一个工具的输入最终答案质量答案是否准确、完整7.2 效果评估维度检索精度RAG工具返回的文档是否与问题高度相关可以尝试问一些边缘问题测试。Agent决策能力对于模棱两可的问题如“介绍一下我们公司”Agent是直接调用知识库还是错误地使用了网络搜索复杂问题处理多步骤问题是否被正确拆解和执行效率与成本一次复杂的查询调用了多少次LLM和工具这关系到API调用成本和响应时间。8. 常见问题、陷阱与排查思路在实际开发中你会遇到各种问题。以下是一些典型问题及其解决方案。问题现象可能原因排查方式解决方案运行basic_rag.py时报错No module named ‘langchain_openai’依赖未正确安装或版本冲突。1. 检查虚拟环境是否激活。2. 运行pip list | grep langchain查看已安装版本。3. 查看错误堆栈。1. 确保在虚拟环境中。2. 尝试安装指定版本pip install langchain-openai。3. 或使用langchain的旧版导入方式from langchain.embeddings import OpenAIEmbeddings。RAG答案不准确或“幻觉”1. 检索到的文档不相关。2. 文本分割块太大或太小。3. LLM的temperature参数过高。1. 检查result[“source_documents”]看返回的文档是否切题。2. 调整chunk_size和chunk_overlap。3. 将temperature设为0。1. 优化检索器尝试不同的search_type如mmr或调整k值。2. 尝试不同的文本分割器或分割策略。3. 确保temperature0以获得更确定性的输出。Agent陷入循环或无法停止1.max_iterations设置过高。2. LLM无法生成正确的Final Answer格式。3. 工具描述不清导致Agent无法做出决定。观察verbose日志看Agent是否在重复相同的Thought和Action。1. 合理设置max_iterations如5-10。2. 使用early_stopping_method”generate”。3. 仔细打磨工具的description确保清晰无歧义。Agent选择了错误的工具工具描述description不够精确或者LLM理解有偏差。查看verbose日志中Agent选择工具时的Thought过程。重写工具的description使其职责范围更明确。例如将“查询信息”改为“查询公司内部知识库信息”。计算器工具eval安全风险代码中存在严重安全漏洞。回顾第5.1节中的安全警告。生产环境必须替换。使用ast.literal_eval仅支持简单表达式或numexpr、sympy等安全的数学表达式求值库。向量数据库加载失败persist_directory路径错误或之前未成功持久化。1. 检查./chroma_db目录是否存在及内容。2. 确认运行basic_rag.py时成功输出了“向量知识库已创建并持久化”。1. 确保路径正确。2. 重新运行basic_rag.py生成向量库。API调用超时或报错网络问题或API密钥无效、额度不足。1. 检查网络连接。2. 验证OPENAI_API_KEY环境变量是否正确设置。3. 查看OpenAI平台控制台的用量和错误信息。1. 配置网络代理注意合规性。2. 重新设置API密钥。3. 检查账单和额度。9. 最佳实践与进阶建议掌握了基础搭建后以下建议能让你的Agentic RAG系统更健壮、更强大。9.1 工程化与性能分离配置将API密钥、模型参数、向量库路径等配置信息抽取到.env文件或配置类中。异步处理对于高并发场景使用LangChain的异步接口ainvoke,astream提升性能。缓存对LLM调用和嵌入计算实施缓存显著降低成本和延迟。LangChain支持多种缓存后端如InMemoryCache, RedisCache。日志与监控记录Agent的完整执行轨迹Thought, Action, Observation便于调试和优化。监控API调用次数和耗时。9.2 提升RAG效果优质分块文本分割是RAG的基石。对于代码、Markdown、PDF等不同格式使用专用的分割器如MarkdownHeaderTextSplitter。重排序简单的向量相似度搜索可能返回相关但不精确的片段。在检索后加入一个“重排序”模型对Top K结果进行精排可以大幅提升精度。元数据过滤在存储文档时为其添加元数据如来源、章节、日期。检索时可以结合元数据过滤实现更精准的查询。多索引混合检索结合关键词检索如BM25和向量检索取长补短。9.3 增强Agent能力记忆为Agent添加对话记忆ConversationBufferMemory使其能处理多轮对话参考历史上下文。工具扩展集成更多实用工具如数据库查询、发送邮件、调用内部API、执行Shell命令需极其谨慎等。多智能体协作对于超复杂任务可以设计多个各司其职的Agent让它们通过消息队列或共享状态进行协作。LangGraph库是构建这类工作流的强大工具。验证与护栏在Agent执行关键操作如写数据库、调用付费API前加入验证步骤或人工确认环节防止意外后果。9.4 生产环境部署考量安全性彻底移除eval等危险函数对用户输入进行严格的清洗和校验为工具调用设置权限边界。可靠性为所有外部工具调用LLM、API、数据库添加重试和超时机制。可观测性除了日志集成APM工具如OpenTelemetry来追踪链路监控系统健康度。成本控制设置预算和用量告警对非关键任务使用更经济的模型利用缓存减少重复计算。通过本教程你不仅快速入门了LangChain更完成了一个融合Agent与RAG的综合性项目实战。你理解了如何将LLM、工具、知识库组合成一个能思考、会行动、有知识的智能体。记住这里的每一个组件——RAG的检索精度、工具描述的清晰度、Agent的Prompt设计——都是可以持续优化的杠杆。下一步你可以尝试用更复杂的业务逻辑、更丰富的工具集、以及更强大的模型如GPT-4来挑战你的智能体让它解决真实世界的问题。建议收藏本文在后续的深入实践中反复查阅。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度