此版本仍在开发中,尚未被视为稳定版本。最新的快照版本请使用 Spring AI 1.0.0-SNAPSHOT! |
ETL 管道
提取、转换和加载 (ETL) 框架是检索增强生成 (RAG) 用例中数据处理的主干。
ETL 管道编排从原始数据源到结构化向量存储的流程,确保数据处于最佳格式,以便 AI 模型进行检索。
RAG 用例是文本,通过从数据主体中检索相关信息来提高生成输出的质量和相关性,从而增强生成模型的功能。
API 概述
ETL 管道创建、转换和存储实例。Document
该类包含文本、元数据和可选的 addall 媒体类型,如图像、音频和视频。Document
ETL 管道有三个主要组件:
-
DocumentReader
实现Supplier<List<Document>>
-
DocumentTransformer
实现Function<List<Document>, List<Document>>
-
DocumentWriter
实现Consumer<List<Document>>
类内容是在 的帮助下从 PDF、文本文件和其他文档类型创建的。Document
DocumentReader
要构建简单的 ETL 管道,您可以将每种类型的实例链接在一起。
假设我们有这三种 ETL 类型的以下实例
-
PagePdfDocumentReader
的实现DocumentReader
-
TokenTextSplitter
的实现DocumentTransformer
-
VectorStore
的实现DocumentWriter
要执行将数据基本加载到 Vector Database 中以用于 Retrieval Augmented Generation 模式的操作,请使用以下 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();
}
}
文档Transformer
在处理工作流中转换一批文档。
public interface DocumentTransformer extends Function<List<Document>, List<Document>> {
default List<Document> transform(List<Document> transform) {
return apply(transform);
}
}
文档读者
JSON 格式
该 API 处理 JSON 文档,将其转换为对象列表。JsonReader
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
:指向 JSON 文件的 Spring 对象。Resource
-
jsonKeysToUse
:JSON 中的键数组,应用作结果对象中的文本内容。Document
-
jsonMetadataGenerator
:为每个 .JsonMetadataGenerator
Document
行为
按如下方式处理 JSON 内容:JsonReader
-
它可以处理 JSON 数组和单个 JSON 对象。
-
对于每个 JSON 对象(在数组或单个对象中):
-
它根据指定的 .
jsonKeysToUse
-
如果未指定键,则使用整个 JSON 对象作为内容。
-
它使用提供的元数据(如果未提供,则使用空元数据)。
JsonMetadataGenerator
-
它会创建一个包含提取的内容和元数据的对象。
Document
-
使用 JSON 指针
现在支持使用 JSON 指针检索 JSON 文档的特定部分。此功能允许您轻松地从复杂的 JSON 结构中提取嵌套数据。JsonReader
示例 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."
}
]
在此示例中,如果 配置为 ,它将创建对象,其中内容是数组中每辆自行车的 “description” 字段的值。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);
-
Reader 使用 Spring 的抽象,允许它从各种来源(Classpath、文件系统、URL 等)读取数据。
Resource
-
自定义元数据可以添加到读者使用该方法创建的所有文档中。
getCustomMetadata()
Markdown
处理 Markdown 文档,将它们转换为对象列表。MarkdownDocumentReader
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();
}
}
允许您自定义 MarkdownDocumentReader 的行为:MarkdownDocumentReaderConfig
-
horizontalRuleCreateDocument
:当设置为 时,Markdown 中的水平线将创建新对象。true
Document
-
includeCodeBlock
:设置为 时,代码块将包含在与周围文本相同的文本中。当 时,代码块将创建单独的对象。true
Document
false
Document
-
includeBlockquote
:当设置为 时,块引用将包含在与周围文本相同的文本中。当 , blockquotes 创建单独的对象时。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 对象中,也可以包含在周围的文本中。
-
块引用可以分隔到它们自己的 Document 对象中,也可以包含在周围的文本中。
-
水平线可用于将内容拆分为单独的 Document 对象。
Reader 在 Document 对象的内容中保留内联代码、列表和文本样式等格式。
PDF 页面
使用 Apache PdfBox 库解析 PDF 文档PagePdfDocumentReader
使用 Maven 或 Gradle 将依赖项添加到您的项目中。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>
或您的 Gradle 构建文件。build.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 段落
它使用 PDF 目录(例如 TOC)信息将输入 PDF 拆分为文本段落,并为每个段落输出一个文本段落。
注意:并非所有 PDF 文档都包含 PDF 目录。ParagraphPdfDocumentReader
Document
依赖
使用 Maven 或 Gradle 将依赖项添加到您的项目中。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>
或您的 Gradle 构建文件。build.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...
它使用 Apache Tika 从各种文档格式中提取文本,例如 PDF、DOC/DOCX、PPT/PPTX 和 HTML。有关受支持格式的完整列表,请参阅 Tika 文档。TikaDocumentReader
依赖
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-tika-document-reader</artifactId>
</dependency>
或您的 Gradle 构建文件。build.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();
}
}
变形金刚
TokenTextSplitter
这是一种实现,它使用 CL100K_BASE 编码根据令牌计数将文本拆分为块。TokenTextSplitter
TextSplitter
用法
@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
:要包含的 chunk 的最小长度(默认值:5)。 -
maxNumChunks
:从文本生成的最大块数(默认值:10000)。 -
keepSeparator
:是否在块中保留分隔符(如换行符)(默认:true)。
行为
按如下方式处理文本内容:TokenTextSplitter
-
它使用 CL100K_BASE 编码将输入文本编码为标记。
-
它根据 .
defaultChunkSize
-
对于每个块:
-
它将块解码回文本。
-
它尝试在 .
minChunkSizeChars
-
如果找到断点,它会在该点截断块。
-
它会修剪块,并根据设置选择性地删除换行符。
keepSeparator
-
如果生成的块长于 ,则会将其添加到输出中。
minChunkLengthToEmbed
-
-
此过程将一直持续,直到处理完或达到所有令牌为止。
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());
}
关键字元数据扩充器
这是一个使用生成式 AI 模型从文档内容中提取关键字并将其添加为元数据的 API。KeywordMetadataEnricher
DocumentTransformer
用法
@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);
}
}
构造 函数
构造函数采用两个参数:KeywordMetadataEnricher
-
ChatModel chatModel
:用于生成关键字的 AI 模型。 -
int keywordCount
:要为每个文档提取的关键字数。
行为
流程文档如下:KeywordMetadataEnricher
-
对于每个输入文档,它将使用文档的内容创建一个提示。
-
它将此提示发送到提供的 以生成关键字。
ChatModel
-
生成的关键字将添加到文档元数据的键 “excerpt_keywords” 下。
-
将返回扩充的文档。
定制
可以通过修改类中的常量来自定义关键字提取提示。默认模板为:KEYWORDS_TEMPLATE
\{context_str}. Give %s unique keywords for this document. Format as comma separated. Keywords:
Where 替换为文档内容,并替换为指定的关键字计数。{context_str}
%s
例
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
这是一个使用生成式 AI 模型为文档创建摘要并将其添加为元数据的 a。它可以为当前文档以及相邻文档(上一个和下一个)生成摘要。SummaryMetadataEnricher
DocumentTransformer
用法
@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
:一个枚举值列表,指示要生成的摘要(PREVIOUS、CURRENT、NEXT)。SummaryType
-
summaryTemplate
:用于生成摘要的自定义模板(可选)。 -
metadataMode
:指定在生成摘要时如何处理文档元数据(可选)。
行为
流程文档如下:SummaryMetadataEnricher
-
对于每个输入文档,它将使用文档的内容和指定的摘要模板创建一个提示。
-
它会将此提示发送到 provided 以生成摘要。
ChatModel
-
根据 specified ,它会将以下元数据添加到每个文档:
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
-
第一个文档收到 a 但没有 .
next_section_summary
prev_section_summary
-
第二个文档接收 a 但没有 .
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。
-
对于输入列表中的每个文档:
-
如果为 true,则写入包含文档索引和页码的文档标记。
withDocumentMarkers
-
它根据指定的 .
metadataMode
-
-
写入所有文档后,文件将关闭。
文档标记
当设置为 true 时,编写器将按以下格式包含每个文档的标记:withDocumentMarkers
### Doc: [index], pages:[start_page_number,end_page_number]
矢量存储
提供与各种矢量存储的集成。 有关完整列表,请参阅 Vector DB 文档。