## 01、痛点

我是老李。最近帮一个电商团队做知识库问答，需求听起来很简单：用户问“华东区上季度退款率是多少”，系统要从几十万条运营文档里找到答案。最初版本非常经典：把问题向量化，调用 similaritySearch() 拿回最相似的 3 条文档，拼到上下文里，再让大模型回答。

演示时没问题，上线后开始翻车。用户问“华东区上季度退款率是多少”，召回的前两条是《华东区退货政策说明》和《退款流程操作手册》，第三条是《上季度华东区订单汇总表》。模型看了一眼，非常流畅地回答：“上季度华东区退款率为 2.1%。” 但这个数字实际出自订单汇总表里的“退款单占比”，并不是财务口径的退款率。

我们第一个反应是换更大的模型。从 7B 换到 32B，又换到闭源旗舰，结果只是把错误答案说得更自信、更圆润。为什么？因为问题不在生成，而在检索：该来的文档没进上下文，不该来的文档抢了位置。模型再大，也只能基于错误的材料推理。

Spring AI 这两年变化很大。它不再只是一个 similaritySearch() 后拼上下文的工具箱，而是把 RAG 拆成了查询变换、检索、上下文增强等可替换模块。换句话说，我们可以像搭乐高一样把 RAG 流水线搭出来，并且能直接使用现成的 RAG 模式。这就是现在要讲这件事的原因：如果你还在用“相似度搜索 + 大模型”的旧思路，很多 RAG 错误会一直跟着你，换什么模型都救不回来。

## 02、是什么

Spring AI 当前的 RAG 能力已经模块化。它把一次检索增强生成拆成几个明确的环节：Query、Retrieve、Augment，最后才是生成。对应到 Spring AI 里，有几个核心抽象：

- QueryTransformer：负责查询变换，比如把口语问题改写成更利于检索的句子，或者扩展出多个查询。
- DocumentRetriever：负责文档检索，可以是向量检索、关键字检索，也可以是多个检索器的组合。
- ContextAugmenter：负责上下文增强，在把文档交给大模型之前，做截断、去重、标注来源等处理。
- RetrievalAugmentationAdvisor：一个更上层的入口，可以把上述模块串成一套现成可用的 RAG 模式。

也就是说，Spring AI 不再强制你走“向量搜索 -> 拼文本”这条单一路径。你可以围绕 Query 做查询改写，围绕 Retrieve 做多路召回和元数据过滤，围绕 Augment 做上下文策略。也可以直接用 Advisor，把一套经过验证的 RAG 流程嵌入到现有调用里。

这种模块化带来的最大变化是：RAG 从“一个方法调用”变成了“一条可组装、可观测的流水线”。每个环节都可以独立替换、独立测试、独立定位问题。

## 03、为什么

模块化不是为了好看，而是因为 RAG 错误的来源非常分散。

一次典型的 RAG 问答会经历：用户提问 -> 查询变换 -> 文档召回 -> 上下文组装 -> 模型生成答案。这个链路里，任何一个环节出错，都可能导致最终答案错误。比如：

- 查询变换没做好，用户问的是“退款率”，系统却去检索“退款流程”。
- 文档召回没做好，真正包含答案的文档没有进入 TopK。
- 上下文组装没做好，进了 TopK 的文档被截断，关键数字丢了。
- 生成模型没用好，文档里有正确答案，但模型没有忠实引用。

换一个更大的模型，只能改善最后两个环节中的“生成能力”，对前三个检索环节几乎没有帮助。更关键的是，如果检索已经漏掉了正确答案，大模型往往会根据错误材料“一本正经”地编一个答案，反而更难发现错误。

所以，必须把 RAG 当成一个检索系统加一个生成系统来看。模块化架构的价值，就在于让每个环节可以被单独分析、单独优化。你不需要再靠“感觉”来判断是检索不好还是生成不好，而是可以通过架构设计把问题隔离出来。

## 04、架构

我用一个简化的调用链来说明模块化后的 RAG 架构：

用户问题
  -> QueryTransformer（查询改写、扩展）
  -> DocumentRetriever（向量检索 + 元数据过滤 + TopK）
  -> ContextAugmenter（去重、截断、来源标注）
  -> 大模型生成答案

在 Spring AI 中，这三个环节可以由不同实现组合而成。比如查询重写可以用一个专门的大模型调用完成，也可以使用规则模板；检索可以是单个向量库，也可以是多个检索器并行召回后再合并；上下文增强可以做 TopK 截断、按相关度排序、注入文档元信息等。

