跳到主要内容
版本:2.0.1

MariaDB 向量存储

QWen 3.8 中英对照 MariaDB Vector Store

本节将指导您设置 MariaDBVectorStore,以存储文档嵌入并执行相似度搜索。

MariaDB Vector 是 MariaDB 11.7 的一部分,支持存储和检索机器学习生成的嵌入向量。它利用向量索引提供高效的向量相似性搜索功能,支持余弦相似度和欧氏距离两种度量。

前提条件​

自动配置​

备注

Spring AI 的自动配置和 starter 模块的 artifact 名称已发生重大变更。请参阅 升级说明 以获取更多信息。

Spring AI 为 MariaDB Vector Store 提供了 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 添加到您的构建文件中。

向量存储实现可以为您初始化所需的 schema,但您必须通过显式指定来启用:在相应的构造函数中设置 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>
提示

请参考 Artifact Repositories 部分,以在您的构建文件中添加 Maven Central 和/或 Snapshot Repositories。

现在你可以在应用程序中自动装配 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 将 MariaDB Vector 作为 Spring Boot 开发服务运行,则无需配置 URL、用户名和密码,因为 Spring Boot 会自动进行配置。

以 spring.ai.vectorstore.mariadb.* 开头的属性用于配置 MariaDBVectorStore:

属性描述默认值
spring.ai.vectorstore.mariadb.initialize-schema是否初始化所需的 schemafalse
spring.ai.vectorstore.mariadb.distance-type搜索距离类型。使用 COSINE(默认)或 EUCLIDEAN。如果向量已归一化为长度 1,可以使用 EUCLIDEAN 以获得最佳性能。COSINE
spring.ai.vectorstore.mariadb.dimensionsEmbedding 维度。如果未明确指定,将从提供的 EmbeddingModel 中获取维度。1536
spring.ai.vectorstore.mariadb.remove-existing-vector-store-table在启动时删除现有的向量存储表。false
spring.ai.vectorstore.mariadb.schema-name向量存储 schema 名称null
spring.ai.vectorstore.mariadb.table-name向量存储表名称vector_store
spring.ai.vectorstore.mariadb.schema-validation启用 schema 和表名校验,以确保它们是有效且已存在的对象。false
提示

如果您配置了自定义的 schema 和/或表名,建议通过设置 spring.ai.vectorstore.mariadb.schema-validation=true 来启用 schema 验证。这可以确保名称的正确性,并降低 SQL 注入攻击的风险。

手动配置​

您可以选择手动配置 MariaDB 向量存储,而无需使用 Spring Boot 自动配置。为此,您需要向项目中添加以下依赖项:

<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(OpenAiEmbeddingOptions.builder().apiKey(System.getenv("OPENAI_API_KEY")).build());
}

元数据筛选​

您可以利用通用且可移植的 元数据过滤器 结合 MariaDB Vector store 使用。

例如,您可以使用文本表达式语言:

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);
}

搜索结果排序​

搜索结果会按照相似度分数降序自动排序(分数最高的排在最前)。这确保了最相关的文档显示在结果列表的顶部。

距离元数据​

除了相似度分数之外,原始距离值仍然存在于文档元数据中:

for (Document doc : results) {
double score = doc.getScore();
float distance = (Float) doc.getMetadata().get("distance");

System.out.println("Score: " + score + ", Distance: " + distance);
}

相似度阈值​

在搜索请求中使用相似度阈值时,请将阈值指定为分数值(0.0 至 1.0),而不是距离:

List<Document> results = vectorStore.similaritySearch(
SearchRequest.builder()
.query("Spring AI")
.topK(10)
.similarityThreshold(0.8) // Only return documents with score >= 0.8
.build());

这使得阈值值保持一致且直观——较高的值意味着更严格的搜索,仅返回高度相似的文档。

访问 Native Client​

MariaDB Vector Store 实现通过 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 接口暴露)的访问。