从零搭建生产级Agentic RAG系统：架构设计、核心模块与调优实践

1. 从零搭建一套生产级 Agentic RAG 系统，我踩过的坑和最终跑通的方案

RAG 这个词这两年已经被说烂了，但真正在生产环境里跑过的人都知道，Demo 和 Production 之间隔着的不是一条街，而是一整个太平洋。我最初接触 RAG 的时候，觉得不就是“检索+生成”嘛，向量库一接、Prompt 一写就完事了。结果上线第一天就被真实用户的提问打脸：多跳问题答不对、表格数据检索出来是乱的、知识库更新之后旧答案还在飘。后来我开始系统性地研究 Agentic RAG 这个方向，也就是让 RAG 系统具备 Agent 的自主决策能力，不再是一条死板的“检索→拼接→生成”流水线，而是能自己判断该不该检索、该查哪个库、检索结果够不够、要不要换个策略再来一轮。

这套思路落地之后，效果提升非常明显。我把自己从零搭建一套生产级 Agentic RAG 系统的完整过程整理出来，包括架构设计、技术选型、核心模块实现、参数调优、以及那些只有真正跑过才会知道的坑。不管你是刚接触 RAG 的新手，还是已经做过基础 RAG 想往 Agentic 方向升级的开发者，这篇文章里的内容都可以直接参考复现。我不会只讲概念，每个关键环节都会给出具体的实现思路和参数依据，让你看完就能动手。

2. 为什么基础 RAG 在生产环境里不够用

2.1 基础 RAG 的三个致命瓶颈

先说说我一开始用的最朴素的 RAG 架构：用户提问 → 向量化 → 向量库相似度检索 Top-K → 拼接 Prompt → LLM 生成答案。这套流程在 Demo 阶段看起来很美好，但生产环境里很快就暴露了三个瓶颈。

第一个瓶颈是检索决策缺失。不是所有问题都需要查知识库。用户问“你好”或者“帮我写一段代码”，你非要去向量库里捞一圈，不仅浪费资源，还可能把不相关的文档片段塞进 Prompt 里，反而干扰了 LLM 的判断。基础 RAG 没有“要不要检索”这个决策环节，来什么 query 都走同一条路。

第二个瓶颈是单轮检索不够用。很多真实问题需要多跳推理。比如用户问“我们公司去年Q3推出的那款产品的核心技术方案和竞品相比有什么优势”，这个问题需要先找到“去年Q3推出的产品”是哪个，再去找它的技术方案文档，再去找竞品分析文档，最后做对比。基础 RAG 一次检索只能捞一批文档，根本覆盖不了这种多跳需求。

第三个瓶颈是检索质量无法自评估。向量相似度高不代表内容真的相关。我遇到过很多次，检索出来的文档和问题在语义空间里距离很近，但实际内容答非所问。基础 RAG 没有机制去判断“我捞到的这些东西到底能不能回答问题”，直接就往 LLM 里塞，生成质量自然不稳定。

2.2 Agentic RAG 的核心思路：让系统自己决定怎么查

Agentic RAG 的核心思路其实很直观：把 RAG 流程中的每个关键环节都交给 Agent 来决策。具体来说，系统需要具备以下几种能力：

• 路由决策：判断用户问题是否需要检索知识库，如果需要，该查哪个知识库（可能有多个不同领域的库）。
• 查询改写：把用户的原始问题改写成更适合检索的形式，包括同义词扩展、指代消解、子问题拆解等。
• 多轮检索：根据第一轮检索结果判断信息是否充足，不足则生成新的查询继续检索。
• 结果评估：对检索到的文档进行相关性评分，过滤掉低质量内容。
• 生成验证：生成答案后检查是否有幻觉，是否忠实于检索到的内容。

这些能力组合起来，就形成了一个有自主决策能力的 RAG 系统。和基础 RAG 最大的区别在于，Agentic RAG 不是一条固定流水线，而是一个带反馈回路的动态系统。

2.3 什么场景适合上 Agentic RAG

不是所有场景都需要 Agentic RAG。如果你的知识库很小、问题类型单一、对延迟要求极高，那基础 RAG 可能就够了。但如果你遇到以下情况，就值得考虑升级：

