ETL 管道

提取、转换和加载 (ETL) 框架是检索增强生成 (RAG) 用例中数据处理的主干。spring-doc.cadn.net.cn

ETL 管道编排从原始数据源到结构化向量存储的流程,确保数据处于最佳格式,以便 AI 模型进行检索。spring-doc.cadn.net.cn

RAG 用例是文本,通过从数据主体中检索相关信息来提高生成输出的质量和相关性,从而增强生成模型的功能。spring-doc.cadn.net.cn

API 概述

ETL 管道创建、转换和存储Document实例。spring-doc.cadn.net.cn

Spring AI 消息 API

Document类包含文本、元数据和可选的 AdditionAll 媒体类型,如图像、音频和视频。spring-doc.cadn.net.cn

ETL 管道有三个主要组件:spring-doc.cadn.net.cn

Document类内容是在 PDF、文本文件和其他文档类型的帮助下创建的DocumentReader.spring-doc.cadn.net.cn

要构建简单的 ETL 管道,您可以将每种类型的实例链接在一起。spring-doc.cadn.net.cn

ETL 管道

假设我们有这三种 ETL 类型的以下实例spring-doc.cadn.net.cn

要执行将数据基本加载到 Vector Database 中以用于 Retrieval Augmented Generation 模式的作,请使用以下 Java 函数样式语法代码。spring-doc.cadn.net.cn

vectorStore.accept(tokenTextSplitter.apply(pdfReader.get()));

或者,您可以使用对域更自然地表达的方法名称spring-doc.cadn.net.cn

vectorStore.write(tokenTextSplitter.split(pdfReader.read()));

ETL 接口

ETL 管道由以下接口和实现组成。 详细的 ETL 类图显示在 ETL 类图部分中。spring-doc.cadn.net.cn

文档阅读器

提供来自不同来源的文档源。spring-doc.cadn.net.cn

public interface DocumentReader extends Supplier<List<Document>> {

    default List<Document> read() {
		return get();
	}
}

文档Transformer

在处理工作流中转换一批文档。spring-doc.cadn.net.cn

public interface DocumentTransformer extends Function<List<Document>, List<Document>> {

    default List<Document> transform(List<Document> transform) {
		return apply(transform);
	}
}

文档编写器

管理 ETL 流程的最后阶段,准备要存储的文档。spring-doc.cadn.net.cn

public interface DocumentWriter extends Consumer<List<Document>> {

    default void write(List<Document> documents) {
		accept(documents);
	}
}

ETL 类图

下面的类图说明了 ETL 接口和实现。spring-doc.cadn.net.cn

ETL 类图

文档读者

JSON 格式

JsonReader处理 JSON 文档,并将其转换为Document对象。spring-doc.cadn.net.cn

@Component
class MyJsonReader {

	private final Resource resource;

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

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

构造函数选项

JsonReader提供了几个构造函数选项:spring-doc.cadn.net.cn

  1. JsonReader(Resource resource)spring-doc.cadn.net.cn

  2. JsonReader(Resource resource, String…​ jsonKeysToUse)spring-doc.cadn.net.cn

  3. JsonReader(Resource resource, JsonMetadataGenerator jsonMetadataGenerator, String…​ jsonKeysToUse)spring-doc.cadn.net.cn

参数

行为

JsonReader按如下方式处理 JSON 内容:spring-doc.cadn.net.cn

使用 JSON 指针

JsonReader现在支持使用 JSON 指针检索 JSON 文档的特定部分。此功能允许您轻松地从复杂的 JSON 结构中提取嵌套数据。spring-doc.cadn.net.cn

get(String pointer)方法
public List<Document> get(String pointer)

此方法允许您使用 JSON 指针检索 JSON 文档的特定部分。spring-doc.cadn.net.cn

参数
  • pointer:一个 JSON 指针字符串(如 RFC 6901 中所定义),用于在 JSON 结构中查找所需的元素。spring-doc.cadn.net.cn

返回值
行为
JsonReader jsonReader = new JsonReader(resource, "description");
List<Document> documents = this.jsonReader.get("/store/books/0");

示例 JSON 结构

[
  {
    "id": 1,
    "brand": "Trek",
    "description": "A high-performance mountain bike for trail riding."
  },
  {
    "id": 2,
    "brand": "Cannondale",
    "description": "An aerodynamic road bike for racing enthusiasts."
  }
]

在此示例中,如果JsonReader配置了"description"作为jsonKeysToUse,它将创建Document对象,其中 content 是数组中每辆 bike 的 “description” 字段的值。spring-doc.cadn.net.cn

笔记

发短信

TextReader处理纯文本文档,将它们转换为Document对象。spring-doc.cadn.net.cn

@Component
class MyTextReader {

