SpringAI 深入解析 RAG 检索增强工作流程与调优

• 文档收集和切割
• 向量转换和存储
• 文档过滤和检索
• 查询增强和关联

文档收集和切割 - ETL

文档收集和切割阶段，我们要对自己准备好的知识库文档进行处理，然后保存到向量数据库中。这个过程俗称 ETL（抽取、转换、加载），Spring AI 提供了对 ETL 的支持，参考 官方文档。

文档

什么是 Spring AI 中的文档呢？文档不仅仅包含文本，还可以包含一系列元信息和多媒体附件：

查看源码：

ETL

在 Spring AI 中，对 Document 的处理通常遵循以下流程：

1. 读取文档：使用 DocumentReader 组件从数据源（如本地文件、网络资源、数据库等）加载文档。
2. 转换文档：根据需求将文档转换为适合后续处理的格式，比如去除冗余信息、分词、词性标注等，可以使用 DocumentTransformer 组件实现。
3. 写入文档：使用 DocumentWriter 将文档以特定格式保存到存储中，比如将文档以嵌入向量的形式写入到向量数据库，或者以键值对字符串的形式保存到 Redis 等 KV 存储中。

流程如图：

我们利用 Spring AI 实现 ETL，核心就是要学习 DocumentReader、DocumentTransformer、DocumentWriter 三大组件。完整的 ETL 类图如下，先简单了解一下即可，下面分别来详细讲解这 3 大组件：

抽取（Extract）

Spring AI 通过 DocumentReader 组件实现文档抽取，也就是把文档加载到内存中。

看下源码，DocumentReader 接口实现了 Supplier<List<Document>> 接口：主要负责从各种数据源读取数据并转换为 Document 对象集合。

实现了 Supplier<List<Document>> 接口，就可以调用 Document 就可以调用父类的定义的通用方法：get()

查看 DocumentReader 的具体实现类的源码，查看它们是如何抽取文档，并转换为 Document 对象的：

也就是说，在抽取文档的过程中，调用 DocumentReader 对应格式的实现类，抽取文档中的文本，如果不是 textReader，就可能包含一些媒体类型的信息，需要将这些信息一并抽取，并设置一些默认的元信息；将文档内容（文本、媒体信息）、元信息作为参数实例一个 Document 对象。

实际开发中，我们可以直接使用 Spring AI 内置的多种 DocumentReader 实现类，用于处理不同类型的数据源：

1. JsonReader：读取 JSON 文档
2. TextReader：读取纯文本文件
3. MarkdownReader：读取 Markdown 文件
4. PDFReader：读取 PDF 文档，基于 Apache PdfBox 库实现
   • PagePdfDocumentReader：按照分页读取 PDF
   • ParagraphPdfDocumentReader：按照段落读取 PDF
5. HtmlReader：读取 HTML 文档，基于 jsoup 库实现
6. TikaDocumentReader：基于 Apache Tika 库处理多种格式的文档，更灵活

以 JsonReader 为例，支持 JSON Pointers 特性，能够快速指定从 JSON 文档中提取哪些字段和内容：

{
 "帅哥":{
  "name": "小雷"
 }
}

Spring AI 的 JsonReader 可以通过 JSON Pointers 特性，通过 帅哥.name 一次性读取到 name 中的值：

// 从 classpath 下的 JSON 文件中读取文档
@Component
class MyJsonReader {
    private final Resource resource;

    MyJsonReader(@Value("classpath:products.json") Resource resource) {
        this.resource = resource;
    }

    // 基本用法
    List<Document> loadBasicJsonDocuments() {
        JsonReader jsonReader = new JsonReader(this.resource);
        return jsonReader.get();
    }

    // 指定使用哪些 JSON 字段作为文档内容
    List<Document> loadJsonWithSpecificFields() {
        JsonReader jsonReader = new JsonReader(this.resource, "description", "features");
        return jsonReader.get();
    }

    // 使用 JSON 指针精确提取文档内容
    List<Document> loadJsonWithPointer() {
        JsonReader jsonReader = new JsonReader(this.resource);
        return jsonReader.get("/items"); // 提取 items 数组内的内容
    }
}

更多的文档读取器等用到的时候再了解用法即可。

此外，Spring AI Alibaba 官方社区提供了 更多的文档读取器，比如加载飞书文档、提取 B 站视频信息和字幕、加载邮件、加载 GitHub 官方文档、加载数据库等等。

💡 思考：如果让你自己实现一个 DocumentReader 组件，你会怎么实现呢？

当然是先看官方 开源的代码仓库，看看大佬们是怎么实现的：

比如一个邮件文档读取器的实现其实并不难，核心代码就是解析邮件文档并且转换为 Document 列表：

邮件解析器的实现：

public class MsgEmailParser {
    private MsgEmailParser() {
        // Private constructor to prevent instantiation
    }

