用 Spring AI 走通 RAG：从文档切割到检索增强的实战拆解

源码定义也很清楚：

ETL 三步走

Spring AI 的 ETL 流程可以用一张图概括：

三大组件的关系：DocumentReader 负责从各种来源加载文档，DocumentTransformer 负责对文档做加工（切分、补元数据等），DocumentWriter 负责把最终文档写入目标存储。完整的类层次如下：

抽取（Extract）

DocumentReader 接口扩展了 Supplier<List<Document>>，核心方法就是 get()，返回一个文档列表。

get() 的内部实现依赖各个读取器对数据源的解析：

深入到 DocumentReader 的具体实现里，能看到它们是怎么把不同格式的数据转成 Document 的。核心逻辑是：调用对应格式的实现类读取文本，如果不是纯文本，就把媒体类型等信息也抽出来，设置默认的元信息，然后用内容和元信息实例化一个 Document 对象。

Spring AI 内置了多种 Reader 实现，覆盖了常见的文档格式：

• JsonReader：读 JSON，支持 JSON Pointer 精准提取字段
• TextReader：纯文本
• MarkdownReader：Markdown
• PDFReader：基于 PdfBox，有按页（PagePdfDocumentReader）和按段落（ParagraphPdfDocumentReader）两种
• HtmlReader：基于 jsoup
• TikaDocumentReader：基于 Apache Tika，几乎什么格式都吃

用 JsonReader 的时候，可以用 JSON Pointer 直接指定要加载哪部分数据：

@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();
    }

    List<Document> loadJsonWithSpecificFields() {
        JsonReader jsonReader = new JsonReader(this.resource, "description", "features");
        return jsonReader.get();
    }

    List<Document> loadJsonWithPointer() {
        JsonReader jsonReader = new JsonReader(this.resource);
        return jsonReader.get("/items");
    }
}

如果内置的 Reader 不够用，Spring AI Alibaba 社区还贡献了不少扩展，比如飞书文档、B 站视频字幕、邮件、GitHub 仓库等。

自己实现一个 Reader 也不复杂。以邮件读取器为例，思路就是解析邮件内容，把正文当作文本，把发件人、主题、时间等放进元数据，然后封装成 Document 对象。

邮件解析器的核心代码大致是这样的：

public class MsgEmailParser {
    public static Document convertToDocument(MsgEmailElement element) {
        Map<String, Object> metadata = new HashMap<>();
        if (StringUtils.hasText(element.getSubject())) {
            metadata.put("subject", element.getSubject());
        }
        // ... 其他元数据和内容提取
        String content = StringUtils.hasText(element.getText()) ? element.getText() : "";
        return new Document(content, metadata);
    }
}

读取器的 get() 方法里遍历所有邮件，调用解析器，收集成 List 返回就完事了。

转换（Transform）

DocumentTransformer 接口实现了 Function<List<Document>, List<Document>>，负责对文档做流水线加工。

转换是影响 RAG 效果的关键一步。Spring AI 提供了三类主要的 Transformer。

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);
    }
}

构造参数可以控制块大小、最小字符数、块数量上限、是否保留分隔符等。内部流程大致是：先用 CL100K_BASE 编码文本，按默认 800 token 的大小分块，然后在每个块的约 350 字符之后找个句子边界断开，最后把长度大于 5 个 token 的块收集起来，直到达到最大块数。

MetadataEnricher 元数据增强器

这类转换器不改文档内容，只是给文档的元数据字段补上一些有用信息，方便后续检索。常用的有两个：

• KeywordMetadataEnricher：调大模型提取关键词，放入元数据。
• SummaryMetadataEnricher：让大模型为每个文档块生成摘要，还可以把前一块、后一块的摘要也带上，让摘要更连贯。

示例：

@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);
    }
}

ContentFormatter 内容格式化工具

DefaultContentFormatter 可以把文档内容和元数据拼成一个结构化字符串，同时按需过滤掉某些元数据字段，这对最终送入大模型的提示词很有用。

它用 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 流程里，格式化工具可以帮我们剔除无关元数据、统一格式，让模型更容易理解。

加载（Load）

DocumentWriter 接口继承了 Consumer<List<Document>>，负责把最终文档写入目标存储。Spring AI 自带两种实现：

• FileDocumentWriter：写到文件系统，可以控制路径、是否追加、元数据模式等。
• VectorStoreWriter：实际上就是 VectorStore 接口本身，因为 VectorStore 也继承了 DocumentWriter。所以直接把文档列表传给 vectorStore.accept(docs) 就行。

写法通常是这样：

@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 串起来

一个完整的 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())));

这就把原始文档加工成了可供检索的向量化知识片段。

向量转换与存储

向量数据库是 RAG 的基石。Spring AI 通过 VectorStore 接口统一了各种向量数据库的访问。

接口定义很简洁：

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

其实 VectorStore 继承自 DocumentWriter，所以也承担着'写入'的职责。Spring AI 已经为 Milvus、Redis、PGVector、Elasticsearch 等主流向量数据库提供了 Starter，集成时引入对应依赖，配好连接信息，在代码里注入 VectorStore 就能直接用。

到这里，我们梳理了 Spring AI 对 RAG 索引构建阶段的支持。后面的内容会聚焦检索策略的优化、怎么减少幻觉、以及高级 RAG 架构的取舍——这些在实际项目中才会碰到的坑和权衡。