• 知识库覆盖多个领域，不同领域的问题需要查不同的库
• 用户问题复杂度高，经常需要多步推理
• 对答案准确性要求高，不能容忍太多幻觉
• 知识库更新频繁，需要系统能自适应

我这次搭建的系统主要面向企业内部的文档问答场景，知识库包含产品文档、技术方案、会议纪要、客户反馈等多种类型，问题复杂度跨度很大。这种场景下，Agentic RAG 的优势非常明显。

3. 整体架构设计与技术选型

3.1 系统分层架构

我把整个系统分成了四层，从下到上依次是：

存储层：负责文档的存储和索引。这里我用了两种存储方式——向量库用于语义检索，Elasticsearch 用于关键词检索。两者结合做混合检索，效果比单用向量库好很多。

检索层：封装了检索相关的所有逻辑，包括查询改写、混合检索、重排序、结果过滤。这一层是 Agentic RAG 的核心，Agent 的决策逻辑主要在这里体现。

编排层：负责整个流程的调度。我用了一个状态机来管理 Agent 的执行流程，每个状态对应一个决策节点，根据当前状态决定下一步做什么。

接口层：对外提供 API，处理用户请求和返回结果。这一层还包括流式输出的处理，因为生产环境里用户不可能等十几秒才看到第一个字。

3.2 为什么选 LangGraph 而不是 LangChain

技术选型这块我纠结了很久。LangChain 的生态确实丰富，但它的 Chain 抽象对于 Agentic RAG 这种需要动态决策的场景来说太僵硬了。Chain 本质上是线性的，虽然可以用各种 Router 来做分支，但一旦流程复杂起来，代码就会变得非常难维护。

LangGraph 的思路不一样，它把整个流程建模成一个图，节点是执行单元，边是状态转移。这种模型天然适合 Agentic RAG，因为 Agent 的决策过程本身就是一个状态机。我可以用条件边来实现“如果检索结果不够好就回到查询改写节点”这种循环逻辑，用 LangGraph 写起来非常自然。

当然 LangGraph 也不是没有缺点。它的学习曲线比 LangChain 陡一些，文档也没有那么完善。但一旦理解了它的核心概念——State、Node、Edge、Checkpoint——用起来还是很顺手的。

3.3 向量库选型：Qdrant vs Milvus vs pgvector

向量库的选型我对比了三个主流方案：

最终我选了 Qdrant。原因有几个：一是它的过滤检索做得很好，支持在向量检索的同时做复杂的 payload 过滤，这对多知识库场景很重要；二是它的部署确实简单，一个 Docker 容器就能跑起来；三是它的 Rust 底层让性能很稳，我实测在百万级向量下检索延迟依然在毫秒级。

pgvector 其实也很有吸引力，毕竟可以直接用 PostgreSQL 的生态。但它的检索性能在数据量上去之后下降比较明显，而且过滤和向量检索的结合不如 Qdrant 灵活。如果你的数据量在十万级以下，pgvector 完全够用，而且运维成本最低。

3.4 Embedding 模型选择

Embedding 模型直接决定了检索质量的上限。我对比了几个主流方案：

• OpenAI text-embedding-3-large：效果确实好，但成本高，而且有网络延迟
• BGE-M3：开源模型里效果最好的之一，支持多语言，可以本地部署
• GTE-large：阿里开源，中文效果不错
• Cohere embed-v3：多语言支持好，但同样有 API 成本

最终我选了 BGE-M3 做本地部署。原因很简单：数据不出本地，成本可控，而且效果和 OpenAI 的差距在可接受范围内。BGE-M3 还有一个好处是它同时支持稠密检索、稀疏检索和多向量检索，一个模型就能覆盖多种检索模式。

不过本地部署 Embedding 模型需要注意硬件。BGE-M3 的模型大小是 2.2GB 左右，推理时需要 GPU 显存至少 4GB。如果没有 GPU，用 CPU 推理也可以，但吞吐量会低很多。我建议至少用一张 T4 或者 RTX 3060 级别的卡。

4. 核心模块实现细节

4.1 查询理解与路由模块

这个模块负责判断用户问题的意图，决定后续走哪条路径。我把它设计成一个轻量级的分类器加规则引擎的组合。

分类器用 LLM 来做，Prompt 大概是这样的：