    private final Resource resource;

    MyTextReader(@Value("classpath:text-source.txt") Resource resource) {
        this.resource = resource;
    }

	List<Document> loadText() {
		TextReader textReader = new TextReader(this.resource);
		textReader.getCustomMetadata().put("filename", "text-source.txt");

		return textReader.read();
    }
}

构造函数选项

TextReader提供两个构造函数选项:spring-doc.cadn.net.cn

  1. TextReader(String resourceUrl)spring-doc.cadn.net.cn

  2. TextReader(Resource resource)spring-doc.cadn.net.cn

参数

配置

  • setCharset(Charset charset):设置用于读取文本文件的字符集。默认值为 UTF-8。spring-doc.cadn.net.cn

  • getCustomMetadata():返回一个可变映射,您可以在其中为文档添加自定义元数据。spring-doc.cadn.net.cn

行为

TextReader按如下方式处理文本内容:spring-doc.cadn.net.cn

笔记

  • TextReader将整个文件内容读取到内存中,因此它可能不适合非常大的文件。spring-doc.cadn.net.cn

  • 如果您需要将文本拆分为较小的块,您可以使用文本拆分器,例如TokenTextSplitter阅读文档后:spring-doc.cadn.net.cn

List<Document> documents = textReader.get();
List<Document> splitDocuments = new TokenTextSplitter().apply(this.documents);
  • Reader 使用 Spring 的Resourceabstraction 的 API 中读取,允许它从各种来源(类路径、文件系统、URL 等)读取。spring-doc.cadn.net.cn

  • 自定义元数据可以添加到读者使用getCustomMetadata()方法。spring-doc.cadn.net.cn

Markdown

MarkdownDocumentReader处理 Markdown 文档,将它们转换为Document对象。spring-doc.cadn.net.cn

@Component
class MyMarkdownReader {

    private final Resource resource;

    MyMarkdownReader(@Value("classpath:code.md") Resource resource) {
        this.resource = resource;
    }

    List<Document> loadMarkdown() {
        MarkdownDocumentReaderConfig config = MarkdownDocumentReaderConfig.builder()
            .withHorizontalRuleCreateDocument(true)
            .withIncludeCodeBlock(false)
            .withIncludeBlockquote(false)
            .withAdditionalMetadata("filename", "code.md")
            .build();

        MarkdownDocumentReader reader = new MarkdownDocumentReader(this.resource, config);
        return reader.get();
    }
}

MarkdownDocumentReaderConfig允许您自定义 MarkdownDocumentReader 的行为:spring-doc.cadn.net.cn

  • horizontalRuleCreateDocument:设置为true,Markdown 中的水平线将创建新的Document对象。spring-doc.cadn.net.cn

  • includeCodeBlock:设置为true,则代码块将包含在相同的Document作为周围的文本。什么时候false,代码块创建单独的Document对象。spring-doc.cadn.net.cn

  • includeBlockquote:设置为true,blockquotes 将包含在相同的Document作为周围的文本。什么时候false,块引用创建单独的Document对象。spring-doc.cadn.net.cn

  • additionalMetadata:允许您将自定义元数据添加到所有创建的Document对象。spring-doc.cadn.net.cn

示例文档:code.md

This is a Java sample application:

```java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
```

Markdown also provides the possibility to `use inline code formatting throughout` the entire sentence.

---

Another possibility is to set block code without specific highlighting:

```
./mvnw spring-javaformat:apply
```

行为:MarkdownDocumentReader 处理 Markdown 内容并根据配置创建 Document 对象:spring-doc.cadn.net.cn

Reader 在 Document 对象的内容中保留内联代码、列表和文本样式等格式。spring-doc.cadn.net.cn

PDF 页面

PagePdfDocumentReader使用 Apache PdfBox 库解析 PDF 文档spring-doc.cadn.net.cn

使用 Maven 或 Gradle 将依赖项添加到您的项目中。spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>

或发送到您的 Gradlebuild.gradlebuild 文件。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-pdf-document-reader'
}

@Component
public class MyPagePdfDocumentReader {

	List<Document> getDocsFromPdf() {

		PagePdfDocumentReader pdfReader = new PagePdfDocumentReader("classpath:/sample1.pdf",
				PdfDocumentReaderConfig.builder()
					.withPageTopMargin(0)
					.withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
						.withNumberOfTopTextLinesToDelete(0)
						.build())
					.withPagesPerDocument(1)
					.build());

		return pdfReader.read();
    }

}

PDF 段落

