Agentic RAG完整实现指南：原理、架构与代码实战

传统RAG系统的局限性正在被越来越多的开发者感知到：检索结果答非所问、无法应对信息不完整的场景、缺乏自主决策能力。2025年，Agentic RAG作为RAG技术的根本性升级，正在成为大模型应用开发的核心范式。本文将从传统RAG出发，深入剖析Agentic RAG的原理，并给出完整的代码实现方案。

传统RAG的工作流程与局限

离线流程：文档处理与向量化存储

传统RAG的实现可以分为两条流水线。第一条是离线流水线，负责将原始文档转化为可检索的向量数据。

具体步骤如下：首先加载原始文档（PDF、Word、TXT等），然后对文档进行切片处理。由于完整文档可能包含数万字，无法一次性全部输入大模型，因此需要将其切分为固定长度的段落（如256个字符），段落之间保留一定的重叠区域以保证语义连贯性。

切片完成后，使用Embedding模型将每个段落转化为固定维度的向量表示，最后将这些向量存储到向量数据库（如ChromaDB）中。

关于Embedding模型与向量化原理：Embedding模型是一种将文本映射到高维向量空间的神经网络模型。其核心思想源自分布式语义假说——语义相近的文本在向量空间中距离更近。常见的Embedding模型包括OpenAI的text-embedding-3-small（1536维）、BGE系列（中文优化）以及Sentence-BERT等。向量化后的文本可以通过余弦相似度或欧氏距离进行语义匹配，这比传统的关键词匹配能更好地捕捉同义词、近义词和语义等价表达。向量维度的选择直接影响检索精度和存储成本之间的平衡。

关于ChromaDB的技术特点：ChromaDB是一款开源的轻量级向量数据库，专为AI应用设计。它支持内存存储和持久化存储两种模式，内置了多种距离度量（余弦相似度、L2距离、内积），并提供元数据过滤功能。与Pinecone、Milvus、Weaviate等生产级向量数据库相比，ChromaDB更适合原型开发和中小规模应用。在生产环境中，开发者通常需要考虑向量索引算法（如HNSW、IVF）的选择、分片策略、以及与传统数据库的混合查询能力。

传统RAG离线流程：文档加载、切片、向量化与存储

在线流程：检索、拼接与生成

第二条是在线流水线，处理用户的实时查询请求。当用户提出问题后，系统首先对问题进行改写（Query Rewriting），使其更适合检索场景。

改写后的查询会经过两路检索：一路通过BM25进行关键词检索，另一路通过Embedding模型转化为向量后进行语义相似度匹配。两路检索的结果合并后，再经过重排序（Reranking）筛选出最相关的文档片段，最终将这些片段注入到Prompt模板的Context部分，交由大模型生成答案。

关于BM25与混合检索策略：BM25（Best Matching 25）是信息检索领域经典的概率排序算法，基于词频（TF）、逆文档频率（IDF）和文档长度归一化来计算查询与文档的相关性得分。它在精确关键词匹配场景下表现优异，但无法理解语义等价。混合检索（Hybrid Search）将BM25的关键词检索与向量语义检索结合，通过加权融合或RRF（Reciprocal Rank Fusion）算法合并两路结果，兼顾精确匹配和语义理解的优势。这种策略在实际生产环境中已被证明比单一检索方式效果更好。

传统RAG的核心痛点

整个过程是单向、固定、一次性的。模型只能基于第一轮检索的结果生成回答，无法做到：

检索失败时自动换一种方式重新检索
主动判断是否需要补充上下文信息
回答"知识库中有哪些文档"这类元数据问题
动态调整检索策略以获取更完整的信息

当检索不到有效内容时，模型只能回复"不知道"，而不会尝试改写查询或调用其他工具来获取答案。这正是Agentic RAG要解决的核心问题。

Agentic RAG：从流水线到智能闭环

核心理念：将检索能力工具化

Agentic RAG是对传统RAG的根本性升级。它的核心思想是：将RAG中的各个环节（Query改写、向量检索、关键词搜索等）全部封装为可调用的工具（Tool），并赋予大模型自主决策的权利。

Agentic RAG流程：思考-行动-观察的智能闭环

模型不再沿着固定流水线执行，而是进入一个**"思考→行动→观察→再思考"的循环闭环**。在生成最终答案之前，模型可以进行多步工具调用、动态调整策略，直到获取足够的信息。

关于ReAct范式：ReAct（Reasoning + Acting）是2022年由Google Research和Princeton大学提出的Agent推理范式。它将大模型的推理能力（Chain-of-Thought）与行动能力（工具调用）交织在一起，形成Thought→Action→Observation的循环。与纯推理（CoT）相比，ReAct能够通过外部工具获取实时信息来修正推理过程；与纯行动相比，它通过显式推理来规划下一步操作。LangGraph中的create_react_agent正是基于这一范式实现的，它允许模型在每一步都进行思考并决定是调用工具还是输出最终答案。

Agentic RAG的三大核心能力

Agentic RAG的实现依赖模型具备以下三类能力：

规划能力（Planning）：体现在Chain-of-Thought推理过程中，模型能够规划执行步骤、评估中间结果
工具调用能力（Tool Calling）：模型能够根据需要选择并调用合适的工具，甚至进行多Agent协作
多步迭代能力（Multi-step Iteration）：在回答最终答案之前，模型可以进行多轮工具调用和结果评估