    /**
     * Convert MsgEmailElement to Document
     * @param element MSG email element
     * @return Document object
     */
    public static Document convertToDocument(MsgEmailElement element) {
        if (element == null) {
            throw new IllegalArgumentException("MsgEmailElement cannot be null");
        }
        // Build metadata
        Map<String, Object> metadata = new HashMap<>();
        // Add metadata with null check
        if (StringUtils.hasText(element.getSubject())) {
            metadata.put("subject", element.getSubject());
        }
        // ... 省略更多元信息的设置
        // Create Document object with content null check
        String content = StringUtils.hasText(element.getText()) ? element.getText() : "";
        return new Document(content, metadata);
    }
}

邮件解析器获取文档的原理，就是以邮件中的一些信息（收信人、发信人等…）作为元信息，抽取出邮件的文本，结合元信息，实例一个 Document 对象；这个对象作为解析结果返回；

邮件文档读取器中的 get() 方法，会接收所有的解析结果，集成一个列表对象，作为文档对象列表，并返回，就实现了单次抽取一些邮件，转为 Document 的功能；

转换（Transform）

Spring AI 通过 DocumentTransformer 组件实现文档转换。看下源码：

DocumentTransformer 接口实现了 Function<List<Document>, List<Document>> 接口，负责将一组文档转换为另一组文档。

public interface DocumentTransformer extends Function<List<Document>, List<Document>> {
    default List<Document> transform(List<Document> documents) {
        return apply(documents);
    }
}

文档转换是保证 RAG 效果的核心步骤，也就是如何将大文档，合理拆分为便于检索的知识碎片，Spring AI 提供了多种 DocumentTransformer 实现类，可以简单分为 3 类。

1. TextSplitter 文本分割器

其中 TextSplitter 是文本分割器的基类，提供了分割单词的流程方法：

TokenTextSplitter 是其实现类，基于 Token 的文本分割器。它考虑了语义边界（比如句子结尾）来创建有意义的文本段落，是成本较低的文本切分方式。

@Component
class MyTokenTextSplitter {
    public List<Document> splitDocuments(List<Document> documents) {
        TokenTextSplitter splitter = new TokenTextSplitter();
        return splitter.apply(documents);
    }

    public List<Document> splitCustomized(List<Document> documents) {
        TokenTextSplitter splitter = new TokenTextSplitter(1000, 400, 10, 5000, true);
        return splitter.apply(documents);
    }
}

TokenTextSplitter 提供了两种构造函数选项：

1. TokenTextSplitter()：使用默认设置创建分割器。
2. TokenTextSplitter(int defaultChunkSize, int minChunkSizeChars, int minChunkLengthToEmbed, int maxNumChunks, boolean keepSeparator)：使用自定义参数创建分割器，通过调整参数，可以控制分割的粒度和方式，适应不同的应用场景。

参数说明（无需记忆）：

• defaultChunkSize：每个文本块的目标大小（以 token 为单位，默认值：800）。
• minChunkSizeChars：每个文本块的最小大小（以字符为单位，默认值：350）。
• minChunkLengthToEmbed：要被包含的块的最小长度（默认值：5）。
• maxNumChunks：从文本中生成的最大块数（默认值：10000）。
• keepSeparator：是否在块中保留分隔符（如换行符）（默认值：true）。

官方文档有对 Token 分词器工作原理的详细解释，可以简单了解下：

1. 使用 CL100K_BASE 编码将输入文本编码为 token。
2. 根据 defaultChunkSize 将编码后的文本分割成块。
3. 对于每个块：
   • 将块解码回文本。
   • 尝试在 minChunkSizeChars 之后找到合适的断点（句号、问号、感叹号或换行符）。
   • 如果找到断点，则在该点截断块。
   • 修剪块并根据 keepSeparator 设置选择性地删除换行符。
   • 如果生成的块长度大于 minChunkLengthToEmbed，则将其添加到输出中。
4. 这个过程会一直持续到所有 token 都被处理完或达到 maxNumChunks 为止。
5. 如果剩余文本长度大于 minChunkLengthToEmbed，则会作为最后一个块添加。

2. MetadataEnricher 元数据增强器

元数据增强器的作用是为文档补充更多的元信息，便于后续检索，而不是改变文档本身的切分规则。包括：

• KeywordMetadataEnricher：使用 AI 提取关键词并添加到元数据
• SummaryMetadataEnricher：使用 AI 生成文档摘要并添加到元数据。不仅可以为当前文档生成摘要，还能关联前一个和后一个相邻的文档，让摘要更完整。

示例代码：

@Component
class MyDocumentEnricher {
    private final ChatModel chatModel;