ParagraphPdfDocumentReader使用 PDF 目录(例如 TOC)信息将输入 PDF 拆分为文本段落并输出单个Document每段。 注意:并非所有 PDF 文档都包含 PDF 目录。spring-doc.cadn.net.cn

依赖

使用 Maven 或 Gradle 将依赖项添加到您的项目中。spring-doc.cadn.net.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>

或发送到您的 Gradlebuild.gradlebuild 文件。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-pdf-document-reader'
}

@Component
public class MyPagePdfDocumentReader {

	List<Document> getDocsFromPdfWithCatalog() {

        ParagraphPdfDocumentReader pdfReader = new ParagraphPdfDocumentReader("classpath:/sample1.pdf",
                PdfDocumentReaderConfig.builder()
                    .withPageTopMargin(0)
                    .withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
                        .withNumberOfTopTextLinesToDelete(0)
                        .build())
                    .withPagesPerDocument(1)
                    .build());

	    return pdfReader.read();
    }
}

蒂卡 (DOCX, PPTX, HTML...

TikaDocumentReader使用 Apache Tika 从各种文档格式(如 PDF、DOC/DOCX、PPT/PPTX 和 HTML)中提取文本。有关受支持格式的完整列表,请参阅 Tika 文档spring-doc.cadn.net.cn

依赖

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>

或发送到您的 Gradlebuild.gradlebuild 文件。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-tika-document-reader'
}

@Component
class MyTikaDocumentReader {

    private final Resource resource;

    MyTikaDocumentReader(@Value("classpath:/word-sample.docx")
                            Resource resource) {
        this.resource = resource;
    }

    List<Document> loadText() {
        TikaDocumentReader tikaDocumentReader = new TikaDocumentReader(this.resource);
        return tikaDocumentReader.read();
    }
}

变形金刚

TextSplitter 文本拆分器

TextSplitter一个抽象基类,可帮助划分文档以适应 AI 模型的上下文窗口。spring-doc.cadn.net.cn

TokenTextSplitter

TokenTextSplitterTextSplitter它使用 CL100K_BASE 编码根据令牌计数将文本拆分为块。spring-doc.cadn.net.cn

用法

@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提供两个构造函数选项:spring-doc.cadn.net.cn

  1. TokenTextSplitter():使用默认设置创建拆分器。spring-doc.cadn.net.cn

  2. TokenTextSplitter(int defaultChunkSize, int minChunkSizeChars, int minChunkLengthToEmbed, int maxNumChunks, boolean keepSeparator)spring-doc.cadn.net.cn

参数

  • defaultChunkSize:每个文本块的目标大小(以 tokens 为单位)(默认值:800)。spring-doc.cadn.net.cn

  • minChunkSizeChars:每个文本块的最小大小(以字符为单位)(默认值:350)。spring-doc.cadn.net.cn

  • minChunkLengthToEmbed:要包含的 chunk 的最小长度(默认值:5)。spring-doc.cadn.net.cn

  • maxNumChunks:从文本生成的最大块数(默认值:10000)。spring-doc.cadn.net.cn

  • keepSeparator:是否在块中保留分隔符(如换行符)(默认:true)。spring-doc.cadn.net.cn

行为

TokenTextSplitter按如下方式处理文本内容:spring-doc.cadn.net.cn

  1. 它使用 CL100K_BASE 编码将输入文本编码为标记。spring-doc.cadn.net.cn

  2. 它根据defaultChunkSize.spring-doc.cadn.net.cn

  3. 对于每个块:spring-doc.cadn.net.cn

    1. 它将块解码回文本。spring-doc.cadn.net.cn

    2. 它尝试在minChunkSizeChars.spring-doc.cadn.net.cn

    3. 如果找到断点,它会在该点截断块。spring-doc.cadn.net.cn

    4. 它会修剪块,并根据keepSeparator设置。spring-doc.cadn.net.cn

    5. 如果生成的块长度大于minChunkLengthToEmbed,则会将其添加到输出中。spring-doc.cadn.net.cn

  4. 此过程将一直持续,直到处理完所有令牌或maxNumChunks到达。spring-doc.cadn.net.cn

  5. 如果文本长度超过minChunkLengthToEmbed.spring-doc.cadn.net.cn

Document doc1 = new Document("This is a long piece of text that needs to be split into smaller chunks for processing.",
        Map.of("source", "example.txt"));
Document doc2 = new Document("Another document with content that will be split based on token count.",
        Map.of("source", "example2.txt"));

TokenTextSplitter splitter = new TokenTextSplitter();
List<Document> splitDocuments = this.splitter.apply(List.of(this.doc1, this.doc2));