ROUTER_PROMPT = """你是一个查询路由器。根据用户问题，判断应该走哪条路径： 1. direct_answer：问题不需要查知识库，可以直接回答（如打招呼、简单计算、通用知识） 2. single_retrieval：问题需要查一次知识库就能回答 3. multi_retrieval：问题需要多轮检索和推理才能回答 4. clarify：问题太模糊，需要向用户澄清 用户问题：{question} 只输出路径名称，不要解释。"""

这个分类器看起来简单，但实际效果很好。关键是要给 LLM 足够的上下文来说明每条路径的含义。我试过用更复杂的 Prompt，加了很多 few-shot 示例，但效果反而没有这个简洁版本好。原因是 few-shot 示例容易让 LLM 过拟合到示例的模式上，遇到稍微不同的问法就判断错误。

规则引擎作为兜底，处理一些明显的情况。比如问题长度小于 5 个字符，直接走 direct_answer；问题里包含“对比”“比较”“区别”等词，优先走 multi_retrieval。

注意：路由模块的准确率直接影响整个系统的效率和效果。我建议在初期把路由决策的日志都记录下来，定期分析错误案例，不断优化 Prompt。我上线第一周就发现了十几个路由错误，修正之后整体延迟下降了 30%。

4.2 查询改写与子问题拆解

查询改写是提升检索召回率的关键步骤。用户的原始问题往往包含指代、省略、口语化表达，直接拿去检索效果很差。

我实现了三种改写策略：

指代消解：把“它”“这个”“那个”等指代词替换成具体内容。这需要结合对话历史来做。比如用户上一轮问“BGE-M3 的模型大小是多少”，这一轮问“它支持多语言吗”，改写后应该是“BGE-M3 支持多语言吗”。

同义词扩展：把问题中的关键词扩展成同义词集合。比如“部署”扩展成“部署、安装、搭建”，“性能”扩展成“性能、效率、速度”。这一步我用了同义词词典加 LLM 结合的方式，词典保证常用词的覆盖率，LLM 处理词典里没有的词。

子问题拆解：对于复杂问题，拆解成多个子问题分别检索。比如“我们公司去年Q3推出的那款产品的核心技术方案和竞品相比有什么优势”，拆解成：

• 子问题1：我们公司去年Q3推出了哪款产品？
• 子问题2：这款产品的核心技术方案是什么？
• 子问题3：竞品的核心技术方案是什么？
• 子问题4：两者对比有什么优势？

拆解之后，每个子问题独立检索，最后把结果汇总给 LLM 做综合推理。这一步的效果提升非常明显，多跳问题的回答准确率从 40% 左右提升到了 75% 以上。

4.3 混合检索与重排序

混合检索就是把向量检索和关键词检索的结果融合。我用的融合算法是 Reciprocal Rank Fusion（RRF），公式很简单：

RRF_score(d) = Σ 1 / (k + rank_i(d))

其中 k 是一个常数，通常取 60，rank_i(d) 是文档 d 在第 i 个检索器中的排名。RRF 的好处是不需要归一化不同检索器的分数，直接基于排名融合，鲁棒性很好。

重排序我用了一个 Cross-Encoder 模型，具体是 BGE-Reranker-v2-m3。它的原理是把 query 和 document 拼在一起输入模型，输出一个相关性分数。和向量检索的 Bi-Encoder 相比，Cross-Encoder 能捕捉 query 和 document 之间的细粒度交互，精度更高，但速度慢。所以我先用混合检索召回 Top-50，再用 Cross-Encoder 重排序取 Top-5，这样在精度和速度之间取得平衡。

重排序这一步的效果提升也很明显。我做过对比测试，不做重排序的情况下，Top-5 里平均只有 2.8 个是真正相关的；做了重排序之后，Top-5 里平均有 4.5 个是相关的。这个提升直接反映在了最终答案的准确率上。

4.4 检索结果评估与迭代

这是 Agentic RAG 区别于基础 RAG 的关键模块。系统需要判断检索到的内容是否足够回答问题，如果不够，要能自动发起新一轮检索。

我实现了一个基于 LLM 的评估器，Prompt 大概是这样的：

