过去大半年我一直在折腾一件事把 RAG 从“能跑”推到“生产级”。期间刷了不少课程也踩了不少坑最近把成果整理成一个新项目production-agentic-rag-course——不是又一套概念罗列而是实实在在讲 agentic RAG 怎么落地、怎么权衡、怎么评估、怎么排障。如果你已经做过 RAG demo但总觉得“上了生产就到处冒烟”或者被“rag瓶颈”“rag知识库到底怎么搭”“要不要上知识图谱”这些问题卡住那这篇文章就是给你准备的。这篇文章不聊空对空的理论我会把我在生产环境里反复验证过的架构、参数、代码、评估方式和踩坑记录一次性摊开。内容包括传统 RAG 为什么在 production 场景会哑火、agentic 化之后系统长什么样、非结构化知识库与结构化知识图谱各自的适用边界、以及一套在 mac 上就能完整跑起来的落地底座。全程以“能复现”为标准看完你至少能搭出一个带评估闭环的 agentic RAG 最小系统。1. 为什么传统 RAG 总是卡在“building for production”1.1 三道经典瓶颈检索、上下文、评估很多人第一次跑通 RAG 时都很兴奋文档一切embedding 一算top-k 一召回大模型就能回答私有知识了。但兴奋期一过问题就来了。第一道瓶颈是检索质量的上限。普通的“切块→向量化→相似度 top-k”管线召回质量完全取决于 embedding 模型对领域术语、同义词、句式变化的理解。比如你问“上个月华北区退货率高是什么原因”如果知识库里写的是“退货险赔付流程”彼此没有字面重合向量召回往往就找不到。更不用提复合问题、否定表达、多跳推理传统 RAG 在这类场景下几乎无能为力。第二道瓶颈是上下文窗口的“假宽容”。模型能塞的 token 变多了很多人就习惯把 8 个、16 个 chunk 全塞进 prompt结果关键信息被淹没在无关片段里。业内做过不少实验结论很一致位置靠中间的上下文经常被模型忽略这就是“lost in the middle”。召回出来的片段越多生成质量不一定越好反而可能越差。第三道瓶颈最致命没有评估闭环。大部分团队的 RAG 项目停留在“肉眼看好坏”的阶段改一个 chunk size 到底变好还是变坏说不清。没有回归集、没有量化指标生产环境一换数据源就崩根本没有可维护性可言。这三道瓶颈其实就是“building for production 卡住”的根源。你要在 production 上跑的不是一个能回答问题的 demo而是一个能稳定回答、出错了能追踪、改了参数能评估的系统。1.2 从“检索-拼接-生成”到“Agent 决策环”传统 RAG 的本质是一条单向流水线query 进去检索一次拼接上下文生成答案。它假设“第一步检索的结果一定够用”但现实中这个假设几乎不成立。agentic RAG 的思路是把这个过程变成一个决策环大模型不再只是“生成器”而是整个检索流程的调度者。它会先拆解问题判断自己是否真的需要检索需要的话选择从哪个数据源查、用什么关键词查、查几轮查完之后自己判断证据够不够不够就改写查询继续查或者换一个工具最后才聚合证据生成答案。我经常用一个生活类比传统 RAG 就像你拿着一个关键词在搜索引擎里只搜一次然后复制第一页结果就写报告agentic RAG 则像有个靠谱助理他会先问你要查什么判断是查公告还是查内部系统查完了发现信息不全还会换几个词再查一遍最后把几条来源摆在一起告诉你结论。代价是每个环节都要调一次模型延迟和 token 成本都会上升但换来的是检索质量的大幅提升。1.3 生产化的真正含义质量、延迟、成本的三角取舍所谓 production-ready不是加一个 API 接口、挂一个 Docker 就算完。它意味着你要对系统的质量、延迟、成本做有意识的取舍并且每一项都有数据支撑。我建议任何 agentic RAG 系统上线前至少要盯住一组指标检索命中率top-k 里是否包含正确证据、答案采纳率用户对答案的认可比例、幻觉率答案是否忠实于检索出来的证据、端到端延迟 p95、单次请求成本。这五个指标缺一不可。没有这些你在生产环境里改任何东西都是开盲盒。2. 知识库形态选型非结构化、结构化与知识图谱2.1 RAG 知识库能不能存图片真正要看的是信息形态“rag知识库能存储图片嘛”这类问题被问得很多。直接答案是能但单纯把图片二进制塞进向量库没有意义——你要解决的是“图片里的信息如何被检索、被推理”而不是“图片能不能存进去”。图片进 RAG 通常有三条路线。第一条是图片转文本对扫描件跑 OCR、对产品图做 caption把识别出来的文字作为普通文本块入库。这是最便宜、最可控的方案适用于说明书、票据、截图这类信息以文字为主的场景。第二条是视觉向量化用 CLIP 之类的模型把图片编码成向量单独建索引查询时用文字向量去匹配图片向量。适合“找一张外观相似的产品图”这种场景。第三条是多模态直读生成阶段把图片直接作为多模态模型的输入信息损失最少但成本最高而且检索阶段仍然要先找到这张图。我的经验是能用文本描述解决的问题不要急着上多模态。先 OCR、先写 caption很多“图片检索”需求到这一步就解决了。剩下检索不到图片的 case再把视觉向量化作为补充而不是一开始就把架构搞复杂。2.2 “RAG 知识库”和“结构化知识库”是互补关系不是替代关系很多人把“rag知识库和结构知识库区分”理解为二选一其实它们是两种截然不同的信息组织形态各有各的适用场景。非结构化知识库以自然语言文本为主比如操作手册、规章制度、会议纪要。它的优势是表达灵活适合“怎么理解”“为什么这样做”这类开放问题缺点是检索靠语义相似度精确性和一致性难以保证。结构化知识库则是把信息组织成表格、JSON、图结构比如库存表、价格表、人员组织架构。它适合“某某型号库存是多少”“这个审批流到哪一步了”这类精确查询结果准确、可解释但灵活性差没法回答“谈谈你对这件事的看法”。生产系统里两套都很常见查库存走 SQL读操作说明走向量检索。如果知识库里大量是精确数值、一对多关系、跨实体多跳查询那就别硬塞进向量库里尽早引入结构化存储。等 quantity 和 unit price 这种字段被 embedding 切碎的时候再回头改架构就晚了。2.3 知识图谱与 Ontology 在 agentic RAG 里的真正价值知识图谱KG和 ontology 最近讨论度很高但也不是银弹。一个基于 ontology 设计的知识图谱核心价值是两件事实体与关系的确定性以及支持多跳路径的显式推理。举个例子你问“研发部的张工能不能报销异地出差的餐费”纯向量检索会把“研发部”“张工”“报销政策”“异地出差”几个概念拆成片段然后找一些字面相关的段落拼在一起很容易拼出错误结论。但如果知识库里有组织结构图、报销制度图、流程状态图agent 就可以通过图谱做路径推理先确认张工所属部门再查询该部门报销等级再匹配异地餐费规则和当前审批状态每一跳都有明确的实体和关系最后答案可解释、可追溯。ontology 在这里的价值是“固定世界模型”规定有哪些实体类型、哪些关系类型、属性取值范围。它让知识图谱免于“什么都能连”的脏数据问题也让 Rerank 和生成阶段能依赖确定的关系路径而不是 embedding 的模糊语义。但这不代表所有 RAG 项目都需要上 KG。如果知识库是几百篇文档用户问题以“某篇文档讲了什么”为主老老实实做文本切分和向量检索就够了。KG 的维护成本很高它适合的是多跳查询占比高、实体间关系复杂且重要、结论需要可解释路径、涉及聚合统计的业务场景。先有问题再上图谱不要为了图谱而图谱。3. 生产级 agentic RAG 的架构与关键参数设计3.1 分层架构每一层都要能被单独观测和替换我用的生产架构不是一个大 prompt 包办而是按职责拆成五层查询解析层、检索规划层、工具/数据源层、生成综合层、护栏层。这样拆的最大好处是每一层都能单独评测、单独降级出问题时能快速定位。查询解析层负责把用户问题标准化识别意图、抽取关键实体、区分“需要检索外部知识”和“可以直接回答”两类问题。检索规划层是 agentic 的核心它决定查什么、查几次、从哪个源查、结果够不够相当于给检索过程加了“思考能力”。工具/数据源层把向量库、图数据库、SQL 数据库、外部 API 统一封装成工具接口agent 通过路由选择调用。生成综合层负责把多个来源的证据聚合成最终答案。护栏层则是最后一道防线过滤不合规内容、检测幻觉、校验答案格式。这个分层思路和单体 RAG 的核心区别在于检索动作从“一次性调用”变成了“可编程的决策单元”。你可以针对每一层单独做回归测试比如只测查询改写好不好、只测路由选择准不准哪一层出问题就替换哪一层而不是整个系统推倒重来。3.2 关键参数怎么定chunk、top-k、embedding 与评估集chunk 切分chunk 的大小决定检索的最小证据粒度。我实测下来按 token 300 到 500 是一个比较稳的区间。太碎了一个完整的知识点被切进多个 chunk多跳信息容易断裂太大了噪声变多向量表示会被无关内容稀释。overlap 我一般设 10% 到 15%这个值能保证相邻 chunk 之间不会因为切分边界丢失语义又不至于让重复内容严重拖慢检索。需要强调的是不要盲目按固定字符数硬切。正确的做法是优先按文档结构切——Markdown 标题、段落、表格行都是天然边界切不动的长段再按 token 截断。这样切出来的 chunk 语义完整度高很多。top-k 与混合检索top-k 不是越大越好。我一般先画出“召回率k”曲线找一个膝点k 增大到某个值之后召回率不再明显上升那个值就是当前数据集的合理 top-k。经验上区间通常在 8 到 32取决于文档碎片化程度。embedding 只做召回不做精排。生产环境我强烈建议用稀疏检索BM25和稠密向量做混合再把两路结果合并送进 rerank。原因很简单向量擅长语义相关但字面差异大的匹配BM25 擅长精确术语和编号匹配两者互补。不要迷信“向量模型最强”keyword 检索这种“笨办法”在代码类、型号类、编号类问题上往往比向量还可靠。评估集构建这是最容易偷懒但最不能偷懒的一步。上线前至少要准备 20 到 50 条真实用户问题每条标注出对应的黄金文档或标准答案并且按难度分类单跳检索题、多跳推理题、否定/干扰题、完全无关题。没有这套评估集后面所有调优都是空谈。我自己在项目里固定保留一个eval_set.jsonl每次改动任何参数都要在这个集合上跑一遍完整回归。3.3 用 Agent 编排串起多轮检索agentic RAG 的编排我习惯用一个有限状态的循环结构来实现而不是“套一个大 prompt 让模型为所欲为”。核心逻辑是四步路由决策、查询改写、工具调用、证据判断。第一步判断“这个问题需要检索吗”需要的话进入第二步根据 query 生成多个搜索表达式或者拆解成子问题第三步调用数据源工具拿到结果第四步让模型判断“这些证据够不够回答问题”。不够就回到第二步改写查询再来一轮够了才进入生成。为了防止出现死循环我必须强调一点每一轮循环都要有步数上限这个上限我通常设 2 到 3超过上限就进入“拒答”或者“基于已有证据尽力回答”的兜底分支。这个决策环还有一个工程细节不是每一轮都要调用大模型。比如“是否需要检索”这一步用一个小的分类模型就能完成成本比大模型低一个数量级。把 agentic 理解为“关键步骤用模型做决策”而不是“每一步都上大模型”生产成本才能压得下来。4. 实操记录在 mac 上从零搭一套 agentic RAG 底座4.1 环境准备与框架选型我手头的环境是 macOS Python 3.10用uv管理依赖比 pip 快很多装包也干净。向量库本地开发用 Chroma 就行零配置跑起来快生产我建议换 Qdrant 或者云向量库支持更完整的过滤和索引调优。brew install python3.11 uv uv init agentic-rag-demo cd agentic-rag-demo uv add langgraph chromadb openai bm25s pymupdf unstructured这里langgraph负责状态编排chromadb管向量存储bm25s做稀疏检索pymupdf和unstructured管文档解析。框架选型上我多说几句LangGraph 适合你明确知道自己的编排逻辑、想完全控制状态流的情况LlamaIndex 在数据索引和摄取方面集成度更好适合快速建知识库Dify 是低代码路线交互快但灵活性受限自研编排最可控但工程量也最大。我不觉得有“最好”的框架只有“当前阶段最顺手”的框架。4.2 最小实现检索代理加合成模块下面是一个极简的 agentic RAG 循环我用 python 写出来保留了核心的分支判断便于你看懂整体结构。from typing import TypedDict, List from langgraph.graph import StateGraph, END class AgentState(TypedDict): query: str steps: int evidences: List[str] answer: str need_retrieval: bool def parse_and_route(state: AgentState) - AgentState: # 判断是否需要检索这一步可以用小模型或者分类器 state[need_retrieval] True # 简化处理实际要接模型判断 return state def retrieve(state: AgentState) - AgentState: # 混合检索向量召回 BM25 召回 合并 vec_hits vector_search(state[query], top_k8) bm25_hits bm25_search(state[query], top_k8) merged merge_and_deduplicate(vec_hits, bm25_hits) state[evidences] merged return state def grade_evidences(state: AgentState) - AgentState: # 判断证据是否充足不充足则改写查询重新检索 enough llm_judge(evidence_sufficient, state[query], state[evidences]) state[steps] 1 if not enough and state[steps] 3: state[query] rewrite_query(state[query], state[evidences]) return retrieve return generate def generate(state: AgentState) - AgentState: state[answer] llm_generate(state[query], state[evidences]) return state graph StateGraph(AgentState) graph.add_node(route, parse_and_route) graph.add_node(retrieve, retrieve) graph.add_node(generate, generate) graph.set_entry_point(route) graph.add_conditional_edge(route, lambda s: retrieve if s[need_retrieval] else generate) graph.add_conditional_edge(retrieve, grade_evidences, {retrieve: retrieve, generate: generate}) graph.add_edge(generate, END)这段代码里最关键的两个点是条件判断grade_evidences决定要不要多查一轮steps变量防止死循环。没有这个循环上限agent 很容易在复杂问题上反复检索、烧掉大量 token。4.3 本地知识库搭建实操从文档到向量库Mac 上搭 RAG 知识库完整流程是“解析→清洗→切分→向量化→入库”下面每一步都是我实际跑过的。第一步解析文档。PDF 用PyMuPDF转文本扫描件先过 OCR表格建议用unstructured或者专门的表格解析不要直接用 PDF 提取文本否则表格结构会全乱。要注意 mac 上中文文件名和编码问题统一转成 UTF-8否则入库阶段会莫名报错。第二步清洗。去掉页眉页脚、重复标题、页码把列表和表格转成 Markdown 格式保持层级结构。这一步很多人跳过但脏文本对向量质量的伤害比想象中大得多——页眉里那个公司名可能会被反复进入向量把检索结果带偏。第三步切分。按 Markdown 标题层级切分长段落再按 token 截断设置 overlap 10% 到 15%。切分时保留 metadata包括来源文件名、页码、章节标题这些字段在后续过滤和引用追溯中非常关键。python -c from src.ingest import ingest_documents ingest_documents( input_dir./docs, chunk_size400, chunk_overlap50, embedding_modelBAAI/bge-m3, ) 第四步向量化和入库。Embedding 模型我常用BAAI/bge-m3对中文支持好并且同时支持稠密和稀疏两种向量一套模型搞定混合检索。入库前最好做一次去重按内容 hash 过滤重复文档否则同一个文档被重复摄录召回结果会被大量重复片段污染。完成这四步一个能在 mac 上本地跑起来的 RAG 知识库就搭好了。你还可以把它挂到前端做问答演示但生产级使用还需要继续做评估和护栏设计。5. 上线前必须做的事评估、成本与护栏5.1 离线评估不要让自己既当运动员又当裁判评估是 agentic RAG 项目里最容易被低估的环节。我坚持的做法是建立 golden 评估集用独立的 judge 模型做打分而不依赖生成答案的那个模型给自己打分。否则就会出现“自己答的题自己判卷”的虚高成绩。judge 的打分维度我一般定三个答案是否忠实于检索证据是否完整覆盖了问题是否有胡编乱造的内容。每条问题一个 1 到 5 分低于 3 分的 case 全部拉出来人工复核。给一个我常用的 judge prompt 的简化版你是一名严格的质量评审员。请根据以下标准对模型回答打分 1. 忠实度答案内容是否能在提供的证据中找到依据 2. 完整性答案是否完整回答了用户问题 3. 准确性答案是否存在事实错误或臆测内容 评分范围 1-53 分以下视为不合格需要附上具体原因。这里的关键是 judge 模型要比生成模型强或者至少是同级否则它会“看不懂”答案的错误。并且在构造评估集时不要只选那些“好回答”的问题要把真实用户里那些刁钻的、表述模糊的、有歧义的问题也放进去那些才是生产环境真正的压力来源。5.2 在线监控trace 全链路才能在生产环境里排障离线评估做得再好线上也会出现没见过的 case。所以生产环境必须有 trace 链路从用户请求进入系统开始分配一个 trace id日志里记录路由结果、改写后的查询、检索命中的文档 id、每个环节的 token 消耗和耗时。有了 trace 之后线上出问题才能定位。用户反馈“答案不对”时你会知道到底是路由判断错了、查询改写歪了、还是检索召回到了错误文档、或者生成环节没忠实于证据。没有 trace 的 agentic RAG线上出问题只能靠猜那种体验一次就够了。监控指标这件事我前面提过的那五个指标在线上也要持续采检索命中率、答案采纳率、幻觉率、延迟 p95、单次请求成本。每次发版前用离线评估集跑一遍发版中盯线上指标有没有明显波动这是生产级系统能“越跑越稳”的基本盘。5.3 成本控制与延迟优化按模型能力分层该省省该花花agentic RAG 相比传统 RAG最大的生产阻力就是成本和延迟因为你从“一次大模型调用”变成了“多次小模型调用”。我落地时的优化思路是三板斧。第一板斧是模型分层。路由判断、证据是否充足的判断用便宜的小模型查询改写、最终答案生成用能力更强的大模型。不要让大模型去做“判断该不该检索”这种简单活。第二板斧是结果缓存。对高频问题做幂等缓存同样的问题在短时间内重复咨询直接命中缓存不重新走完整 agent 链路能省掉一大块成本。第三板斧是控制循环和并行的节奏。该循环的循环但一旦证据足够立刻跳到生成多个子查询之间能并行的就并行不要串行地跑完一个再跑下一个延迟会成倍放大。这里没有银弹。在 production 环境里每一分钱延迟都要靠数据说话把每次请求的延迟和 token 成本都打点记录下来隔一段时间看一眼分布哪个环节最贵、最慢就去优化哪个环节而不是凭感觉调参。6. 常见问题与排查技巧实录6.1 问题速查表下面这张表是我在真实生产项目里整理出来的高频故障以及对应的排查方向可以直接照抄使用症状可能原因排查方法解决方向检索结果相关但生成答案明显错误生成阶段没有对证据保持忠实模型在自我发挥把 top-k 的黄金证据单独喂给模型不复用检索链路看输出是否还错强约束生成 prompt“只使用给定材料”并让答案带上引用来源Agent 在复杂问题上反复检索形成死循环证据判断条件过于宽松模型总认为“还不够”观察 trace 中 grade 环节的模型输出看它卡在什么判断上设置最大步数为 2 到 3强制走“尽力回答”或“拒答”分支图片类资料在知识库中检索不到图片只做了文件存储没有提取文字或视觉向量确认是否对扫描件做了 OCR、对图片生成 caption 并文本化优先走“OCR caption 转文本块”方案知识库文档很多检索变慢向量索引参数或数据分片不合理查看检索 p95 耗时分布确认是否全表暴力扫描调整 HNSW 的 ef_search 和 M 参数或者按业务域分片索引中英文混排文档切出大量无意义 chunk切分器按字节或固定长度硬切把句子从中间割断抽查切分结果观察断点位置使用按语言感知的切分器优先按句号和换行符切召回结果出现大量重复片段文档入库前没有做去重检查向量库中重复文档的 hash 对比入库前按内容 hash 去重运维脚本定期清理top-k 调大到 20 之后噪声明显变多只有召回没有精排噪音文档混入上下文检查 rerank 环节是否启用引入 rerank 模型或者“BM25 向量”混合后精排6.2 排查方法论先定位是检索层还是生成层遇到答案质量问题时第一步不要急着调参数先做“检索层 vs 生成层”的二分定位。做法很简单把人工确认正确的黄金文档直接拼进 prompt不经过检索链路直接让生成模型回答。如果这样输出依然错问题在生成层比如 prompt 约束不够、模型能力不足、上下文顺序不对。如果这样输出正确问题基本出在检索层那么继续往下拆是路由选错数据源、查询改写不好、召回不到相关内容、还是 rerank 把正确结果排后面了。“Ablation”思想在这个阶段特别有用。每个环节逐个去掉关掉 rerank、只用 BM25、只用量化检索、或者一步到位用大模型解释对比同样的评估集分数就能看到每个模块的边际贡献。我在项目里固定留了一个ablation/目录每次做这类对比试验都留下 notes方便日后回头复盘。6.3 我踩过最难受的几个坑这里说几个常规教程里不会写的经验。第一个坑是关于 embedding 模型的一致性。开发阶段用本地 bge-m3 嵌入后来上线换成了 API 版本向量维度一致但分布略有差异导致旧索引的检索质量明显下降。这个问题的本质是“嵌入模型版本不一致”。所以从第一天起就要把 embedding 模型名和版本写进 metadata所有向量库的集合都记录来源模型换模型必须重建索引。第二个坑是 PDF 里的表格。尤其财务类、技术参数类文档PDF 直接抽取文本会把表格的单元格顺序打乱一个“型号A 保修期 12 个月”会被抽成“A 保修期月 12”检索出来完全没法用。后来我强制要求这类文档先转 Markdown 表格再切块遇到复杂表格直接用表格专用解析器从源头解决。第三个坑是长文档里重复信息对检索的干扰。常见于公司制度类文档同一个政策正文和附件附录里往往是同一段话复制了两遍。向量检索时这两个重复 chunk 会被同时召回占掉一半上下文位置。我在入库前加了基于 SimHash 的去重策略重复度高于阈值的 chunk 只保留一份这个问题才算解决。第四个坑说出来有点不好意思我早期把“答案是否足够”的判断 prompt 写得太宽松模型几乎永远回答“可以回答”agent 变成了普通 RAG根本没有体现出多轮检索的价值。后来我把判断 prompt 改成输出的形式规定得很死要求模型先列举证据涉及的关键实体再比对问题中的实体最后才给出“足够/不足”结论判断质量才上来。这再次说明一点agentic 系统里模型不是越自由越好而是要用结构化约束把它锁在业务逻辑之内。结尾做完这套production-agentic-rag-course之后我最大的体会是agentic RAG 的难点从来不在“会用 LangGraph”或者“知道什么叫 agent”而在于你有没有能力回答清楚三个问题——什么时候该由模型做决策这种决策的边界在哪以及怎么证明它是对的。生产级的本质不是堆功能而是可评估、可定位、可降级。最后再分享一个小技巧无论你的架构规划得多复杂都先从一条最小的闭环开始——一个能路由的 agent、一个混合检索的底座、一个二十条问题的评估集。先用这个极简单体跑通评估和回归再逐步加入图谱、多轮改写、多数据源这些复杂能力。你会发现很多问题在最小闭环里就已经暴露出来了远比架构全搭好再调参省时间。这个项目后续我还会继续扩展但核心方法论不会变所有复杂度的增加都必须有可量化的收益证明自己是值得的。这套思路也是我建议你在自己的生产 RAG 项目里始终坚持的原则。