for (Document doc : splitDocuments) {
    System.out.println("Chunk: " + doc.getContent());
    System.out.println("Metadata: " + doc.getMetadata());
}

笔记

  • TokenTextSplitter使用 CL100K_BASE 编码jtokkit库,它与较新的 OpenAI 模型兼容。spring-doc.cadn.net.cn

  • 拆分器尝试在可能的情况下通过在句子边界处断开来创建语义上有意义的块。spring-doc.cadn.net.cn

  • 原始文档中的元数据将被保留并复制到从该文档派生的所有块中。spring-doc.cadn.net.cn

  • 如果copyContentFormatter设置为true(默认行为)。spring-doc.cadn.net.cn

  • 此拆分器对于为具有标记限制的大型语言模型准备文本特别有用,可确保每个块都在模型的处理容量范围内。spring-doc.cadn.net.cn

ContentFormatTransformer 格式转换器

确保所有文档中的内容格式一致。spring-doc.cadn.net.cn

关键字元数据扩充器

KeywordMetadataEnricher是一个DocumentTransformer它使用生成式 AI 模型从文档内容中提取关键字并将其添加为元数据。spring-doc.cadn.net.cn

用法

@Component
class MyKeywordEnricher {

    private final ChatModel chatModel;

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

    List<Document> enrichDocuments(List<Document> documents) {
        KeywordMetadataEnricher enricher = new KeywordMetadataEnricher(this.chatModel, 5);
        return enricher.apply(documents);
    }
}

构造 函数

KeywordMetadataEnricherconstructor 接受两个参数:spring-doc.cadn.net.cn

  1. ChatModel chatModel:用于生成关键字的 AI 模型。spring-doc.cadn.net.cn

  2. int keywordCount:要为每个文档提取的关键字数。spring-doc.cadn.net.cn

行为

KeywordMetadataEnricher按如下方式处理文档:spring-doc.cadn.net.cn

  1. 对于每个输入文档,它将使用文档的内容创建一个提示。spring-doc.cadn.net.cn

  2. 它会将此提示发送到提供的ChatModel生成关键字。spring-doc.cadn.net.cn

  3. 生成的关键字将添加到文档元数据的键 “excerpt_keywords” 下。spring-doc.cadn.net.cn

  4. 将返回扩充的文档。spring-doc.cadn.net.cn

定制

可以通过修改KEYWORDS_TEMPLATEconstant 的 Expression 中。默认模板为:spring-doc.cadn.net.cn

\{context_str}. Give %s unique keywords for this document. Format as comma separated. Keywords:

哪里{context_str}替换为文档内容,并且%s替换为指定的关键字 count。spring-doc.cadn.net.cn

ChatModel chatModel = // initialize your chat model
KeywordMetadataEnricher enricher = new KeywordMetadataEnricher(chatModel, 5);

Document doc = new Document("This is a document about artificial intelligence and its applications in modern technology.");

List<Document> enrichedDocs = enricher.apply(List.of(this.doc));

Document enrichedDoc = this.enrichedDocs.get(0);
String keywords = (String) this.enrichedDoc.getMetadata().get("excerpt_keywords");
System.out.println("Extracted keywords: " + keywords);

笔记

摘要元数据Enricher

SummaryMetadataEnricher是一个DocumentTransformer使用生成式 AI 模型为文档创建摘要并将其添加为元数据。它可以为当前文档以及相邻文档(上一个和下一个)生成摘要。spring-doc.cadn.net.cn

用法

@Configuration
class EnricherConfig {

    @Bean
    public SummaryMetadataEnricher summaryMetadata(OpenAiChatModel aiClient) {
        return new SummaryMetadataEnricher(aiClient,
            List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));
    }
}

@Component
class MySummaryEnricher {

    private final SummaryMetadataEnricher enricher;

    MySummaryEnricher(SummaryMetadataEnricher enricher) {
        this.enricher = enricher;
    }

    List<Document> enrichDocuments(List<Document> documents) {
        return this.enricher.apply(documents);
    }
}

构造 函数

SummaryMetadataEnricher提供两个构造函数:spring-doc.cadn.net.cn

  1. SummaryMetadataEnricher(ChatModel chatModel, List<SummaryType> summaryTypes)spring-doc.cadn.net.cn

  2. SummaryMetadataEnricher(ChatModel chatModel, List<SummaryType> summaryTypes, String summaryTemplate, MetadataMode metadataMode)spring-doc.cadn.net.cn

参数

行为

