如果你已经在网上看过大量 Agent 教程大概率处于两种状态之一要么觉得“什么都会一写就废”要么收藏夹里囤了几十个视频看完标题很兴奋等到动手时不知道先做哪个。这不是学习态度的问题而是 Agent 开发的路径比传统 Web 开发模糊得多。传统后端至少知道“Java 基础 → SSM → Spring Boot → 微服务”的大致方向Agent 开发却横跨大模型 API、提示词工程、向量检索、Agent 框架、工具调用、工作流编排、效果评测……每一块单拎出来都有深度放在一起很多人就不知道按什么顺序学、学到什么程度才算“会”。这篇文章想给你一个相对完整的解法从 Agent、RAG、Langchain 的核心概念讲起拆出一条从入门到进阶的学习路线再按初中高三个层级拆解 50 个实战项目并附上可直接复制的代码示例、运行验证方式、高频面试题和工程最佳实践。先给一个核心判断Agent 开发真正的分水岭不是你会不会调用大模型 API而是你能不能把一个业务问题拆解成“模型能力 工具调用 状态管理 评测验证”。本文所有内容都围绕这句话展开。1. Agent 开发到底在开发什么1.1 Agent 不是新职业是一个新技术栈很多人在问“Agent 开发做什么的”。从岗位定义看它确实还没有像后端、前端那样成熟但企业侧的需求已经非常明确客服机器人、知识库问答、运维告警处理、代码审查助手、数据分析报表、自动化测试生成、政务/企业知识库……这些都不再是传统规则引擎能搞定的东西而是需要大模型具备“理解问题、调用工具、执行步骤、给结果”的能力。所以“Agent 开发”更准确的理解是基于大模型构建自动化决策与执行系统。你写的代码不是“一个接口”而是一个会自己思考下一步做什么的智能体。1.2 很多人的学习误区我观察到的典型误区有三个。第一个是“只调 API不建系统”。跑通了一个 chat completion就认为自己会 Agent 开发了。实际上那只是“一次性问答”离 Agent 还差得远。第二个是“只跑 Demo不做评测”。很多教程教你搭一个 RAG 问答跑起来能回答问题就结束了。但真实项目里你需要回答“准确率多少”“为什么换一种分块策略效果更好”“召回 Top-K 应该取几”。没有评测的 RAG 项目面试官一问就露馅。第三个是“只跟视频不读框架源码”。视频教会你“怎么用”但不会告诉你“为什么这么设计”。等你遇到 LangChain 某次版本升级改了 API或者生产环境需要自己加一个工具节点就完全卡住了。1.3 什么样的读者适合读这篇文章如果你满足以下任意一条这篇文章就是为你准备的刚入门的 Python 开发者想进入 AI 应用方向但不清楚从哪起步。已经会调用大模型 API但想系统学习 RAG、Agent、Langchain把能力串起来。准备面试 AI 应用 / Agent 方向的岗位需要一个清晰的项目清单和复习重点。工作中遇到了知识库问答、自动化工单、智能助手类需求想找落地思路。2. 核心概念Agent、RAG、Langchain 到底是什么关系2.1 Agent从“问答机器”到“会动手的助手”传统方式下你给大模型一个 prompt它返回一段文本交互到此结束。你是不是“记得上一轮聊了什么”、是不是“能主动查数据、发消息、跑代码”全靠你在代码里写死的逻辑。Agent 则不同。它的核心是模型自己去判断“下一步要做什么”。以 ReActReasoning Acting模式为代表模型会经历“思考 → 行动 → 观察 → 再思考”的循环直到完成目标。举个例子。用户说“帮我检查一下 api-server 的状态如果没在运行就发告警。”传统代码你需要提前写好status check_server(api-server) if status ! running: send_alert(api-server is down)而 Agent 的方式是你只告诉它你有两个工具get_server_status和send_alert它会自己决定先调用哪个、根据返回结果判断是否继续调用下一个。遇到你没预料到的情况它也能根据模型能力做出合理选择。这就是 Agent 和普通 API 调用最大的区别控制权从开发者写死的 if-else转移给了模型的推理过程。2.2 RAG让大模型“读过你的文档”再回答RAGRetrieval-Augmented Generation检索增强生成要解决的是大模型的两个天然缺陷知识有截止日期以及不知道你的私有数据。传统问答里你直接问“根据公司内部的报销制度差旅费上限是多少”模型没读过这份制度只能瞎编。RAG 的做法是把文档切块、向量化存入向量数据库。用户提问时把问题向量化到库里检索最相关的片段。把“问题 相关片段”一起塞给大模型让它基于检索结果作答。这就是为什么dense vector search稠密向量检索在 RAG 中特别重要。它做的事是基于语义相似度召回内容而不是关键词匹配。你可以搜索“哪些差旅费可以报销”即便文档里写的是“交通、住宿、餐补”模型也能通过语义向量找到它们。2.3 Langchain / LangGraph把组件串起来的“胶水层”Langchain 本质是 LLM 应用开发的组件库。它不提供大模型也不提供向量库它提供的是标准化封装LLM 调用、Prompt 模板、输出解析、记忆、工具、检索器等。它的价值在于你不需要从零实现“LLM 客户端 Prompt 拼接 结果解析 会话记忆”这些样板代码同时可以比较方便地替换不同的模型、向量库、Embedding 服务。但经典的 LangChainChain是线性流程遇到“条件分支”“循环执行”“多 Agent 协作”“人工介入审批”这种复杂场景就很吃力。LangGraph 就是在这个背景下出现的。它把执行流程建模成“图”节点是函数或模型边是状态转移。复杂业务可以清晰地表达为状态机。从经验看两者并不冲突维度LangChainLangGraph定位组件库与编排框架状态化工作流框架适合场景简单链式调用、快速原型、RAG 基础链路多分支、循环、人工审批、多 Agent 协作核心抽象Chain、Agent、RetrieverStateGraph、Node、Edge、State学习曲线平缓资料多略陡需要理解状态流转典型用法对话框、文档问答、基础工具调用复杂 Agent、大模型工作流、生产级系统简单地说简单 Agent 用 LangChain 足够复杂流程优先 LangGraph。2.4 三者关系不是替代是互补Agent、RAG、Langchain 这三者经常被放在一起提但它们解决的不是同一个问题RAG 解决“模型不知道”的问题外部知识注入。Agent 解决“模型只能聊天”的问题让模型能调用工具、执行任务。Langchain / LangGraph 解决“怎么把这些能力工程化”的问题组件串联、状态管理、流程编排。RAG 是 Agent 的核心能力之一Agent 是 RAG 的决策大脑。近年很热门的 Agentic RAG 就是这个趋势不是每次提问都固定检索 Top-K而是让 Agent 判断“是否需要检索”“检索一次够不够”“用关键词还是向量检索”“要不要重写问题后再检索”。RAG 从“固定管线”进化成了“按需决策”这正是 Agent 加入后带来的变化。3. 从入门到高级的学习路线拆解3.1 初级从单点技能练起这个阶段的目标不是做出复杂的系统而是熟悉工具链。学习目标掌握 Python 基础至少会写函数、类、异常处理。熟悉 OpenAI 兼容接口的环境变量和基本调用方式。理解 Prompt 基础系统角色、上下文、few-shot 示例。掌握 LangChain 的核心组件ChatOpenAI、PromptTemplate、StrOutputParser。关键实践用 LangChain 写一个翻译工具。用 LangChain 实现带记忆的多轮聊天。掌握标准能不看教程独立写一个调用大模型、带 Prompt 模板和输出解析的小工具。3.2 中级把 RAG 和 Agent 组合起来这是绝大多数 Agent 开发者的主战场也是“能写进简历”的第一道门槛。学习目标掌握 RAG 完整流程文档加载、分块、Embedding、向量库、检索、生成。知道什么是dense vector searchEmbedding 和 Rerank 各自的职责。掌握工具调用用tool定义工具让 Agent 自动决定调用顺序。掌握 LangGraph 基础StateGraph、节点、边、状态流转。学会做 RAG 测评构建评测集统计检索命中和答案质量指标。关键实践做一个企业内部知识库问答系统。做一个能调用多个工具的运维助手或数据分析助手。掌握标准能独立完成一个 RAG Agent 的端到端项目并说清楚“哪个环节效果差、你是如何优化的”。3.3 高级多 Agent 协作与企业级落地高级阶段拼的不是“会更多 API”而是工程化能力。学习目标掌握 Agentic RAGAgent 自主决定检索策略。掌握 LangGraph 复杂状态机条件分支、循环、人工审核节点。了解常用多 Agent 框架LangGraph、CrewAI、AutoGen。掌握性能优化缓存、并发、流式输出、模型路由。理解安全边界工具权限最小化、操作审计、提示词注入防护。关键实践做一个带人工审批节点的企业工单 Agent。做一个评估体系完善的 RAG 平台。多个 Agent 协作完成任务比如负责人 Agent 拆分任务执行 Agent 调用不同工具。掌握标准能设计一个生产可用的 Agent 系统包括评测、日志、回滚、安全控制。3.4 不同阶段的时间规划参考以下时间仅供参考因人而异层级业余学习参考时间核心产出初级3 - 4 周能熟练调用 LLM API完成工具型小应用中级6 - 8 周完成 2 - 3 个 RAG / Agent 完整项目高级3 个月以上完成带评测、安全、多 Agent 协作的完整系统4. 50 个实战项目的结构化拆解“50 个实战项目”听起来很多但如果只是复制粘贴清单你做完也记不住。我更建议按“能力维度 × 业务场景”来拆把项目分成文档处理类、业务问答类、自动化执行类、多 Agent 协作类、企业级工程化类。每一类锻炼的核心能力不同。下面按初中高三个层级列出参考清单编号只为了让你对数量有概念实际做的时候可以按需选择。4.1 初级项目单能力训练编号 1 - 10这组项目不需要复杂的架构目的是让你把“LLM API Prompt 解析”练熟。文档摘要工具输入长文本输出结构化摘要。多语言翻译助手支持指定语气和术语表。关键词与实体提取从新闻或合同中抽取关键信息。代码注释生成器输入函数生成注释和使用示例。CSV 数据分析问答把 CSV 转成文本让模型回答问题。简单客服问答基于 Prompt 的规则问答不接外部数据。PDF 文档问答 v1把 PDF 转文本后直接塞进上下文。Prompt 优化助手让模型帮你改进 Prompt。文章分类器多标签文本分类。带记忆的聊天机器人用 LangChain 的会话记忆实现“记得上一轮”。4.2 中级项目组合能力训练编号 11 - 30这组项目是简历中的主力核心任务是学会 RAG 和 Agent 的组合。多文档 RAG 知识库支持多份文档统一检索。带 Rerank 的 RAG 问答先粗召回再精排。混合检索知识库BM25 关键词 dense vector search。企业 FAQ 机器人带兜底策略检索不到时明确回答“不知道”。NL2SQL Agent把自然语言问题转成 SQL 查询。工具调用 Agent查询服务状态 发送告警。长期记忆 Agent把用户偏好写入向量库下次对话可读取。网页爬取与摘要 Agent输入 URL自动抓取并总结。周报生成 Agent结合 Git 提交记录和日程生成周报。邮件分类与回复 Agent自动分类邮件并生成草稿。代码审查 Agent读取 PR diff输出问题清单和建议。会议纪要 Agent根据会议转写文本整理待办事项。多轮 RAG 对话支持追问和指代消解。工具库扩展 Agent给 Agent 增加天气、计算器、日期等工具。RAG 评测工具离线评测集统计检索命中率和答案准确率。文档解析 Pipeline统一处理 PDF / Word / Markdown / HTML。LangGraph 多步骤查询 Agent先查用户权限再查业务数据。RAG 对话纠错当检测到答案与检索片段矛盾时触发重新检索。提示词注入防护 Agent识别并阻隔外部输入的恶意指令。文档版本对比 Agent对比两版文档差异并生成变更说明。4.3 高级项目工程化与简历亮点编号 31 - 50这组项目体现的是架构设计、评测体系、安全控制和业务落地能力。Agentic RAG让 Agent 自主决定检索策略和次数。多 Agent 协作主管 Agent 拆分任务执行 Agent 分工完成。LangGraph 复杂流程加入人工审核节点实现半自动审批。企业工单系统Agent 自动分诊人工确认后执行。政务知识库落地参考 Dify 完成政务 RAG 知识库的实践思路对接内部文档权限体系。企业数据中台问答统一查询多个业务数据库。高并发 RAG 服务引入缓存、异步、批量入库优化响应时间。智能运维诊断 Agent读取监控指标定位故障并给出处置建议。自动化测试生成 Agent根据接口文档和代码生成测试用例。数据分析 Agent自动生成图表和业务结论。跨系统任务流 Agent串联 CRM、工单、通知系统。知识库自动更新与质量监控文档更新后自动增量入库。Embedding Rerank 专项调优对比不同组合的准确率变化。大模型应用安全评测覆盖提示词注入、越权访问、敏感信息泄露。RAG 自动回归评测平台每次代码改动自动跑评测集。多模型路由 Agent简单问题用便宜的小模型复杂问题用强模型。报表查询 Agent用户用自然语言查指标输出报表。长文本多跳推理 RAG问题需要结合多个片段才能得出答案。Agent 执行日志与可观测性记录每次调用的输入输出、耗时、token 数量。“零代码”Agent 配置平台简化版业务人员通过界面配置知识库和 Agent 行为。4.4 哪些项目真正值得写进简历这里给一个判断标准能写进简历的项目不是代码数量最多的项目而是你能讲清楚“业务问题、技术选型、优化过程、量化结果”的项目。推荐组合是 3 - 5 个一个从零到一的 RAG 知识库项目。这是基础项必须能独立讲清楚。一个工具调用 / Agent 自动化项目。体现你理解 Agent 不只是检索问答。一个 Agentic RAG 或多 Agent 协作项目。这是加分项能拉开差距。一个带评测和调优的项目。体现工程化意识这正是企业最看重的。5. 环境准备与基础依赖5.1 环境要求本文章节中的示例代码建议在以下环境运行Python 3.10 及以上。一个可用的 OpenAI 兼容的大模型 API密钥通过环境变量注入。建议使用虚拟环境避免污染全局 Python。如果你在公司内网或者需要使用国内合规的大模型服务只要它提供 OpenAI 兼容接口同样可以用下面的代码。不同服务商的差异主要是base_url和api_key代码结构不变。5.2 创建虚拟环境python -m venv .venv source .venv/bin/activate # Windows PowerShell 用户使用 # .venv\Scripts\activate5.3 安装依赖版本以你实际项目为准本节演示通用安装方式。pip install langchain0.1,1.0 \ langchain-openai \ langchain-community \ langgraph \ chromadb \ python-dotenv5.4 配置环境变量export OPENAI_API_KEY你的API密钥 # Windows PowerShell 用户使用 # $env:OPENAI_API_KEY你的API密钥生产环境中不要用这种方式应该通过密钥管理服务注入避免密钥进入代码仓库和日志。5.5 项目目录结构后续三个示例建议按以下结构组织agent-learning/ ├── rag_demo/ │ ├── docs/ │ │ └── knowledge_base.txt │ ├── rag_app.py │ └── .env ├── agent_demo/ │ ├── check_agent.py │ └── .env └── langgraph_demo/ ├── query_graph.py └── .env6. 核心代码实现与运行验证6.1 示例一最小可用的 RAG 问答# 文件路径rag_demo/docs/knowledge_base.txt 企业内部报销制度 1. 差旅费报销需要提供发票和行程单。 2. 住宿标准为一线城市每晚不超过800元其他城市不超过500元。 3. 餐饮补贴按天计算每天100元无需发票。 4. 报销申请需在出差结束后5个工作日内提交。# 文件路径rag_demo/rag_app.py import os from dotenv import load_dotenv from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain.chains import RetrievalQA load_dotenv() # 1. 加载本地文档 loader TextLoader(docs/knowledge_base.txt, encodingutf-8) documents loader.load() # 2. 文本分块 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) chunks text_splitter.split_documents(documents) # 3. 向量化并存入向量库 # 注意同一个 Embedding 模型在入库和检索时必须保持一致 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents( chunks, embeddings, persist_directory./chroma_db ) # 4. 构建检索问答链 llm ChatOpenAI(modelgpt-4o-mini, temperature0) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 3}) ) # 5. 提问并打印结果 question 一线城市差旅住宿标准是多少 answer qa_chain.invoke(question) print(answer[result])这段代码的关键点有三个第一同一 Embedding 模型必须保证一致。入库和检索阶段如果用了不同模型向量空间不对齐检索结果会完全不可用。这几乎是新手踩得最多的坑。第二分块策略直接影响效果。这里使用了 500 字符 50 字符重叠的常见配置。实际项目中要根据文档类型调整带章节结构的文档优先按标题分块表格类内容要单独处理。第三k3表示召回 3 个片段。k 不是越大越好因为塞进上下文的噪声也会变多。真实项目中通常先用 Rerank 把候选片段精排后再取前 3 - 5 个作为最终上下文。6.2 示例二带工具调用能力的 Agent这个示例演示 Agent 的核心能力根据用户问题自动决定调用哪些工具并根据工具返回结果继续决策。# 文件路径agent_demo/check_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.tools import tool from langchain_core.prompts import ChatPromptTemplate load_dotenv() tool def get_server_status(server_name: str) - str: 查询服务器运行状态入参为服务器名称。 # 实际项目中这里可以替换为监控系统 API status_map { api-server: running, worker-server: degraded, db-server: running, } return status_map.get(server_name, unknown) tool def send_alert(message: str) - str: 给值班人员发送告警消息。 # 实际项目中这里可以替换为短信、钉钉、飞书等通知服务 print(f[ALERT] {message}) return sent llm ChatOpenAI(modelgpt-4o-mini, temperature0) tools [get_server_status, send_alert] prompt ChatPromptTemplate.from_messages([ (system, 你是一名运维助手根据用户问题调用工具来查询信息并给出结论。), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, verboseTrue) result executor.invoke({ input: 请检查 api-server 的状态如果不在运行就发送告警 }) print(result[output])这里真正容易踩坑的地方是工具函数的 docstring 和质量直接决定模型是否会正确调用它。语言模型是通过函数名、参数名和 docstring 来理解工具的。如果你写“status_map 是内部数据、不要问为什么”模型可能会困惑。运行这段代码时agent 会先调用get_server_status(api-server)得到running后判断“不需要告警”最终返回类似“api-server 当前运行正常无需发送告警”的结果。6.3 示例三LangGraph 基础状态图这个示例展示了 LangGraph 最核心的思想State 在节点之间流转每个节点接收前一个节点的输出并返回更新后的状态。# 文件路径langgraph_demo/query_graph.py from typing import TypedDict from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage # 定义全局状态的数据结构 class QueryState(TypedDict): question: str answer: str def answer_node(state: QueryState): 生成回答节点读取 state 中的 question写入 answer。 llm ChatOpenAI(modelgpt-4o-mini, temperature0.3) msg llm.invoke([HumanMessage(contentstate[question])]) return {answer: msg.content} # 构建状态图 graph StateGraph(QueryState) graph.add_node(answer, answer_node) graph.set_entry_point(answer) graph.add_edge(answer, END) # 编译成可执行对象 app graph.compile() result app.invoke({question: LangGraph 和 LangChain 的区别是什么}) print(result[answer])LangGraph 的核心概念只需要理解四个State贯穿全流程的数据结构所有节点共享。Node一个函数接收 state返回部分更新。Edge定义节点之间的流转关系可以是顺序、分支或循环。compile / invoke把图编译为可执行对象输入初始 state得到最终 state。这个示例虽然简单但“图”这个抽象一旦建立你就能轻松加入条件分支、工具调用节点和人工审核节点。这也是为什么 LangGraph 在高级 Agent 项目中越来越受欢迎。6.4 三个示例的运行与验证方式分别进入对应目录执行cd rag_demo python rag_app.py预期输出根据 knowledge_base.txt 内容回答“一线城市差旅住宿标准是每晚不超过800元”。cd ../agent_demo python check_agent.py预期输出控制台中能看到 Agent 的思考与工具调用过程最终返回“api-server 当前运行正常无需发送告警”。cd ../langgraph_demo python query_graph.py预期输出一段对 LangGraph 和 LangChain 区别的说明文字。如果运行失败第一步检查的是.env是否配置正确以及模型名称是否替换为你账号可用的模型。7. 常见问题与排查思路问题现象可能原因排查方式解决方案RAG 回答与文档无关分块不合理召回片段不相关打印检索回来的 Top-K 内容肉眼检查调整 chunk_size增加 Rerank换混合检索检索结果为空向量库为空或 Embedding 模型不一致检查 chroma_db 目录是否存在、向量数量重新入库确保入库和检索用同一 EmbeddingAgent 不调用工具工具描述不清晰或模型不支持 Tool Calling打开 verbose 日志观察模型输出优化函数名和 docstring更换支持 Tool Calling 的模型工具被调用但报错参数类型不匹配查看工具函数内部异常增加参数校验返回友好错误信息LangChain 升级后代码报错API 变更如旧版initialize_agent被弃用查看 ImportError 和弃用警告改用新版 API锁定依赖版本API 限流或超时并发过高、配额不足查看 API 错误码和调用日志增加退避重试、缓存、请求队列这里有一个更经验的提醒排查 RAG 问题要先分清楚是“检索问题”还是“生成问题”。很多新人一看到答案不对就改 Prompt其实问题出在检索。正确做法是先打印检索结果确认召回的片段本身是否相关片段相关但答案不对是生成环节问题片段本身就不相关是检索环节问题。8. Agent 开发面试与简历建议8.1 面试官真正在考察什么Agent 方向面试不会只问“你会不会用 LangChain”。从常见的 RAG 面试题和 Agent 面试题来看考察点集中在三块概念理解、工程细节、场景设计。概念题考察你是否理解 Agent 的本质工程细节题考察你有没有真实做过项目场景题考察你能不能把技术用在具体业务中。8.2 高频面试题与回答要点下面这些问题是在 RAG 实践和 Agent 开发中经常被问到的给你一份自查清单什么是 Agent和普通 API 调用有什么区别Agent 由模型自主决定下一步动作核心是 ReAct 的“思考-行动-观察”循环。什么是 RAG和微调怎么选RAG 注入知识微调改变行为。私有知识、实时知识优先 RAG风格和格式要求优先微调。RAG 中的 dense vector search 是怎样的工作原理通过 Embedding 模型把文本映射为稠密向量用向量相似度召回语义相近的文本。为什么召回后还要 Rerank向量召回是粗排Rerank 用更精细的交叉编码器对候选片段精排能显著提高 Top-K 准确率。RAG 测评怎么做构建评测集离线统计检索命中率、MRR、答案忠实度、相关度、完整性在线做人工抽检和案例分析。什么是 Agentic RAG让 Agent 自主决定是否检索、检索几次、用哪种检索策略比固定管线更适合复杂问题。LangGraph 和 LangChain 的区别LangChain 是组件库LangGraph 是状态化工作流框架复杂流程用 LangGraph 更清晰。ReAct 是什么为什么有效ReAct 把推理和行动交替进行让模型在每一步都能反思观察结果减少一次性推理的错误累积。工具调用失败怎么办工具层做好参数校验和错误返回Agent 层捕获异常并让模型重新规划关键操作增加人工确认。如何控制 Agent 成本和延迟模型路由、缓存、限制最大迭代轮数、流式输出、批量处理。8.3 简历写法示例写简历项目时推荐使用“业务背景 → 技术方案 → 个人职责 → 量化结果”的结构。示例具体数字需换成你的真实结果项目名称企业内部知识库智能问答系统 项目描述基于 Langchain RAG 构建内部文档问答系统 支持多格式文档导入、向量检索、Rerank 精排、 答案引用溯源与离线评测集验证。 个人职责 - 独立设计文档解析 Pipeline覆盖 PDF / Word / Markdown - 对比多种分块策略确定标题优先 500 字符分块方案 - 搭建 Chroma 向量库实现 BM25 dense vector search 混合检索 - 引入 Rerank 精排解决专业术语精确匹配问题 - 构建 200 条离线评测集建立回归评测流程。 技术栈Python、Langchain、Chroma、LangGraph、Rerank 项目成果检索命中率提升约 15 个百分点答案引用可溯源 支持每日定时更新知识库。结尾可以补充一个你踩过的坑和解决方案比如“最初分块过大导致检索噪声高改为按标题切分后准确率明显提升”。这个过程往往比项目本身更能打动面试官。9. 最佳实践与工程建议9.1 RAG 工程优化清单RAG 项目能不能落地很大程度上取决于文档处理和检索细节而不只是“接个大模型”。文档加载与清洗的顺序是先判断格式再做内容提取最后清洗噪声。PDF 里的表格如果直接按纯文本读结构会丢优先转成 Markdown 或 HTML 再切块。分块策略上优先按结构分块再配合固定长度分块兜底。中文场景要留意字符数和 token 数的区别部分模型对 token 有限制。检索上只用 dense vector search 会遇到专业术语和精确匹配的问题。更稳的方案是混合检索BM25 关键词召回 向量召回再做结果融合和 Rerank 精排。9.2 Agent 安全边界必须重视Agent 一旦接入数据库、发送消息、执行业务操作安全边界就变成了第一优先级。最小权限原则Agent 调用的每个工具只授予完成该任务所需的最小权限不要给它一个能删库的账号。人工确认节点涉及删除、修改、发送消息、生产环境变更的操作在 LangGraph 中插入人工审批节点未确认前不执行。提示词注入防护不要盲信外部输入。用户上传的文档里可能包含恶意指令不能直接拼进系统 Prompt工具返回的内容要按“数据”处理不当作指令执行。操作日志与回滚记录 Agent 每次工具调用的输入输出保留操作前状态以便回滚。9.3 性能与成本控制Agent 每次推理都会消耗 token多轮工具调用更是如此。实际项目里我建议关注这几点给 Agent 设置最大迭代轮数防止进入死循环。相同或相似的问题做缓存。简单问题用便宜的小模型复杂问题用强模型路由处理。需要长回答时用流式输出提升用户体感。批量文档入库时用异步和批处理不要一条条串行调用。9.4 可观测性与日志体系没有日志的 Agent 项目在线上会遇到一个很尴尬的问题用户说答案不对你根本无法定位是哪一步出的问题。建议至少记录以下信息每次调用的输入输出、模型名称、token 用量、耗时、工具调用轨迹、错误信息、会话 ID。生产环境可以接入专门的 LLM 可观测平台或者自建一套日志表结构。9.5 团队协作与工程流程多人协作开发 Agent 项目时提示词和工具定义应该纳入代码评审而不是只存在于 Chat 调试框里。评测集像单元测试一样纳入版本管理每次修改后自动跑回归。业务指标发生变化时先看评测集再下结论。10. 总结这篇文章希望帮你解决一个核心问题Agent 开发到底应该按什么顺序学、做什么项目、练到什么程度。我把答案拆成了四个部分概念上理解 Agent、RAG、Langchain 的分工路线上按初级、中级、高级逐层递进项目上从单能力训练做到企业级工程化项目工程上把评测、安全、可观测性放到和功能开发同等重要的位置。读完这篇文章下一步建议你这样做把两个最小示例跑通RAG 问答和工具调用 Agent。用 LangGraph 重构其中一个示例加上条件分支。自己做一个完整项目比如企业知识库问答或运维助手。为这个项目建一个评测集记录优化前后指标变化。把这个项目和过程整理成简历上的一个真实故事。Agent 开发这个方向还远没有定型框架和工具都在快速迭代。真正能拉开差距的不是你会背多少概念而是你是否亲手踩过坑、做过评测、被生产环境毒打过。从一个小项目开始跑通远比收藏几十个教程更有价值。 Agent开发实战：从RAG到LangGraph的完整学习路线与50个项目案例
如果你已经在网上看过大量 Agent 教程大概率处于两种状态之一要么觉得“什么都会一写就废”要么收藏夹里囤了几十个视频看完标题很兴奋等到动手时不知道先做哪个。这不是学习态度的问题而是 Agent 开发的路径比传统 Web 开发模糊得多。传统后端至少知道“Java 基础 → SSM → Spring Boot → 微服务”的大致方向Agent 开发却横跨大模型 API、提示词工程、向量检索、Agent 框架、工具调用、工作流编排、效果评测……每一块单拎出来都有深度放在一起很多人就不知道按什么顺序学、学到什么程度才算“会”。这篇文章想给你一个相对完整的解法从 Agent、RAG、Langchain 的核心概念讲起拆出一条从入门到进阶的学习路线再按初中高三个层级拆解 50 个实战项目并附上可直接复制的代码示例、运行验证方式、高频面试题和工程最佳实践。先给一个核心判断Agent 开发真正的分水岭不是你会不会调用大模型 API而是你能不能把一个业务问题拆解成“模型能力 工具调用 状态管理 评测验证”。本文所有内容都围绕这句话展开。1. Agent 开发到底在开发什么1.1 Agent 不是新职业是一个新技术栈很多人在问“Agent 开发做什么的”。从岗位定义看它确实还没有像后端、前端那样成熟但企业侧的需求已经非常明确客服机器人、知识库问答、运维告警处理、代码审查助手、数据分析报表、自动化测试生成、政务/企业知识库……这些都不再是传统规则引擎能搞定的东西而是需要大模型具备“理解问题、调用工具、执行步骤、给结果”的能力。所以“Agent 开发”更准确的理解是基于大模型构建自动化决策与执行系统。你写的代码不是“一个接口”而是一个会自己思考下一步做什么的智能体。1.2 很多人的学习误区我观察到的典型误区有三个。第一个是“只调 API不建系统”。跑通了一个 chat completion就认为自己会 Agent 开发了。实际上那只是“一次性问答”离 Agent 还差得远。第二个是“只跑 Demo不做评测”。很多教程教你搭一个 RAG 问答跑起来能回答问题就结束了。但真实项目里你需要回答“准确率多少”“为什么换一种分块策略效果更好”“召回 Top-K 应该取几”。没有评测的 RAG 项目面试官一问就露馅。第三个是“只跟视频不读框架源码”。视频教会你“怎么用”但不会告诉你“为什么这么设计”。等你遇到 LangChain 某次版本升级改了 API或者生产环境需要自己加一个工具节点就完全卡住了。1.3 什么样的读者适合读这篇文章如果你满足以下任意一条这篇文章就是为你准备的刚入门的 Python 开发者想进入 AI 应用方向但不清楚从哪起步。已经会调用大模型 API但想系统学习 RAG、Agent、Langchain把能力串起来。准备面试 AI 应用 / Agent 方向的岗位需要一个清晰的项目清单和复习重点。工作中遇到了知识库问答、自动化工单、智能助手类需求想找落地思路。2. 核心概念Agent、RAG、Langchain 到底是什么关系2.1 Agent从“问答机器”到“会动手的助手”传统方式下你给大模型一个 prompt它返回一段文本交互到此结束。你是不是“记得上一轮聊了什么”、是不是“能主动查数据、发消息、跑代码”全靠你在代码里写死的逻辑。Agent 则不同。它的核心是模型自己去判断“下一步要做什么”。以 ReActReasoning Acting模式为代表模型会经历“思考 → 行动 → 观察 → 再思考”的循环直到完成目标。举个例子。用户说“帮我检查一下 api-server 的状态如果没在运行就发告警。”传统代码你需要提前写好status check_server(api-server) if status ! running: send_alert(api-server is down)而 Agent 的方式是你只告诉它你有两个工具get_server_status和send_alert它会自己决定先调用哪个、根据返回结果判断是否继续调用下一个。遇到你没预料到的情况它也能根据模型能力做出合理选择。这就是 Agent 和普通 API 调用最大的区别控制权从开发者写死的 if-else转移给了模型的推理过程。2.2 RAG让大模型“读过你的文档”再回答RAGRetrieval-Augmented Generation检索增强生成要解决的是大模型的两个天然缺陷知识有截止日期以及不知道你的私有数据。传统问答里你直接问“根据公司内部的报销制度差旅费上限是多少”模型没读过这份制度只能瞎编。RAG 的做法是把文档切块、向量化存入向量数据库。用户提问时把问题向量化到库里检索最相关的片段。把“问题 相关片段”一起塞给大模型让它基于检索结果作答。这就是为什么dense vector search稠密向量检索在 RAG 中特别重要。它做的事是基于语义相似度召回内容而不是关键词匹配。你可以搜索“哪些差旅费可以报销”即便文档里写的是“交通、住宿、餐补”模型也能通过语义向量找到它们。2.3 Langchain / LangGraph把组件串起来的“胶水层”Langchain 本质是 LLM 应用开发的组件库。它不提供大模型也不提供向量库它提供的是标准化封装LLM 调用、Prompt 模板、输出解析、记忆、工具、检索器等。它的价值在于你不需要从零实现“LLM 客户端 Prompt 拼接 结果解析 会话记忆”这些样板代码同时可以比较方便地替换不同的模型、向量库、Embedding 服务。但经典的 LangChainChain是线性流程遇到“条件分支”“循环执行”“多 Agent 协作”“人工介入审批”这种复杂场景就很吃力。LangGraph 就是在这个背景下出现的。它把执行流程建模成“图”节点是函数或模型边是状态转移。复杂业务可以清晰地表达为状态机。从经验看两者并不冲突维度LangChainLangGraph定位组件库与编排框架状态化工作流框架适合场景简单链式调用、快速原型、RAG 基础链路多分支、循环、人工审批、多 Agent 协作核心抽象Chain、Agent、RetrieverStateGraph、Node、Edge、State学习曲线平缓资料多略陡需要理解状态流转典型用法对话框、文档问答、基础工具调用复杂 Agent、大模型工作流、生产级系统简单地说简单 Agent 用 LangChain 足够复杂流程优先 LangGraph。2.4 三者关系不是替代是互补Agent、RAG、Langchain 这三者经常被放在一起提但它们解决的不是同一个问题RAG 解决“模型不知道”的问题外部知识注入。Agent 解决“模型只能聊天”的问题让模型能调用工具、执行任务。Langchain / LangGraph 解决“怎么把这些能力工程化”的问题组件串联、状态管理、流程编排。RAG 是 Agent 的核心能力之一Agent 是 RAG 的决策大脑。近年很热门的 Agentic RAG 就是这个趋势不是每次提问都固定检索 Top-K而是让 Agent 判断“是否需要检索”“检索一次够不够”“用关键词还是向量检索”“要不要重写问题后再检索”。RAG 从“固定管线”进化成了“按需决策”这正是 Agent 加入后带来的变化。3. 从入门到高级的学习路线拆解3.1 初级从单点技能练起这个阶段的目标不是做出复杂的系统而是熟悉工具链。学习目标掌握 Python 基础至少会写函数、类、异常处理。熟悉 OpenAI 兼容接口的环境变量和基本调用方式。理解 Prompt 基础系统角色、上下文、few-shot 示例。掌握 LangChain 的核心组件ChatOpenAI、PromptTemplate、StrOutputParser。关键实践用 LangChain 写一个翻译工具。用 LangChain 实现带记忆的多轮聊天。掌握标准能不看教程独立写一个调用大模型、带 Prompt 模板和输出解析的小工具。3.2 中级把 RAG 和 Agent 组合起来这是绝大多数 Agent 开发者的主战场也是“能写进简历”的第一道门槛。学习目标掌握 RAG 完整流程文档加载、分块、Embedding、向量库、检索、生成。知道什么是dense vector searchEmbedding 和 Rerank 各自的职责。掌握工具调用用tool定义工具让 Agent 自动决定调用顺序。掌握 LangGraph 基础StateGraph、节点、边、状态流转。学会做 RAG 测评构建评测集统计检索命中和答案质量指标。关键实践做一个企业内部知识库问答系统。做一个能调用多个工具的运维助手或数据分析助手。掌握标准能独立完成一个 RAG Agent 的端到端项目并说清楚“哪个环节效果差、你是如何优化的”。3.3 高级多 Agent 协作与企业级落地高级阶段拼的不是“会更多 API”而是工程化能力。学习目标掌握 Agentic RAGAgent 自主决定检索策略。掌握 LangGraph 复杂状态机条件分支、循环、人工审核节点。了解常用多 Agent 框架LangGraph、CrewAI、AutoGen。掌握性能优化缓存、并发、流式输出、模型路由。理解安全边界工具权限最小化、操作审计、提示词注入防护。关键实践做一个带人工审批节点的企业工单 Agent。做一个评估体系完善的 RAG 平台。多个 Agent 协作完成任务比如负责人 Agent 拆分任务执行 Agent 调用不同工具。掌握标准能设计一个生产可用的 Agent 系统包括评测、日志、回滚、安全控制。3.4 不同阶段的时间规划参考以下时间仅供参考因人而异层级业余学习参考时间核心产出初级3 - 4 周能熟练调用 LLM API完成工具型小应用中级6 - 8 周完成 2 - 3 个 RAG / Agent 完整项目高级3 个月以上完成带评测、安全、多 Agent 协作的完整系统4. 50 个实战项目的结构化拆解“50 个实战项目”听起来很多但如果只是复制粘贴清单你做完也记不住。我更建议按“能力维度 × 业务场景”来拆把项目分成文档处理类、业务问答类、自动化执行类、多 Agent 协作类、企业级工程化类。每一类锻炼的核心能力不同。下面按初中高三个层级列出参考清单编号只为了让你对数量有概念实际做的时候可以按需选择。4.1 初级项目单能力训练编号 1 - 10这组项目不需要复杂的架构目的是让你把“LLM API Prompt 解析”练熟。文档摘要工具输入长文本输出结构化摘要。多语言翻译助手支持指定语气和术语表。关键词与实体提取从新闻或合同中抽取关键信息。代码注释生成器输入函数生成注释和使用示例。CSV 数据分析问答把 CSV 转成文本让模型回答问题。简单客服问答基于 Prompt 的规则问答不接外部数据。PDF 文档问答 v1把 PDF 转文本后直接塞进上下文。Prompt 优化助手让模型帮你改进 Prompt。文章分类器多标签文本分类。带记忆的聊天机器人用 LangChain 的会话记忆实现“记得上一轮”。4.2 中级项目组合能力训练编号 11 - 30这组项目是简历中的主力核心任务是学会 RAG 和 Agent 的组合。多文档 RAG 知识库支持多份文档统一检索。带 Rerank 的 RAG 问答先粗召回再精排。混合检索知识库BM25 关键词 dense vector search。企业 FAQ 机器人带兜底策略检索不到时明确回答“不知道”。NL2SQL Agent把自然语言问题转成 SQL 查询。工具调用 Agent查询服务状态 发送告警。长期记忆 Agent把用户偏好写入向量库下次对话可读取。网页爬取与摘要 Agent输入 URL自动抓取并总结。周报生成 Agent结合 Git 提交记录和日程生成周报。邮件分类与回复 Agent自动分类邮件并生成草稿。代码审查 Agent读取 PR diff输出问题清单和建议。会议纪要 Agent根据会议转写文本整理待办事项。多轮 RAG 对话支持追问和指代消解。工具库扩展 Agent给 Agent 增加天气、计算器、日期等工具。RAG 评测工具离线评测集统计检索命中率和答案准确率。文档解析 Pipeline统一处理 PDF / Word / Markdown / HTML。LangGraph 多步骤查询 Agent先查用户权限再查业务数据。RAG 对话纠错当检测到答案与检索片段矛盾时触发重新检索。提示词注入防护 Agent识别并阻隔外部输入的恶意指令。文档版本对比 Agent对比两版文档差异并生成变更说明。4.3 高级项目工程化与简历亮点编号 31 - 50这组项目体现的是架构设计、评测体系、安全控制和业务落地能力。Agentic RAG让 Agent 自主决定检索策略和次数。多 Agent 协作主管 Agent 拆分任务执行 Agent 分工完成。LangGraph 复杂流程加入人工审核节点实现半自动审批。企业工单系统Agent 自动分诊人工确认后执行。政务知识库落地参考 Dify 完成政务 RAG 知识库的实践思路对接内部文档权限体系。企业数据中台问答统一查询多个业务数据库。高并发 RAG 服务引入缓存、异步、批量入库优化响应时间。智能运维诊断 Agent读取监控指标定位故障并给出处置建议。自动化测试生成 Agent根据接口文档和代码生成测试用例。数据分析 Agent自动生成图表和业务结论。跨系统任务流 Agent串联 CRM、工单、通知系统。知识库自动更新与质量监控文档更新后自动增量入库。Embedding Rerank 专项调优对比不同组合的准确率变化。大模型应用安全评测覆盖提示词注入、越权访问、敏感信息泄露。RAG 自动回归评测平台每次代码改动自动跑评测集。多模型路由 Agent简单问题用便宜的小模型复杂问题用强模型。报表查询 Agent用户用自然语言查指标输出报表。长文本多跳推理 RAG问题需要结合多个片段才能得出答案。Agent 执行日志与可观测性记录每次调用的输入输出、耗时、token 数量。“零代码”Agent 配置平台简化版业务人员通过界面配置知识库和 Agent 行为。4.4 哪些项目真正值得写进简历这里给一个判断标准能写进简历的项目不是代码数量最多的项目而是你能讲清楚“业务问题、技术选型、优化过程、量化结果”的项目。推荐组合是 3 - 5 个一个从零到一的 RAG 知识库项目。这是基础项必须能独立讲清楚。一个工具调用 / Agent 自动化项目。体现你理解 Agent 不只是检索问答。一个 Agentic RAG 或多 Agent 协作项目。这是加分项能拉开差距。一个带评测和调优的项目。体现工程化意识这正是企业最看重的。5. 环境准备与基础依赖5.1 环境要求本文章节中的示例代码建议在以下环境运行Python 3.10 及以上。一个可用的 OpenAI 兼容的大模型 API密钥通过环境变量注入。建议使用虚拟环境避免污染全局 Python。如果你在公司内网或者需要使用国内合规的大模型服务只要它提供 OpenAI 兼容接口同样可以用下面的代码。不同服务商的差异主要是base_url和api_key代码结构不变。5.2 创建虚拟环境python -m venv .venv source .venv/bin/activate # Windows PowerShell 用户使用 # .venv\Scripts\activate5.3 安装依赖版本以你实际项目为准本节演示通用安装方式。pip install langchain0.1,1.0 \ langchain-openai \ langchain-community \ langgraph \ chromadb \ python-dotenv5.4 配置环境变量export OPENAI_API_KEY你的API密钥 # Windows PowerShell 用户使用 # $env:OPENAI_API_KEY你的API密钥生产环境中不要用这种方式应该通过密钥管理服务注入避免密钥进入代码仓库和日志。5.5 项目目录结构后续三个示例建议按以下结构组织agent-learning/ ├── rag_demo/ │ ├── docs/ │ │ └── knowledge_base.txt │ ├── rag_app.py │ └── .env ├── agent_demo/ │ ├── check_agent.py │ └── .env └── langgraph_demo/ ├── query_graph.py └── .env6. 核心代码实现与运行验证6.1 示例一最小可用的 RAG 问答# 文件路径rag_demo/docs/knowledge_base.txt 企业内部报销制度 1. 差旅费报销需要提供发票和行程单。 2. 住宿标准为一线城市每晚不超过800元其他城市不超过500元。 3. 餐饮补贴按天计算每天100元无需发票。 4. 报销申请需在出差结束后5个工作日内提交。# 文件路径rag_demo/rag_app.py import os from dotenv import load_dotenv from langchain_community.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain.chains import RetrievalQA load_dotenv() # 1. 加载本地文档 loader TextLoader(docs/knowledge_base.txt, encodingutf-8) documents loader.load() # 2. 文本分块 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) chunks text_splitter.split_documents(documents) # 3. 向量化并存入向量库 # 注意同一个 Embedding 模型在入库和检索时必须保持一致 embeddings OpenAIEmbeddings() vectorstore Chroma.from_documents( chunks, embeddings, persist_directory./chroma_db ) # 4. 构建检索问答链 llm ChatOpenAI(modelgpt-4o-mini, temperature0) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 3}) ) # 5. 提问并打印结果 question 一线城市差旅住宿标准是多少 answer qa_chain.invoke(question) print(answer[result])这段代码的关键点有三个第一同一 Embedding 模型必须保证一致。入库和检索阶段如果用了不同模型向量空间不对齐检索结果会完全不可用。这几乎是新手踩得最多的坑。第二分块策略直接影响效果。这里使用了 500 字符 50 字符重叠的常见配置。实际项目中要根据文档类型调整带章节结构的文档优先按标题分块表格类内容要单独处理。第三k3表示召回 3 个片段。k 不是越大越好因为塞进上下文的噪声也会变多。真实项目中通常先用 Rerank 把候选片段精排后再取前 3 - 5 个作为最终上下文。6.2 示例二带工具调用能力的 Agent这个示例演示 Agent 的核心能力根据用户问题自动决定调用哪些工具并根据工具返回结果继续决策。# 文件路径agent_demo/check_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.tools import tool from langchain_core.prompts import ChatPromptTemplate load_dotenv() tool def get_server_status(server_name: str) - str: 查询服务器运行状态入参为服务器名称。 # 实际项目中这里可以替换为监控系统 API status_map { api-server: running, worker-server: degraded, db-server: running, } return status_map.get(server_name, unknown) tool def send_alert(message: str) - str: 给值班人员发送告警消息。 # 实际项目中这里可以替换为短信、钉钉、飞书等通知服务 print(f[ALERT] {message}) return sent llm ChatOpenAI(modelgpt-4o-mini, temperature0) tools [get_server_status, send_alert] prompt ChatPromptTemplate.from_messages([ (system, 你是一名运维助手根据用户问题调用工具来查询信息并给出结论。), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) executor AgentExecutor(agentagent, toolstools, verboseTrue) result executor.invoke({ input: 请检查 api-server 的状态如果不在运行就发送告警 }) print(result[output])这里真正容易踩坑的地方是工具函数的 docstring 和质量直接决定模型是否会正确调用它。语言模型是通过函数名、参数名和 docstring 来理解工具的。如果你写“status_map 是内部数据、不要问为什么”模型可能会困惑。运行这段代码时agent 会先调用get_server_status(api-server)得到running后判断“不需要告警”最终返回类似“api-server 当前运行正常无需发送告警”的结果。6.3 示例三LangGraph 基础状态图这个示例展示了 LangGraph 最核心的思想State 在节点之间流转每个节点接收前一个节点的输出并返回更新后的状态。# 文件路径langgraph_demo/query_graph.py from typing import TypedDict from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage # 定义全局状态的数据结构 class QueryState(TypedDict): question: str answer: str def answer_node(state: QueryState): 生成回答节点读取 state 中的 question写入 answer。 llm ChatOpenAI(modelgpt-4o-mini, temperature0.3) msg llm.invoke([HumanMessage(contentstate[question])]) return {answer: msg.content} # 构建状态图 graph StateGraph(QueryState) graph.add_node(answer, answer_node) graph.set_entry_point(answer) graph.add_edge(answer, END) # 编译成可执行对象 app graph.compile() result app.invoke({question: LangGraph 和 LangChain 的区别是什么}) print(result[answer])LangGraph 的核心概念只需要理解四个State贯穿全流程的数据结构所有节点共享。Node一个函数接收 state返回部分更新。Edge定义节点之间的流转关系可以是顺序、分支或循环。compile / invoke把图编译为可执行对象输入初始 state得到最终 state。这个示例虽然简单但“图”这个抽象一旦建立你就能轻松加入条件分支、工具调用节点和人工审核节点。这也是为什么 LangGraph 在高级 Agent 项目中越来越受欢迎。6.4 三个示例的运行与验证方式分别进入对应目录执行cd rag_demo python rag_app.py预期输出根据 knowledge_base.txt 内容回答“一线城市差旅住宿标准是每晚不超过800元”。cd ../agent_demo python check_agent.py预期输出控制台中能看到 Agent 的思考与工具调用过程最终返回“api-server 当前运行正常无需发送告警”。cd ../langgraph_demo python query_graph.py预期输出一段对 LangGraph 和 LangChain 区别的说明文字。如果运行失败第一步检查的是.env是否配置正确以及模型名称是否替换为你账号可用的模型。7. 常见问题与排查思路问题现象可能原因排查方式解决方案RAG 回答与文档无关分块不合理召回片段不相关打印检索回来的 Top-K 内容肉眼检查调整 chunk_size增加 Rerank换混合检索检索结果为空向量库为空或 Embedding 模型不一致检查 chroma_db 目录是否存在、向量数量重新入库确保入库和检索用同一 EmbeddingAgent 不调用工具工具描述不清晰或模型不支持 Tool Calling打开 verbose 日志观察模型输出优化函数名和 docstring更换支持 Tool Calling 的模型工具被调用但报错参数类型不匹配查看工具函数内部异常增加参数校验返回友好错误信息LangChain 升级后代码报错API 变更如旧版initialize_agent被弃用查看 ImportError 和弃用警告改用新版 API锁定依赖版本API 限流或超时并发过高、配额不足查看 API 错误码和调用日志增加退避重试、缓存、请求队列这里有一个更经验的提醒排查 RAG 问题要先分清楚是“检索问题”还是“生成问题”。很多新人一看到答案不对就改 Prompt其实问题出在检索。正确做法是先打印检索结果确认召回的片段本身是否相关片段相关但答案不对是生成环节问题片段本身就不相关是检索环节问题。8. Agent 开发面试与简历建议8.1 面试官真正在考察什么Agent 方向面试不会只问“你会不会用 LangChain”。从常见的 RAG 面试题和 Agent 面试题来看考察点集中在三块概念理解、工程细节、场景设计。概念题考察你是否理解 Agent 的本质工程细节题考察你有没有真实做过项目场景题考察你能不能把技术用在具体业务中。8.2 高频面试题与回答要点下面这些问题是在 RAG 实践和 Agent 开发中经常被问到的给你一份自查清单什么是 Agent和普通 API 调用有什么区别Agent 由模型自主决定下一步动作核心是 ReAct 的“思考-行动-观察”循环。什么是 RAG和微调怎么选RAG 注入知识微调改变行为。私有知识、实时知识优先 RAG风格和格式要求优先微调。RAG 中的 dense vector search 是怎样的工作原理通过 Embedding 模型把文本映射为稠密向量用向量相似度召回语义相近的文本。为什么召回后还要 Rerank向量召回是粗排Rerank 用更精细的交叉编码器对候选片段精排能显著提高 Top-K 准确率。RAG 测评怎么做构建评测集离线统计检索命中率、MRR、答案忠实度、相关度、完整性在线做人工抽检和案例分析。什么是 Agentic RAG让 Agent 自主决定是否检索、检索几次、用哪种检索策略比固定管线更适合复杂问题。LangGraph 和 LangChain 的区别LangChain 是组件库LangGraph 是状态化工作流框架复杂流程用 LangGraph 更清晰。ReAct 是什么为什么有效ReAct 把推理和行动交替进行让模型在每一步都能反思观察结果减少一次性推理的错误累积。工具调用失败怎么办工具层做好参数校验和错误返回Agent 层捕获异常并让模型重新规划关键操作增加人工确认。如何控制 Agent 成本和延迟模型路由、缓存、限制最大迭代轮数、流式输出、批量处理。8.3 简历写法示例写简历项目时推荐使用“业务背景 → 技术方案 → 个人职责 → 量化结果”的结构。示例具体数字需换成你的真实结果项目名称企业内部知识库智能问答系统 项目描述基于 Langchain RAG 构建内部文档问答系统 支持多格式文档导入、向量检索、Rerank 精排、 答案引用溯源与离线评测集验证。 个人职责 - 独立设计文档解析 Pipeline覆盖 PDF / Word / Markdown - 对比多种分块策略确定标题优先 500 字符分块方案 - 搭建 Chroma 向量库实现 BM25 dense vector search 混合检索 - 引入 Rerank 精排解决专业术语精确匹配问题 - 构建 200 条离线评测集建立回归评测流程。 技术栈Python、Langchain、Chroma、LangGraph、Rerank 项目成果检索命中率提升约 15 个百分点答案引用可溯源 支持每日定时更新知识库。结尾可以补充一个你踩过的坑和解决方案比如“最初分块过大导致检索噪声高改为按标题切分后准确率明显提升”。这个过程往往比项目本身更能打动面试官。9. 最佳实践与工程建议9.1 RAG 工程优化清单RAG 项目能不能落地很大程度上取决于文档处理和检索细节而不只是“接个大模型”。文档加载与清洗的顺序是先判断格式再做内容提取最后清洗噪声。PDF 里的表格如果直接按纯文本读结构会丢优先转成 Markdown 或 HTML 再切块。分块策略上优先按结构分块再配合固定长度分块兜底。中文场景要留意字符数和 token 数的区别部分模型对 token 有限制。检索上只用 dense vector search 会遇到专业术语和精确匹配的问题。更稳的方案是混合检索BM25 关键词召回 向量召回再做结果融合和 Rerank 精排。9.2 Agent 安全边界必须重视Agent 一旦接入数据库、发送消息、执行业务操作安全边界就变成了第一优先级。最小权限原则Agent 调用的每个工具只授予完成该任务所需的最小权限不要给它一个能删库的账号。人工确认节点涉及删除、修改、发送消息、生产环境变更的操作在 LangGraph 中插入人工审批节点未确认前不执行。提示词注入防护不要盲信外部输入。用户上传的文档里可能包含恶意指令不能直接拼进系统 Prompt工具返回的内容要按“数据”处理不当作指令执行。操作日志与回滚记录 Agent 每次工具调用的输入输出保留操作前状态以便回滚。9.3 性能与成本控制Agent 每次推理都会消耗 token多轮工具调用更是如此。实际项目里我建议关注这几点给 Agent 设置最大迭代轮数防止进入死循环。相同或相似的问题做缓存。简单问题用便宜的小模型复杂问题用强模型路由处理。需要长回答时用流式输出提升用户体感。批量文档入库时用异步和批处理不要一条条串行调用。9.4 可观测性与日志体系没有日志的 Agent 项目在线上会遇到一个很尴尬的问题用户说答案不对你根本无法定位是哪一步出的问题。建议至少记录以下信息每次调用的输入输出、模型名称、token 用量、耗时、工具调用轨迹、错误信息、会话 ID。生产环境可以接入专门的 LLM 可观测平台或者自建一套日志表结构。9.5 团队协作与工程流程多人协作开发 Agent 项目时提示词和工具定义应该纳入代码评审而不是只存在于 Chat 调试框里。评测集像单元测试一样纳入版本管理每次修改后自动跑回归。业务指标发生变化时先看评测集再下结论。10. 总结这篇文章希望帮你解决一个核心问题Agent 开发到底应该按什么顺序学、做什么项目、练到什么程度。我把答案拆成了四个部分概念上理解 Agent、RAG、Langchain 的分工路线上按初级、中级、高级逐层递进项目上从单能力训练做到企业级工程化项目工程上把评测、安全、可观测性放到和功能开发同等重要的位置。读完这篇文章下一步建议你这样做把两个最小示例跑通RAG 问答和工具调用 Agent。用 LangGraph 重构其中一个示例加上条件分支。自己做一个完整项目比如企业知识库问答或运维助手。为这个项目建一个评测集记录优化前后指标变化。把这个项目和过程整理成简历上的一个真实故事。Agent 开发这个方向还远没有定型框架和工具都在快速迭代。真正能拉开差距的不是你会背多少概念而是你是否亲手踩过坑、做过评测、被生产环境毒打过。从一个小项目开始跑通远比收藏几十个教程更有价值。