关于Function Calling机制：Function Calling是大模型厂商（如OpenAI、Anthropic、Google等）提供的结构化工具调用能力。开发者以JSON Schema格式定义工具的名称、描述和参数结构，模型在推理过程中会判断是否需要调用工具，并输出结构化的调用请求（包含工具名和参数值）。系统执行工具后将结果返回模型，模型再基于结果继续推理。这一机制的关键在于模型经过了专门的指令微调（Instruction Tuning），使其能够理解工具描述并生成符合格式要求的调用指令，而非简单的文本补全。

Agentic RAG与传统RAG的本质区别

传统RAG中，大模型只在最后的生成阶段才被使用。而在Agentic RAG中，从用户输入问题的那一刻起，大模型就开始参与决策——判断是否需要检索、选择哪种检索方式、评估检索结果是否充分、决定是否需要补充信息。

传统RAG vs Agentic RAG架构对比

举个具体例子：传统RAG面对一个查询，执行一次向量检索后发现命中率很低，只能将低质量的结果交给模型。而Agentic RAG会观察到命中率低，自动改写查询词进行第二轮搜索，获取更相关的片段后再进行第三轮补充搜索，最终基于整合后的高质量上下文生成回答。

ChatPDF Boss开源实现解析

架构设计：用时间换智能

以开源项目ChatPDF Boss为例，其Agentic RAG的实现逻辑非常值得借鉴。系统的核心设计理念是用时间换取模型的智能。

ChatPDF Boss Agentic RAG架构设计

当用户发送问题后，系统首先判断模型是否支持工具调用（Function Calling）：

如果不支持工具调用：通过Prompt判断问题是否需要检索。不需要检索则直接回复；需要检索则进行语义搜索，将相关片段注入Context后生成回答。这种方式比在Prompt中让模型忽略无关Context更优，因为使用了两个模型分别做决策。

如果支持工具调用：将所有工具集合注册到模型中，由模型自主决策调用哪些工具。这才是真正的Agentic模式。

四个核心工具的设计思路

ChatPDF Boss设计了四个核心工具，覆盖了知识库交互的主要场景：

工具名称	功能说明
Search Query	基础的语义检索工具，执行向量相似度搜索
List Files	列出知识库中的文件清单，解决传统RAG无法回答元数据问题的痛点
Read File	根据文档ID精确读取特定片段，支持主动读取前后片段补充上下文
Gather File Meta	获取文件的元数据信息

其中List Files和Read File是最具特色的设计。传统RAG无法回答"知识库里有哪些文档"这类问题，因为它本质上只能检索内容片段。而List Files工具让模型能够获取文件清单和数量信息。Read File则允许模型在发现信息不完整时，主动读取前后片段来补充上下文，不再完全依赖语义相似度检索。

代码实现：从传统RAG到Agentic RAG

传统RAG的LangChain代码实现

基于LangChain框架，传统RAG的实现分为离线和在线两部分：

离线部分：加载文档→文本切分（设置chunk_size和overlap）→使用Embedding模型向量化→存储到ChromaDB。代码核心是通过LangChain的文本分割器和ChromaDB的from_documents方法完成。

在线部分：加载向量数据库→构造用户Query→调用similarity_search方法检索Top-K相关片段→将片段拼接到Prompt模板→交由大模型生成回答。

实际工作中，离线流水线才是重点。如何切分文档、选择什么Embedding模型、是否需要微调、缓存策略如何设计——这些都直接影响最终检索结果的质量。

Agentic RAG的LangGraph代码实现

核心实现借助LangGraph中的create_react_agent，代码结构出奇地简洁：

定义工具集：将Search Query、List Files、Read File等封装为标准工具函数
编写System Prompt：引导模型如何使用这些工具，注意需要限制回复格式以避免工具调用失败
创建React Agent：传入大模型实例、工具列表和系统提示词
运行Agent：调用invoke方法传入用户问题即可

关于LangGraph框架：LangGraph是LangChain团队推出的Agent编排框架，基于有向图（Graph）的概念来组织Agent的执行流程。与LangChain的链式调用不同，LangGraph支持循环、条件分支和状态持久化，更适合构建需要多轮迭代的复杂Agent。其核心概念包括：State（全局状态）、Node（执行节点，如LLM调用或工具执行）、Edge（节点间的转换条件）。create_react_agent是LangGraph提供的高层封装，内部实现了ReAct循环的状态转换逻辑，开发者只需定义工具和提示词即可获得完整的Agent能力。

# Agentic RAG核心代码结构（简化版）
agent = create_react_agent(
    llm=model,           # 大模型实例
    tools=tool_list,     # 工具列表
    system_prompt=prompt  # 系统提示词
)
result = agent.invoke({"messages": user_query})

代码看上去简单，但它释放了模型的自主决策能力，实现了动态、灵活的检索与生成交互。很多大模型应用产品的核心逻辑，本质上就是这样的实现方式。

总结与思考

传统RAG是一条固定的流水线：切片→向量化→检索→拼接→生成。简单直接，但缺乏灵活性，无法应对检索失败或信息不完整的场景。

Agentic RAG则将检索、文件读取等能力封装为工具，赋予大模型自主决策的权利。模型可以动态规划、调用工具、观察结果、多轮迭代，直到获得足够信息后生成最终答案。这真正体现了智能体的行为模式：思考→行动→观察→再思考。

对于开发者来说，从传统RAG迁移到Agentic RAG的关键在于两点：一是将检索流程拆解为独立的工具函数，二是选择支持Function Calling的大模型并借助LangGraph等框架构建React Agent。

一句话总结：工具赋予能力，智能在于选择。真正的Agentic RAG，始于检索，成于决策。