尧图网站建设 
如果你最近关注大模型应用开发大概率被这三个词刷屏了RAG、Agent、MCP。它们听起来都很酷但你真的清楚它们分别解决什么问题、彼此之间是什么关系、以及在实际项目中该如何选择吗很多人容易陷入一个误区把这些概念当成并列的“技术选型”来比较。实际上它们处于大模型应用栈的不同层级解决的是完全不同维度的问题。盲目跟风只会让你在技术选型时一头雾水或者在本地部署时踩进无数深坑。这篇文章的目的就是帮你彻底拆解这三个“热词”的底层逻辑。我们不只讲“是什么”更要讲清楚“为什么需要它”、“它解决了什么具体问题”以及“在什么场景下用”。更重要的是我会结合一次完整的本地部署实测从环境准备、代码实现到最终运行手把手带你走通一个融合了RAG和Agent的Demo项目并附上我踩过的所有坑和解决方案。读完本文你将能清晰地画出大模型应用的技术地图并具备动手搭建一个可运行原型的能力。1. 核心问题我们到底在解决什么在深入技术细节之前我们必须先统一认知当前基于大语言模型LLM的应用开发核心要解决的是LLM自身的几个固有缺陷知识陈旧与幻觉大模型的训练数据有截止日期无法获取最新、最专有的信息并且会“自信地”编造看似合理实则错误的内容幻觉。缺乏执行能力大模型本身是“思考者”而非“行动者”。它无法直接操作数据库、调用API、发送邮件或执行代码。上下文长度限制即使上下文窗口不断增大也无法将海量的私有知识库全部塞进提示词Prompt。这三个缺陷恰好对应了三个技术方向RAG 主要解决问题1为模型注入外部、最新、专有的知识。Agent 主要解决问题2赋予模型使用工具、规划任务、执行动作的能力。MCP 可以看作是问题2的工程化解决方案它定义了工具能力如何以一种标准、统一的方式被暴露给Agent或应用。所以它们的关系不是“三选一”而更像是“组合拳”。一个复杂的应用可能同时需要用RAG获取知识用Agent进行推理和规划并通过MCP协议调用各种工具来执行。2. 概念拆解RAG、Agent、MCP到底是什么2.1 RAG大模型的“外部记忆体”通俗理解想象一下你是一个知识渊博但只记得2023年以前事情的专家大模型。当有人问你今天的股价时你无法回答。RAG就像给你配了一个超级助理这个助理会飞快地查阅最新的财经报告向量数据库把关键信息摘要递给你。你结合自己的通用知识模型参数和这份最新资料就能给出准确的回答。技术定义检索增强生成。其核心流程是一个闭环索引将文档切块、向量化存入向量数据库。检索根据用户问题从向量库中查找最相关的文本片段。增强将检索到的片段作为上下文与用户问题一起构成提示词提交给大模型。生成大模型基于增强后的提示词生成最终答案。关键点RAG的核心价值在于知识更新无需重新训练模型成本极低。它让大模型从“通才”变成了某个垂直领域的“专才”。2.2 Agent大模型的“手和脚”通俗理解如果大模型是一个聪明的大脑那么Agent就是给这个大脑配上了可以指挥的身体和工具。大脑负责思考“要做什么”和“怎么做”身体负责执行。例如大脑Agent分析出“用户想查天气然后订机票”它就会指挥手工具先去调用天气API再调用机票预订API。技术定义智能体。它是一个能够感知环境、进行决策并执行动作以实现目标的系统。在大模型语境下Agent通常由以下几部分组成规划模块分解任务制定步骤。记忆模块保存对话历史、工具执行结果等。工具使用模块调用外部函数或API。执行与反思模块执行动作并根据结果调整策略。关键点Agent的核心是自主性和工具调用。它让静态的问答变成了动态的任务流。2.3 MCP工具的“通用插座”通俗理解以前每个电器工具都有自己独特的插头接口Agent需要为每个插头准备不同的转换器适配代码非常麻烦。MCP就像定义了一种全球通用的“插座标准”。任何工具只要按照这个标准制造插头就能被所有支持这个标准的Agent电器即插即用。技术定义模型上下文协议。它是一个开放协议用于标准化大模型与外部工具、数据源之间的通信方式。它定义了工具如何被描述、如何被调用、以及如何返回结果。关键点MCP解决的是集成复杂度和生态碎片化问题。它让开发者可以像搭积木一样为Agent组合来自不同提供商的能力而无需关心底层实现。三者关系总结技术角色比喻核心解决问题输出RAG图书管理员/研究助理知识实时性、专有性、抗幻觉增强后的提示词上下文Agent项目经理/指挥官任务分解、自主决策、工具调用一系列动作和最终结果MCPUSB协议/插座标准工具接入的标准化和互操作性统一的工具描述和调用规范一个高级应用可能是Agent接收到复杂任务先使用RAG从知识库查询必要背景信息然后通过MCP标准接口调用计算器、代码执行器、邮件发送器等工具逐步完成任务。3. 环境准备本地部署实战起点理论讲完了我们进入实战。目标是搭建一个本地环境运行一个结合了RAG和Agent的简单应用。你会需要以下准备操作系统Windows 10/11, macOS 或 Linux (本文以 macOS/Linux 命令行示例为主Windows 用户建议使用 WSL2)。Python版本 3.10 或 3.11。这是目前大多数AI框架最兼容的版本。包管理工具pip最新版。代码编辑器VS Code 或 PyCharm。硬件建议拥有至少 8GB 空闲内存。本地运行大模型需要一定资源。第一步创建并激活虚拟环境这是避免包版本冲突的最佳实践。# 创建名为 rag-agent-demo 的虚拟环境 python -m venv rag-agent-demo # 激活虚拟环境 # macOS/Linux: source rag-agent-demo/bin/activate # Windows: # rag-agent-demo\Scripts\activate激活后命令行提示符前会出现(rag-agent-demo)字样。第二步安装核心框架我们将使用LangChain和LangGraph。LangChain 是构建LLM应用的事实标准框架LangGraph 则专门用于构建复杂的、有状态的Agent工作流。pip install langchain langchain-community langgraph踩坑提示1不要直接pip install langchain就以为装全了。langchain-community包含了大量第三方集成如各种向量数据库、工具必须单独安装。第三步安装嵌入模型和向量数据库RAG需要将文本转换为向量嵌入。我们使用轻量级的sentence-transformers本地模型和Chroma向量数据库。pip install sentence-transformers chromadb踩坑提示2sentence-transformers首次运行时会自动下载模型确保网络通畅。也可以选择更小的模型如all-MiniLM-L6-v2来提速。第四步安装大模型运行环境为了完全本地化我们使用Ollama来在本地运行开源大模型。请根据官网指引安装 Ollama。 安装后拉取一个模型例如轻量级的llama3.2:1b10亿参数用于演示ollama pull llama3.2:1b踩坑提示3模型大小需根据电脑配置选择。llama3.2:1b对内存要求较低但能力也较弱。如果资源充足可以尝试llama3.1:8b。4. 项目实战构建一个本地问答助手RAG Agent现在我们来构建一个应用它首先能基于本地文档回答问题RAG当遇到需要计算或获取实时信息的问题时能自动调用相应的工具Agent。4.1 项目结构rag_agent_demo/ ├── data/ # 存放知识库文档 │ └── company_faq.txt ├── vector_db/ # Chroma数据库存储目录 ├── tools.py # 自定义工具定义 ├── rag_chain.py # RAG检索链 ├── agent_graph.py # Agent工作流定义 └── main.py # 主程序入口4.2 第一步准备知识库并实现RAG链在data/company_faq.txt里放入一些公司FAQ例如Q: 公司的年假政策是怎样的 A: 员工入职满一年后享有10天带薪年假。 Q: 报销流程是什么 A: 员工需在费用发生后30天内通过内部财务系统提交报销单并附上发票。 Q: 技术部的核心项目是什么 A: 目前核心项目是“星海”AI平台开发旨在提升内部研发效率。创建rag_chain.py# rag_chain.py from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.document_loaders import TextLoader from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings from langchain.chains import RetrievalQA from langchain_community.llms import Ollama # 1. 加载文档 loader TextLoader(./data/company_faq.txt) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) texts text_splitter.split_documents(documents) # 3. 初始化嵌入模型和向量数据库 # 使用本地嵌入模型 embeddings HuggingFaceEmbeddings(model_nameall-MiniLM-L6-v2) # 指定持久化路径 vectorstore Chroma.from_documents( documentstexts, embeddingembeddings, persist_directory./vector_db ) vectorstore.persist() # 持久化到磁盘 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3个片段 # 4. 初始化本地LLM llm Ollama(modelllama3.2:1b, temperature0) # 5. 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将检索到的文档“堆叠”进提示词 retrieverretriever, return_source_documentsTrue # 返回源文档便于调试 ) def ask_question(question): 提问函数 result qa_chain.invoke({query: question}) answer result[result] sources result[source_documents] print(f问题: {question}) print(f答案: {answer}) print(参考来源:) for doc in sources: print(f - {doc.page_content[:100]}...) # 打印来源前100字符 print(- * 50) return answer if __name__ __main__: # 测试RAG功能 ask_question(公司的年假有多少天) ask_question(报销有什么时间限制)运行测试python rag_chain.py预期看到模型能根据company_faq.txt中的内容回答问题并打印出它参考了哪些原文片段。4.3 第二步定义工具并创建Agent现在我们让这个系统不仅能回答知识库问题还能进行简单计算。创建tools.py# tools.py from langchain.tools import tool from datetime import datetime tool def calculator(expression: str) - str: 用于执行数学表达式计算。输入应为一个字符串形式的数学表达式如 3 5 * 2。 try: # 警告使用eval存在安全风险仅用于演示。生产环境应用更安全的计算库如ast.literal_eval限制操作。 result eval(expression) return f计算结果: {result} except Exception as e: return f计算错误: {e} tool def get_current_time() - str: 获取当前的系统日期和时间。 now datetime.now() return f当前时间是: {now.strftime(%Y-%m-%d %H:%M:%S)} # 工具列表 tools [calculator, get_current_time]踩坑提示4tool装饰器会自动根据函数文档字符串生成工具的描述这是LangChain Agent能理解工具用途的关键。描述必须清晰。接下来创建agent_graph.py使用 LangGraph 构建一个能决定何时使用RAG、何时使用工具的Agent。# agent_graph.py from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated, List from langchain_core.messages import HumanMessage, AIMessage from langchain_community.llms import Ollama from langchain.tools.render import render_text_description from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.agents import create_react_agent, AgentExecutor import operator # 1. 定义Agent的状态 class AgentState(TypedDict): messages: Annotated[List, operator.add] # 消息历史 question: str # 当前问题 # 2. 初始化LLM和工具从tools.py导入 from tools import tools llm Ollama(modelllama3.2:1b, temperature0) # 3. 构建一个简单的ReAct Agent # ReAct提示词模板 react_prompt ChatPromptTemplate.from_messages([ (system, 你是一个有帮助的助手可以访问以下工具 {工具列表} 请严格按以下格式思考 问题用户的问题 思考我需要一步步分析。是否需要使用工具如果需要用哪个 行动要使用的工具名称 行动输入工具的输入 观察工具返回的结果 ...这个思考-行动-观察循环可以重复多次 最终答案给用户的最终答案 如果问题明显是关于公司内部知识如政策、流程、项目请直接使用“知识库查询”能力不要使用上述工具。 当前对话 {聊天历史} .replace({工具列表}, render_text_description(tools))), MessagesPlaceholder(variable_namemessages), (user, {input}), ]) # 创建Agent执行器 agent create_react_agent(llm, tools, react_prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 4. 定义两个节点一个处理通用/工具问题一个处理知识库问题这里简化实际需集成RAG链 def general_agent_node(state: AgentState): 处理需要工具或通用对话的节点 human_message state[messages][-1].content if state[messages] else state[question] result agent_executor.invoke({input: human_message, chat_history: state[messages][:-1]}) return {messages: [AIMessage(contentresult[output])]} def rag_node(state: AgentState): 处理知识库问题的节点此处为示意需调用前面写的qa_chain # 此处应集成4.2节中的qa_chain.invoke # 为演示我们模拟一个固定回答 simulated_answer 【来自知识库】根据公司政策员工年假为10天。 return {messages: [AIMessage(contentsimulated_answer)]} # 5. 定义路由逻辑判断问题类型 def router(state: AgentState): 根据问题内容决定下一步 last_message state[messages][-1].content if state[messages] else state[question] # 简单的关键词路由如果问题包含“公司”、“政策”、“流程”、“项目”等词走RAG节点 rag_keywords [公司, 政策, 流程, 报销, 项目, 年假] if any(keyword in last_message for keyword in rag_keywords): return rag_query else: return general_agent # 6. 构建图 workflow StateGraph(AgentState) # 添加节点 workflow.add_node(general_agent, general_agent_node) workflow.add_node(rag_query, rag_node) # 设置入口点 workflow.set_entry_point(router) # 添加条件边 workflow.add_conditional_edges( router, router, { general_agent: general_agent, rag_query: rag_query, } ) # 从各节点指向结束 workflow.add_edge(general_agent, END) workflow.add_edge(rag_query, END) # 编译图 app workflow.compile()4.4 第三步创建主程序并运行测试创建main.py# main.py from agent_graph import app from langchain_core.messages import HumanMessage def run_conversation(): print( 本地RAGAgent助手 ) print(输入 退出 或 quit 结束对话。) # 初始化状态 config {recursion_limit: 50} while True: user_input input(\n你: ) if user_input.lower() in [退出, quit]: print(再见) break # 调用编译好的图应用 inputs {messages: [HumanMessage(contentuser_input)], question: user_input} result app.invoke(inputs, configconfig) # 输出最终答案 final_message result[messages][-1] print(f助手: {final_message.content}) if __name__ __main__: run_conversation()运行完整应用确保 Ollama 服务正在运行通常安装后会自动运行。在终端执行python main.py5. 运行结果与效果验证运行python main.py后你应该会进入一个交互式对话界面。测试用例1知识库问答触发RAG路径你: 我们公司的年假政策是怎样的 助手: 【来自知识库】根据公司政策员工年假为10天。验证点助手识别出“公司”、“年假”关键词路由到rag_node并返回了基于知识库的答案。测试用例2工具调用触发Agent路径你: 计算一下 15 乘以 28 等于多少 助手: 思考用户需要计算一个数学表达式。我可以使用计算器工具。 行动calculator 行动输入15 * 28 观察计算结果: 420 最终答案15乘以28等于420。验证点助手识别出这是一个计算问题触发了general_agent_node规划使用calculator工具并正确执行和返回了结果。测试用例3混合场景未来扩展方向一个更复杂的Agent可以先通过RAG查询“报销流程”得知需要“30天内提交”然后自动调用日历工具为用户创建一个“报销截止日期”提醒。这需要更复杂的图工作流设计但原理已在本项目中奠定。6. 常见问题与排查思路在本地部署过程中你几乎一定会遇到以下问题问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named langchain_community未安装langchain-community包。检查pip list输出。运行pip install langchain-community。Ollama: model llama3.2:1b not foundOllama未拉取指定模型或模型名称错误。运行ollama list查看本地已有模型。使用ollama pull llama3.2:1b拉取模型。确保Ollama服务在运行。运行时代理错误或网络超时环境存在网络代理影响sentence-transformers下载模型或Ollama调用。检查requests库是否因代理报错。1. 尝试关闭代理。2. 或在代码中为requests/httpx设置代理os.environ[HTTP_PROXY] http://your-proxy:port(注意此处仅为示例实际需根据合法网络配置调整)。ChromaDB 报权限错误或无法持久化向量数据库存储目录./vector_db无写入权限。检查目录是否存在及权限。确保当前用户对项目目录有读写权限或指定一个绝对路径。Agent 不调用工具总是直接回答1. 提示词Prompt未清晰引导工具使用。2. 模型能力太弱如1B参数无法理解工具调用格式。1. 打印出发送给模型的完整提示词检查。2. 换一个更强模型测试如llama3.1:8b。1. 优化提示词明确要求模型按“思考-行动-观察”格式输出。2. 升级本地模型或考虑使用云端API模型如OpenAI GPT-4进行开发调试。程序运行后无反应或卡住1. 模型加载慢首次。2. 图工作流陷入循环。1. 观察CPU/内存占用。2. 检查config {recursion_limit: 50}是否设置过小或过大。1. 耐心等待首次加载。使用更小模型。2. 确保工作流有明确的终止条件如指向END。7. 最佳实践与工程建议基于本次实测和常见陷阱总结以下建议从简单开始逐步复杂化不要一开始就设计复杂的多Agent系统。先用一个工具、一个知识源跑通整个流程RAG检索 - 增强提示 - LLM生成 - 输出再逐步添加工具和路由逻辑。模型选择权衡本地部署时在模型大小速度/资源和模型能力智能程度间做权衡。开发调试阶段可先用云端大模型如GPT-4保证智能体逻辑正确再切换为本地模型优化成本。提示词工程是关键Agent的可靠性极度依赖提示词。清晰、结构化、带有示例的提示词能极大提升工具调用的准确率。将提示词模板化、外部化如存入JSON或YAML文件便于管理。向量数据库的优化分块策略根据文档类型调整chunk_size和chunk_overlap。法律合同可能需要大块保持上下文聊天记录可能需要小块。元数据过滤为每个文本块添加来源、类型、日期等元数据检索时可以进行过滤提高精度。混合检索结合向量检索语义相似和关键词检索精确匹配效果更好。错误处理与稳定性工具调用容错为每个工具调用添加try...catch并设计重试或降级策略如计算失败时让LLM尝试估算。设置超时与限制对LLM调用和工具调用设置超时防止长时间挂起。限制Agent的最大循环步数recursion_limit防止死循环。MCP的引入时机当你的工具数量增多且希望它们能被不同的Agent或应用复用时就是考虑引入MCP的时候。你可以将自研的工具封装成MCP Server这样任何支持MCP的客户端如Claude Desktop、Cline IDE都能直接使用你的工具实现能力复用。8. 总结与后续方向通过这次从理论到实战的拆解我们可以清晰地看到RAG是解决大模型知识“失忆”和“幻觉”的标配方案它通过外部检索将最新、最专的知识动态注入上下文技术栈核心是文本处理 - 向量化 - 向量数据库。Agent是赋予大模型行动力的大脑中枢它通过规划、工具调用、反思来实现复杂任务技术栈核心是规划器 工具集 记忆 执行引擎。MCP是构建强大Agent生态的连接器标准它让工具接入变得标准化是提升开发效率、促进生态繁荣的底层协议。对于开发者而言当下的学习路径应该是先深入理解RAG和Agent的核心原理与实现动手搭建一个可工作的原型。在工具多起来后再自然地去了解和应用MCP来规范你的工具层。后续可以深入的方向优化RAG尝试不同的嵌入模型、重排序技术、以及更复杂的检索策略如HyDE。强化Agent在LangGraph中实现更复杂的循环、子图、人工审核节点构建真正多步骤的工作流。接入真实工具将工具替换为真实的API调用如发送邮件、查询数据库、操作文件系统。引入MCP尝试将你的工具封装为MCP Server并在支持MCP的客户端中测试。前端交互为你的智能助手搭建一个简单的Web界面如用Gradio或Streamlit。本地部署大模型应用已不再是遥不可及的事情。它虽有门槛但每一步的坑都有迹可循。希望这篇结合了底层逻辑拆解和实战踩坑指南的文章能为你提供一个坚实的起点。建议收藏本文在搭建过程中遇到问题时回来对照排查。 大模型应用开发实战：RAG、Agent与MCP本地部署全解析
如果你最近关注大模型应用开发大概率被这三个词刷屏了RAG、Agent、MCP。它们听起来都很酷但你真的清楚它们分别解决什么问题、彼此之间是什么关系、以及在实际项目中该如何选择吗很多人容易陷入一个误区把这些概念当成并列的“技术选型”来比较。实际上它们处于大模型应用栈的不同层级解决的是完全不同维度的问题。盲目跟风只会让你在技术选型时一头雾水或者在本地部署时踩进无数深坑。这篇文章的目的就是帮你彻底拆解这三个“热词”的底层逻辑。我们不只讲“是什么”更要讲清楚“为什么需要它”、“它解决了什么具体问题”以及“在什么场景下用”。更重要的是我会结合一次完整的本地部署实测从环境准备、代码实现到最终运行手把手带你走通一个融合了RAG和Agent的Demo项目并附上我踩过的所有坑和解决方案。读完本文你将能清晰地画出大模型应用的技术地图并具备动手搭建一个可运行原型的能力。1. 核心问题我们到底在解决什么在深入技术细节之前我们必须先统一认知当前基于大语言模型LLM的应用开发核心要解决的是LLM自身的几个固有缺陷知识陈旧与幻觉大模型的训练数据有截止日期无法获取最新、最专有的信息并且会“自信地”编造看似合理实则错误的内容幻觉。缺乏执行能力大模型本身是“思考者”而非“行动者”。它无法直接操作数据库、调用API、发送邮件或执行代码。上下文长度限制即使上下文窗口不断增大也无法将海量的私有知识库全部塞进提示词Prompt。这三个缺陷恰好对应了三个技术方向RAG 主要解决问题1为模型注入外部、最新、专有的知识。Agent 主要解决问题2赋予模型使用工具、规划任务、执行动作的能力。MCP 可以看作是问题2的工程化解决方案它定义了工具能力如何以一种标准、统一的方式被暴露给Agent或应用。所以它们的关系不是“三选一”而更像是“组合拳”。一个复杂的应用可能同时需要用RAG获取知识用Agent进行推理和规划并通过MCP协议调用各种工具来执行。2. 概念拆解RAG、Agent、MCP到底是什么2.1 RAG大模型的“外部记忆体”通俗理解想象一下你是一个知识渊博但只记得2023年以前事情的专家大模型。当有人问你今天的股价时你无法回答。RAG就像给你配了一个超级助理这个助理会飞快地查阅最新的财经报告向量数据库把关键信息摘要递给你。你结合自己的通用知识模型参数和这份最新资料就能给出准确的回答。技术定义检索增强生成。其核心流程是一个闭环索引将文档切块、向量化存入向量数据库。检索根据用户问题从向量库中查找最相关的文本片段。增强将检索到的片段作为上下文与用户问题一起构成提示词提交给大模型。生成大模型基于增强后的提示词生成最终答案。关键点RAG的核心价值在于知识更新无需重新训练模型成本极低。它让大模型从“通才”变成了某个垂直领域的“专才”。2.2 Agent大模型的“手和脚”通俗理解如果大模型是一个聪明的大脑那么Agent就是给这个大脑配上了可以指挥的身体和工具。大脑负责思考“要做什么”和“怎么做”身体负责执行。例如大脑Agent分析出“用户想查天气然后订机票”它就会指挥手工具先去调用天气API再调用机票预订API。技术定义智能体。它是一个能够感知环境、进行决策并执行动作以实现目标的系统。在大模型语境下Agent通常由以下几部分组成规划模块分解任务制定步骤。记忆模块保存对话历史、工具执行结果等。工具使用模块调用外部函数或API。执行与反思模块执行动作并根据结果调整策略。关键点Agent的核心是自主性和工具调用。它让静态的问答变成了动态的任务流。2.3 MCP工具的“通用插座”通俗理解以前每个电器工具都有自己独特的插头接口Agent需要为每个插头准备不同的转换器适配代码非常麻烦。MCP就像定义了一种全球通用的“插座标准”。任何工具只要按照这个标准制造插头就能被所有支持这个标准的Agent电器即插即用。技术定义模型上下文协议。它是一个开放协议用于标准化大模型与外部工具、数据源之间的通信方式。它定义了工具如何被描述、如何被调用、以及如何返回结果。关键点MCP解决的是集成复杂度和生态碎片化问题。它让开发者可以像搭积木一样为Agent组合来自不同提供商的能力而无需关心底层实现。三者关系总结技术角色比喻核心解决问题输出RAG图书管理员/研究助理知识实时性、专有性、抗幻觉增强后的提示词上下文Agent项目经理/指挥官任务分解、自主决策、工具调用一系列动作和最终结果MCPUSB协议/插座标准工具接入的标准化和互操作性统一的工具描述和调用规范一个高级应用可能是Agent接收到复杂任务先使用RAG从知识库查询必要背景信息然后通过MCP标准接口调用计算器、代码执行器、邮件发送器等工具逐步完成任务。3. 环境准备本地部署实战起点理论讲完了我们进入实战。目标是搭建一个本地环境运行一个结合了RAG和Agent的简单应用。你会需要以下准备操作系统Windows 10/11, macOS 或 Linux (本文以 macOS/Linux 命令行示例为主Windows 用户建议使用 WSL2)。Python版本 3.10 或 3.11。这是目前大多数AI框架最兼容的版本。包管理工具pip最新版。代码编辑器VS Code 或 PyCharm。硬件建议拥有至少 8GB 空闲内存。本地运行大模型需要一定资源。第一步创建并激活虚拟环境这是避免包版本冲突的最佳实践。# 创建名为 rag-agent-demo 的虚拟环境 python -m venv rag-agent-demo # 激活虚拟环境 # macOS/Linux: source rag-agent-demo/bin/activate # Windows: # rag-agent-demo\Scripts\activate激活后命令行提示符前会出现(rag-agent-demo)字样。第二步安装核心框架我们将使用LangChain和LangGraph。LangChain 是构建LLM应用的事实标准框架LangGraph 则专门用于构建复杂的、有状态的Agent工作流。pip install langchain langchain-community langgraph踩坑提示1不要直接pip install langchain就以为装全了。langchain-community包含了大量第三方集成如各种向量数据库、工具必须单独安装。第三步安装嵌入模型和向量数据库RAG需要将文本转换为向量嵌入。我们使用轻量级的sentence-transformers本地模型和Chroma向量数据库。pip install sentence-transformers chromadb踩坑提示2sentence-transformers首次运行时会自动下载模型确保网络通畅。也可以选择更小的模型如all-MiniLM-L6-v2来提速。第四步安装大模型运行环境为了完全本地化我们使用Ollama来在本地运行开源大模型。请根据官网指引安装 Ollama。 安装后拉取一个模型例如轻量级的llama3.2:1b10亿参数用于演示ollama pull llama3.2:1b踩坑提示3模型大小需根据电脑配置选择。llama3.2:1b对内存要求较低但能力也较弱。如果资源充足可以尝试llama3.1:8b。4. 项目实战构建一个本地问答助手RAG Agent现在我们来构建一个应用它首先能基于本地文档回答问题RAG当遇到需要计算或获取实时信息的问题时能自动调用相应的工具Agent。4.1 项目结构rag_agent_demo/ ├── data/ # 存放知识库文档 │ └── company_faq.txt ├── vector_db/ # Chroma数据库存储目录 ├── tools.py # 自定义工具定义 ├── rag_chain.py # RAG检索链 ├── agent_graph.py # Agent工作流定义 └── main.py # 主程序入口4.2 第一步准备知识库并实现RAG链在data/company_faq.txt里放入一些公司FAQ例如Q: 公司的年假政策是怎样的 A: 员工入职满一年后享有10天带薪年假。 Q: 报销流程是什么 A: 员工需在费用发生后30天内通过内部财务系统提交报销单并附上发票。 Q: 技术部的核心项目是什么 A: 目前核心项目是“星海”AI平台开发旨在提升内部研发效率。创建rag_chain.py# rag_chain.py from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.document_loaders import TextLoader from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings from langchain.chains import RetrievalQA from langchain_community.llms import Ollama # 1. 加载文档 loader TextLoader(./data/company_faq.txt) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) texts text_splitter.split_documents(documents) # 3. 初始化嵌入模型和向量数据库 # 使用本地嵌入模型 embeddings HuggingFaceEmbeddings(model_nameall-MiniLM-L6-v2) # 指定持久化路径 vectorstore Chroma.from_documents( documentstexts, embeddingembeddings, persist_directory./vector_db ) vectorstore.persist() # 持久化到磁盘 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3个片段 # 4. 初始化本地LLM llm Ollama(modelllama3.2:1b, temperature0) # 5. 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将检索到的文档“堆叠”进提示词 retrieverretriever, return_source_documentsTrue # 返回源文档便于调试 ) def ask_question(question): 提问函数 result qa_chain.invoke({query: question}) answer result[result] sources result[source_documents] print(f问题: {question}) print(f答案: {answer}) print(参考来源:) for doc in sources: print(f - {doc.page_content[:100]}...) # 打印来源前100字符 print(- * 50) return answer if __name__ __main__: # 测试RAG功能 ask_question(公司的年假有多少天) ask_question(报销有什么时间限制)运行测试python rag_chain.py预期看到模型能根据company_faq.txt中的内容回答问题并打印出它参考了哪些原文片段。4.3 第二步定义工具并创建Agent现在我们让这个系统不仅能回答知识库问题还能进行简单计算。创建tools.py# tools.py from langchain.tools import tool from datetime import datetime tool def calculator(expression: str) - str: 用于执行数学表达式计算。输入应为一个字符串形式的数学表达式如 3 5 * 2。 try: # 警告使用eval存在安全风险仅用于演示。生产环境应用更安全的计算库如ast.literal_eval限制操作。 result eval(expression) return f计算结果: {result} except Exception as e: return f计算错误: {e} tool def get_current_time() - str: 获取当前的系统日期和时间。 now datetime.now() return f当前时间是: {now.strftime(%Y-%m-%d %H:%M:%S)} # 工具列表 tools [calculator, get_current_time]踩坑提示4tool装饰器会自动根据函数文档字符串生成工具的描述这是LangChain Agent能理解工具用途的关键。描述必须清晰。接下来创建agent_graph.py使用 LangGraph 构建一个能决定何时使用RAG、何时使用工具的Agent。# agent_graph.py from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated, List from langchain_core.messages import HumanMessage, AIMessage from langchain_community.llms import Ollama from langchain.tools.render import render_text_description from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.agents import create_react_agent, AgentExecutor import operator # 1. 定义Agent的状态 class AgentState(TypedDict): messages: Annotated[List, operator.add] # 消息历史 question: str # 当前问题 # 2. 初始化LLM和工具从tools.py导入 from tools import tools llm Ollama(modelllama3.2:1b, temperature0) # 3. 构建一个简单的ReAct Agent # ReAct提示词模板 react_prompt ChatPromptTemplate.from_messages([ (system, 你是一个有帮助的助手可以访问以下工具 {工具列表} 请严格按以下格式思考 问题用户的问题 思考我需要一步步分析。是否需要使用工具如果需要用哪个 行动要使用的工具名称 行动输入工具的输入 观察工具返回的结果 ...这个思考-行动-观察循环可以重复多次 最终答案给用户的最终答案 如果问题明显是关于公司内部知识如政策、流程、项目请直接使用“知识库查询”能力不要使用上述工具。 当前对话 {聊天历史} .replace({工具列表}, render_text_description(tools))), MessagesPlaceholder(variable_namemessages), (user, {input}), ]) # 创建Agent执行器 agent create_react_agent(llm, tools, react_prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 4. 定义两个节点一个处理通用/工具问题一个处理知识库问题这里简化实际需集成RAG链 def general_agent_node(state: AgentState): 处理需要工具或通用对话的节点 human_message state[messages][-1].content if state[messages] else state[question] result agent_executor.invoke({input: human_message, chat_history: state[messages][:-1]}) return {messages: [AIMessage(contentresult[output])]} def rag_node(state: AgentState): 处理知识库问题的节点此处为示意需调用前面写的qa_chain # 此处应集成4.2节中的qa_chain.invoke # 为演示我们模拟一个固定回答 simulated_answer 【来自知识库】根据公司政策员工年假为10天。 return {messages: [AIMessage(contentsimulated_answer)]} # 5. 定义路由逻辑判断问题类型 def router(state: AgentState): 根据问题内容决定下一步 last_message state[messages][-1].content if state[messages] else state[question] # 简单的关键词路由如果问题包含“公司”、“政策”、“流程”、“项目”等词走RAG节点 rag_keywords [公司, 政策, 流程, 报销, 项目, 年假] if any(keyword in last_message for keyword in rag_keywords): return rag_query else: return general_agent # 6. 构建图 workflow StateGraph(AgentState) # 添加节点 workflow.add_node(general_agent, general_agent_node) workflow.add_node(rag_query, rag_node) # 设置入口点 workflow.set_entry_point(router) # 添加条件边 workflow.add_conditional_edges( router, router, { general_agent: general_agent, rag_query: rag_query, } ) # 从各节点指向结束 workflow.add_edge(general_agent, END) workflow.add_edge(rag_query, END) # 编译图 app workflow.compile()4.4 第三步创建主程序并运行测试创建main.py# main.py from agent_graph import app from langchain_core.messages import HumanMessage def run_conversation(): print( 本地RAGAgent助手 ) print(输入 退出 或 quit 结束对话。) # 初始化状态 config {recursion_limit: 50} while True: user_input input(\n你: ) if user_input.lower() in [退出, quit]: print(再见) break # 调用编译好的图应用 inputs {messages: [HumanMessage(contentuser_input)], question: user_input} result app.invoke(inputs, configconfig) # 输出最终答案 final_message result[messages][-1] print(f助手: {final_message.content}) if __name__ __main__: run_conversation()运行完整应用确保 Ollama 服务正在运行通常安装后会自动运行。在终端执行python main.py5. 运行结果与效果验证运行python main.py后你应该会进入一个交互式对话界面。测试用例1知识库问答触发RAG路径你: 我们公司的年假政策是怎样的 助手: 【来自知识库】根据公司政策员工年假为10天。验证点助手识别出“公司”、“年假”关键词路由到rag_node并返回了基于知识库的答案。测试用例2工具调用触发Agent路径你: 计算一下 15 乘以 28 等于多少 助手: 思考用户需要计算一个数学表达式。我可以使用计算器工具。 行动calculator 行动输入15 * 28 观察计算结果: 420 最终答案15乘以28等于420。验证点助手识别出这是一个计算问题触发了general_agent_node规划使用calculator工具并正确执行和返回了结果。测试用例3混合场景未来扩展方向一个更复杂的Agent可以先通过RAG查询“报销流程”得知需要“30天内提交”然后自动调用日历工具为用户创建一个“报销截止日期”提醒。这需要更复杂的图工作流设计但原理已在本项目中奠定。6. 常见问题与排查思路在本地部署过程中你几乎一定会遇到以下问题问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named langchain_community未安装langchain-community包。检查pip list输出。运行pip install langchain-community。Ollama: model llama3.2:1b not foundOllama未拉取指定模型或模型名称错误。运行ollama list查看本地已有模型。使用ollama pull llama3.2:1b拉取模型。确保Ollama服务在运行。运行时代理错误或网络超时环境存在网络代理影响sentence-transformers下载模型或Ollama调用。检查requests库是否因代理报错。1. 尝试关闭代理。2. 或在代码中为requests/httpx设置代理os.environ[HTTP_PROXY] http://your-proxy:port(注意此处仅为示例实际需根据合法网络配置调整)。ChromaDB 报权限错误或无法持久化向量数据库存储目录./vector_db无写入权限。检查目录是否存在及权限。确保当前用户对项目目录有读写权限或指定一个绝对路径。Agent 不调用工具总是直接回答1. 提示词Prompt未清晰引导工具使用。2. 模型能力太弱如1B参数无法理解工具调用格式。1. 打印出发送给模型的完整提示词检查。2. 换一个更强模型测试如llama3.1:8b。1. 优化提示词明确要求模型按“思考-行动-观察”格式输出。2. 升级本地模型或考虑使用云端API模型如OpenAI GPT-4进行开发调试。程序运行后无反应或卡住1. 模型加载慢首次。2. 图工作流陷入循环。1. 观察CPU/内存占用。2. 检查config {recursion_limit: 50}是否设置过小或过大。1. 耐心等待首次加载。使用更小模型。2. 确保工作流有明确的终止条件如指向END。7. 最佳实践与工程建议基于本次实测和常见陷阱总结以下建议从简单开始逐步复杂化不要一开始就设计复杂的多Agent系统。先用一个工具、一个知识源跑通整个流程RAG检索 - 增强提示 - LLM生成 - 输出再逐步添加工具和路由逻辑。模型选择权衡本地部署时在模型大小速度/资源和模型能力智能程度间做权衡。开发调试阶段可先用云端大模型如GPT-4保证智能体逻辑正确再切换为本地模型优化成本。提示词工程是关键Agent的可靠性极度依赖提示词。清晰、结构化、带有示例的提示词能极大提升工具调用的准确率。将提示词模板化、外部化如存入JSON或YAML文件便于管理。向量数据库的优化分块策略根据文档类型调整chunk_size和chunk_overlap。法律合同可能需要大块保持上下文聊天记录可能需要小块。元数据过滤为每个文本块添加来源、类型、日期等元数据检索时可以进行过滤提高精度。混合检索结合向量检索语义相似和关键词检索精确匹配效果更好。错误处理与稳定性工具调用容错为每个工具调用添加try...catch并设计重试或降级策略如计算失败时让LLM尝试估算。设置超时与限制对LLM调用和工具调用设置超时防止长时间挂起。限制Agent的最大循环步数recursion_limit防止死循环。MCP的引入时机当你的工具数量增多且希望它们能被不同的Agent或应用复用时就是考虑引入MCP的时候。你可以将自研的工具封装成MCP Server这样任何支持MCP的客户端如Claude Desktop、Cline IDE都能直接使用你的工具实现能力复用。8. 总结与后续方向通过这次从理论到实战的拆解我们可以清晰地看到RAG是解决大模型知识“失忆”和“幻觉”的标配方案它通过外部检索将最新、最专的知识动态注入上下文技术栈核心是文本处理 - 向量化 - 向量数据库。Agent是赋予大模型行动力的大脑中枢它通过规划、工具调用、反思来实现复杂任务技术栈核心是规划器 工具集 记忆 执行引擎。MCP是构建强大Agent生态的连接器标准它让工具接入变得标准化是提升开发效率、促进生态繁荣的底层协议。对于开发者而言当下的学习路径应该是先深入理解RAG和Agent的核心原理与实现动手搭建一个可工作的原型。在工具多起来后再自然地去了解和应用MCP来规范你的工具层。后续可以深入的方向优化RAG尝试不同的嵌入模型、重排序技术、以及更复杂的检索策略如HyDE。强化Agent在LangGraph中实现更复杂的循环、子图、人工审核节点构建真正多步骤的工作流。接入真实工具将工具替换为真实的API调用如发送邮件、查询数据库、操作文件系统。引入MCP尝试将你的工具封装为MCP Server并在支持MCP的客户端中测试。前端交互为你的智能助手搭建一个简单的Web界面如用Gradio或Streamlit。本地部署大模型应用已不再是遥不可及的事情。它虽有门槛但每一步的坑都有迹可循。希望这篇结合了底层逻辑拆解和实战踩坑指南的文章能为你提供一个坚实的起点。建议收藏本文在搭建过程中遇到问题时回来对照排查。