你有没有遇到过这样的场景：团队花了两周把几百份 PDF 灌进向量库，又花了一周调模型参数，结果问一个具体版本号，系统还是答得牛头不对马嘴？我是老李，今天不聊模型微调，也不聊推理加速，只聊 RAG 里最容易被忽略的前半段——数据工程。过去大家一提到 RAG，第一反应是 Chat，是生成，是模型。但真正做过落地的人都知道，RAG 的第一半并不是 Chat，而是 Data Engineering。为什么现在讲？因为 Spring AI 已经给出了一套相对完整的 ETL Pipeline，正好可以帮我们把这件事说清楚。

## 01、痛点

很多团队做 RAG 的流程非常短平快：读文件、切块、调 Embedding、入库、查询。看起来每一步都有，但每一步都做得很粗。最常见的做法是把 PDF 扔给解析库，抽出一堆文本，按 500 或者 800 个字符切一段，直接送到向量库。到查询的时候，用户问“最新版本的配置项是什么”，系统召回了两段看起来相关的文本，结果一段是目录页，另一段是旧版本的更新说明。模型只能基于这些片段硬着头皮生成答案，自然牛头不对马嘴。

我见过一个比较典型的例子：团队在做内部知识库问答，数据源里有大量 Markdown 和 PDF 技术手册。PDF 解析出来的文本带着页眉页脚、重复的版权声明、翻页造成的断裂表格，还有莫名其妙的乱码。直接 Embedding 后，向量库里有大量高度相似但毫无信息量的块，真正有用的段落反而被淹没。团队第一反应是换更好的模型，换了之后发现召回还是不对；又怀疑向量库不行，换了一个，效果依旧；最后调 TopK，从 5 调到 10，召回质量反而更差，因为噪声更多了。

问题其实不在模型和向量库，而在数据管道。原始资料没有经过清洗，块与块之间没有语义边界，元数据几乎为零，出问题也没法追溯。这样的知识库，模型调用之前的质量上限已经被锁死了。

## 02、是什么

RAG 的前半段，本质上是数据工程。所谓数据工程，就是把原始资料变成可以被检索、被模型使用的高质量文本块。Spring AI 官方提供了一套 ETL Pipeline，把这件事拆成三个标准动作：读取、转换、写入，也就是 DocumentReader → DocumentTransformer → DocumentWriter。

DocumentReader 的职责是从不同来源把原始内容读进来。来源可以是本地 Markdown、PDF、Word 文档，也可以是网页、数据库记录。读进来之后，统一变成 Spring AI 里的 Document 对象。Document 由两部分组成：一部分是 pageContent，用来承载正文；另一部分是 metadata，用来描述这个文档的属性，比如标题、来源路径、更新时间、版本号、页码等。

DocumentTransformer 负责所有转换工作。常见的转换包括清洗空行、去掉页眉页脚、统一换行符、按 token 或语义边界切分文本块，以及补充 metadata。把长文档切成一个个小块的过程叫 Chunking。切分后的每个块仍然是一个 Document，可以单独 Embedding 和入库。

DocumentWriter 则是把处理好的 Document 列表写进目标存储。它通常对接向量库，比如 PgVector、Redis Stack、Milvus，或者私有云上的向量服务。Writer 会把每个块的向量和元数据一起保存，方便后续检索和过滤。

这套管线对应的是传统数据仓库里的 Extract、Transform、Load。Extract 对应 Read，Transform 对应清洗、切分、补元数据，Load 对应 Write。理解了这三个阶段的职责，就会明白为什么 RAG 不能省掉 Transform 这一步。

## 03、为什么

为什么 PDF 拆出来就直接 Embedding 往往效果不好？因为 PDF 本质上是一种展示格式，不是结构化的文本格式。解析出来的文本往往带着大量噪声，而且丢失了文档结构。页眉页脚、页码、目录、导航文字、重复的版权声明，这些内容会被当作正文进入向量库，检索时噪声比信号还多。

更麻烦的是，固定长度切分经常把完整语义切成两半。比如一个 Java 方法的签名在第一块的结尾，方法体在第二块的开头，甚至异常说明被切到了第三块。用户问这个方法会抛什么异常，系统召回的是第二块，里面只有方法体的一部分，模型只能靠猜。还有表格、代码块、列表，这些结构在 PDF 提取时很容易被拉平或错位，直接切分就更不可控。

Metadata 的缺失是另一个硬伤。没有元数据，检索时就没办法按来源、版本、模块进行过滤。同一个文档如果存在多个版本，旧版本的块和新版本的块混在一起，模型可能把旧逻辑当成新逻辑。没有页码或者锚点，即使找到了相关块，也很难核对原始出处。

Embedding 本身并不理解业务，它只是把文本映射成向量。你能把文本切得多干净、结构保留得多完整、元数据补得多齐全，直接决定了向量检索能走多远。换句话说，模型调用之前的数据质量，就是 RAG 系统的天花板。

## 04、架构

