|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
MariaDB 向量存储
本节将指导您设置 MariaDBVectorStore 以存储文档嵌入并执行相似性搜索。
MariaDB Vector 是 MariaDB 11.7 的一部分，可实现对机器学习生成的嵌入进行存储和搜索。 它使用向量索引提供高效的向量相似性搜索功能，支持余弦相似度和欧几里得距离度量。
前置条件
-
一个正在运行的 MariaDB（11.7+）实例。以下选项可用：
-
如果需要，为EmbeddingModel提供一个API密钥，用于生成由
MariaDBVectorStore存储的嵌入向量。
Auto-Configuration
|
Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。 |
Spring AI 为 MariaDB 向量存储库提供了 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到项目中的 Maven pom.xml 文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-mariadb</artifactId>
</dependency>请将以下内容添加到您的Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-vector-store-mariadb'
}| 请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。 |
向量存储实现可以为您初始化所需的模式，但您必须通过在适当的构造函数中指定initializeSchema布尔值或在application.properties文件中设置…initialize-schema=true来选择加入。
| 这是一个破坏性变更！在早期版本的 Spring AI 中，此架构初始化是默认发生的。 |
此外，您还需要一个已配置的 EmbeddingModel bean。
有关更多信息，请参阅 EmbeddingModel 部分。
例如，要使用 OpenAI EmbeddingModel，请添加以下依赖项：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>| 请参阅 构件仓库 部分，将 Maven 中央仓库和/或快照仓库添加到您的构建文件中。 |
现在你可以在应用程序中自动装配MariaDBVectorStore：
@Autowired VectorStore vectorStore;
// ...
List<Document> documents = List.of(
new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
new Document("The World is Big and Salvation Lurks Around the Corner"),
new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));
// Add the documents to MariaDB
vectorStore.add(documents);
// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());配置属性
要连接到 MariaDB 并使用 MariaDBVectorStore，您需要为您的实例提供访问详细信息。
可以通过 Spring Boot 的 application.yml 提供一个简单的配置：
spring:
datasource:
url: jdbc:mariadb://localhost/db
username: myUser
password: myPassword
ai:
vectorstore:
mariadb:
initialize-schema: true
distance-type: COSINE
dimensions: 1536| 如果您通过 Docker Compose 或 Testcontainers 以 Spring Boot dev 服务的方式运行 MariaDB Vector， 由于它们由 Spring Boot 自动配置，因此您无需配置 URL、用户名和密码。 |
以 spring.ai.vectorstore.mariadb.* 开头的属性用于配置 MariaDBVectorStore：
| <property> </property> | <description> </description> | 默认值 |
|---|---|---|
|
是否初始化所需的模式 |
|
|
搜索距离类型。使用 |
|
|
嵌入维度。如果没有明确指定，将从提供的 |
|
|
启动时删除现有的向量存储表。 |
|
|
向量存储模式名称 |
|
|
向量存储表名 |
|
|
启用模式和表名验证，以确保它们是有效且存在的对象。 |
|
如果您配置了自定义的模式和/或表名，请考虑通过设置spring.ai.vectorstore.mariadb.schema-validation=true来启用模式验证。
这可以确保名称的正确性，并降低SQL注入攻击的风险。 |
手动配置
不使用 Spring Boot 自动配置，您可以手动配置 MariaDB 向量存储。 为此，您需要向项目中添加以下依赖项：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.mariadb.jdbc</groupId>
<artifactId>mariadb-java-client</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mariadb-store</artifactId>
</dependency>| 请参阅依赖管理部分，将Spring AI BOM添加到您的构建文件中。 |
然后使用构建器模式创建 MariaDBVectorStore bean：
@Bean
public VectorStore vectorStore(JdbcTemplate jdbcTemplate, EmbeddingModel embeddingModel) {
return MariaDBVectorStore.builder(jdbcTemplate, embeddingModel)
.dimensions(1536) // Optional: defaults to 1536
.distanceType(MariaDBDistanceType.COSINE) // Optional: defaults to COSINE
.schemaName("mydb") // Optional: defaults to null
.vectorTableName("custom_vectors") // Optional: defaults to "vector_store"
.contentFieldName("text") // Optional: defaults to "content"
.embeddingFieldName("embedding") // Optional: defaults to "embedding"
.idFieldName("doc_id") // Optional: defaults to "id"
.metadataFieldName("meta") // Optional: defaults to "metadata"
.initializeSchema(true) // Optional: defaults to false
.schemaValidation(true) // Optional: defaults to false
.removeExistingVectorStoreTable(false) // Optional: defaults to false
.maxDocumentBatchSize(10000) // Optional: defaults to 10000
.build();
}
// This can be any EmbeddingModel implementation
@Bean
public EmbeddingModel embeddingModel() {
return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY")));
}元数据过滤
您可以将通用、可移植的元数据过滤器与 MariaDB 向量存储一起使用。
例如，您可以使用文本表达式语言：
vectorStore.similaritySearch(
SearchRequest.builder()
.query("The World")
.topK(TOP_K)
.similarityThreshold(SIMILARITY_THRESHOLD)
.filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());或以编程方式使用 Filter.Expression DSL：
FilterExpressionBuilder b = new FilterExpressionBuilder();
vectorStore.similaritySearch(SearchRequest.builder()
.query("The World")
.topK(TOP_K)
.similarityThreshold(SIMILARITY_THRESHOLD)
.filterExpression(b.and(
b.in("author", "john", "jill"),
b.eq("article_type", "blog")).build()).build());| 这些过滤表达式将自动转换为等效的 MariaDB JSON 路径表达式。 |
相似度分数
MariaDB 向量存储会自动为相似性搜索返回的文档计算相似度分数。 这些分数提供了一个标准化的度量，用于衡量每个文档与您的搜索查询的匹配程度。
分数计算
相似度分数使用公式 score = 1.0 - distance 计算，其中：
-
分数：介于
0.0和1.0之间的值，其中1.0表示完全相似，0.0表示没有相似性 -
距离：使用配置的距离类型计算的原始距离值（
COSINE或EUCLIDEAN）
这意味着距离较小（更相似）的文档将获得更高的分数，从而使结果更直观易懂。
访问分数
您可以通过 getScore() 方法访问每个文档的相似度得分：
List<Document> results = vectorStore.similaritySearch(
SearchRequest.builder()
.query("Spring AI")
.topK(5)
.build());
for (Document doc : results) {
double score = doc.getScore(); // Value between 0.0 and 1.0
System.out.println("Document: " + doc.getText());
System.out.println("Similarity Score: " + score);
}访问原生客户端
MariaDB 向量存储实现通过 getNativeClient() 方法提供对底层原生 JDBC 客户端（JdbcTemplate）的访问：
MariaDBVectorStore vectorStore = context.getBean(MariaDBVectorStore.class);
Optional<JdbcTemplate> nativeClient = vectorStore.getNativeClient();
if (nativeClient.isPresent()) {
JdbcTemplate jdbc = nativeClient.get();
// Use the native client for MariaDB-specific operations
}原生客户端使您能够访问 MariaDB 特有的功能和操作，这些功能和操作可能无法通过 VectorStore 接口公开。