EVAL_PROMPT = """你是一个检索质量评估器。根据用户问题和检索到的文档，判断这些文档是否足够回答问题。 用户问题：{question} 检索到的文档： {documents} 请输出： - sufficient：文档是否足够回答问题（yes/no） - missing：如果不够，还缺少什么信息 - next_query：如果不够，建议的下一步查询 以 JSON 格式输出。"""

这个评估器会输出三个字段：sufficient 表示是否足够，missing 表示缺少什么，next_query 表示建议的下一步查询。如果 sufficient 是 no，系统就会用 next_query 发起新一轮检索，最多迭代 3 次。

这里有个经验：迭代次数不要设太多。我一开始设了 5 次，结果发现很多情况下系统会陷入“检索-评估-再检索”的循环，每次都觉得不够，但实际已经捞不到更多有用信息了。后来改成 3 次，并且在评估器里加了一个判断“如果连续两轮检索结果高度重叠，就强制停止”，效果好很多。

4.5 生成与幻觉检测

生成模块的 Prompt 设计很关键。我的原则是：严格约束 LLM 只能基于检索到的内容回答，不允许自由发挥。

GENERATION_PROMPT = """你是一个严谨的问答助手。请严格基于以下检索到的文档回答用户问题。 规则： 1. 只使用文档中明确提到的信息，不要添加文档之外的知识 2. 如果文档中没有足够信息回答问题，直接说“根据现有资料无法回答” 3. 引用具体文档时，标注文档来源 4. 如果文档之间存在矛盾，指出矛盾并说明 检索到的文档： {documents} 用户问题：{question} 回答："""

生成之后，我还会做一次幻觉检测。检测方法是用另一个 LLM 调用，把生成的答案和检索到的文档一起输入，判断答案中的每个事实性陈述是否都能在文档中找到依据。如果发现幻觉，就重新生成或者降级返回“根据现有资料无法回答”。

这一步会增加一些延迟，但对于企业级应用来说，准确性比延迟更重要。我实测幻觉检测能把幻觉率从 8% 左右降到 2% 以下。

5. 完整实操流程与关键配置

5.1 环境准备与依赖安装

先说一下我的环境：Ubuntu 22.04，Python 3.11，一张 RTX 4090（24GB 显存）。如果你没有 GPU，Embedding 和重排序模型可以用 CPU 跑，但速度会慢很多。

核心依赖：

pip install langgraph langchain-core qdrant-client elasticsearch pip install sentence-transformers FlagEmbedding pip install fastapi uvicorn pip install ragas # 用于评估

Qdrant 和 Elasticsearch 用 Docker 部署：

docker run -d --name qdrant -p 6333:6333 -v ./qdrant_data:/qdrant/storage qdrant/qdrant docker run -d --name elasticsearch -p 9200:9200 -e "discovery.type=single-node" -e "xpack.security.enabled=false" elasticsearch:8.11.0

5.2 文档处理与索引构建

文档处理流程：加载 → 分块 → 向量化 → 索引。

分块策略我试过很多种，最终用的是语义分块+重叠窗口的组合。具体来说，先用 LLM 判断文档的自然段落边界，在边界处切分，然后每个块保留前后各 100 个 token 的重叠。块大小控制在 512 个 token 左右。

为什么是 512？我做过实验，块太小（256）会导致上下文不完整，检索出来的片段缺少关键信息；块太大（1024）会导致检索精度下降，因为一个块里混了太多主题。512 是一个比较平衡的值，适合大多数文档类型。

索引构建代码的核心逻辑：

from FlagEmbedding import BGEM3FlagModel from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams, PointStruct model = BGEM3FlagModel('BAAI/bge-m3', use_fp16=True) client = QdrantClient(host='localhost', port=6333) client.create_collection( collection_name='knowledge_base', vectors_config=VectorParams(size=1024, distance=Distance.COSINE) ) def index_documents(chunks): embeddings = model.encode( [c['text'] for c in chunks], batch_size=32, max_length=512 )['dense_vecs'] points = [ PointStruct( id=i, vector=embeddings[i].tolist(), payload={ 'text': chunks[i]['text'], 'source': chunks[i]['source'], 'doc_type': chunks[i]['doc_type'] } ) for i in range(len(chunks)) ] client.upsert(collection_name='knowledge_base', points=points)