多个 Retriever 的组合思路尤其值得关注。现实里的知识库往往不是纯语义问题。像“华东区上季度退款率”这种问题，既需要语义召回“退款率”相关文档，也需要元数据过滤“华东区”和“上季度”。如果只用向量相似度，很难同时表达语义和结构化条件。这时可以组合两个检索器：一个语义检索器负责召回“退款率”相关的指标说明，一个元数据过滤检索器负责筛选 region=华东、quarter=2024Q4 的文档。两者合并后再做 TopK，召回质量会显著提升。

这种架构的好处是：每个模块的输入输出都很明确。查询变换输出的是改写后的查询；检索器输出的是带元数据的文档列表；上下文增强输出的是生成模型真正看到的上下文。哪一段出了问题，直接看对应环节的输出即可。

## 05、实战

继续用“华东区上季度退款率是多少”这个例子。上一章里，我们的做法是直接 similaritySearch() 拿 Top3，然后拼给大模型。这次我们把它改成模块化流水线。

第一步，加入 Query Rewrite。原始问题是“华东区上季度退款率是多少”，直接向量化后，容易检索到“退款政策”“退款流程”这类文档。我们可以在查询变换环节把问题改写成：“退款率 计算公式 华东区 2024Q4 退款金额 除以 订单数”。这样语义更接近指标说明文档。

第二步，加入 Metadata Filter。在检索器上增加过滤条件：region=华东，quarter=2024Q4，doc_type=指标说明。这样可以排除大量无关文档，避免“退货政策”和“退款流程”抢位置。

第三步，设置 TopK。把召回数量从 3 提高到 10，先让更多候选文档进入上下文增强环节，再由增强模块做精排和截断。这里的关键不是无脑调大 TopK，而是先放开召回，再用后处理控制质量。

第四步，加入 Context Augment。在送进大模型之前，对候选文档做去重、按相关度排序，并给每段文档加上来源文件和更新时间。最终只保留最相关的 5 条，拼成上下文。

流程用伪代码表示如下：

```text
输入问题：华东区上季度退款率是多少

1. 查询重写
rewritten = queryTransformer.rewrite(问题)
输出：退款率 计算公式 华东区 2024Q4 退款金额 除以 订单数

2. 多路检索
语义召回 = semanticRetriever.search(rewritten, 10)
元数据过滤召回 = metadataRetriever.search(
    region=华东, quarter=2024Q4, docType=指标说明, topK=10
)

3. 合并去重
合并结果 = merger.merge(语义召回, 元数据过滤召回)

4. 上下文增强
最终上下文 = contextAugmenter.augment(合并结果)
    .去重()
    .按相关度排序()
    .保留前5条()
    .添加来源信息()
    .构建()

最终答案 = chatClient.call(rewritten, 最终上下文)
```

对比召回效果：旧的单路相似度检索里，Top5 命中包含答案的文档只有 1 条，Recall@5 约 0.2，且前两条完全无关。加入 Query Rewrite、Metadata Filter 和合并去重后，真正包含“退款率”指标定义的文档进入了前 3，Top5 命中 4 条，Recall@5 提升到 0.8。最终生成答案从错误的 2.1% 变成了基于正确文档的 3.4%，并给出了计算公式和来源。

这个例子说明：很多时候我们不需要先换模型。先把检索链路改清楚，答案质量就能大幅提升。

## 06、洞见

RAG 本质上是一个检索系统加一个生成系统。检索系统负责从海量文档里找出可能包含答案的素材；生成系统负责根据素材产出自然语言答案。两者耦合在一起，但错误来源不同。

当答案出错时，先不要急着改模型。先问一个问题：包含正确答案的文档，有没有进入最终交给模型的上下文？

如果没进入，说明问题出在检索。可能是查询改写不够好，可能是召回数量不够，可能是元数据过滤太严，也可能是排序策略不对。这时候换再大的模型也没用，因为模型根本没有看到正确答案。

如果正确答案确实在上下文里，但模型还是答错了，说明问题出在生成。可能是模型没有忠实引用文档，可能是上下文太长导致注意力分散，也可能是生成参数设置不合理。这时候才应该考虑调整模型能力或生成策略。

这个判断逻辑非常实用。它把“RAG 答错了”这种笼统问题，拆成了两个可验证的问题：检索有没有漏？生成有没有偏？

有了这个洞见，优化 RAG 就不再是玄学。你可以像排查后端接口一样排查 RAG 流水线：先看召回日志，再看生成输出。错误定位清晰了，改进方向自然就出来了。

## 07、行动

建立两套独立指标，是模块化 RAG 落地最关键的一步。

第一套指标：Retrieval Recall。它衡量检索系统有没有把包含答案的文档找回来。常见的计算方式是，在一批标注问题上，看 TopK 结果里有多少包含了“标准答案文档”。例如 Recall@5 表示每道题召回的前 5 条文档中，有几条命中了标准答案。这个指标只看检索，不看生成，可以单独衡量 Query Rewrite、Metadata Filter、TopK、多路召回等策略的效果。