Spring AI 的 ETL Pipeline 架构其实很直接。原始文件先经过一个或多个 DocumentReader，变成 List<Document>。接着这个列表会流过一条 Transformer 链，链上的每个 Transformer 都做一件事：清洗、切分、补元数据、改结构。最后，处理好的 Document 列表交给 DocumentWriter，写入向量库或者其它存储。

这套架构的关键是 Document 对象。Document 是数据管道里的统一货币。不管原始来源是 PDF 还是 Markdown，进了管道都变成 Document。Document 的 pageContent 存正文，metadata 存描述信息。所有 Transformer 都基于这个统一结构工作，所以可以自由组合。

常见 Transformer 可以分成几类。一类是清洗类，比如去掉多余空行、统一换行、删除页眉页脚。一类是切分类，比如 TokenTextSplitter，按 token 数量切块，支持 overlap 防止语义断开；也有的按 Markdown 标题层级切分，结构更好。一类是元数据增强类，比如从文件名、目录路径、文档标题里提取 source、module、version，写进 metadata。还有一类是内容增强类，比如给长文本块生成简短摘要，作为额外字段保存。

流程上可以这样理解：

原始文件 → DocumentReader → List<Document> → Transformer 链 → List<Document> → VectorStoreWriter → 向量库

这个架构和传统 ETL 很像，但对象变成了非结构化的文档。它的好处是每个环节职责单一，清洗、切分、补元数据可以独立测试，也可以复用。你在一个项目里写的 PDF 清洗器，换个数据源还能用；你定义的 Markdown 切分策略，改改参数就能适配另一个知识库。

## 05、实战

拿一个实际场景来说。假设我们要给内部研发团队做一个技术知识库，数据源是一组 Markdown 设计文档和几份 PDF 版本发布说明。目标是让同事可以直接问“某某模块最新版的配置项是什么”“这个异常在哪个版本引入的”。我们按 Spring AI 的管道一步步来。

第一步，定义读取器。Markdown 文件用文本读取器直接读目录；PDF 文件用 PDF 读取器，指定保留页码信息。读入之后，所有内容都变成 Document，metadata 里可以先放上原始路径。

第二步，清洗。写一个清洗 Transformer，循环处理每个 Document。去空行、统一换行符、移除 PDF 页眉页脚和固定版权声明。如果发现文本里有乱码，比如 � 这种字符，直接替换或删除。对于表格拉平的问题，如果无法还原结构，可以在清洗时保留原始换行，不做强行拼接。清洗完的 Document 更适合后续切分。

第三步，切分。Markdown 文档适合按标题层级切分，比如把每个二级标题下的内容作为一个块，这样每个块有独立的语义主题。PDF 文档由于结构信息丢失，可以先用 TokenTextSplitter 按约 500 token 切，overlap 设 50 token，保证跨块的上下文不断裂。这里要特别小心，固定长度切分不一定是最终方案，切完后可以抽样检查，发现问题就调整切分参数或者改用语义切分。

第四步，补 metadata。对每个块，写入 source 文档路径、页码或者 Markdown 标题、模块名、版本号、更新时间、文档类型。比如从目录结构里提取模块名，从文件名里提取版本号。metadata 的 key 要统一，比如 source、page、section、version、updated_at。这一步非常重要，后续检索过滤和可追溯都靠它。

第五步，Embedding。把所有 Document 交给 Embedding 模型，生成向量。这里可以选择合适的向量模型，一般用与业务语言接近的通用模型先跑通。向量维度、归一化方式要和向量库匹配。

第六步，入库。用 VectorStoreWriter 批量写入向量库。每个向量记录里同时保存 metadata，方便后续用 source 或 version 做过滤。入库完成后做一次抽样查询，看看相似块是否合理，不合理就回到清洗或切分环节调整。

示意代码大致是：

```java
var reader = new FilesystemDocumentReader(“./docs”);
var cleaner = new CleaningTransformer();
var splitter = new TokenTextSplitter(500, 50, 10, 10000, true);
var enricher = new MetadataEnricher(doc -> {
    doc.getMetadata().put(“source”, doc.getId());
    doc.getMetadata().put(“version”, “2025.06”);
});
var writer = new VectorStoreWriter(vectorStore);

List<Document> docs = reader.read();
docs = cleaner.apply(docs);
docs = splitter.apply(docs);
docs = enricher.apply(docs);
writer.write(docs);
```

注意这里只是示意，实际使用时可以根据项目封装成配置化的管道。

## 06、洞见

Chunk 是越小召回越准吗？答案是否定的。很多人觉得块越小，信息越精炼，检索就越准。但实际上，块太小会让语义完整被破坏。一个函数的说明、参数、返回值、异常列表如果被切成好几块，检索时可能只召回其中一小段，模型看到的上下文是不完整的，反而更容易生成错误答案。

块太大也不好。大块里会混入太多无关内容，检索时虽然命中了，但有用的信息被稀释，模型需要从一大段文字里找答案，难度增加，而且容易把噪声也读进去。召回准不准，不是单独看块的大小，而是看块是否保留了完整的语义单元，并且和用户的问题粒度匹配。

