双非背景入局 AI Agent 开发真正的问题不是学不会而是学习材料太散。LangGraph、RAG、私有化部署、调优、对齐……这些概念单独搜都能看到教程串起来却容易卡在中间LangGraph 的 State 到底怎么理解RAG 知识库怎么和 Agent 对接模型部署上线后为什么回答质量下降。这篇指南把 7 天的学习路径收敛成一条主线先跑通最小 Agent再加入 RAG 知识库然后封装成私有化服务最后通过日志和评测做调优与对齐。目标不是让零基础的人七天变成什么都懂的“大神”而是能独立搭出一个可演示、可部署、可继续扩展的 Agent 项目。先说明一点本文不假设你有名校背景也不假设你能申请到大量算力。你只需要一台能运行 Python 的电脑一个愿意持续动手的节奏以及不回避报错日志的耐心。AI Agent 开发更像是“工程能力 模型理解”的组合而不是“论文推导能力”的比拼。下面直接进入技术主线。1. 先看清 AI Agent 开发的技术栈再决定 7 天怎么分配1.1 AI Agent、LangGraph 和 RAG 分别解决什么问题AI Agent 不是一个新的模型而是一种应用形态。它让大模型不只是回答单轮问题而是能根据用户目标自主完成多步操作理解任务、拆解步骤、调用工具、读取知识、整理结果。真实项目里的 Agent 往往要串联查询数据库、调用内部 API、检索知识库、生成报告等动作这就需要一套“编排框架”来管理流程。LangGraph 就是用来编排 Agent 流程的图框架。它把 Agent 的执行过程建模成一张有向图节点是动作边是动作之间的跳转状态对象会在图里流转。相比写一串 if else 调用大模型LangGraph 更强调流程可视化、分支可控、可恢复适合从简单问答升级到多工具协同的工程场景。RAG 解决的是知识时效和事实准确的问题。大模型训练数据有截止时间也没有企业内部资料直接问会“一本正经地胡说八道”。RAG 先把文档切块、向量化、存入知识库用户提问时检索最相关的片段再拼进 Prompt 让模型基于这些片段回答。RAG 和 Agent 的关系是互补Agent 负责“怎么调用”RAG 负责“给模型提供依据”。三者合在一起就是常见的企业 Agent 形态Agent 决定要不要查知识库RAG 返回候选资料Agent 把资料交给模型生成带来源的回答。7 天路线要做的就是一步步把这个链路落地。1.2 双非背景的学习路径不能按科班顺序走科班路线通常是机器学习理论、深度学习、NLP、Transformer、微调、部署。这条路径很完整但对入局 Agent 开发来说太慢而且很多内容在初期用不到。更务实的学习顺序是先理解应用层流程再根据需要去补充底层知识。第一天不需要懂 Attention 公式但要知道一个 Agent 从输入到输出经过哪些环节第二天不需要会训练模型但要能修改 LangGraph 的节点函数第三天不需要研究所有切块算法但要能跑通一个 RAG 检索闭环。这种路径的核心逻辑是“用项目带知识”。每做一个功能遇到不会的地方再针对性查资料。双非背景的优势在于工程落地训练通常更多而 Agent 开发恰好吃工程能力。不要因为没写过论文就觉得自己不能入场代码运行结果不会看学历。1.3 7 天时间线和每日验收标准以下是可行的 7 天节奏适合每天投入 3 到 5 小时的人。时间紧张时可以拉长到 10 天但顺序不建议乱。天数学习重点动手任务验收标准第 1 天技术栈梳理、环境安装用 LangGraph 跑通最小 Agent本地能运行一个输入输出闭环第 2 天LangGraph 核心机制实现条件路由和循环同一个图能根据输入走不同分支第 3 天Agent 工具调用与子图给 Agent 增加天气或计算工具Agent 在需要时自动调用工具第 4 天RAG 文档处理与切块加载 PDF 并切块建库能对文档内容做向量检索第 5 天RAG 检索优化与引用溯源把检索结果拼入 Prompt回答能返回来源 chunk第 6 天私有化部署用 FastAPI 封装服务通过 HTTP 接口请求 Agent第 7 天调优、对齐与评测记录日志、做 10 个测试问题能说清哪些问题失败及原因不要跳过验收标准。每个任务做完后写一句“这个环节是通过什么命令或日志确认成功的”这对后面排查问题非常关键。2. 环境和依赖准备先跑通最小 Agent 再谈深度2.1 Python 环境、依赖安装和版本确认推荐使用 Python 3.9 或更高版本。不要在系统全局环境里直接装包先建虚拟环境避免项目之间依赖冲突。python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install --upgrade pip pip install langgraph langchain langchain-community fastapi uvicorn chromadb sentence-transformers依赖版本变化很快安装完成后先确认版本再继续后面的步骤pip show langgraph langchain fastapi不同版本的 LangGraph API 可能有差异。比如StateGraph在早期版本和较新版本中引入方式不同add_conditional_edges的参数形式也调整过多次。如果按教程写代码报错提示找不到某个类优先检查版本号并去对应版本文档查找。模型接入有两种方式学习阶段至少要选一种跑通调用云端模型 API使用langchain-openai或langchain-google-genai等适配器申请 API Key 后直接使用。本地模型使用llama-cpp-python加载 GGUF 格式模型适合练习私有化部署。建议学习阶段先选云端 API因为响应更快能让你专注理解 Agent 编排逻辑到第 6 天再切换到本地模型练习私有化场景。2.2 用 LangGraph 搭一个最小 ReAct Agent不引入工具和外部知识先把 LangGraph 的最小结构跑通。结构上需要三样东西状态定义、节点函数、图编译。from typing import TypedDict from langgraph.graph import StateGraph, END class AgentState(TypedDict): messages: list def call_model(state: AgentState): prompt \n.join(state[messages]) reply f已收到{prompt} return {messages: [fassistant: {reply}]}这里的AgentState定义了图上流转的数据结构。节点函数接收state处理后返回一个词典这个词典只会更新对应的字段不会覆盖整个状态。这是 LangGraph 最重要的设计状态是增量更新的。接下来把节点加入图并连接graph StateGraph(AgentState) graph.add_node(agent, call_model) graph.set_entry_point(agent) graph.add_edge(agent, END) app graph.compile() result app.invoke({messages: [你好请介绍一下你自己]}) print(result)compile()会把图转换为可执行对象invoke()是同步运行入口。运行后你会看到输出里包含agent节点返回的新消息。这个最小闭环虽然还没有真正调用大模型但已经足够说明 LangGraph 的基本运行方式。2.3 本地验证从输入到输出的完整闭环写完代码后不要只看代码能运行还要验证三个点初始状态是否正确传入。节点返回的字段是否出现在最终结果里。修改messages内容后输出是否跟着变化。验证时可以在代码里加一行临时打印观察调用顺序def call_model(state: AgentState): print(当前 state:, state[messages]) prompt \n.join(state[messages]) reply f已收到{prompt} return {messages: [fassistant: {reply}]}如果输出里出现多个 “当前 state” 打印说明图里存在多次执行或循环如果没有打印说明节点没有被调用。这个习惯在看 LangGraph 循环和分支时会非常有用。这里还要提醒一个常见坑不要一开始就同时装 langchain、langgraph、chromadb、fastapi 一大堆依赖然后对着报错改。先把最小 Agent 跑通再逐步加组件。依赖越少问题越好定位。3. LangGraph 核心机制状态、节点和条件路由3.1 StateGraph 的状态传递和节点设计LangGraph 的图由状态驱动。状态不只是一个普通字典还定义了每个字段如何更新。默认情况下节点返回的是字段替换如果某个字段需要追加可以使用Annotated配合 reducer 函数。from typing import Annotated, TypedDict from operator import add class AgentState(TypedDict): messages: Annotated[list, add] next_action: str这里的addreducer 表示新返回的messages会追加到已有列表而不是覆盖。这种设计方便节点之间累积信息比如每轮对话都保留历史记录。节点设计原则一个节点只做一件事。命名要能表达动作比如retrieve_docs、call_model、check_answer不要写一个几百行的大函数包办所有逻辑。这样之后想要增加并行分支或子图改动的成本会低很多。节点之间通过 state 通信而不是通过全局变量。全局变量在单线程调试时看起来很顺手一旦图里出现并发或恢复现场就会变成数据混乱的源头。把信息都放进 state才能保证每次执行结果是可预期的。3.2 conditional_edges 实现分支和循环条件路由是 Agent 的核心能力。没有条件路由图只能按固定顺序执行加上conditional_edgesAgent 才能根据用户输入决定下一步走向。def route_by_last_action(state: AgentState) - str: if state[next_action] retrieve: return retrieve if state[next_action] finish: return finish return call_model graph.add_conditional_edges( agent, route_by_last_action, { retrieve: retrieve_docs, call_model: agent, finish: END, } )route_by_last_action的返回值必须能在映射字典里找到对应目标。如果返回了一个不存在的 key运行时会报错。这个报错信息通常会直接告诉你未匹配到哪个键排查时先看函数返回值再看映射字典。循环也是这样实现某个条件分支把下一个节点指回自身或前面的节点。Agent 如果认为工具结果不足可以再次调用工具或模型形成“思考 - 行动 - 观察”的循环。要注意设置最大迭代次数否则模型反复触发某个分支会导致死循环。def should_continue(state: AgentState) - str: if len(state[messages]) 10: return end return agent限定循环次数是生产环境必备的防御手段。3.3 子图、并行分支和长期记忆的落地方式子图用于复用流程。比如一个“文档问答”子图可以在多个父图中被引用。LangGraph 支持把编译好的图作为节点加入另一个图本质上和普通节点一样接收 state 并返回 state。并行分支适合同时调用多个工具的场景。比如用户问“对比这份文档和昨天报表的数据”Agent 可以并行启动两个检索节点再把结果合并给下一个节点。LangGraph 的fanout写法在版本间差异较大学习时不用急着追新特性先理解“多路输入汇合到一个节点”的语义即可。实现时只要确保每个分支都写入 state 的不同字段就不会互相覆盖。长期记忆是 Agent 从 Demo 走向实用必须解决的问题。对话内的短期记忆通过 state 保存跨会话记忆需要把关键信息持久化到外部存储。LangGraph 新版本中的 checkpointer 机制可以保存图的执行状态但落地时要结合数据库设计自己的记忆 schema用户 ID、会话 ID、摘要、关键事实、过期时间。不要把所有历史都塞进 Prompt上下文长度有限而且无关信息会干扰模型判断。4. RAG 知识库文档加载、切块、向量检索和引用溯源4.1 RAG 是什么和 Agent 如何配合RAG 全称是 Retrieval-Augmented Generation意思是在生成前先做检索。它解决的问题很直接模型不知道的知识通过检索外部文档来补上。RAG 的完整链路包括文档解析和清洗。文档切块。Embedding 向量化。向量数据库存储。用户查询时召回相关片段。把片段拼进 Prompt。模型生成带依据的回答。在 Agent 流程里RAG 不是独立的问答接口而是 Agent 的一个工具或一个子图。Agent 先判断用户问题是否需要查内部资料需要时调用 RAG 检索再根据结果生成回答。这样不会所有问题都走知识库也能在知识库没有答案时让 Agent 明确说“不知道”。4.2 文档加载解析全流程PDF、Markdown 和表格文档加载是 RAG 最容易低估的一步。PDF 里的文字层级、表格、图片注释Markdown 里的代码块Word 里的批注每种格式都有不同坑。以 LangChain 为例加载 PDF 和 Markdown 的常见写法from langchain_community.document_loaders import PyPDFLoader, TextLoader pdf_loader PyPDFLoader(./docs/help.pdf) pdf_docs pdf_loader.load() md_loader TextLoader(./docs/guide.md, encodingutf-8) md_docs md_loader.load()PDF 解析出来的文档对象里通常包含page_content和metadata。metadata里有页码、来源文件等字段这些字段在引用溯源时非常有用不要随意丢弃。表格是 RAG 的难点。直接把 Excel 表格转成文本后按行列切检索效果往往很差。推荐先把表格转成 Markdown 表格再按行或按含义分组切块。比如一行一个“规则”文本让 embedding 能检索到完整语义。表格转 Markdown 示例 | 状态 | 说明 | 处理人 | | --- | --- | --- | | PENDING | 等待审核 | 张三 | | APPROVED | 审核通过 | 李四 |如果原始材料是图片型 PDF需要 OCR 识别。OCR 后要把文本块的位置信息保留下来例如“第 3 页左上角”方便后续定位到原文档。4.3 切块策略与 embedding 选择切块没有万能参数只有适合场景的策略。这里给出常见策略对比切块策略优点缺点适用场景固定长度切块实现简单可控会把一句话或一个表格拦腰切断快速原型按段落切块语义相对完整段落过长时容易超过模型上下文规范文档递归分隔符切块兼顾结构和长度分隔符优先级需要调多格式文档的通用起点语义切块语义完整度高计算成本高需要分类模型对回答质量要求高的场景RecursiveCharacterTextSplitter是按优先级依次尝试分隔符切分初学时推荐先用它跑通from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, ., ], ) chunks splitter.split_documents(pdf_docs) print(len(chunks))chunk_size是目标长度实际会略长或略短。chunk_overlap是前后重叠用来保留跨块上下文。如果检索结果经常漏掉关键信息先调大重叠值如果回答精读差先检查切块是否破坏了语义。embedding 选择要结合语言和数据特点。中文场景常用BAAI/bge-small-zh-v1.5这类模型体积小、效果够用。加载方式和模型名要按实际安装版本调整from langchain_community.embeddings import HuggingFaceEmbeddings embedding HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5 )如果没有本地模型缓存需要先从可用模型源下载。如果下载受限可以换用国内模型托管平台下载。注意不要在一个项目里混用两套 embedding 模型否则查询向量和文档向量不在同一向量空间检索结果会失真。4.4 检索、重排和引用溯源检索代码的核心是把 query 向量化后到向量库找相似文档from langchain_community.vectorstores import Chroma vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db ) query 报销流程是什么 docs vectorstore.similarity_search(query, k4)k是返回的片段数量。学习时取 3 到 5 个够了生产环境要根据真实问答情况调整。片段太少可能漏信息太多会把无关内容塞进 Prompt导致模型被错误上下文带偏。只用相似度检索在真实项目里不够。推荐加入重排先召回 20 个候选片段再用重排模型选出最相关的 5 个。这一步能明显提升回答准确性但会增加延迟。是否引入重排要看对实时性的要求。引用溯源是 RAG 容易被忽略的安全能力。生成回答时要把答案对应的来源一起返回def build_prompt(query, retrieved_docs): context \n\n.join( f[{i1}] {doc.page_content} for i, doc in enumerate(retrieved_docs) ) prompt f请根据资料回答问题。\n资料\n{context}\n\n问题{query} return prompt在返回结果时把retrieved_docs的metadata也拼进答案结构。用户能点开原文确认开发者也能在评测时判断模型是不是读了正确资料。5. 私有化部署从本地 Notebook 到服务化5.1 私有化部署的动机和边界私有化部署的典型场景是企业内部知识库问答、政企数据隔离、离线环境使用。相比直接调用云端 API私有化部署能把文档数据留在内网也能在无外网环境运行。但不要为了“私有化”而私有化。私有化部署要自己维护模型、依赖、资源监控和故障恢复成本并不低。进入决策前先问三个问题数据是否真的不能出内网。业务并发量有多大。团队有没有能力维护部署环境。如果只是个人学习可以先在本机跑一个小模型如果是企业项目再根据数据规模选择单机 GPU 还是集群方案。5.2 用 FastAPI 封装 AgentRAG 服务把前面写好的 Agent 和 RAG 逻辑封装成 HTTP 接口是私有化部署的基础动作。用 FastAPI 写一个最小服务from fastapi import FastAPI from pydantic import BaseModel class QueryRequest(BaseModel): query: str class QueryResponse(BaseModel): answer: str sources: list[str] app FastAPI() def run_agent_pipeline(query: str): # 这里调用 LangGraph 图和向量库检索 # 返回 answer 和 sources return {answer: 示例回答, sources: [docs/help.pdf#page3]} app.post(/agent, response_modelQueryResponse) def agent_endpoint(req: QueryRequest): result run_agent_pipeline(req.query) return QueryResponse(answerresult[answer], sourcesresult[sources])启动服务uvicorn main:app --host 0.0.0.0 --port 8000这样 Agent 就从“本地函数”变成了“可被前端或其他系统调用的服务”。实际项目里还要加三样东西请求日志、异常捕获、超时控制。比如用户传了一个空 query要返回 400 而不是让 Agent 跑一次无效流程。如果系统并发要求高先不要在 FastAPI 内部开大量线程而是把模型加载和向量检索设计成独立组件。向量库可以单独启动为服务模型推理也可以放进独立推理服务FastAPI 只做编排。这样不会因为一次大查询阻塞所有请求。5.3 模型加载、并发控制和内存调优使用本地模型时模型文件通常很大加载一次成本高。正确的做法是启动时加载一次各请求复用同一个模型实例不要在每次请求里反复加载。以llama-cpp-python加载 Qwen 等 GGUF 模型为例思路是先加载后调用from llama_cpp import Llama llm Llama( model_path/models/qwen2-7b-instruct-q4_k_m.gguf, n_ctx4096, n_gpu_layers-1, verboseFalse )n_ctx控制上下文窗口长度n_gpu_layers控制多少层放到 GPU。这两个参数直接影响内存和显存占用。7B 模型的量化版在普通消费级显卡上可以运行但如果是 CPU 推理单次生成速度会明显慢学习环境要有心理准备。内存调优优先关注以下几点上下文长度不是越大越好过大会增加显存占用和生成延迟。并发数单卡并发太高会显存溢出要测出合适的上限。量化精度Q4 比 Q8 省显存但可能有精度损失需要评测。缓存重复问题可以加语义缓存减少重复计算。学习环境和生产环境的差异可以用表格说明项目学习环境生产环境模型本机小模型或云端 API按数据量和 GPU 选型存储本地目录独立向量库和数据备份日志print结构化日志和监控并发单用户压测后确定并发上限回滚重新跑脚本版本发布和模型灰度6. 调优与对齐让 Agent 在真实场景里更可靠6.1 调优先看日志和可观测性不要盲目换模型很多人在 Agent 回答不好时第一反应是换大模型但真正的问题往往出在检索或 Prompt 上。调优前先建立日志把每次请求的关键信息记录下来。建议每条日志至少包含{ query: 报销流程是什么, retrieved_chunks: [doc1#p3, doc2#p7], prompt: 完整 Prompt 或省略内容, answer: 模型回答, latency_ms: 1200, model: qwen2-7b-q4, timestamp: 2026-01-01T10:00:00Z }有了日志才能回答几个关键问题是没检索到还是检索到了但没用对是 Prompt 没有约束格式还是模型能力不够是网络或推理耗时高还是知识库本身缺内容排查顺序建议先看检索结果再看 Prompt最后看模型本身。绝大多数 RAG 类 Agent 的问题都出在前两层。6.2 对齐输出格式、安全边界和指令遵循AI 对齐在 Agent 场景里不是玄学而是让系统行为和用户预期一致。具体到工程上主要有三个层面。第一是输出格式对齐。如果系统要求 Agent 返回 JSON不要靠“请返回 JSON”一句提示最好在 Prompt 里给出明确 schema并设置解析失败后的兜底逻辑。AGENT_PROMPT 你是企业知识库助手。 回答要求 1. 先给结论再给理由。 2. 引用资料时用 [来源编号]。 3. 回答必须是 JSON{answer: ..., sources: [...]} 4. 资料中没有的内容必须回答资料中未找到。 5. 不编造、不调侃、不执行越权操作。 第二是安全边界对齐。企业 Agent 要能识别哪些问题不能答、哪些操作不能做。比如涉及删除数据库、绕过权限、获取他人隐私等请求应该拒绝并转人工。这类规则不能只写在 Prompt 里还要在代码层加校验。因为 Prompt 可能被用户绕过代码过滤更硬。第三是指令遵循对齐。如果模型总是无视输出格式先检查 Prompt 是否过载。不要在一个 Prompt 里塞二十个约束模型记不住更重要的是约束之间可能冲突。把最重要的条件放在前面格式示例放中间知识库提示放后面。6.3 常用指标和评测方式Agent 调优不能只靠“感觉变好了”。至少要维护一份最小评测集包含 10 到 30 个问题覆盖正常问题、边界问题、资料缺失问题、敏感问题。每次改动后跑一遍记录通过率。常用指标回答准确率人工判断或分类模型判断答案是否与资料一致。引用准确率模型标出的来源是否真的是答案依据。格式合法率JSON 等结构化输出是否能被解析。无效调用率Agent 在不需要工具时是否也调用了工具。端到端延迟从用户请求到返回结果的耗时。评测结果可以用表格记录方便对比不同 Prompt、不同切块参数、不同模型的效果。注意评测问题不要用训练时见过的文档否则测的是记忆而不是 Agent 能力。7. 常见问题排查和 7 天落地清单7.1 LangGraph 和 RAG 的典型报错问题现象常见原因检查方式处理建议LangGraph 编译报错提示找不到节点节点名称和 add_node 不一致检查映射字典和函数名统一节点命名避免拼写差异图执行后 state 不符合预期忘记写返回字段或 reducer 配置错误打印节点前后 state为关键节点加临时日志条件路由一直走默认分支route 函数返回 key 不在映射表中打印 route 返回值先修函数返回值再检查映射表RAG 检索不到相关内容切块过大或 embedding 模型不匹配打印检索结果片段调整 chunk_size、overlap 或换 embedding回答引用错误来源检索到相似但不相关的片段查看召回列表加重排模型、调整 top_k、增加过滤本地模型响应很慢模型过大、上下文过长或 CPU 推理观察资源占用换量化模型、减小 n_ctx、加 GPU输出不是合法 JSONPrompt 约束不足或模型能力不足查看原始输出增加格式示例和失败重试逻辑遇到报错先读最后几行日志再回到输入的 query 和状态数据。不要只把报错截图拉出来问人先自己排除“输入是否正确、路径是否存在、版本是否匹配”这三类问题。7.2 双非开发者最容易踩的节奏坑第一个坑是第一天就装全套大模型部署工具结果一个模型文件几十 GB到最后也没有跑通。正确做法是先跑通云端 API 或小模型理解流程后再处理部署。第二个坑是跟着教程敲代码但从不修改参数。教程里的切块大小、top_k、Prompt 都是针对某个具体场景的不适用你的文档和问题。每跑通一段代码要主动改一个参数看结果变化才能建立手感。第三个坑是过早追求“高级特性”。LangGraph 的长期记忆、多智能体、复杂子图都是好功能但如果连最小 Agent 和条件路由都不熟加再多的概念只会增加混乱。7 天里先把基础链路做扎实剩下的留到第 8 天以后继续。第四个坑是忽略文档数据质量。很多 RAG 项目效果差不是模型问题而是 PDF 解析出来乱码、表格被切碎、重复内容太多。数据清洗和切块占 60% 的工作量要在第一天就建立这个意识。7.3 7 天学习清单和下一步扩展天数必做动作输出物排查关键词第 1 天建虚拟环境跑通最小 Agent可运行脚本StateGraph, compile, invoke第 2 天实现条件路由和循环分支执行日志conditional_edges, END第 3 天给 Agent 接入一个工具自动调用工具效果tool calling, add_node第 4 天完成文档加载和切块切块数量统计PyPDFLoader, RecursiveCharacterTextSplitter第 5 天完成向量检索和引用溯源检索结果带来源Chroma, similarity_search第 6 天FastAPI 封装 AgentHTTP 接口可调用uvicorn, POST /agent第 7 天日志、评测集、调优10 个问题的评测表和日志文件latency, accuracy, prompt第 8 天开始不要继续看零散教程。找一个自己身边真实存在的问题比如把某本书、某个企业文档、某个开源项目的说明做成 Agent然后不断修改检索、Prompt 和部署配置。把 7 天学到的东西套进自己的场景才是从小白到能独立开发的分水岭。AI Agent 开发的门槛正在从“会不会模型算法”转向“能不能把模型、数据、流程和服务工程化地组织起来”。双非背景不代表没有入场机会关键是先有一份能运行的代码再慢慢补原理。希望这份 7 天学习路线能帮你少走弯路至少先把主线跑通。 AI Agent开发7天实战：LangGraph+RAG+私有化部署全攻略
双非背景入局 AI Agent 开发真正的问题不是学不会而是学习材料太散。LangGraph、RAG、私有化部署、调优、对齐……这些概念单独搜都能看到教程串起来却容易卡在中间LangGraph 的 State 到底怎么理解RAG 知识库怎么和 Agent 对接模型部署上线后为什么回答质量下降。这篇指南把 7 天的学习路径收敛成一条主线先跑通最小 Agent再加入 RAG 知识库然后封装成私有化服务最后通过日志和评测做调优与对齐。目标不是让零基础的人七天变成什么都懂的“大神”而是能独立搭出一个可演示、可部署、可继续扩展的 Agent 项目。先说明一点本文不假设你有名校背景也不假设你能申请到大量算力。你只需要一台能运行 Python 的电脑一个愿意持续动手的节奏以及不回避报错日志的耐心。AI Agent 开发更像是“工程能力 模型理解”的组合而不是“论文推导能力”的比拼。下面直接进入技术主线。1. 先看清 AI Agent 开发的技术栈再决定 7 天怎么分配1.1 AI Agent、LangGraph 和 RAG 分别解决什么问题AI Agent 不是一个新的模型而是一种应用形态。它让大模型不只是回答单轮问题而是能根据用户目标自主完成多步操作理解任务、拆解步骤、调用工具、读取知识、整理结果。真实项目里的 Agent 往往要串联查询数据库、调用内部 API、检索知识库、生成报告等动作这就需要一套“编排框架”来管理流程。LangGraph 就是用来编排 Agent 流程的图框架。它把 Agent 的执行过程建模成一张有向图节点是动作边是动作之间的跳转状态对象会在图里流转。相比写一串 if else 调用大模型LangGraph 更强调流程可视化、分支可控、可恢复适合从简单问答升级到多工具协同的工程场景。RAG 解决的是知识时效和事实准确的问题。大模型训练数据有截止时间也没有企业内部资料直接问会“一本正经地胡说八道”。RAG 先把文档切块、向量化、存入知识库用户提问时检索最相关的片段再拼进 Prompt 让模型基于这些片段回答。RAG 和 Agent 的关系是互补Agent 负责“怎么调用”RAG 负责“给模型提供依据”。三者合在一起就是常见的企业 Agent 形态Agent 决定要不要查知识库RAG 返回候选资料Agent 把资料交给模型生成带来源的回答。7 天路线要做的就是一步步把这个链路落地。1.2 双非背景的学习路径不能按科班顺序走科班路线通常是机器学习理论、深度学习、NLP、Transformer、微调、部署。这条路径很完整但对入局 Agent 开发来说太慢而且很多内容在初期用不到。更务实的学习顺序是先理解应用层流程再根据需要去补充底层知识。第一天不需要懂 Attention 公式但要知道一个 Agent 从输入到输出经过哪些环节第二天不需要会训练模型但要能修改 LangGraph 的节点函数第三天不需要研究所有切块算法但要能跑通一个 RAG 检索闭环。这种路径的核心逻辑是“用项目带知识”。每做一个功能遇到不会的地方再针对性查资料。双非背景的优势在于工程落地训练通常更多而 Agent 开发恰好吃工程能力。不要因为没写过论文就觉得自己不能入场代码运行结果不会看学历。1.3 7 天时间线和每日验收标准以下是可行的 7 天节奏适合每天投入 3 到 5 小时的人。时间紧张时可以拉长到 10 天但顺序不建议乱。天数学习重点动手任务验收标准第 1 天技术栈梳理、环境安装用 LangGraph 跑通最小 Agent本地能运行一个输入输出闭环第 2 天LangGraph 核心机制实现条件路由和循环同一个图能根据输入走不同分支第 3 天Agent 工具调用与子图给 Agent 增加天气或计算工具Agent 在需要时自动调用工具第 4 天RAG 文档处理与切块加载 PDF 并切块建库能对文档内容做向量检索第 5 天RAG 检索优化与引用溯源把检索结果拼入 Prompt回答能返回来源 chunk第 6 天私有化部署用 FastAPI 封装服务通过 HTTP 接口请求 Agent第 7 天调优、对齐与评测记录日志、做 10 个测试问题能说清哪些问题失败及原因不要跳过验收标准。每个任务做完后写一句“这个环节是通过什么命令或日志确认成功的”这对后面排查问题非常关键。2. 环境和依赖准备先跑通最小 Agent 再谈深度2.1 Python 环境、依赖安装和版本确认推荐使用 Python 3.9 或更高版本。不要在系统全局环境里直接装包先建虚拟环境避免项目之间依赖冲突。python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install --upgrade pip pip install langgraph langchain langchain-community fastapi uvicorn chromadb sentence-transformers依赖版本变化很快安装完成后先确认版本再继续后面的步骤pip show langgraph langchain fastapi不同版本的 LangGraph API 可能有差异。比如StateGraph在早期版本和较新版本中引入方式不同add_conditional_edges的参数形式也调整过多次。如果按教程写代码报错提示找不到某个类优先检查版本号并去对应版本文档查找。模型接入有两种方式学习阶段至少要选一种跑通调用云端模型 API使用langchain-openai或langchain-google-genai等适配器申请 API Key 后直接使用。本地模型使用llama-cpp-python加载 GGUF 格式模型适合练习私有化部署。建议学习阶段先选云端 API因为响应更快能让你专注理解 Agent 编排逻辑到第 6 天再切换到本地模型练习私有化场景。2.2 用 LangGraph 搭一个最小 ReAct Agent不引入工具和外部知识先把 LangGraph 的最小结构跑通。结构上需要三样东西状态定义、节点函数、图编译。from typing import TypedDict from langgraph.graph import StateGraph, END class AgentState(TypedDict): messages: list def call_model(state: AgentState): prompt \n.join(state[messages]) reply f已收到{prompt} return {messages: [fassistant: {reply}]}这里的AgentState定义了图上流转的数据结构。节点函数接收state处理后返回一个词典这个词典只会更新对应的字段不会覆盖整个状态。这是 LangGraph 最重要的设计状态是增量更新的。接下来把节点加入图并连接graph StateGraph(AgentState) graph.add_node(agent, call_model) graph.set_entry_point(agent) graph.add_edge(agent, END) app graph.compile() result app.invoke({messages: [你好请介绍一下你自己]}) print(result)compile()会把图转换为可执行对象invoke()是同步运行入口。运行后你会看到输出里包含agent节点返回的新消息。这个最小闭环虽然还没有真正调用大模型但已经足够说明 LangGraph 的基本运行方式。2.3 本地验证从输入到输出的完整闭环写完代码后不要只看代码能运行还要验证三个点初始状态是否正确传入。节点返回的字段是否出现在最终结果里。修改messages内容后输出是否跟着变化。验证时可以在代码里加一行临时打印观察调用顺序def call_model(state: AgentState): print(当前 state:, state[messages]) prompt \n.join(state[messages]) reply f已收到{prompt} return {messages: [fassistant: {reply}]}如果输出里出现多个 “当前 state” 打印说明图里存在多次执行或循环如果没有打印说明节点没有被调用。这个习惯在看 LangGraph 循环和分支时会非常有用。这里还要提醒一个常见坑不要一开始就同时装 langchain、langgraph、chromadb、fastapi 一大堆依赖然后对着报错改。先把最小 Agent 跑通再逐步加组件。依赖越少问题越好定位。3. LangGraph 核心机制状态、节点和条件路由3.1 StateGraph 的状态传递和节点设计LangGraph 的图由状态驱动。状态不只是一个普通字典还定义了每个字段如何更新。默认情况下节点返回的是字段替换如果某个字段需要追加可以使用Annotated配合 reducer 函数。from typing import Annotated, TypedDict from operator import add class AgentState(TypedDict): messages: Annotated[list, add] next_action: str这里的addreducer 表示新返回的messages会追加到已有列表而不是覆盖。这种设计方便节点之间累积信息比如每轮对话都保留历史记录。节点设计原则一个节点只做一件事。命名要能表达动作比如retrieve_docs、call_model、check_answer不要写一个几百行的大函数包办所有逻辑。这样之后想要增加并行分支或子图改动的成本会低很多。节点之间通过 state 通信而不是通过全局变量。全局变量在单线程调试时看起来很顺手一旦图里出现并发或恢复现场就会变成数据混乱的源头。把信息都放进 state才能保证每次执行结果是可预期的。3.2 conditional_edges 实现分支和循环条件路由是 Agent 的核心能力。没有条件路由图只能按固定顺序执行加上conditional_edgesAgent 才能根据用户输入决定下一步走向。def route_by_last_action(state: AgentState) - str: if state[next_action] retrieve: return retrieve if state[next_action] finish: return finish return call_model graph.add_conditional_edges( agent, route_by_last_action, { retrieve: retrieve_docs, call_model: agent, finish: END, } )route_by_last_action的返回值必须能在映射字典里找到对应目标。如果返回了一个不存在的 key运行时会报错。这个报错信息通常会直接告诉你未匹配到哪个键排查时先看函数返回值再看映射字典。循环也是这样实现某个条件分支把下一个节点指回自身或前面的节点。Agent 如果认为工具结果不足可以再次调用工具或模型形成“思考 - 行动 - 观察”的循环。要注意设置最大迭代次数否则模型反复触发某个分支会导致死循环。def should_continue(state: AgentState) - str: if len(state[messages]) 10: return end return agent限定循环次数是生产环境必备的防御手段。3.3 子图、并行分支和长期记忆的落地方式子图用于复用流程。比如一个“文档问答”子图可以在多个父图中被引用。LangGraph 支持把编译好的图作为节点加入另一个图本质上和普通节点一样接收 state 并返回 state。并行分支适合同时调用多个工具的场景。比如用户问“对比这份文档和昨天报表的数据”Agent 可以并行启动两个检索节点再把结果合并给下一个节点。LangGraph 的fanout写法在版本间差异较大学习时不用急着追新特性先理解“多路输入汇合到一个节点”的语义即可。实现时只要确保每个分支都写入 state 的不同字段就不会互相覆盖。长期记忆是 Agent 从 Demo 走向实用必须解决的问题。对话内的短期记忆通过 state 保存跨会话记忆需要把关键信息持久化到外部存储。LangGraph 新版本中的 checkpointer 机制可以保存图的执行状态但落地时要结合数据库设计自己的记忆 schema用户 ID、会话 ID、摘要、关键事实、过期时间。不要把所有历史都塞进 Prompt上下文长度有限而且无关信息会干扰模型判断。4. RAG 知识库文档加载、切块、向量检索和引用溯源4.1 RAG 是什么和 Agent 如何配合RAG 全称是 Retrieval-Augmented Generation意思是在生成前先做检索。它解决的问题很直接模型不知道的知识通过检索外部文档来补上。RAG 的完整链路包括文档解析和清洗。文档切块。Embedding 向量化。向量数据库存储。用户查询时召回相关片段。把片段拼进 Prompt。模型生成带依据的回答。在 Agent 流程里RAG 不是独立的问答接口而是 Agent 的一个工具或一个子图。Agent 先判断用户问题是否需要查内部资料需要时调用 RAG 检索再根据结果生成回答。这样不会所有问题都走知识库也能在知识库没有答案时让 Agent 明确说“不知道”。4.2 文档加载解析全流程PDF、Markdown 和表格文档加载是 RAG 最容易低估的一步。PDF 里的文字层级、表格、图片注释Markdown 里的代码块Word 里的批注每种格式都有不同坑。以 LangChain 为例加载 PDF 和 Markdown 的常见写法from langchain_community.document_loaders import PyPDFLoader, TextLoader pdf_loader PyPDFLoader(./docs/help.pdf) pdf_docs pdf_loader.load() md_loader TextLoader(./docs/guide.md, encodingutf-8) md_docs md_loader.load()PDF 解析出来的文档对象里通常包含page_content和metadata。metadata里有页码、来源文件等字段这些字段在引用溯源时非常有用不要随意丢弃。表格是 RAG 的难点。直接把 Excel 表格转成文本后按行列切检索效果往往很差。推荐先把表格转成 Markdown 表格再按行或按含义分组切块。比如一行一个“规则”文本让 embedding 能检索到完整语义。表格转 Markdown 示例 | 状态 | 说明 | 处理人 | | --- | --- | --- | | PENDING | 等待审核 | 张三 | | APPROVED | 审核通过 | 李四 |如果原始材料是图片型 PDF需要 OCR 识别。OCR 后要把文本块的位置信息保留下来例如“第 3 页左上角”方便后续定位到原文档。4.3 切块策略与 embedding 选择切块没有万能参数只有适合场景的策略。这里给出常见策略对比切块策略优点缺点适用场景固定长度切块实现简单可控会把一句话或一个表格拦腰切断快速原型按段落切块语义相对完整段落过长时容易超过模型上下文规范文档递归分隔符切块兼顾结构和长度分隔符优先级需要调多格式文档的通用起点语义切块语义完整度高计算成本高需要分类模型对回答质量要求高的场景RecursiveCharacterTextSplitter是按优先级依次尝试分隔符切分初学时推荐先用它跑通from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, ., ], ) chunks splitter.split_documents(pdf_docs) print(len(chunks))chunk_size是目标长度实际会略长或略短。chunk_overlap是前后重叠用来保留跨块上下文。如果检索结果经常漏掉关键信息先调大重叠值如果回答精读差先检查切块是否破坏了语义。embedding 选择要结合语言和数据特点。中文场景常用BAAI/bge-small-zh-v1.5这类模型体积小、效果够用。加载方式和模型名要按实际安装版本调整from langchain_community.embeddings import HuggingFaceEmbeddings embedding HuggingFaceEmbeddings( model_nameBAAI/bge-small-zh-v1.5 )如果没有本地模型缓存需要先从可用模型源下载。如果下载受限可以换用国内模型托管平台下载。注意不要在一个项目里混用两套 embedding 模型否则查询向量和文档向量不在同一向量空间检索结果会失真。4.4 检索、重排和引用溯源检索代码的核心是把 query 向量化后到向量库找相似文档from langchain_community.vectorstores import Chroma vectorstore Chroma.from_documents( documentschunks, embeddingembedding, persist_directory./chroma_db ) query 报销流程是什么 docs vectorstore.similarity_search(query, k4)k是返回的片段数量。学习时取 3 到 5 个够了生产环境要根据真实问答情况调整。片段太少可能漏信息太多会把无关内容塞进 Prompt导致模型被错误上下文带偏。只用相似度检索在真实项目里不够。推荐加入重排先召回 20 个候选片段再用重排模型选出最相关的 5 个。这一步能明显提升回答准确性但会增加延迟。是否引入重排要看对实时性的要求。引用溯源是 RAG 容易被忽略的安全能力。生成回答时要把答案对应的来源一起返回def build_prompt(query, retrieved_docs): context \n\n.join( f[{i1}] {doc.page_content} for i, doc in enumerate(retrieved_docs) ) prompt f请根据资料回答问题。\n资料\n{context}\n\n问题{query} return prompt在返回结果时把retrieved_docs的metadata也拼进答案结构。用户能点开原文确认开发者也能在评测时判断模型是不是读了正确资料。5. 私有化部署从本地 Notebook 到服务化5.1 私有化部署的动机和边界私有化部署的典型场景是企业内部知识库问答、政企数据隔离、离线环境使用。相比直接调用云端 API私有化部署能把文档数据留在内网也能在无外网环境运行。但不要为了“私有化”而私有化。私有化部署要自己维护模型、依赖、资源监控和故障恢复成本并不低。进入决策前先问三个问题数据是否真的不能出内网。业务并发量有多大。团队有没有能力维护部署环境。如果只是个人学习可以先在本机跑一个小模型如果是企业项目再根据数据规模选择单机 GPU 还是集群方案。5.2 用 FastAPI 封装 AgentRAG 服务把前面写好的 Agent 和 RAG 逻辑封装成 HTTP 接口是私有化部署的基础动作。用 FastAPI 写一个最小服务from fastapi import FastAPI from pydantic import BaseModel class QueryRequest(BaseModel): query: str class QueryResponse(BaseModel): answer: str sources: list[str] app FastAPI() def run_agent_pipeline(query: str): # 这里调用 LangGraph 图和向量库检索 # 返回 answer 和 sources return {answer: 示例回答, sources: [docs/help.pdf#page3]} app.post(/agent, response_modelQueryResponse) def agent_endpoint(req: QueryRequest): result run_agent_pipeline(req.query) return QueryResponse(answerresult[answer], sourcesresult[sources])启动服务uvicorn main:app --host 0.0.0.0 --port 8000这样 Agent 就从“本地函数”变成了“可被前端或其他系统调用的服务”。实际项目里还要加三样东西请求日志、异常捕获、超时控制。比如用户传了一个空 query要返回 400 而不是让 Agent 跑一次无效流程。如果系统并发要求高先不要在 FastAPI 内部开大量线程而是把模型加载和向量检索设计成独立组件。向量库可以单独启动为服务模型推理也可以放进独立推理服务FastAPI 只做编排。这样不会因为一次大查询阻塞所有请求。5.3 模型加载、并发控制和内存调优使用本地模型时模型文件通常很大加载一次成本高。正确的做法是启动时加载一次各请求复用同一个模型实例不要在每次请求里反复加载。以llama-cpp-python加载 Qwen 等 GGUF 模型为例思路是先加载后调用from llama_cpp import Llama llm Llama( model_path/models/qwen2-7b-instruct-q4_k_m.gguf, n_ctx4096, n_gpu_layers-1, verboseFalse )n_ctx控制上下文窗口长度n_gpu_layers控制多少层放到 GPU。这两个参数直接影响内存和显存占用。7B 模型的量化版在普通消费级显卡上可以运行但如果是 CPU 推理单次生成速度会明显慢学习环境要有心理准备。内存调优优先关注以下几点上下文长度不是越大越好过大会增加显存占用和生成延迟。并发数单卡并发太高会显存溢出要测出合适的上限。量化精度Q4 比 Q8 省显存但可能有精度损失需要评测。缓存重复问题可以加语义缓存减少重复计算。学习环境和生产环境的差异可以用表格说明项目学习环境生产环境模型本机小模型或云端 API按数据量和 GPU 选型存储本地目录独立向量库和数据备份日志print结构化日志和监控并发单用户压测后确定并发上限回滚重新跑脚本版本发布和模型灰度6. 调优与对齐让 Agent 在真实场景里更可靠6.1 调优先看日志和可观测性不要盲目换模型很多人在 Agent 回答不好时第一反应是换大模型但真正的问题往往出在检索或 Prompt 上。调优前先建立日志把每次请求的关键信息记录下来。建议每条日志至少包含{ query: 报销流程是什么, retrieved_chunks: [doc1#p3, doc2#p7], prompt: 完整 Prompt 或省略内容, answer: 模型回答, latency_ms: 1200, model: qwen2-7b-q4, timestamp: 2026-01-01T10:00:00Z }有了日志才能回答几个关键问题是没检索到还是检索到了但没用对是 Prompt 没有约束格式还是模型能力不够是网络或推理耗时高还是知识库本身缺内容排查顺序建议先看检索结果再看 Prompt最后看模型本身。绝大多数 RAG 类 Agent 的问题都出在前两层。6.2 对齐输出格式、安全边界和指令遵循AI 对齐在 Agent 场景里不是玄学而是让系统行为和用户预期一致。具体到工程上主要有三个层面。第一是输出格式对齐。如果系统要求 Agent 返回 JSON不要靠“请返回 JSON”一句提示最好在 Prompt 里给出明确 schema并设置解析失败后的兜底逻辑。AGENT_PROMPT 你是企业知识库助手。 回答要求 1. 先给结论再给理由。 2. 引用资料时用 [来源编号]。 3. 回答必须是 JSON{answer: ..., sources: [...]} 4. 资料中没有的内容必须回答资料中未找到。 5. 不编造、不调侃、不执行越权操作。 第二是安全边界对齐。企业 Agent 要能识别哪些问题不能答、哪些操作不能做。比如涉及删除数据库、绕过权限、获取他人隐私等请求应该拒绝并转人工。这类规则不能只写在 Prompt 里还要在代码层加校验。因为 Prompt 可能被用户绕过代码过滤更硬。第三是指令遵循对齐。如果模型总是无视输出格式先检查 Prompt 是否过载。不要在一个 Prompt 里塞二十个约束模型记不住更重要的是约束之间可能冲突。把最重要的条件放在前面格式示例放中间知识库提示放后面。6.3 常用指标和评测方式Agent 调优不能只靠“感觉变好了”。至少要维护一份最小评测集包含 10 到 30 个问题覆盖正常问题、边界问题、资料缺失问题、敏感问题。每次改动后跑一遍记录通过率。常用指标回答准确率人工判断或分类模型判断答案是否与资料一致。引用准确率模型标出的来源是否真的是答案依据。格式合法率JSON 等结构化输出是否能被解析。无效调用率Agent 在不需要工具时是否也调用了工具。端到端延迟从用户请求到返回结果的耗时。评测结果可以用表格记录方便对比不同 Prompt、不同切块参数、不同模型的效果。注意评测问题不要用训练时见过的文档否则测的是记忆而不是 Agent 能力。7. 常见问题排查和 7 天落地清单7.1 LangGraph 和 RAG 的典型报错问题现象常见原因检查方式处理建议LangGraph 编译报错提示找不到节点节点名称和 add_node 不一致检查映射字典和函数名统一节点命名避免拼写差异图执行后 state 不符合预期忘记写返回字段或 reducer 配置错误打印节点前后 state为关键节点加临时日志条件路由一直走默认分支route 函数返回 key 不在映射表中打印 route 返回值先修函数返回值再检查映射表RAG 检索不到相关内容切块过大或 embedding 模型不匹配打印检索结果片段调整 chunk_size、overlap 或换 embedding回答引用错误来源检索到相似但不相关的片段查看召回列表加重排模型、调整 top_k、增加过滤本地模型响应很慢模型过大、上下文过长或 CPU 推理观察资源占用换量化模型、减小 n_ctx、加 GPU输出不是合法 JSONPrompt 约束不足或模型能力不足查看原始输出增加格式示例和失败重试逻辑遇到报错先读最后几行日志再回到输入的 query 和状态数据。不要只把报错截图拉出来问人先自己排除“输入是否正确、路径是否存在、版本是否匹配”这三类问题。7.2 双非开发者最容易踩的节奏坑第一个坑是第一天就装全套大模型部署工具结果一个模型文件几十 GB到最后也没有跑通。正确做法是先跑通云端 API 或小模型理解流程后再处理部署。第二个坑是跟着教程敲代码但从不修改参数。教程里的切块大小、top_k、Prompt 都是针对某个具体场景的不适用你的文档和问题。每跑通一段代码要主动改一个参数看结果变化才能建立手感。第三个坑是过早追求“高级特性”。LangGraph 的长期记忆、多智能体、复杂子图都是好功能但如果连最小 Agent 和条件路由都不熟加再多的概念只会增加混乱。7 天里先把基础链路做扎实剩下的留到第 8 天以后继续。第四个坑是忽略文档数据质量。很多 RAG 项目效果差不是模型问题而是 PDF 解析出来乱码、表格被切碎、重复内容太多。数据清洗和切块占 60% 的工作量要在第一天就建立这个意识。7.3 7 天学习清单和下一步扩展天数必做动作输出物排查关键词第 1 天建虚拟环境跑通最小 Agent可运行脚本StateGraph, compile, invoke第 2 天实现条件路由和循环分支执行日志conditional_edges, END第 3 天给 Agent 接入一个工具自动调用工具效果tool calling, add_node第 4 天完成文档加载和切块切块数量统计PyPDFLoader, RecursiveCharacterTextSplitter第 5 天完成向量检索和引用溯源检索结果带来源Chroma, similarity_search第 6 天FastAPI 封装 AgentHTTP 接口可调用uvicorn, POST /agent第 7 天日志、评测集、调优10 个问题的评测表和日志文件latency, accuracy, prompt第 8 天开始不要继续看零散教程。找一个自己身边真实存在的问题比如把某本书、某个企业文档、某个开源项目的说明做成 Agent然后不断修改检索、Prompt 和部署配置。把 7 天学到的东西套进自己的场景才是从小白到能独立开发的分水岭。AI Agent 开发的门槛正在从“会不会模型算法”转向“能不能把模型、数据、流程和服务工程化地组织起来”。双非背景不代表没有入场机会关键是先有一份能运行的代码再慢慢补原理。希望这份 7 天学习路线能帮你少走弯路至少先把主线跑通。