第二套指标：Answer Quality。它衡量最终生成答案的质量，包括答案是否准确、是否忠实于上下文、是否包含来源引用等。可以用人工评审，也可以用自动评估模型打分。这个指标看的是生成端，和检索指标分开。

这样，每次改动都能知道改进了哪一段。比如你调整了元数据过滤规则，就应该先看 Retrieval Recall 有没有提升；如果 Recall 没变甚至下降，说明过滤条件可能有问题。如果你换了更大的模型，就应该看 Answer Quality 有没有提升，而不应该期望它改善 Recall。

具体行动清单：

1. 选一批有代表性的问题，每条标注出“标准答案文档”和“标准答案”。
2. 固定测试集，跑当前 RAG 流水线，记录 Recall@5 和 Answer Quality 基线。
3. 每次改动只动一个模块，比如只改查询重写，或只改 TopK。
4. 对比改动前后的 Recall@5，判断检索是否变好。
5. 对比改动前后的 Answer Quality，判断生成是否变好。
6. 如果 Recall 低，先优化检索；如果 Recall 高但 Answer Quality 低，再优化生成或换模型。

建立这两套指标之后，你会发现很多优化决策变得简单了。比如“要不要换更大模型”这个问题，答案很明确：先看 Recall 是否已经足够高。如果 Recall 只有 0.3，换模型基本是浪费钱；如果 Recall 已经 0.9 但 Answer Quality 只有 0.6，那才值得在生成端投入。

## 08、小结

Spring AI 的 RAG 已经从一个简单的相似度搜索加生成，发展为围绕 Query、Retrieve、Augment 的模块化架构。它可以组合查询重写、多路检索、元数据过滤、TopK 截断和上下文增强，也能通过 Advisor 直接使用现成模式。

这意味着我们不能再把 RAG 当成一个黑盒。相反，应该把它当作一条可观测、可拆解的流水线。每当答案出错，先判断错误发生在检索还是生成，再决定改哪些模块。

换一个更大的模型，不一定能解决 RAG 回答错误。如果检索漏掉了正确答案，模型越大，反而可能把错误答案说得越可信。真正有效的做法是：先用模块化架构把检索链路做扎实，再用两套独立指标持续度量检索和生成。这样，RAG 的优化才有方向，投入才有回报。

## 09、链接与概念说明

- Spring AI 官方文档：建议重点阅读“Retrieval Augmented Generation”章节，了解 QueryTransformer、DocumentRetriever、ContextAugmenter 和 RetrievalAugmentationAdvisor 的用法。
- RAG 相关论文：可查阅原始 RAG 论文以及后续关于查询改写、多路召回、重排的论文，理解检索与生成的边界。
- 向量数据库：检索召回常依赖向量数据库，需关注其元数据过滤、混合检索、TopK 等能力。
- 评估指标：Recall@K 是检索系统的常用指标；生成端可参考忠实度、答案准确率等指标。
- 后续可扩展：多路召回之外，还可以引入重排模型、查询扩展、上下文压缩等模块，继续提升 RAG 表现。

我是老李。最近帮一个电商团队做知识库问答，需求听起来很简单：用户问“华东区上季度退款率是多少”，系统要从几十万条运营文档里找到答案。最初版本非常经典：把问题向量化，调用 similaritySearch() 拿回最相似的 3 条文档，拼到上下文里，再让大模型回答。

《Spring AI 2.0实战》第10招 RAG进入模块化

Spring AI 的 RAG 已模块化，可组合查询变换、检索与上下文增强。本文通过实战对比召回效果，并说明为什么换大模型不一定解决错误，如何建立两套独立指标。

架构师

人工智能

后端

架构设计

SpringAI的RAG已从简单相似度搜索升级为模块化流水线，通过查询重写、元数据过滤、多路检索和上下文增强，显著提升召回准确率。若检索漏掉正确答案，换更大模型只会让错误更自信。建议用Recall@5和AnswerQuality双指标分别评估检索与生成，先优化检索链路，再调整生成端，才能有效解决“华东区退款率”这类问题。

向量数据库

代码解释

数据库

2026上云采购 | AI焕新·智启新局

advisor

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

SpringAI的RAG已从简单相似度搜索升级为模块化流水线，通过查询重写、元数据过滤、多路检索和上下文增强，显著提升召回准确率。若检索漏掉正确答案，换更大模型只会让错误更自信。建议用Recall@5和AnswerQuality双指标分别评估检索与生成，先优化检索链路，再调整生成端，才能有效解决“华东区退款率”这类问题...

《Spring AI 2.0实战》第10招 RAG进入模块化-腾讯云开发者社区-腾讯云

《Spring AI 2.0实战》第10招 RAG进入模块化

《Spring AI 2.0实战》第10招 RAG进入模块化

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