一个更好的做法是优先考虑语义边界。能按标题、段落、代码块、列表项切分，就不要硬按字符数切。固定长度切分只适合结构已经很规整的纯文本。对于技术文档，最好的切分粒度通常是一个小节，比如一个 API 的完整描述，或者一个配置项的说明加示例。具体多大可以通过实验调出来。

还有一点更关键：RAG 的质量上限经常在模型调用之前就被 ETL 决定了。模型只能基于你喂进去的块来生成答案。如果数据管道没有清洗干净、没有补全元数据、切分没有语义边界，模型再强也补不出本来就不存在的信息。我们常犯的错误是拼命优化模型和检索参数，却不肯回头把数据管道做扎实。

## 07、行动

落到行动上，有一件事值得马上做：为知识库建立“原始文档 → Chunk → Vector → Source”的可追溯链。

具体来说，每个 Chunk 的 metadata 里必须有 source 字段，记录它来自哪个原始文档；有 page 或者 anchor 字段，记录它在原始文档里的位置；有 version 和 updated_at 字段，记录文档版本和更新时间；有 section 或 heading 字段，记录它所属的章节。这样任何一个向量被召回，都能快速定位到原始内容。

入库时，不要把原始文档丢掉。可以保留一份原始文档的备份，或者把清洗后的中间结果保存为结构化文件。向量库只存向量和 Chunk 的 metadata，需要回溯时再用 source 和 page 去原始文档里找原文。

查询返回结果时，把命中的 Chunk 和它的 source 一起返回给前端。这样用户不仅能看到答案，还能看到答案依据的出处。出现错误答案时，可以先查 tracing 记录，看是召回了哪些块、块来自哪里、清洗和切分有没有问题。

最后，把 ETL 管道配置化和版本化。每个文档版本变化时，重新跑一遍读取、清洗、切分、Embedding、入库流程，保证向量库和源文档一致。定期抽样评估召回质量，发现问题就回到清洗或切分环节调优，而不是先换模型。

## 08、小结

RAG 不是只有 Chat 这一半，Data Engineering 同样重要。Spring AI 提供的 ETL Pipeline 把读取、转换、写入拆得清清楚楚，让我们有条件把数据管道做扎实。理解 Extract、Transform、Load、Document、Metadata、Chunking 的职责，是做好 RAG 的地基。PDF 直接 Embedding 效果差，不是 Embedding 不行，而是前面的清洗和切分没做好。Chunk 也不是越小越好，语义完整和边界清晰才是关键。把可追溯链建起来，才能让每一次回答都有据可查。地基打好了，上面的模型才能盖得稳。

## 09、链接与概念说明

概念说明：

- ETL：Extract、Transform、Load 的缩写，数据工程里的经典流程，这里用来描述 RAG 的数据准备。
- Document：Spring AI 中表示一份原始文档或一个切分块的对象，包含 pageContent 和 metadata。
- Metadata：描述文档属性的键值对，如 source、page、version、updated_at，对过滤和追溯至关重要。
- Chunking：把长文档切成小块的过程，切分粒度和策略直接影响召回质量。
- Embedding：把文本块转成向量表示，用于相似度检索。

参考链接：

- Spring AI 官方文档：https://spring.io/projects/spring-ai
- RAG 经典论文：Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks
- 向量库选型可参考 PgVector、Redis Stack、Milvus 的官方文档

你有没有遇到过这样的场景：团队花了两周把几百份 PDF 灌进向量库，又花了一周调模型参数，结果问一个具体版本号，系统还是答得牛头不对马嘴？我是老李，今天不聊模型微调，也不聊推理加速，只聊 RAG 里最容易被忽略的前半段——数据工程。过去大家一提到 RAG，第一反应是 Chat，是生成，是模型。但真正做过落地的人都知道，RAG 的第一半并不是 Chat，而是 Data Engineering。为什么现在讲？因为 Spring AI 已经给出了一套相对完整的 ETL Pipeline，正好可以帮我们把这件事说清楚。

《Spring AI 2.0实战》第8招 文档怎么进向量库

RAG 的质量上限常在模型调用前被数据管道决定，本文用 Spring AI 的 ETL 管线讲清读取、清洗、切分、补元数据、入库与可追溯。

架构师

人工智能

后端

RAG落地效果差，往往不是模型或向量库的问题，而是ETL数据管道没做好。本文详解SpringAI的ETLPipeline，通过文档读取、清洗、语义切分、元数据补全等步骤，建立“原始文档→Chunk→Vector→Source”的可追溯链，从源头解决检索召回不准的痛点，提升问答质量。

数据仓库

数据管道

代码解释

数据库

私有云

Java

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

bigdata-class

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

《Spring AI 2.0实战》第8招 文档怎么进向量库-腾讯云开发者社区-腾讯云

《Spring AI 2.0实战》第8招文档怎么进向量库

《Spring AI 2.0实战》第8招文档怎么进向量库

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring AI 2.0实战》第8招 文档怎么进向量库

《Spring AI 2.0实战》第8招 文档怎么进向量库

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring AI 2.0实战》第8招文档怎么进向量库

《Spring AI 2.0实战》第8招文档怎么进向量库