    MyDocumentEnricher(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    // 关键词元信息增强器
    List<Document> enrichDocumentsByKeyword(List<Document> documents) {
        KeywordMetadataEnricher enricher = new KeywordMetadataEnricher(this.chatModel, 5);
        return enricher.apply(documents);
    }

    // 摘要元信息增强器
    List<Document> enrichDocumentsBySummary(List<Document> documents) {
        SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel, List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));
        return enricher.apply(documents);
    }
}

3. ContentFormatter 内容格式化工具

用于统一文档内容格式。我们不妨看它的实现类 DefaultContentFormatter 的源码来了解他的功能：

主要提供了 3 类功能：

1. 文档格式化：将文档内容与元数据，合并成特定格式的字符串，以便于后续处理。
2. 元数据过滤：根据不同的元数据模式（MetadataMode）筛选需要保留的元数据项：
   • ALL：保留所有元数据
   • NONE：移除所有元数据
   • INFERENCE：用于推理场景，排除指定的推理元数据
   • EMBED：用于嵌入场景，排除指定的嵌入元数据
3. 自定义模板：支持自定义以下格式：
   • 元数据模板：控制每个元数据项的展示方式
   • 元数据分隔符：控制多个元数据项之间的分隔方式
   • 文本模板：控制元数据和内容如何结合

该类采用 Builder 模式创建实例，使用示例：

DefaultContentFormatter formatter = DefaultContentFormatter.builder()
    .withMetadataTemplate("{key}: {value}")
    .withMetadataSeparator("\n")
    .withTextTemplate("{metadata_string}\n\n{content}")
    .withExcludedInferenceMetadataKeys("embedding", "vector_id")
    .withExcludedEmbedMetadataKeys("source_url", "timestamp")
    .build();
// 使用格式化器处理文档
String formattedText = formatter.format(document, MetadataMode.INFERENCE);

在 RAG 系统中，这个格式化器可以有下面的作用：

1. 提供上下文：将元数据（如文档来源、时间、标签等）与内容结合，丰富大语言模型的上下文信息
2. 过滤无关信息：通过排除特定元数据，减少噪音，提高检索和生成质量
3. 场景适配：为不同场景（如推理和嵌入）提供不同的格式化策略
4. 结构化输出：为 AI 模型提供结构化的输入，使其能更好地理解和处理文档内容

加载（Load）

Spring AI 通过 DocumentWriter 组件实现文档加载（写入）。

DocumentWriter 接口实现了 Consumer<List<Document>> 接口，负责将处理后的文档写入到目标存储中：

Spring AI 提供了 2 种内置的 DocumentWriter 实现：

1. FileDocumentWriter：将文档写入到文件系统

@Component
class MyDocumentWriter {
    public void writeDocuments(List<Document> documents) {
        FileDocumentWriter writer = new FileDocumentWriter("output.txt", true, MetadataMode.ALL, false);
        writer.accept(documents);
    }
}

2. VectorStoreWriter：将文档写入到向量数据库

@Component
class MyVectorStoreWriter {
    private final VectorStore vectorStore;

    MyVectorStoreWriter(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    public void storeDocuments(List<Document> documents) {
        vectorStore.accept(documents);
    }
}

当然，你也可以同时将文档写入多个存储，只需要创建多个 Writer 或者自定义 Writer 即可。

ETL 流程示例

将上述 3 大组件组合起来，可以实现完整的 ETL 流程：

// 抽取：从 PDF 文件读取文档
PDFReader pdfReader = new PagePdfDocumentReader("knowledge_base.pdf");
List<Document> documents = pdfReader.read();

// 转换：分割文本并添加摘要
TokenTextSplitter splitter = new TokenTextSplitter(500, 50);
List<Document> splitDocuments = splitter.apply(documents);
SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel, List.of(SummaryType.CURRENT));
List<Document> enrichedDocuments = enricher.apply(splitDocuments);

// 加载：写入向量数据库
vectorStore.write(enrichedDocuments);
// 或者使用链式调用
vectorStore.write(enricher.apply(splitter.apply(pdfReader.read())));

通过这种方式，我们完成了从原始文档到向量数据库的整个 ETL 过程，为后续的检索增强生成提供了基础。

向量转换和存储

上一节教程中有介绍过，向量存储是 RAG 应用中的核心组件，它将文档转换为向量（嵌入）并存储起来，以便后续进行高效的相似性搜索。

Spring AI 官方 提供了向量数据库接口 VectorStore 和向量存储整合包，帮助开发者快速集成各种第三方向量存储，比如 Milvus、Redis、PGVector、Elasticsearch 等。

VectorStore 接口介绍

VectorStore 是 Spring AI 中用于与向量数据库交互的核心接口，它继承自 DocumentWriter，主要提供以下功能：

public interface VectorStore extends DocumentWriter {
    default String getName() {
        return this.getClass().getSimpleName();
    }
    void add(List<Document> documents);
}