SummaryMetadataEnricher按如下方式处理文档:spring-doc.cadn.net.cn

  1. 对于每个输入文档,它将使用文档的内容和指定的摘要模板创建一个提示。spring-doc.cadn.net.cn

  2. 它会将此提示发送到提供的ChatModel以生成摘要。spring-doc.cadn.net.cn

  3. 根据指定的summaryTypes,它会将以下元数据添加到每个文档中:spring-doc.cadn.net.cn

  4. 将返回扩充的文档。spring-doc.cadn.net.cn

定制

可以通过提供自定义summaryTemplate.默认模板为:spring-doc.cadn.net.cn

"""
Here is the content of the section:
{context_str}

Summarize the key topics and entities of the section.

Summary:
"""

ChatModel chatModel = // initialize your chat model
SummaryMetadataEnricher enricher = new SummaryMetadataEnricher(chatModel,
    List.of(SummaryType.PREVIOUS, SummaryType.CURRENT, SummaryType.NEXT));

Document doc1 = new Document("Content of document 1");
Document doc2 = new Document("Content of document 2");

List<Document> enrichedDocs = enricher.apply(List.of(this.doc1, this.doc2));

// Check the metadata of the enriched documents
for (Document doc : enrichedDocs) {
    System.out.println("Current summary: " + doc.getMetadata().get("section_summary"));
    System.out.println("Previous summary: " + doc.getMetadata().get("prev_section_summary"));
    System.out.println("Next summary: " + doc.getMetadata().get("next_section_summary"));
}

提供的示例演示了预期的行为:spring-doc.cadn.net.cn

笔记

  • SummaryMetadataEnricher需要一个功能ChatModel以生成摘要。spring-doc.cadn.net.cn

  • 扩充器可以处理任何大小的文档列表,正确处理第一个和最后一个文档的边缘情况。spring-doc.cadn.net.cn

  • 此扩充器对于创建上下文感知摘要特别有用,从而可以更好地了解序列中的文档关系。spring-doc.cadn.net.cn

  • MetadataMode参数允许控制如何将现有元数据合并到摘要生成过程中。spring-doc.cadn.net.cn

作家

文件

FileDocumentWriter是一个DocumentWriter实现写入Document对象添加到文件中。spring-doc.cadn.net.cn

用法

@Component
class MyDocumentWriter {

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

构造 函数

FileDocumentWriter提供三个构造函数:spring-doc.cadn.net.cn

  1. FileDocumentWriter(String fileName)spring-doc.cadn.net.cn

  2. FileDocumentWriter(String fileName, boolean withDocumentMarkers)spring-doc.cadn.net.cn

  3. FileDocumentWriter(String fileName, boolean withDocumentMarkers, MetadataMode metadataMode, boolean append)spring-doc.cadn.net.cn

参数

行为

FileDocumentWriter按如下方式处理文档:spring-doc.cadn.net.cn

  1. 它将打开指定文件名的 FileWriter。spring-doc.cadn.net.cn

  2. 对于输入列表中的每个文档:spring-doc.cadn.net.cn

    1. 如果withDocumentMarkers为 true,则它会写入一个包含文档索引和页码的文档标记。spring-doc.cadn.net.cn

    2. 它根据指定的metadataMode.spring-doc.cadn.net.cn

  3. 写入所有文档后,文件将关闭。spring-doc.cadn.net.cn

文档标记

什么时候withDocumentMarkers设置为 true,则 Writer 将按以下格式包含每个文档的标记:spring-doc.cadn.net.cn

### Doc: [index], pages:[start_page_number,end_page_number]

元数据处理

编写器使用两个特定的元数据键:spring-doc.cadn.net.cn

这些在编写文档标记时使用。spring-doc.cadn.net.cn

List<Document> documents = // initialize your documents
FileDocumentWriter writer = new FileDocumentWriter("output.txt", true, MetadataMode.ALL, true);
writer.accept(documents);

这会使用所有可用的元数据将所有文档写入“output.txt”,包括文档标记,并附加到文件(如果已存在)。spring-doc.cadn.net.cn

笔记

  • 编写器使用FileWriter,因此它会使用作系统的默认字符编码写入文本文件。spring-doc.cadn.net.cn

  • 如果在写入过程中发生错误,则RuntimeException以原始异常作为其原因引发。spring-doc.cadn.net.cn

  • metadataMode参数允许控制如何将现有元数据合并到写入的内容中。spring-doc.cadn.net.cn

  • 此编写器对于调试或创建文档集合的可读输出特别有用。spring-doc.cadn.net.cn

矢量存储

提供与各种矢量存储的集成。 有关完整列表,请参阅 Vector DB 文档spring-doc.cadn.net.cn