注意：BGE-M3 输出的稠密向量维度是 1024。如果你换用其他模型，记得同步修改 Qdrant collection 的向量维度配置，否则会报错。

5.3 LangGraph 状态机编排

整个 Agentic RAG 流程用 LangGraph 编排，核心状态定义：

from typing import TypedDict, List class RAGState(TypedDict): question: str rewritten_queries: List[str] retrieved_docs: List[dict] retrieval_round: int is_sufficient: bool answer: str route: str

节点定义包括：route_node（路由决策）、rewrite_node（查询改写）、retrieve_node（检索）、evaluate_node（结果评估）、generate_node（生成）、verify_node（幻觉检测）。

条件边的逻辑：

def should_continue(state: RAGState): if state['is_sufficient']: return 'generate' if state['retrieval_round'] >= 3: return 'generate' return 'rewrite' graph.add_conditional_edges( 'evaluate', should_continue, { 'generate': 'generate', 'rewrite': 'rewrite' } )

这个状态机的核心在于 evaluate 节点之后的条件边。如果检索结果足够，直接走生成；如果不够且还没到最大轮次，回到改写节点继续检索；如果到了最大轮次，强制走生成（并在生成时告知 LLM 信息可能不完整）。

5.4 关键参数调优记录

参数调优这块我花了很多时间做实验，这里把关键参数和调优结论整理出来：

这些参数不是绝对的，需要根据你的具体数据和场景调整。但调优的方向是一致的：召回阶段宁多勿少，精排阶段宁精勿滥。

6. 常见问题与排查技巧实录

6.1 检索结果不相关怎么办

这是最常见的问题。排查思路按优先级来：

第一步，检查 Embedding 模型是否适合你的语言和领域。如果你的文档主要是中文，但用的是英文为主的 Embedding 模型，效果肯定差。BGE-M3 和 GTE-large 对中文支持都很好。

第二步，检查分块策略。我遇到过很多次，检索出来的块把关键信息切断了。比如一个表格被从中间切开，检索到的是上半部分，但答案在下半部分。解决办法是调整分块边界，或者在分块时识别表格、代码块等特殊结构，整块保留。

第三步，检查查询改写是否到位。用户的口语化表达和文档的书面表达之间往往有语义鸿沟。查询改写就是架这座桥的。如果改写没做好，检索效果会大打折扣。

第四步，考虑加混合检索。纯向量检索对关键词匹配不敏感。比如用户搜一个产品型号“XYZ-2000”，向量检索可能返回一堆语义相似但型号不同的文档。加上关键词检索就能精准匹配。

6.2 多跳问题答不对怎么破

多跳问题的核心难点在于：第一轮检索到的信息可能只是中间答案，需要基于它生成第二轮查询。

我的解决方案是在评估节点里显式地做子问题拆解。当评估器判断信息不足时，不仅输出 next_query，还输出一个“已解决子问题”和“待解决子问题”的列表。下一轮检索只针对待解决的子问题，避免重复检索已经覆盖的内容。

另外，多跳问题的生成阶段也需要特殊处理。我会在 Prompt 里明确告诉 LLM：“这是一个多跳问题，你需要综合多轮检索的结果进行推理，推理过程要显式展示。”这样 LLM 会更倾向于做逐步推理，而不是直接给答案。

6.3 知识库更新后旧答案还在飘

这是向量库的经典问题。文档更新了，但旧的向量还在库里，检索时新旧内容一起返回，LLM 可能采信旧内容。

解决方案是给每个文档块打上版本号和时间戳，检索时优先返回最新版本。具体做法是在 payload 里加version和updated_at字段，检索时用 Qdrant 的过滤功能：

from qdrant_client.models import Filter, FieldCondition, MatchValue filter_condition = Filter( must=[ FieldCondition( key='version', match=MatchValue(value='latest') ) ] )

文档更新时，先把旧版本的 version 改成 'archived'，再插入新版本。这样检索时只返回最新版本，旧版本保留用于审计。

6.4 延迟太高怎么优化

生产环境里延迟是硬指标。我总结了几条优化经验：

流式输出：生成阶段用流式输出，用户能更快看到第一个字。虽然总时间没变，但感知延迟大幅降低。

