这次我们来看一个面向双非背景开发者、从零到一掌握 AI Agent 开发的系统性教程。这个教程的核心价值在于它没有停留在概念层面而是将 RAG、Agent、LangChain 三大技术栈与应用落地紧密结合提供了一套可执行、可验证的学习路径。对于希望快速入局并实现就业的开发者而言最关心的是学什么、怎么学、以及学完能做什么。本文将围绕这三个核心问题拆解这套教程的完整内容并提供一个从环境搭建到项目实战的实操指南。教程的核心特点是“全链路”和“重实战”。它覆盖了从基础概念、环境配置、核心组件RAG、Agent、LangChain开发到最终集成部署的完整流程。硬件门槛极低主要依赖 Python 开发环境和主流开源库对 GPU 没有强制要求普通笔记本电脑即可开始学习。本文将带你快速梳理知识脉络并通过一个具体的“智能文档问答助手”项目演示如何将 RAG 与 Agent 结合构建一个具备知识检索和推理能力的应用。1. 核心能力速览本教程所涵盖的技术栈与学习目标可以概括为下表能力项说明技术栈核心RAG (检索增强生成)、Agent (智能体)、LangChain (开发框架)学习目标从零掌握 AI Agent 开发全流程具备构建企业级应用的能力硬件门槛极低。主要依赖 CPU 和内存GPU 仅用于加速部分嵌入模型或大语言模型推理非必需。环境依赖Python 3.8 pip 包管理 主流操作系统Windows/macOS/Linux均可。启动方式本地命令行启动开发服务器或使用 Docker 容器化部署。接口能力支持构建 RESTful API 服务供前端或其他系统调用。批量任务支持对文档库进行批量嵌入处理构建知识库支持批量问答测试。适合场景个人技能提升、毕业设计、企业内部知识管理系统、智能客服原型、面试项目储备。就业导向教程内容直接对标初级 AI 应用开发工程师、Prompt Engineer、LLM 应用开发等岗位技能要求。2. 适用场景与使用边界这套教程适合哪些人又能解决什么问题适用人群在校学生尤其是双非院校缺乏顶尖项目背书需要通过扎实的、有完整闭环的项目来证明工程能力。传统后端/前端开发者希望转型或切入 AI 应用开发领域需要一套降低学习曲线的实践指南。产品经理与技术爱好者希望系统性理解 AI Agent 的构建原理以便更好地进行技术选型或产品设计。能解决的核心问题知识幻觉通过 RAG 技术让大模型基于准确的、实时的外部知识如公司文档、产品手册进行回答减少“胡言乱语”。复杂任务自动化通过 Agent 技术将复杂问题拆解为一系列可执行步骤如搜索、计算、写代码并自动协调工具完成。应用开发效率利用 LangChain 框架提供的标准化模块模型 I/O、记忆、链、代理快速搭建原型避免重复造轮子。使用边界与注意事项非替代性本教程教授的是应用层开发技能不涉及底层大模型的训练或微调。数据安全在构建企业级应用时务必注意敏感数据的处理。使用本地部署的嵌入模型和向量数据库是保障数据隐私的常见方案。成本控制调用商用大模型 API如 OpenAI GPT、通义千问会产生费用在开发测试阶段需注意用量或优先使用开源模型。效果依赖最终应用的效果高度依赖于知识库构建质量文档切分、嵌入模型选择、提示词工程以及任务规划逻辑的设计。3. 环境准备与前置条件在开始实战前需要准备好以下环境。这套配置是兼顾通用性和学习成本的推荐方案。操作系统Windows 10/11 macOS 或 Linux (Ubuntu 20.04)。本文示例以 Windows 为例其他系统命令类似。Python 环境推荐使用 Python 3.10这是一个在兼容性和新特性之间平衡较好的版本。务必确保python和pip命令可用。# 检查Python版本 python --version # 检查pip版本 pip --version代码编辑器/IDEVisual Studio Code (VSCode) 或 PyCharm。VSCode 轻量且插件丰富是入门首选。虚拟环境强烈推荐为每个项目创建独立的 Python 虚拟环境避免包冲突。# 创建虚拟环境 python -m venv venv_ai_agent # 激活虚拟环境 (Windows) venv_ai_agent\Scripts\activate # 激活虚拟环境 (macOS/Linux) source venv_ai_agent/bin/activate网络环境需要能访问 Python 官方包索引 PyPI 以下载依赖。如果需要使用海外大模型 API如 OpenAI需确保网络连通性。基础工具Git用于克隆示例代码、Curl 或 Postman用于测试 API。4. 安装部署与启动方式我们将通过一个具体的“智能文档问答助手”项目来贯穿整个学习过程。这个项目将展示 RAG 和 Agent 的结合。第一步获取项目基础代码你可以从教程提供的仓库克隆或自己初始化一个项目。# 假设教程提供了示例仓库 git clone 教程示例仓库地址 cd ai_agent_doc_qa # 或手动创建项目目录 mkdir ai_agent_doc_qa cd ai_agent_doc_qa第二步安装核心依赖创建requirements.txt文件包含以下核心库langchain0.1.0 langchain-community0.0.10 langchain-openai0.0.5 chromadb0.4.22 sentence-transformers2.2.2 fastapi0.104.1 uvicorn[standard]0.24.0 python-dotenv1.0.0 pypdf3.17.4 tiktoken0.5.2使用 pip 安装pip install -r requirements.txtlangchain核心框架。langchain-community社区第三方集成。langchain-openaiOpenAI 模型集成。chromadb轻量级本地向量数据库用于存储和检索文档嵌入。sentence-transformers用于生成文本嵌入向量的开源模型。fastapiuvicorn用于构建和运行 API 服务。python-dotenv管理环境变量如 API Key。pypdf解析 PDF 文档。tiktoken用于计算 Token 数量。第三步配置环境变量在项目根目录创建.env文件用于安全存储敏感信息。如果你使用 OpenAI 的模型需要填入你的 API Key。也可以配置为使用本地模型。# .env 文件 OPENAI_API_KEYsk-your-openai-api-key-here # 如果使用其他模型例如通义千问或本地模型可相应配置 # DASHSCOPE_API_KEYyour-dashscope-key # LOCAL_LLM_MODEL_PATH./models/your-model重要切勿将.env文件提交到 Git 仓库。请将其添加到.gitignore中。5. 功能测试与效果验证我们将分步构建并测试智能文档问答助手的核心功能。5.1 RAG 知识库构建与测试测试目的验证能否成功从本地 PDF 文档提取文本切分生成向量并存入向量数据库。操作步骤准备文档在项目下创建docs文件夹放入若干 PDF 文档作为知识库来源如产品说明书、技术白皮书。编写知识库构建脚本build_knowledge_base.pyimport os from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from dotenv import load_dotenv load_dotenv() # 加载环境变量 # 1. 加载文档 doc_path ./docs documents [] for file in os.listdir(doc_path): if file.endswith(.pdf): loader PyPDFLoader(os.path.join(doc_path, file)) documents.extend(loader.load()) print(f已加载 {len(documents)} 个文档片段) # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个片段约500字符 chunk_overlap50 # 片段间重叠50字符保持上下文 ) splits text_splitter.split_documents(documents) print(f分割为 {len(splits)} 个文本块) # 3. 创建嵌入模型使用本地模型无需API Key embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) # 4. 构建向量数据库并持久化 vectorstore Chroma.from_documents( documentssplits, embeddingembeddings, persist_directory./chroma_db # 向量数据库存储目录 ) vectorstore.persist() print(知识库构建完成已保存至 ./chroma_db)运行脚本python build_knowledge_base.py预期结果与判断成功运行无报错。控制台输出加载的文档数、分割后的文本块数。项目目录下生成chroma_db文件夹里面存储了向量数据。成功标准chroma_db文件夹非空且脚本正常结束。5.2 基础问答链测试测试目的验证基于已构建的知识库能否正确检索相关文档并生成答案。操作步骤编写问答脚本simple_qa.pyfrom langchain.chains import RetrievalQA from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() # 1. 加载本地向量数据库 embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) vectorstore Chroma( persist_directory./chroma_db, embedding_functionembeddings ) # 2. 初始化大语言模型 (此处使用 OpenAI GPT-3.5可替换为其他模型) llm ChatOpenAI( modelgpt-3.5-turbo, temperature0 # 温度设为0使输出更确定 ) # 3. 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将检索到的文档“塞”给模型 retrievervectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3个片段 ) # 4. 进行问答 while True: query input(\n请输入您的问题 (输入 quit 退出): ) if query.lower() quit: break result qa_chain.invoke({query: query}) print(f答案: {result[result]}) # 可以打印参考来源 # print(f参考文档: {result[source_documents]})运行脚本并测试python simple_qa.py输入一个与你放入docs文件夹的文档内容相关的问题。预期结果与判断模型能基于文档内容生成相关答案。答案不应是模型凭空编造的而应能在原文中找到依据。常见失败原因API Key 未正确设置检查.env文件和load_dotenv()。向量数据库路径错误确认./chroma_db目录存在且是上一步生成的。文档内容不相关问题超出知识库范围模型会依赖自身知识回答可能产生幻觉。5.3 智能体Agent任务规划测试测试目的验证 Agent 能否理解复杂问题并正确调用工具如计算器、搜索、以及我们刚建的 RAG 知识库来分步解决。操作步骤定义工具我们将把上一步的 RAG 问答链封装成一个工具。编写 Agent 脚本agent_with_rag.pyfrom langchain.agents import AgentExecutor, create_react_agent from langchain import hub from langchain.tools import Tool from langchain_openai import ChatOpenAI from dotenv import load_dotenv from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA import os load_dotenv() # 1. 重新初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 2. 将RAG问答链封装为工具 embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) vectorstore Chroma( persist_directory./chroma_db, embedding_functionembeddings ) rag_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 3}) ) def rag_qa(query: str) - str: 一个基于知识库回答问题的工具。输入是一个问题。 result rag_chain.invoke({query: query}) return result[result] rag_tool Tool( nameCompany_Knowledge_Base, funcrag_qa, description当问题涉及公司产品、政策或内部文档时使用此工具。输入是一个具体的问题。 ) # 3. 定义其他工具示例计算器 from langchain.tools import tool tool def calculator(expression: str) - str: 用于计算数学表达式。输入是一个字符串形式的数学表达式如 3 5 * 2。 try: # 警告使用eval有安全风险仅用于演示。生产环境应使用安全计算库。 result eval(expression) return str(result) except Exception as e: return f计算错误: {e} # 4. 创建工具列表 tools [rag_tool, calculator] # 5. 从LangChain Hub拉取一个ReAct风格的Agent提示词模板 prompt hub.pull(hwchase17/react) # 6. 创建Agent agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志观察Agent的思考过程 handle_parsing_errorsTrue # 处理解析错误 ) # 7. 运行Agent complex_query “我们公司产品A的最大用户数限制是多少如果我有150个用户是否超出了限制超出的话超出的比例是多少” result agent_executor.invoke({input: complex_query}) print(f\n最终答案: {result[output]})运行脚本并观察python agent_with_rag.py预期结果与判断Agent 会输出详细的思考过程verboseTrue例如Thought: 我需要先查询产品A的用户数限制。我应该使用 Company_Knowledge_Base 工具。Action: Company_Knowledge_BaseAction Input: 产品A的最大用户数限制是多少Observation: 根据产品手册产品A的最大用户数限制是100。Thought: 现在我知道限制是100。用户有150个超出了限制。我需要计算超出的数量和比例。我应该使用 calculator 工具。Action: calculatorAction Input: 150 - 100Observation: 50Thought: 现在计算超出比例(超出数量 / 限制) * 100%。Action: calculatorAction Input: (50 / 100) * 100Observation: 50.0...最终生成答案。成功标准Agent 能正确识别需要调用哪个工具按顺序执行并整合结果给出最终答案。常见失败提示词设计不佳导致 Agent 无法正确选择工具工具描述不清晰RAG 工具返回的信息不准确。6. 接口 API 与批量任务一个完整的应用需要提供 API 接口并可能处理批量任务。6.1 构建 FastAPI 接口服务目标将我们的智能问答 Agent 封装成 HTTP API。操作步骤创建 API 主文件app.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from agent_with_rag import agent_executor # 导入之前写好的Agent执行器 import uvicorn from dotenv import load_dotenv import os load_dotenv() app FastAPI(titleAI Agent 智能问答 API) class QueryRequest(BaseModel): question: str user_id: str | None None # 可扩展用于用户会话管理 class QueryResponse(BaseModel): answer: str success: bool error_message: str | None None app.post(/query, response_modelQueryResponse) async def query_knowledge_base(request: QueryRequest): 接收用户问题通过Agent获取答案 try: result agent_executor.invoke({input: request.question}) return QueryResponse( answerresult[output], successTrue ) except Exception as e: # 记录日志 print(f处理请求时出错: {e}) raise HTTPException( status_code500, detailf内部服务器错误: {str(e)} ) app.get(/health) async def health_check(): 健康检查端点 return {status: healthy} if __name__ __main__: uvicorn.run( app, host0.0.0.0, # 允许外部访问 port8000 )启动 API 服务python app.py服务将在http://127.0.0.1:8000启动。测试 API使用浏览器访问http://127.0.0.1:8000/docs会自动打开 Swagger UI 交互文档。在/query接口的 “Try it out” 部分输入 JSON 格式的请求体如{question: 产品A支持哪些操作系统}然后点击 Execute。观察返回的 JSON 响应确认answer字段包含正确结果success为true。也可以使用 curl 命令测试curl -X POST http://127.0.0.1:8000/query \ -H Content-Type: application/json \ -d {question: 产品A支持哪些操作系统}6.2 批量问答任务处理目标对一个问题列表进行批量问答并保存结果用于效果评估或数据标注。操作步骤创建批量处理脚本batch_qa.pyimport json import time from tqdm import tqdm # 进度条库需安装: pip install tqdm from agent_with_rag import agent_executor def batch_process(questions_file: str, output_file: str, delay: float 1.0): 批量处理问题列表。 :param questions_file: 包含问题列表的JSON文件路径。 :param output_file: 输出结果文件路径。 :param delay: 每次请求之间的延迟秒避免速率限制。 # 读取问题 with open(questions_file, r, encodingutf-8) as f: questions json.load(f) # 假设文件是JSON列表如 [问题1, 问题2] results [] for q in tqdm(questions, desc处理进度): try: answer agent_executor.invoke({input: q}) results.append({ question: q, answer: answer[output], status: success }) except Exception as e: results.append({ question: q, answer: None, error: str(e), status: failed }) time.sleep(delay) # 延迟避免对API造成压力 # 保存结果 with open(output_file, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) print(f批量处理完成结果已保存至 {output_file}) if __name__ __main__: # 示例创建一个questions.json文件内容为 [问题1, 问题2] batch_process(questions.json, batch_results.json, delay0.5)准备输入文件questions.json[ 产品A的最新版本号是多少, 如何重置产品B的管理员密码, 计算一下 25 * 4 18 等于多少, 我们公司的技术支持电话是什么 ]运行批量脚本python batch_qa.py验证输出查看生成的batch_results.json文件应包含每个问题的答案和处理状态。7. 资源占用与性能观察对于本地部署的 AI Agent 应用性能主要受以下因素影响嵌入模型推理使用sentence-transformers加载本地模型时首次运行会下载模型约几百MB推理过程会占用 CPU 和内存。对于小型模型如MiniLM-L12-v2内存占用通常在 1-2GB。向量数据库ChromaDB在内存中维护索引文档数量巨大时十万级以上内存占用会显著上升。对于学习和小型应用内存占用可忽略。大语言模型调用调用云端 API如 OpenAI性能取决于网络延迟和 API 的响应速度。主要资源消耗在本地是网络 I/O 和轻量的 JSON 解析。成本是主要考虑因素。本地部署大模型这是资源消耗的大头。需要根据模型参数量如 7B、13B、70B准备足够的 GPU 显存或 CPU 内存。例如量化后的 7B 模型可能需要 6-8GB GPU 显存才能在可接受的速度下运行。Agent 思考过程Agent 的 ReAct 模式会导致多次调用 LLM一次思考一次行动因此响应时间可能是简单问答链的 2-3 倍API 调用成本也相应增加。性能优化建议RAG 优化精心设计文本切分策略chunk_size和chunk_overlap选择合适的嵌入模型并优化检索器返回的数量 (k)。缓存对频繁出现的相同或相似查询结果进行缓存可以显著降低 LLM 调用次数和延迟。异步处理对于批量任务或高并发 API使用异步框架如 FastAPI 本身支持 async和异步的 LLM 调用库。本地模型量化如果必须本地部署 LLM优先使用 GPTQ、AWQ、GGUF 等量化格式的模型以大幅降低显存和内存需求。8. 常见问题与排查方法在开发过程中你可能会遇到以下典型问题问题现象可能原因排查方式解决方案导入 LangChain 模块失败版本不兼容或未安装pip list | grep langchain检查版本查看错误信息。使用requirements.txt锁定版本创建新的虚拟环境重装。运行脚本提示OPENAI_API_KEY缺失环境变量未正确加载检查.env文件是否存在、格式是否正确确认脚本中调用了load_dotenv()。确保.env文件在项目根目录且OPENAI_API_KEYsk-...书写正确。可临时在代码中os.environ[‘OPENAI_API_KEY’]‘key’测试。知识库检索结果不相关1. 文档切分不合理2. 嵌入模型不匹配3. 检索参数k不合适1. 检查文本切分后的片段是否完整。2. 尝试不同的嵌入模型。3. 调整search_kwargs{“k”: 3}中的k值。1. 调整chunk_size和chunk_overlap。2. 换用更强大的嵌入模型如bge-large-zh-v1.5。3. 增大k值以获取更多上下文或使用MMR搜索类型去重。Agent 陷入循环或选择错误工具1. 工具描述不清晰2. 提示词Prompt引导不力3. LLM 能力不足开启verboseTrue观察 Agent 的思考链。1. 完善工具的描述description明确其用途和输入格式。2. 定制或优化从 Hub 拉取的 Prompt。3. 换用更强大的 LLM如 GPT-4。API 服务启动失败端口被占用端口 8000 已被其他程序使用运行netstat -ano | findstr :8000(Windows) 或lsof -i:8000(macOS/Linux) 查看占用进程。在uvicorn.run中修改port参数为其他端口如8001。批量处理时速度慢或报错1. 请求频率过高触发限流2. 网络不稳定3. 个别问题导致 Agent 崩溃查看错误日志在批量脚本中加入更详细的异常捕获和重试机制。1. 增加请求间隔 (delay)。2. 实现指数退避重试逻辑。3. 将handle_parsing_errorsTrue等容错参数设置好。本地嵌入模型下载慢或失败网络连接 Hugging Face 问题检查网络观察下载进度。配置镜像源或手动下载模型文件到本地然后从本地路径加载。9. 最佳实践与使用建议遵循以下实践能让你的 AI Agent 项目更加稳健和可维护项目结构规范化将代码按功能模块拆分例如core/核心逻辑、tools/自定义工具、api/接口层、knowledge_base/向量库构建与管理。配置中心化所有可配置参数模型名称、API Base URL、向量库路径、端口号应集中在一个配置文件如config.yaml或settings.py中避免硬编码。日志记录使用 Python 的logging模块为应用添加日志记录信息、警告和错误便于调试和监控。输入验证与清理在 API 层对用户输入进行验证和清理防止 Prompt 注入攻击或非法输入导致系统异常。版本控制使用 Git 管理代码特别是requirements.txt和核心配置。为不同的实验创建分支。效果评估体系构建一个简单的评估集如questions.json和对应的标准答案answers.json定期运行批量测试脚本量化 Agent 回答的准确率指导迭代优化。合规与安全数据确保用于构建知识库的文档已获得使用授权。内容在最终答案返回前可考虑添加一层内容安全过滤。API生产环境部署时务必为 API 添加认证如 API Key和速率限制。10. 总结与下一步这套教程的核心价值在于提供了一个从理论到实践的完整地图。通过构建“智能文档问答助手”这个具体项目你不仅学会了如何串联 RAG、Agent 和 LangChain更重要的是掌握了 AI 应用开发的通用工作流需求分析 - 技术选型 - 环境搭建 - 模块开发 - 集成测试 - API 封装 - 部署上线。最值得尝试的下一步工具扩展为你的 Agent 添加更多实用工具如网络搜索使用 SerpAPI 或 Tavily、数据库查询、发送邮件等。记忆能力为 Agent 或对话链添加记忆功能使其能处理多轮对话记住之前的上下文。LangChain 提供了多种记忆后端。前端界面使用 Gradio 或 Streamlit 快速构建一个 Web 界面让非技术人员也能方便地使用你的 Agent。复杂 Agent 框架探索 LangGraph用它来构建具有复杂工作流、循环和状态管理的更强大 Agent。生产化部署学习使用 Docker 将整个应用容器化然后部署到云服务器如阿里云、腾讯云或 Kubernetes 集群。从“跑通Demo”到“解决真实问题”中间需要大量的调优和迭代。建议你以本项目为起点选择一个你感兴趣或工作中遇到的真实场景如智能客服、代码助手、数据分析报告生成用这套技术栈去尝试解决它。过程中遇到的每一个错误和性能瓶颈都是你深入理解这项技术的绝佳机会。 从零构建AI Agent：RAG与LangChain实战指南
这次我们来看一个面向双非背景开发者、从零到一掌握 AI Agent 开发的系统性教程。这个教程的核心价值在于它没有停留在概念层面而是将 RAG、Agent、LangChain 三大技术栈与应用落地紧密结合提供了一套可执行、可验证的学习路径。对于希望快速入局并实现就业的开发者而言最关心的是学什么、怎么学、以及学完能做什么。本文将围绕这三个核心问题拆解这套教程的完整内容并提供一个从环境搭建到项目实战的实操指南。教程的核心特点是“全链路”和“重实战”。它覆盖了从基础概念、环境配置、核心组件RAG、Agent、LangChain开发到最终集成部署的完整流程。硬件门槛极低主要依赖 Python 开发环境和主流开源库对 GPU 没有强制要求普通笔记本电脑即可开始学习。本文将带你快速梳理知识脉络并通过一个具体的“智能文档问答助手”项目演示如何将 RAG 与 Agent 结合构建一个具备知识检索和推理能力的应用。1. 核心能力速览本教程所涵盖的技术栈与学习目标可以概括为下表能力项说明技术栈核心RAG (检索增强生成)、Agent (智能体)、LangChain (开发框架)学习目标从零掌握 AI Agent 开发全流程具备构建企业级应用的能力硬件门槛极低。主要依赖 CPU 和内存GPU 仅用于加速部分嵌入模型或大语言模型推理非必需。环境依赖Python 3.8 pip 包管理 主流操作系统Windows/macOS/Linux均可。启动方式本地命令行启动开发服务器或使用 Docker 容器化部署。接口能力支持构建 RESTful API 服务供前端或其他系统调用。批量任务支持对文档库进行批量嵌入处理构建知识库支持批量问答测试。适合场景个人技能提升、毕业设计、企业内部知识管理系统、智能客服原型、面试项目储备。就业导向教程内容直接对标初级 AI 应用开发工程师、Prompt Engineer、LLM 应用开发等岗位技能要求。2. 适用场景与使用边界这套教程适合哪些人又能解决什么问题适用人群在校学生尤其是双非院校缺乏顶尖项目背书需要通过扎实的、有完整闭环的项目来证明工程能力。传统后端/前端开发者希望转型或切入 AI 应用开发领域需要一套降低学习曲线的实践指南。产品经理与技术爱好者希望系统性理解 AI Agent 的构建原理以便更好地进行技术选型或产品设计。能解决的核心问题知识幻觉通过 RAG 技术让大模型基于准确的、实时的外部知识如公司文档、产品手册进行回答减少“胡言乱语”。复杂任务自动化通过 Agent 技术将复杂问题拆解为一系列可执行步骤如搜索、计算、写代码并自动协调工具完成。应用开发效率利用 LangChain 框架提供的标准化模块模型 I/O、记忆、链、代理快速搭建原型避免重复造轮子。使用边界与注意事项非替代性本教程教授的是应用层开发技能不涉及底层大模型的训练或微调。数据安全在构建企业级应用时务必注意敏感数据的处理。使用本地部署的嵌入模型和向量数据库是保障数据隐私的常见方案。成本控制调用商用大模型 API如 OpenAI GPT、通义千问会产生费用在开发测试阶段需注意用量或优先使用开源模型。效果依赖最终应用的效果高度依赖于知识库构建质量文档切分、嵌入模型选择、提示词工程以及任务规划逻辑的设计。3. 环境准备与前置条件在开始实战前需要准备好以下环境。这套配置是兼顾通用性和学习成本的推荐方案。操作系统Windows 10/11 macOS 或 Linux (Ubuntu 20.04)。本文示例以 Windows 为例其他系统命令类似。Python 环境推荐使用 Python 3.10这是一个在兼容性和新特性之间平衡较好的版本。务必确保python和pip命令可用。# 检查Python版本 python --version # 检查pip版本 pip --version代码编辑器/IDEVisual Studio Code (VSCode) 或 PyCharm。VSCode 轻量且插件丰富是入门首选。虚拟环境强烈推荐为每个项目创建独立的 Python 虚拟环境避免包冲突。# 创建虚拟环境 python -m venv venv_ai_agent # 激活虚拟环境 (Windows) venv_ai_agent\Scripts\activate # 激活虚拟环境 (macOS/Linux) source venv_ai_agent/bin/activate网络环境需要能访问 Python 官方包索引 PyPI 以下载依赖。如果需要使用海外大模型 API如 OpenAI需确保网络连通性。基础工具Git用于克隆示例代码、Curl 或 Postman用于测试 API。4. 安装部署与启动方式我们将通过一个具体的“智能文档问答助手”项目来贯穿整个学习过程。这个项目将展示 RAG 和 Agent 的结合。第一步获取项目基础代码你可以从教程提供的仓库克隆或自己初始化一个项目。# 假设教程提供了示例仓库 git clone 教程示例仓库地址 cd ai_agent_doc_qa # 或手动创建项目目录 mkdir ai_agent_doc_qa cd ai_agent_doc_qa第二步安装核心依赖创建requirements.txt文件包含以下核心库langchain0.1.0 langchain-community0.0.10 langchain-openai0.0.5 chromadb0.4.22 sentence-transformers2.2.2 fastapi0.104.1 uvicorn[standard]0.24.0 python-dotenv1.0.0 pypdf3.17.4 tiktoken0.5.2使用 pip 安装pip install -r requirements.txtlangchain核心框架。langchain-community社区第三方集成。langchain-openaiOpenAI 模型集成。chromadb轻量级本地向量数据库用于存储和检索文档嵌入。sentence-transformers用于生成文本嵌入向量的开源模型。fastapiuvicorn用于构建和运行 API 服务。python-dotenv管理环境变量如 API Key。pypdf解析 PDF 文档。tiktoken用于计算 Token 数量。第三步配置环境变量在项目根目录创建.env文件用于安全存储敏感信息。如果你使用 OpenAI 的模型需要填入你的 API Key。也可以配置为使用本地模型。# .env 文件 OPENAI_API_KEYsk-your-openai-api-key-here # 如果使用其他模型例如通义千问或本地模型可相应配置 # DASHSCOPE_API_KEYyour-dashscope-key # LOCAL_LLM_MODEL_PATH./models/your-model重要切勿将.env文件提交到 Git 仓库。请将其添加到.gitignore中。5. 功能测试与效果验证我们将分步构建并测试智能文档问答助手的核心功能。5.1 RAG 知识库构建与测试测试目的验证能否成功从本地 PDF 文档提取文本切分生成向量并存入向量数据库。操作步骤准备文档在项目下创建docs文件夹放入若干 PDF 文档作为知识库来源如产品说明书、技术白皮书。编写知识库构建脚本build_knowledge_base.pyimport os from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from dotenv import load_dotenv load_dotenv() # 加载环境变量 # 1. 加载文档 doc_path ./docs documents [] for file in os.listdir(doc_path): if file.endswith(.pdf): loader PyPDFLoader(os.path.join(doc_path, file)) documents.extend(loader.load()) print(f已加载 {len(documents)} 个文档片段) # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个片段约500字符 chunk_overlap50 # 片段间重叠50字符保持上下文 ) splits text_splitter.split_documents(documents) print(f分割为 {len(splits)} 个文本块) # 3. 创建嵌入模型使用本地模型无需API Key embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) # 4. 构建向量数据库并持久化 vectorstore Chroma.from_documents( documentssplits, embeddingembeddings, persist_directory./chroma_db # 向量数据库存储目录 ) vectorstore.persist() print(知识库构建完成已保存至 ./chroma_db)运行脚本python build_knowledge_base.py预期结果与判断成功运行无报错。控制台输出加载的文档数、分割后的文本块数。项目目录下生成chroma_db文件夹里面存储了向量数据。成功标准chroma_db文件夹非空且脚本正常结束。5.2 基础问答链测试测试目的验证基于已构建的知识库能否正确检索相关文档并生成答案。操作步骤编写问答脚本simple_qa.pyfrom langchain.chains import RetrievalQA from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from langchain_openai import ChatOpenAI from dotenv import load_dotenv import os load_dotenv() # 1. 加载本地向量数据库 embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) vectorstore Chroma( persist_directory./chroma_db, embedding_functionembeddings ) # 2. 初始化大语言模型 (此处使用 OpenAI GPT-3.5可替换为其他模型) llm ChatOpenAI( modelgpt-3.5-turbo, temperature0 # 温度设为0使输出更确定 ) # 3. 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将检索到的文档“塞”给模型 retrievervectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3个片段 ) # 4. 进行问答 while True: query input(\n请输入您的问题 (输入 quit 退出): ) if query.lower() quit: break result qa_chain.invoke({query: query}) print(f答案: {result[result]}) # 可以打印参考来源 # print(f参考文档: {result[source_documents]})运行脚本并测试python simple_qa.py输入一个与你放入docs文件夹的文档内容相关的问题。预期结果与判断模型能基于文档内容生成相关答案。答案不应是模型凭空编造的而应能在原文中找到依据。常见失败原因API Key 未正确设置检查.env文件和load_dotenv()。向量数据库路径错误确认./chroma_db目录存在且是上一步生成的。文档内容不相关问题超出知识库范围模型会依赖自身知识回答可能产生幻觉。5.3 智能体Agent任务规划测试测试目的验证 Agent 能否理解复杂问题并正确调用工具如计算器、搜索、以及我们刚建的 RAG 知识库来分步解决。操作步骤定义工具我们将把上一步的 RAG 问答链封装成一个工具。编写 Agent 脚本agent_with_rag.pyfrom langchain.agents import AgentExecutor, create_react_agent from langchain import hub from langchain.tools import Tool from langchain_openai import ChatOpenAI from dotenv import load_dotenv from langchain_community.embeddings import HuggingFaceEmbeddings from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA import os load_dotenv() # 1. 重新初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 2. 将RAG问答链封装为工具 embeddings HuggingFaceEmbeddings( model_namesentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ) vectorstore Chroma( persist_directory./chroma_db, embedding_functionembeddings ) rag_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 3}) ) def rag_qa(query: str) - str: 一个基于知识库回答问题的工具。输入是一个问题。 result rag_chain.invoke({query: query}) return result[result] rag_tool Tool( nameCompany_Knowledge_Base, funcrag_qa, description当问题涉及公司产品、政策或内部文档时使用此工具。输入是一个具体的问题。 ) # 3. 定义其他工具示例计算器 from langchain.tools import tool tool def calculator(expression: str) - str: 用于计算数学表达式。输入是一个字符串形式的数学表达式如 3 5 * 2。 try: # 警告使用eval有安全风险仅用于演示。生产环境应使用安全计算库。 result eval(expression) return str(result) except Exception as e: return f计算错误: {e} # 4. 创建工具列表 tools [rag_tool, calculator] # 5. 从LangChain Hub拉取一个ReAct风格的Agent提示词模板 prompt hub.pull(hwchase17/react) # 6. 创建Agent agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志观察Agent的思考过程 handle_parsing_errorsTrue # 处理解析错误 ) # 7. 运行Agent complex_query “我们公司产品A的最大用户数限制是多少如果我有150个用户是否超出了限制超出的话超出的比例是多少” result agent_executor.invoke({input: complex_query}) print(f\n最终答案: {result[output]})运行脚本并观察python agent_with_rag.py预期结果与判断Agent 会输出详细的思考过程verboseTrue例如Thought: 我需要先查询产品A的用户数限制。我应该使用 Company_Knowledge_Base 工具。Action: Company_Knowledge_BaseAction Input: 产品A的最大用户数限制是多少Observation: 根据产品手册产品A的最大用户数限制是100。Thought: 现在我知道限制是100。用户有150个超出了限制。我需要计算超出的数量和比例。我应该使用 calculator 工具。Action: calculatorAction Input: 150 - 100Observation: 50Thought: 现在计算超出比例(超出数量 / 限制) * 100%。Action: calculatorAction Input: (50 / 100) * 100Observation: 50.0...最终生成答案。成功标准Agent 能正确识别需要调用哪个工具按顺序执行并整合结果给出最终答案。常见失败提示词设计不佳导致 Agent 无法正确选择工具工具描述不清晰RAG 工具返回的信息不准确。6. 接口 API 与批量任务一个完整的应用需要提供 API 接口并可能处理批量任务。6.1 构建 FastAPI 接口服务目标将我们的智能问答 Agent 封装成 HTTP API。操作步骤创建 API 主文件app.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from agent_with_rag import agent_executor # 导入之前写好的Agent执行器 import uvicorn from dotenv import load_dotenv import os load_dotenv() app FastAPI(titleAI Agent 智能问答 API) class QueryRequest(BaseModel): question: str user_id: str | None None # 可扩展用于用户会话管理 class QueryResponse(BaseModel): answer: str success: bool error_message: str | None None app.post(/query, response_modelQueryResponse) async def query_knowledge_base(request: QueryRequest): 接收用户问题通过Agent获取答案 try: result agent_executor.invoke({input: request.question}) return QueryResponse( answerresult[output], successTrue ) except Exception as e: # 记录日志 print(f处理请求时出错: {e}) raise HTTPException( status_code500, detailf内部服务器错误: {str(e)} ) app.get(/health) async def health_check(): 健康检查端点 return {status: healthy} if __name__ __main__: uvicorn.run( app, host0.0.0.0, # 允许外部访问 port8000 )启动 API 服务python app.py服务将在http://127.0.0.1:8000启动。测试 API使用浏览器访问http://127.0.0.1:8000/docs会自动打开 Swagger UI 交互文档。在/query接口的 “Try it out” 部分输入 JSON 格式的请求体如{question: 产品A支持哪些操作系统}然后点击 Execute。观察返回的 JSON 响应确认answer字段包含正确结果success为true。也可以使用 curl 命令测试curl -X POST http://127.0.0.1:8000/query \ -H Content-Type: application/json \ -d {question: 产品A支持哪些操作系统}6.2 批量问答任务处理目标对一个问题列表进行批量问答并保存结果用于效果评估或数据标注。操作步骤创建批量处理脚本batch_qa.pyimport json import time from tqdm import tqdm # 进度条库需安装: pip install tqdm from agent_with_rag import agent_executor def batch_process(questions_file: str, output_file: str, delay: float 1.0): 批量处理问题列表。 :param questions_file: 包含问题列表的JSON文件路径。 :param output_file: 输出结果文件路径。 :param delay: 每次请求之间的延迟秒避免速率限制。 # 读取问题 with open(questions_file, r, encodingutf-8) as f: questions json.load(f) # 假设文件是JSON列表如 [问题1, 问题2] results [] for q in tqdm(questions, desc处理进度): try: answer agent_executor.invoke({input: q}) results.append({ question: q, answer: answer[output], status: success }) except Exception as e: results.append({ question: q, answer: None, error: str(e), status: failed }) time.sleep(delay) # 延迟避免对API造成压力 # 保存结果 with open(output_file, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) print(f批量处理完成结果已保存至 {output_file}) if __name__ __main__: # 示例创建一个questions.json文件内容为 [问题1, 问题2] batch_process(questions.json, batch_results.json, delay0.5)准备输入文件questions.json[ 产品A的最新版本号是多少, 如何重置产品B的管理员密码, 计算一下 25 * 4 18 等于多少, 我们公司的技术支持电话是什么 ]运行批量脚本python batch_qa.py验证输出查看生成的batch_results.json文件应包含每个问题的答案和处理状态。7. 资源占用与性能观察对于本地部署的 AI Agent 应用性能主要受以下因素影响嵌入模型推理使用sentence-transformers加载本地模型时首次运行会下载模型约几百MB推理过程会占用 CPU 和内存。对于小型模型如MiniLM-L12-v2内存占用通常在 1-2GB。向量数据库ChromaDB在内存中维护索引文档数量巨大时十万级以上内存占用会显著上升。对于学习和小型应用内存占用可忽略。大语言模型调用调用云端 API如 OpenAI性能取决于网络延迟和 API 的响应速度。主要资源消耗在本地是网络 I/O 和轻量的 JSON 解析。成本是主要考虑因素。本地部署大模型这是资源消耗的大头。需要根据模型参数量如 7B、13B、70B准备足够的 GPU 显存或 CPU 内存。例如量化后的 7B 模型可能需要 6-8GB GPU 显存才能在可接受的速度下运行。Agent 思考过程Agent 的 ReAct 模式会导致多次调用 LLM一次思考一次行动因此响应时间可能是简单问答链的 2-3 倍API 调用成本也相应增加。性能优化建议RAG 优化精心设计文本切分策略chunk_size和chunk_overlap选择合适的嵌入模型并优化检索器返回的数量 (k)。缓存对频繁出现的相同或相似查询结果进行缓存可以显著降低 LLM 调用次数和延迟。异步处理对于批量任务或高并发 API使用异步框架如 FastAPI 本身支持 async和异步的 LLM 调用库。本地模型量化如果必须本地部署 LLM优先使用 GPTQ、AWQ、GGUF 等量化格式的模型以大幅降低显存和内存需求。8. 常见问题与排查方法在开发过程中你可能会遇到以下典型问题问题现象可能原因排查方式解决方案导入 LangChain 模块失败版本不兼容或未安装pip list | grep langchain检查版本查看错误信息。使用requirements.txt锁定版本创建新的虚拟环境重装。运行脚本提示OPENAI_API_KEY缺失环境变量未正确加载检查.env文件是否存在、格式是否正确确认脚本中调用了load_dotenv()。确保.env文件在项目根目录且OPENAI_API_KEYsk-...书写正确。可临时在代码中os.environ[‘OPENAI_API_KEY’]‘key’测试。知识库检索结果不相关1. 文档切分不合理2. 嵌入模型不匹配3. 检索参数k不合适1. 检查文本切分后的片段是否完整。2. 尝试不同的嵌入模型。3. 调整search_kwargs{“k”: 3}中的k值。1. 调整chunk_size和chunk_overlap。2. 换用更强大的嵌入模型如bge-large-zh-v1.5。3. 增大k值以获取更多上下文或使用MMR搜索类型去重。Agent 陷入循环或选择错误工具1. 工具描述不清晰2. 提示词Prompt引导不力3. LLM 能力不足开启verboseTrue观察 Agent 的思考链。1. 完善工具的描述description明确其用途和输入格式。2. 定制或优化从 Hub 拉取的 Prompt。3. 换用更强大的 LLM如 GPT-4。API 服务启动失败端口被占用端口 8000 已被其他程序使用运行netstat -ano | findstr :8000(Windows) 或lsof -i:8000(macOS/Linux) 查看占用进程。在uvicorn.run中修改port参数为其他端口如8001。批量处理时速度慢或报错1. 请求频率过高触发限流2. 网络不稳定3. 个别问题导致 Agent 崩溃查看错误日志在批量脚本中加入更详细的异常捕获和重试机制。1. 增加请求间隔 (delay)。2. 实现指数退避重试逻辑。3. 将handle_parsing_errorsTrue等容错参数设置好。本地嵌入模型下载慢或失败网络连接 Hugging Face 问题检查网络观察下载进度。配置镜像源或手动下载模型文件到本地然后从本地路径加载。9. 最佳实践与使用建议遵循以下实践能让你的 AI Agent 项目更加稳健和可维护项目结构规范化将代码按功能模块拆分例如core/核心逻辑、tools/自定义工具、api/接口层、knowledge_base/向量库构建与管理。配置中心化所有可配置参数模型名称、API Base URL、向量库路径、端口号应集中在一个配置文件如config.yaml或settings.py中避免硬编码。日志记录使用 Python 的logging模块为应用添加日志记录信息、警告和错误便于调试和监控。输入验证与清理在 API 层对用户输入进行验证和清理防止 Prompt 注入攻击或非法输入导致系统异常。版本控制使用 Git 管理代码特别是requirements.txt和核心配置。为不同的实验创建分支。效果评估体系构建一个简单的评估集如questions.json和对应的标准答案answers.json定期运行批量测试脚本量化 Agent 回答的准确率指导迭代优化。合规与安全数据确保用于构建知识库的文档已获得使用授权。内容在最终答案返回前可考虑添加一层内容安全过滤。API生产环境部署时务必为 API 添加认证如 API Key和速率限制。10. 总结与下一步这套教程的核心价值在于提供了一个从理论到实践的完整地图。通过构建“智能文档问答助手”这个具体项目你不仅学会了如何串联 RAG、Agent 和 LangChain更重要的是掌握了 AI 应用开发的通用工作流需求分析 - 技术选型 - 环境搭建 - 模块开发 - 集成测试 - API 封装 - 部署上线。最值得尝试的下一步工具扩展为你的 Agent 添加更多实用工具如网络搜索使用 SerpAPI 或 Tavily、数据库查询、发送邮件等。记忆能力为 Agent 或对话链添加记忆功能使其能处理多轮对话记住之前的上下文。LangChain 提供了多种记忆后端。前端界面使用 Gradio 或 Streamlit 快速构建一个 Web 界面让非技术人员也能方便地使用你的 Agent。复杂 Agent 框架探索 LangGraph用它来构建具有复杂工作流、循环和状态管理的更强大 Agent。生产化部署学习使用 Docker 将整个应用容器化然后部署到云服务器如阿里云、腾讯云或 Kubernetes 集群。从“跑通Demo”到“解决真实问题”中间需要大量的调优和迭代。建议你以本项目为起点选择一个你感兴趣或工作中遇到的真实场景如智能客服、代码助手、数据分析报告生成用这套技术栈去尝试解决它。过程中遇到的每一个错误和性能瓶颈都是你深入理解这项技术的绝佳机会。