AI Agent开发实战：从RAG到Langchain的完整落地指南

这类教程最怕的就是堆砌概念把一堆听起来高大上的词RAG、Agent、Langchain扔给你却不告诉你它们在实际项目里是怎么串起来的更不告诉你一个普通开发者从零开始到底该怎么走。我花了不少时间梳理了从2024年到2026年初这段时间里AI Agent开发领域真正沉淀下来的、能落地的实践路径。这篇文章不讲虚的就围绕一个核心目标让你能基于现有开源工具搭建一个能跑起来、能解决实际问题的AI Agent系统并且知道每一步为什么这么做以及出了问题该往哪看。特别说明一下这里的“双非”不是指学历而是指非顶尖实验室、非大厂核心团队的普通开发者或小团队。我们的资源有限不能盲目追新论文或烧钱的闭源大模型必须把每一分算力和时间都花在刀刃上。所以整个指南的基调是务实、可复现、优先选择成熟稳定的方案。下面我会按照一个真实项目的推进顺序把RAG、Agent、Langchain这些组件拆开揉碎了讲重点不是背概念而是搞清楚它们在一个系统里各自扮演什么角色以及如何组合。1. 先别急着学框架搞明白你要解决什么问题很多教程一上来就让你装Langchain跑Hello World但你很可能不知道为什么要用它。我们先退一步想清楚AI Agent到底是什么以及RAG和Agent是什么关系。1.1 AI Agent的核心感知、规划、执行、学习你可以把一个AI Agent想象成一个虚拟的、有一定自主能力的“员工”。给它一个目标比如“帮我分析这份财报”它不会只生成一段话就结束。它会感知理解你的指令和当前环境比如能访问哪些工具、数据库。规划拆解目标决定先做什么、后做什么比如先查公司历史数据再计算财务比率最后生成总结。执行调用具体的工具去完成任务调用搜索API、运行Python代码、查询数据库。学习可选根据结果调整后续行动。关键理解一个只会和你聊天的ChatBot不是Agent它只有“感知”和简单的“执行”生成文本。Agent必须有“规划”和调用外部工具“执行”的能力。1.2 RAG是Agent的“长期记忆”和“知识库”RAG检索增强生成解决的是大模型“知识截止”和“胡言乱语”的问题。它让模型在回答前先从你提供的知识库比如公司文档、产品手册里检索相关片段然后基于这些确凿的依据来生成答案。在Agent系统里RAG模块通常扮演一个“专用工具”的角色。当Agent规划发现需要查询特定知识时就会调用这个RAG工具。例如Agent接到任务“回答客户关于产品A的保修政策”它的规划可能是1) 调用RAG工具查询“产品A 保修”2) 将检索到的政策文本交给大模型3) 让大模型生成用户友好的回答。所以RAG和Agent不是二选一而是组合关系。RAG让Agent变得更专业、更可靠。1.3 Langchain/LangGraph是“胶水”和“调度中心”这是最容易混淆的地方。Langchain不是一个具体的AI模型而是一个框架。它帮你把大模型OpenAI、通义千问、DeepSeek等、各种工具搜索引擎、计算器、RAG系统、记忆模块等“零件”方便地组装在一起并定义它们之间协作的流程。Langchain更侧重于构建单一的、链式Chain的工作流。比如“用户提问 - 检索知识 - 生成回答”这样一个固定管道。它适合逻辑相对固定的场景。LangGraph是Langchain团队推出的用于构建有状态、可循环、可分支的复杂Agent。它用“图”的概念来定义Agent的行为节点是执行步骤或工具边是步骤之间的流转条件。这让Agent能处理“尝试方案A如果失败则换方案B”这类需要决策和循环的任务。对于入门和大多数应用Langchain就足够了。当你需要Agent能处理非常复杂的、多步骤的、有依赖关系的任务时再研究LangGraph。现在你明白了我们要搭建的系统大概是用Langchain作为框架把大模型、RAG工具、以及其他API工具组装成一个能自主规划并执行任务的AI Agent。2. 环境准备与核心工具选型走稳定路线别追新对于资源有限的我们稳定压倒一切。下面是我验证过、社区活跃、文档相对友好的组合。2.1 基础运行环境Python版本3.9或3.10。3.11也行但有些老版本库可能有兼容性问题3.9/3.10最稳妥。包管理强烈推荐用conda或venv创建独立的虚拟环境避免包冲突。代码编辑器VS Code装上Python和Jupyter插件。2.2 大模型选择API优先本地为辅核心原则初期开发和验证用云API考虑长期成本、数据隐私或离线需求再评估本地模型。云API推荐入门OpenAI GPT系列生态最好Langchain支持最完善效果稳定。缺点是可能需要处理网络问题且有使用成本。国内大厂API阿里云通义、百度文心、讯飞星火、智谱GLM。优势是网络延迟低符合数据合规要求。需要在Langchain中查找对应的集成包或自己封装。开源模型API服务像DeepSeek、Qwen也提供了API。成本可能更低。怎么选第一个项目建议先用OpenAI的GPT-3.5-turbo。它足够便宜且智能能让你快速验证整个Agent流程。别一上来就追求GPT-4。本地模型谨慎选择何时考虑数据极度敏感不能出域、长期调用量巨大、网络不稳定。挑战需要足够的GPU显存至少8GB推荐16GB需要处理模型加载、推理加速vLLM, Ollama、tokenizer对齐等一系列问题。入门选择可以先用Ollama在本地跑一个轻量模型如llama3.2:1b,qwen2.5:7b来体验流程但生产级部署复杂得多。行动建议在项目根目录创建一个.env文件存放你的API密钥用python-dotenv包来读取。这是安全最佳实践。# .env 文件内容 OPENAI_API_KEYsk-your-key-here2.3 Langchain安装与版本控制安装核心包即可。注意版本不同版本API差异可能很大。pip install langchain langchain-community langchain-openailangchain: 核心框架。langchain-community: 大量第三方工具和集成的集合。langchain-openai: OpenAI模型的官方集成。重要Langchain更新很快教程容易过时。以官方文档为准。如果看到教程里用from langchain.llms import OpenAI这种旧写法现在更推荐用from langchain_openai import ChatOpenAI。2.4 向量数据库与RAG核心件RAG的核心是把文本切成块 - 转换成向量嵌入 - 存到向量数据库 - 检索时查询相似向量。文本切分langchain-text-splitters。负责把长文档切成语义连贯的小段。嵌入模型把文本块转换成向量。同样分API和本地。APIOpenAIEmbeddings(text-embedding-3-small 性价比高)。langchain-openai包里包含。本地sentence-transformers库模型如all-MiniLM-L6-v2。效果不错免费但需要本地计算资源。向量数据库入门首选Chroma。轻量、无需外部服务、纯Python、和Langchain集成好。pip install chromadb2.5 其他可能用到的工具工具调用langchain.tools模块里有很多预设工具如搜索、计算。你也可以用tool装饰器自定义任何Python函数为工具。Agent执行器langchain.agents模块负责驱动Agent的规划-执行循环。记忆langchain.memory让Agent能记住对话历史。简单场景用ConversationBufferMemory。环境准备好了我们开始从最简单的环节搭建RAG知识库。3. 第一步构建一个稳定可用的RAG知识库RAG是Agent的基石这一步必须扎实。我们目标是把一份PDF产品手册变成一个可以被Agent查询的知识工具。3.1 文档加载与切分别小看这一步假设你的产品手册是product_manual.pdf。from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter # 1. 加载文档 loader PyPDFLoader(./product_manual.pdf) documents loader.load() # 2. 切分文档 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块大约500字符 chunk_overlap50, # 块之间重叠50字符避免语义被割裂 length_functionlen, separators[\n\n, \n, 。, , , ] # 中文环境可以调整分隔符 ) docs text_splitter.split_documents(documents) print(f原始文档被切分成 {len(docs)} 个块)关键参数解析chunk_size最重要。太小则信息碎片化检索可能丢失上下文太大则可能包含无关信息且嵌入效果下降。500-1000是通用起点需根据你的文档内容是技术文档还是小说调整。chunk_overlap防止一个句子或关键概念被切成两半。设置chunk_size的10%-20%。separators对于中文确保有句号、逗号等让切分更符合语言习惯。3.2 向量化与存储连接Chromafrom langchain_openai import OpenAIEmbeddings from langchain.vectorstores import Chroma # 使用OpenAI的嵌入模型需要API Key embeddings OpenAIEmbeddings(modeltext-embedding-3-small) # 将切分好的文档转换为向量并存入Chroma # persist_directory 指定向量数据库持久化到磁盘的路径 vectorstore Chroma.from_documents( documentsdocs, embeddingembeddings, persist_directory./chroma_db ) vectorstore.persist() # 显式保存到磁盘注意第一次运行会调用OpenAI嵌入API将每个文本块转换为向量会产生费用但很低。persist_directory会创建一个本地文件夹存储向量数据。下次启动可以直接加载无需重新嵌入。如果使用本地嵌入模型如sentence-transformers则无需API Key但速度取决于你的CPU/GPU。3.3 构建检索链完成RAG闭环现在我们可以测试这个知识库了。# 首先加载已持久化的向量数据库如果已经存在 vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) # 将其转换为一个检索器Retriever retriever vectorstore.as_retriever( search_typesimilarity, # 相似度搜索 search_kwargs{k: 3} # 返回最相似的3个文本块 ) # 测试检索 query 产品A的保修期是多久 relevant_docs retriever.invoke(query) # Langchain新版本推荐用 invoke for i, doc in enumerate(relevant_docs): print(f--- 相关片段 {i1} ---) print(doc.page_content[:200]) # 打印前200字符 print()如果这一步能返回与“保修期”相关的文本片段恭喜你RAG知识库的核心功能就完成了。它已经是一个可以独立使用的“知识查询工具”了。4. 第二步打造你的第一个AI Agent有了RAG工具我们现在用Langchain把它和LLM组装成一个能使用工具的Agent。4.1 定义工具让Agent有“手”和“脚”工具就是Agent可以调用的函数。我们先定义两个工具一个是我们刚建的RAG知识库查询工具另一个是一个简单的计算器工具。from langchain.tools import tool from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub # 工具1RAG知识库查询工具 tool def search_product_knowledge(query: str) - str: 当用户询问关于产品特性、规格、保修、价格等信息时使用此工具从产品知识库中查找答案。 # 使用上一节创建的检索器 relevant_docs retriever.invoke(query) if not relevant_docs: return 在知识库中未找到相关信息。 # 简单地将检索到的前3个片段内容拼接返回 return \n\n.join([doc.page_content for doc in relevant_docs[:3]]) # 工具2计算器工具示例 tool def calculator(expression: str) - str: 执行数学计算。输入一个数学表达式如 2 3 * 4返回计算结果。 try: # 警告使用eval有安全风险仅作演示。生产环境应用安全库如numexpr result eval(expression) return str(result) except Exception as e: return f计算错误{e} # 将工具放入列表 tools [search_product_knowledge, calculator]4.2 创建Agent赋予模型“大脑”和“规划”能力我们将使用经典的ReAct框架它让模型以“思考Reason- 行动Act”的循环来工作。# 1. 初始化大语言模型 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_key你的API密钥) # temperature0 使输出更确定适合工具调用 # 2. 从Langchain Hub拉取一个预设的ReAct提示词模板 # 这个模板会指导LLM如何格式化它的“思考”和“行动” prompt hub.pull(hwchase17/react) # 3. 使用工具和LLM创建Agent agent create_react_agent(llm, tools, prompt) # 4. 创建Agent执行器它负责运行Agent的循环 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设为True可以看到Agent的思考过程调试非常有用 handle_parsing_errorsTrue, # 当模型输出格式错误时尝试修复 max_iterations5, # 限制最大循环次数防止死循环 early_stopping_methodgenerate # 当模型认为最终答案已得出时停止 )4.3 运行与调试看Agent如何“思考”现在让我们问一个需要结合知识和计算的问题。question 产品A的原价是2999元现在有85折优惠请问优惠后价格是多少另外它的保修政策是怎样的 result agent_executor.invoke({input: question}) print(result[output])将verboseTrue后你会在控制台看到类似这样的输出 进入新的Agent执行链... 思考用户问了两个问题计算折扣价和查询保修政策。我需要先回答哪个问题没有明确顺序我可以先计算价格因为它是一个独立的计算任务然后再查询保修政策。 行动使用工具[calculator]计算折扣价。 行动输入2999 * 0.85 观察2549.15 思考我得到了折扣价2549.15元。现在需要查询产品A的保修政策。 行动使用工具[search_product_knowledge]查询保修政策。 行动输入产品A 保修政策 观察这里会输出从知识库检索到的关于保修的文本片段 思考我已经获得了价格和保修信息可以组织最终答案了。 最终答案产品A优惠后的价格为2549.15元。关于保修政策根据知识库...总结检索到的信息...这就是一个AI Agent在工作它自动规划了步骤先调用计算器再调用知识库最后综合信息生成回答。常见调试点工具描述不清tool装饰器下的函数文档字符串...非常重要LLM就是靠这个描述来决定是否以及何时调用这个工具。务必写清楚工具的用途和输入格式。模型不调用工具检查提示词prompt是否合适工具描述是否清晰或者尝试降低temperature。无限循环设置max_iterations如5-10次。如果Agent不停调用工具而不给出最终答案可能是工具返回的结果无法让它满足需要检查工具逻辑或提示词。5. 从Demo到应用落地必须考虑的工程化问题跑通一个Demo只是开始。要让这个Agent真正能用、敢用必须解决以下问题。5.1 记忆与多轮对话上面的Agent是“失忆”的每轮对话独立。要让它记住上下文需要在AgentExecutor中加入记忆。from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 修改Agent Executor的创建传入memory agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # ... 其他参数 ) # 调用时使用带记忆的输入 result agent_executor.invoke({input: question, chat_history: []})这样后续对话中chat_history会自动被管理Agent就能基于之前的对话进行回答。5.2 处理复杂任务与LangGraph当任务需要多个步骤且步骤之间有复杂的依赖或循环时基础的ReAct Agent可能不够用。例如“监控服务器日志如果发现错误A则执行重启服务如果发现错误B则发送告警邮件并等待10分钟再检查。” 这时就需要LangGraph来定义工作流。# 这是一个概念性示例展示LangGraph的思维 from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator # 1. 定义状态State class AgentState(TypedDict): problem: str analysis: str action_taken: list result: str # 2. 定义节点函数 def analyze_problem(state: AgentState): # 调用LLM分析问题 return {analysis: 分析结果...} def take_action_a(state: AgentState): # 执行操作A return {action_taken: state[action_taken] [A], result: A完成} def take_action_b(state: AgentState): # 执行操作B return {action_taken: state[action_taken] [B], result: B完成} # 3. 构建图 graph_builder StateGraph(AgentState) graph_builder.add_node(analyze, analyze_problem) graph_builder.add_node(action_a, take_action_a) graph_builder.add_node(action_b, take_action_b) # 4. 定义边流转逻辑 graph_builder.set_entry_point(analyze) # 根据分析结果决定下一步是action_a还是action_b def decide_next_step(state): if condition_a in state[analysis]: return action_a else: return action_b graph_builder.add_conditional_edges(analyze, decide_next_step) graph_builder.add_edge(action_a, END) graph_builder.add_edge(action_b, END) # 5. 编译并运行图 graph graph_builder.compile() final_state graph.invoke({problem: 初始问题})LangGraph让你能清晰地可视化和管理复杂的工作流适合构建企业级的自动化Agent。5.3 RAG的优化提升检索质量如果你的Agent经常检索不到正确答案问题可能出在RAG环节切分策略不佳调整chunk_size和chunk_overlap。对于结构化文档如Markdown可以使用MarkdownHeaderTextSplitter按标题切分。检索器配置search_kwargs{k: 5}多返回几个结果让LLM有更多上下文。search_typemmr使用最大边际相关性排序在保证相关性的同时增加多样性避免返回内容雷同的片段。重排序在初步检索后用一个更精细的模型或交叉编码器对结果进行重排序把最相关的排在最前。这能显著提升效果但会增加延迟和成本。元数据过滤在存储向量时为每个块添加元数据如来源文件、章节。检索时可以过滤例如“只在用户手册中搜索”。5.4 部署与监控Web接口用FastAPI或Flask将你的agent_executor包装成一个HTTP API。异步处理对于耗时任务使用langchain的异步接口或结合Celery等任务队列。日志记录详细记录每个用户请求、Agent的思考步骤、工具调用和结果。这是排查问题和优化性能的关键。成本监控如果使用付费API务必记录每次调用的token消耗设置预算警报。评估与测试构建一个测试集定期运行监控Agent回答的准确率和工具调用的成功率。6. 学习路径与求职建议如何从“会了”到“精通”如果你跟着做到了这里你已经有了一个可运行的AI Agent项目原型。但要达到“就业”或独立开发的程度还需要系统性地加深。6.1 技术深挖路线图巩固基础Python熟练特别是异步编程asyncio。Langchain核心概念Model I/O, Chains, Agents, Tools, Memory, Indexes (RAG)。读官方文档不要只看教程。深入RAG学习更先进的检索技术HyDE, RAG-Fusion, 父文档检索。实践不同的向量数据库Pinecone(云服务)Weaviate(开源)Qdrant(开源性能好)。了解重排序模型如bge-reranker。掌握高级Agent模式Plan-and-Execute先让一个“规划者”LLM制定详细计划再让一个“执行者”LLM按计划调用工具。适合复杂任务。Multi-Agent多个Agent协作如一个负责分析一个负责执行一个负责审核。研究CrewAI,AutoGen框架。Tool Learning如何让Agent更好地学习使用新工具了解Gorilla等项目。工程化与架构学习如何将Agent部署为微服务。了解LLM应用开发框架LangServe(Langchain官方部署工具)Dify(低代码平台)FastChat(本地模型服务)。关注LangGraph这是构建复杂、有状态工作流的未来方向。6.2 项目经验积累改造现有Demo不要满足于跑通。给你的客服Agent加上“查询物流信息”的工具给你的数据分析Agent加上“自动生成图表”的能力。从头构建一个完整项目例如“智能个人旅行规划Agent”。它需要1) RAG爬取旅行攻略 2) 工具查询天气API、机票比价API 3) 记忆记住用户的预算和偏好 4) 规划生成每日行程。参与开源项目在GitHub上找Langchain、CrewAI等相关项目阅读代码尝试提交Issue或PR。6.3 求职准备技能如何体现面试官不会只问你概念。准备好项目介绍用STAR法则描述你做的Agent项目。背景、任务、你采取的行动技术选型、如何解决RAG检索不准、如何设计Agent流程、结果准确率、效率提升。技术细节“你如何评估你的RAG系统效果”答构建测试集计算命中率、答案相关性“当Agent陷入死循环不返回答案时你怎么调试”答检查verbose日志看是工具返回无效导致重复调用还是提示词指令不清晰设置max_iterations和early_stopping“Langchain和LangGraph在你项目中分别解决了什么问题”“如何降低LLM API的调用成本和延迟”答缓存、对简单任务使用小模型、流式响应、优化提示词减少token对生态的了解能说出除了Langchain外还有哪些流行的Agent框架CrewAI, AutoGen以及它们的优缺点。这条路没有捷径。从把一个Demo跑通到能处理真实场景的复杂问题中间需要大量的调试、优化和学习。最有效的学习方法就是选定一个你感兴趣的具体问题然后用这里介绍的技术栈去解决它。每踩一个坑你对RAG、Agent和Langchain的理解就会深一层。