|
此版本仍在开发中，尚不被认为是稳定的。对于最新的快照版本，请使用 Spring AI 1.0.1！ |
ETL 管道
提取、转换和加载 （ETL） 框架是检索增强生成 （RAG） 用例中数据处理的支柱。
ETL 管道编排从原始数据源到结构化向量存储的流程，确保数据采用 AI 模型检索的最佳格式。
RAG 用例是文本，通过从数据体中检索相关信息来增强生成模型的功能，从而提高生成输出的质量和相关性。
API 概述
ETL 管道创建、转换和存储Document实例。
这Document类包含文本、元数据和可选的其他媒体类型，如图像、音频和视频。
ETL 管道有三个主要组件，
-
DocumentReader实现Supplier<List<Document>> -
DocumentTransformer实现Function<List<Document>, List<Document>> -
DocumentWriter实现Consumer<List<Document>>
这Document类内容是在 PDF、文本文件和其他文档类型的帮助下创建的DocumentReader.
要构造一个简单的 ETL 管道，您可以将每种类型的实例链接在一起。
假设我们有这三种 ETL 类型的以下实例
-
PagePdfDocumentReader实现DocumentReader -
TokenTextSplitter实现DocumentTransformer -
VectorStore实现DocumentWriter
要将数据基本加载到矢量数据库中以与检索增强生成模式一起使用，请使用 Java 函数样式语法中的以下代码。
vectorStore.accept(tokenTextSplitter.apply(pdfReader.get()));或者，您可以使用更自然地表达域的方法名称
vectorStore.write(tokenTextSplitter.split(pdfReader.read()));ETL 接口
ETL 管道由以下接口和实现组成。详细的 ETL 类图显示在 ETL 类图部分。
文档阅读器
提供来自不同来源的文档来源。
public interface DocumentReader extends Supplier<List<Document>> {
default List<Document> read() {
return get();
}
}文档转换器
将一批文档作为处理工作流的一部分进行转换。
public interface DocumentTransformer extends Function<List<Document>, List<Document>> {
default List<Document> transform(List<Document> transform) {
return apply(transform);
}
}
文档阅读器
JSON
这JsonReader处理 JSON 文档，将它们转换为Document对象。
示例
@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提供了几个构造函数选项：
-
JsonReader(Resource resource) -
JsonReader(Resource resource, String… jsonKeysToUse) -
JsonReader(Resource resource, JsonMetadataGenerator jsonMetadataGenerator, String… jsonKeysToUse)
参数
-
resource： SpringResource指向 JSON 文件的对象。 -
jsonKeysToUse：JSON 中的键数组，应用作生成的文本内容Document对象。 -
jsonMetadataGenerator：可选JsonMetadataGenerator为每个Document.
行为
这JsonReader按如下方式处理 JSON 内容：
-
它可以处理 JSON 数组和单个 JSON 对象。
-
对于每个 JSON 对象（在数组或单个对象中）：
-
它根据指定的
jsonKeysToUse. -
如果未指定键，则使用整个 JSON 对象作为内容。
-
它使用提供的
JsonMetadataGenerator（如果未提供，则为空的）。 -
它创建了一个
Document对象，其中包含提取的内容和元数据。
-
使用 JSON 指针
这JsonReader现在支持使用 JSON 指针检索 JSON 文档的特定部分。此功能允许您轻松地从复杂的 JSON 结构中提取嵌套数据。
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对象，其中内容是数组中每辆自行车的“描述”字段的值。
文本
这TextReader处理纯文本文档，将其转换为Document对象。
示例
@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();
}
}配置
-
setCharset(Charset charset)：设置用于读取文本文件的字符集。默认值为 UTF-8。 -
getCustomMetadata()：返回一个可变映射，您可以在其中为文档添加自定义元数据。
行为
这TextReader按如下方式处理文本内容：
-
它将文本文件的全部内容读取为一个
Document对象。 -
文件的内容将成为
Document. -
元数据会自动添加到
Document:-
charset：用于读取文件的字符集（默认值：“UTF-8”）。 -
source：源文本文件的文件名。
-
-
通过
getCustomMetadata()包含在Document.
笔记
-
这
TextReader将整个文件内容读入内存，因此可能不适合非常大的文件。 -
如果您需要将文本拆分为更小的块，您可以使用文本拆分器，例如
TokenTextSplitter阅读文档后：
List<Document> documents = textReader.get();
List<Document> splitDocuments = new TokenTextSplitter().apply(this.documents);-
阅读器使用 Spring 的
Resource抽象，允许它从各种来源（类路径、文件系统、URL 等）读取。 -
自定义元数据可以添加到读者使用
getCustomMetadata()方法。
HTML （JSoup）
这JsoupDocumentReader处理 HTML 文档，将它们转换为Document对象。
示例
@Component
class MyHtmlReader {
private final Resource resource;
MyHtmlReader(@Value("classpath:/my-page.html") Resource resource) {
this.resource = resource;
}
List<Document> loadHtml() {
JsoupDocumentReaderConfig config = JsoupDocumentReaderConfig.builder()
.selector("article p") // Extract paragraphs within <article> tags
.charset("ISO-8859-1") // Use ISO-8859-1 encoding
.includeLinkUrls(true) // Include link URLs in metadata
.metadataTags(List.of("author", "date")) // Extract author and date meta tags
.additionalMetadata("source", "my-page.html") // Add custom metadata
.build();
JsoupDocumentReader reader = new JsoupDocumentReader(this.resource, config);
return reader.get();
}
}这JsoupDocumentReaderConfig允许您自定义JsoupDocumentReader:
-
charset：指定 HTML 文档的字符编码（默认为“UTF-8”）。 -
selector：一个 JSoup CSS 选择器，用于指定从中提取文本的元素（默认为“body”）。 -
separator：用于连接来自多个选定元素的文本的字符串（默认为“\n”）。 -
allElements：如果true，从<body>元素，忽略selector（默认为false). -
groupByElement：如果true，创建一个单独的Document对于与selector（默认为false). -
includeLinkUrls：如果true，提取绝对链接 URL 并将其添加到元数据中（默认为false). -
metadataTags：列表<meta>要从中提取内容的标记名称（默认为["description", "keywords"]). -
additionalMetadata：允许您将自定义元数据添加到所有创建的Document对象。
示例文档：my-page.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Web Page</title>
<meta name="description" content="A sample web page for Spring AI">
<meta name="keywords" content="spring, ai, html, example">
<meta name="author" content="John Doe">
<meta name="date" content="2024-01-15">
<link rel="stylesheet" href="style.css">
</head>
<body>
<header>
<h1>Welcome to My Page</h1>
</header>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
<article>
<h2>Main Content</h2>
<p>This is the main content of my web page.</p>
<p>It contains multiple paragraphs.</p>
<a href="https://www.example.com">External Link</a>
</article>
<footer>
<p>© 2024 John Doe</p>
</footer>
</body>
</html>行为：
这JsoupDocumentReader处理 HTML 内容并创建Document基于配置的对象：
-
这
selector确定哪些元素用于文本提取。 -
如果
allElements是true，则<body>被提取成单个Document. -
如果
groupByElement是true，每个元素都与selector创建一个单独的Document. -
如果两者都不是
allElements也不groupByElement是true，文本来自与selector使用separator. -
文档标题，指定内容
<meta>标记，并且（可选）链接 URL 被添加到Document元数据。 -
用于解析相对链接的基本 URI 将从 URL 资源中提取。
阅读器保留所选元素的文本内容，但删除其中的任何 HTML 标签。
降价
这MarkdownDocumentReader处理 Markdown 文档，将它们转换为Document对象。
示例
@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 的行为：
-
horizontalRuleCreateDocument：设置为true，则 Markdown 中的水平规则将创建新的Document对象。 -
includeCodeBlock：设置为true，代码块将包含在相同的Document作为周围的文字。什么时候false，代码块创建单独的Document对象。 -
includeBlockquote：设置为true，块引用将包含在相同的Document作为周围的文字。什么时候false，块引用创建单独的Document对象。 -
additionalMetadata：允许您将自定义元数据添加到所有创建的Document对象。
示例文档：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 对象：
-
标头成为文档对象中的元数据。
-
段落成为文档对象的内容。
-
代码块可以分离成自己的 Document 对象或包含在周围的文本中。
-
块引号可以分离成自己的 Document 对象或包含在周围的文本中。
-
水平尺可用于将内容拆分为单独的文档对象。
阅读器在 Document 对象的内容中保留内联代码、列表和文本样式等格式。
PDF页面
这PagePdfDocumentReader使用 Apache PdfBox 库解析 PDF 文档
使用 Maven 或 Gradle 将依赖项添加到您的项目中。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>或 Gradlebuild.gradle构建文件。
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 目录。
依赖
使用 Maven 或 Gradle 将依赖项添加到您的项目中。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>或 Gradlebuild.gradle构建文件。
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 文档。
依赖
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>或 Gradlebuild.gradle构建文件。
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();
}
}变形金刚
Tokens文本拆分器
这TokenTextSplitter是TextSplitter使用 CL100K_BASE 编码根据Tokens计数将文本拆分为块。
用法
@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提供两个构造函数选项：
-
TokenTextSplitter()：使用默认设置创建分割器。 -
TokenTextSplitter(int defaultChunkSize, int minChunkSizeChars, int minChunkLengthToEmbed, int maxNumChunks, boolean keepSeparator)
参数
-
defaultChunkSize：每个文本块的目标大小（以Tokens为单位）（默认值：800）。 -
minChunkSizeChars：每个文本块的最小大小（以字符为单位）（默认值：350）。 -
minChunkLengthToEmbed：要包含的块的最小长度（默认值：5）。 -
maxNumChunks：从文本生成的最大块数（默认：10000）。 -
keepSeparator：是否在块中保留分隔符（如换行符）（默认值：true）。
行为
这TokenTextSplitter按如下方式处理文本内容：
-
它使用CL100K_BASE编码将输入文本编码为标记。
-
它根据
defaultChunkSize. -
对于每个块：
-
它将块解码回文本。
-
它试图在
minChunkSizeChars. -
如果找到断点，它会截断该点的块。
-
它修剪块并可选择根据
keepSeparator设置。 -
如果生成的块长于
minChunkLengthToEmbed，则将其添加到输出中。
-
-
此过程一直持续到处理完所有Tokens或
maxNumChunks已达到。 -
如果剩余文本的长度超过
minChunkLengthToEmbed.
示例
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());
}关键字元数据丰富器
这KeywordMetadataEnricher是一个DocumentTransformer使用生成式 AI 模型从文档内容中提取关键字并将其添加为元数据。
用法
@Component
class MyKeywordEnricher {
private final ChatModel chatModel;
MyKeywordEnricher(ChatModel chatModel) {
this.chatModel = chatModel;
}
List<Document> enrichDocuments(List<Document> documents) {
KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
.keywordCount(5)
.build();
// Or use custom templates
KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
.keywordsTemplate(YOUR_CUSTOM_TEMPLATE)
.build();
return enricher.apply(documents);
}
}构造函数选项
这KeywordMetadataEnricher提供两个构造函数选项：
-
KeywordMetadataEnricher(ChatModel chatModel, int keywordCount)：使用默认模板并提取指定数量的关键字。 -
KeywordMetadataEnricher(ChatModel chatModel, PromptTemplate keywordsTemplate)：使用自定义模板进行关键字提取。
行为
这KeywordMetadataEnricher按如下方式处理文档：
-
对于每个输入文档，它会使用文档的内容创建一个提示。
-
它将此提示发送到提供的
ChatModel生成关键字。 -
生成的关键字将添加到文档的元数据中，键“excerpt_keywords”下。
-
将返回扩充的文档。
定制
您可以使用默认模板，也可以通过 keywordsTemplate 参数自定义模板。 默认模板为：
\{context_str}. Give %s unique keywords for this document. Format as comma separated. Keywords:哪里{context_str}替换为文档内容，并且%s替换为指定的关键字计数。
示例
ChatModel chatModel = // initialize your chat model
KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
.keywordCount(5)
.build();
// Or use custom templates
KeywordMetadataEnricher enricher = KeywordMetadataEnricher.builder(chatModel)
.keywordsTemplate(new PromptTemplate("Extract 5 important keywords from the following text and separate them with commas:\n{context_str}"))
.build();
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);SummaryMetadataEnricher
这SummaryMetadataEnricher是一个DocumentTransformer它使用生成式 AI 模型为文档创建摘要并将其添加为元数据。它可以为当前文档以及相邻文档（上一个和下一个）生成摘要。
用法
@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提供了两个构造函数：
-
SummaryMetadataEnricher(ChatModel chatModel, List<SummaryType> summaryTypes) -
SummaryMetadataEnricher(ChatModel chatModel, List<SummaryType> summaryTypes, String summaryTemplate, MetadataMode metadataMode)
参数
-
chatModel：用于生成摘要的 AI 模型。 -
summaryTypes：列表SummaryType枚举值，指示要生成哪些摘要（PREVIOUS、CURRENT、NEXT）。 -
summaryTemplate：用于生成摘要的自定义模板（可选）。 -
metadataMode：指定在生成摘要时如何处理文档元数据（可选）。
行为
这SummaryMetadataEnricher按如下方式处理文档：
-
对于每个输入文档，它使用文档的内容和指定的摘要模板创建一个提示。
-
它将此提示发送到提供的
ChatModel以生成摘要。 -
根据指定的
summaryTypes，它会向每个文档添加以下元数据：-
section_summary：当前文档的摘要。 -
prev_section_summary：上一个文档的摘要（如果可用且要求）。 -
next_section_summary：下一份文件的摘要（如果可用且有要求）。
-
-
将返回扩充的文档。
定制
可以通过提供自定义summaryTemplate.默认模板为：
"""
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"));
}提供的示例演示了预期行为：
-
对于包含两个文档的列表，两个文档都会收到一个
section_summary. -
第一个文档收到一个
next_section_summary但没有prev_section_summary. -
第二个文档收到一个
prev_section_summary但没有next_section_summary. -
这
section_summary的第一个文档与prev_section_summary第二份文件。 -
这
next_section_summary的第一个文档与section_summary第二份文件。
作家
文件
这FileDocumentWriter是一个DocumentWriter写入列表内容的实现Document对象到文件中。
用法
@Component
class MyDocumentWriter {
public void writeDocuments(List<Document> documents) {
FileDocumentWriter writer = new FileDocumentWriter("output.txt", true, MetadataMode.ALL, false);
writer.accept(documents);
}
}构造 函数
这FileDocumentWriter提供三个构造函数：
-
FileDocumentWriter(String fileName) -
FileDocumentWriter(String fileName, boolean withDocumentMarkers) -
FileDocumentWriter(String fileName, boolean withDocumentMarkers, MetadataMode metadataMode, boolean append)
参数
-
fileName：要将文档写入的文件的名称。 -
withDocumentMarkers：是否在输出中包含文档标记（默认值：false）。 -
metadataMode：指定要写入文件的文档内容（默认值：MetadataMode.NONE）。 -
append：如果为 true，则数据将写入文件的末尾而不是开头（默认值：false）。
行为
这FileDocumentWriter按如下方式处理文档：
-
它为指定的文件名打开一个 FileWriter。
-
对于输入列表中的每个文档：
-
如果
withDocumentMarkers为 true，则它会写入一个文档标记，包括文档索引和页码。 -
它根据指定的
metadataMode.
-
-
写入所有文档后，文件将关闭。
文档标记
什么时候withDocumentMarkers设置为 true，则编写器会以以下格式包含每个文档的标记：
### Doc: [index], pages:[start_page_number,end_page_number]矢量存储
提供与各种向量存储的集成。 有关完整列表，请参阅 Vector DB 文档。