并行检索：多个子问题的检索可以并行执行。我用 asyncio 把检索请求并发出去，整体检索时间从串行的 2 秒降到了 500 毫秒左右。

缓存：高频问题的检索结果和生成答案都做缓存。我用 Redis 做缓存，命中率大概在 30% 左右，对整体延迟改善明显。

模型量化：Embedding 和重排序模型用 FP16 甚至 INT8 量化，推理速度能提升 2-3 倍，精度损失在可接受范围内。

减少不必要的 LLM 调用：路由决策和结果评估不一定每次都要用 LLM。我加了一层规则引擎做预判，能规则处理的就不调 LLM，LLM 调用次数减少了 40% 左右。

6.5 常见问题速查表

7. 效果评估与持续迭代

7.1 评估指标与测试集构建

RAG 系统的评估不能只看“感觉好不好”，要有量化指标。我用的核心指标有三个：

检索指标：Recall@K 和 MRR（Mean Reciprocal Rank）。Recall@K 衡量前 K 个结果里有多少是相关的，MRR 衡量相关结果的平均排名。我的目标是 Recall@5 大于 0.9，MRR 大于 0.8。

生成指标：Faithfulness（忠实度）和 Answer Relevancy（答案相关性）。Faithfulness 衡量答案是否忠实于检索内容，Answer Relevancy 衡量答案是否切题。这两个指标我用 Ragas 框架来算。

端到端指标：人工评估的准确率和用户满意度。我每周会抽 100 个真实问题做人工评估，分成“完全正确”“部分正确”“错误”三档。

测试集的构建很关键。我从真实用户问题里采样了 500 个问题，覆盖各种类型：简单事实查询、多跳推理、对比分析、否定问题、模糊问题等。每个问题都标注了标准答案和相关的文档 ID。这个测试集是我迭代优化的基础。

7.2 持续迭代的节奏

RAG 系统不是一次搭好就完事的，需要持续迭代。我的迭代节奏是：

每周：分析路由日志和评估日志，找出错误案例，优化 Prompt 和规则。

每两周：跑一次完整评估，对比各项指标的变化，决定是否调整参数。

每月：更新测试集，加入新的真实用户问题，保持测试集的代表性。

每季度：评估是否需要升级模型或调整架构。

这个节奏看起来慢，但实际执行下来效果很好。我上线三个月，端到端准确率从最初的 62% 提升到了 85% 以上。

7.3 一个真实的优化案例

分享一个我印象最深的优化案例。上线初期，用户反馈“问产品价格的时候经常答错”。我排查之后发现，价格信息在文档里是以表格形式存在的，而我的分块策略把表格切碎了，检索到的片段只有表头没有数据。

解决方案是加了一个表格识别模块，在分块之前先识别文档中的表格，把整个表格作为一个块处理，并且在表格块的文本里加上表头信息，让检索时能匹配到。改完之后，价格相关问题的准确率从 45% 提升到了 92%。

这个案例让我意识到，RAG 系统的效果瓶颈往往不在模型，而在数据处理。文档解析、分块、索引这些“脏活累活”做得好不好，直接决定了系统的上限。

8. 一些个人体会和后续扩展方向

这套系统跑到现在，我最深的体会是：Agentic RAG 的核心价值不在于用了多先进的模型，而在于把决策权交给了系统本身。基础 RAG 是一条死板的流水线，Agentic RAG 是一个有反馈回路的动态系统。这个思路上的转变，带来的效果提升比换任何模型都大。

后续我计划往几个方向扩展。一是引入知识图谱，把结构化的实体关系和非结构化的文档检索结合起来，处理需要关系推理的问题。二是做多模态 RAG，支持图片和表格的检索。三是优化成本，目前 LLM 调用还是主要成本来源，我在研究用更小的模型做路由和评估，把大模型只用在最终的生成环节。

如果你也在做 RAG 相关的项目，我的建议是：先把基础 RAG 跑通，理解每个环节的作用和瓶颈，再逐步引入 Agentic 的能力。不要一上来就追求大而全的架构，从最简单的路由决策开始，一步步加，每一步都做评估，确保每次改动都有正向收益。RAG 这个方向变化很快，但底层的数据处理和检索质量永远是根基，把根基打牢，上层怎么变都不慌。