MariaDB 向量库

本节引导你设置 MariaDBVectorStore 以存储文档嵌入并执行相似度搜索。

MariaDB Vector 是 MariaDB 11.7 的一部分，能够存储并搜索由机器学习生成的嵌入。它使用向量索引提供高效的向量相似度搜索能力，同时支持余弦相似度和欧氏距离两种度量。

前置条件

一个正在运行的 MariaDB（11.7+）实例。有以下可选方案：
- Docker 镜像
- MariaDB Server
- MariaDB SkySQL
如有需要，为 EmbeddingModel 配置一个 API 密钥，以生成 MariaDBVectorStore 所存储的嵌入。

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。更多信息请参阅升级说明。

Spring AI 为 MariaDB 向量库提供 Spring Boot 自动配置。要启用它，请将以下依赖添加到你的项目的 Maven pom.xml 文件：

xml

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-mariadb</artifactId>
</dependency>

或添加到你的 Gradle build.gradle 构建文件。

groovy

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-mariadb'
}

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

向量库实现可以为你初始化所需的模式，但你必须显式开启——在相应的构造器中指定 initializeSchema 布尔值，或在 application.properties 文件中设置 ...initialize-schema=true。

NOTE

这是一处破坏性变更！在较早的 Spring AI 版本中，此模式初始化默认进行。

此外，你还需要一个已配置的 EmbeddingModel bean。更多信息参见 EmbeddingModel 一节。

例如，要使用 OpenAI EmbeddingModel，添加以下依赖：

xml

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

TIP

参见制品仓库一节，把 Maven Central 和/或 Snapshot 仓库添加到你的构建文件。

现在你可以在应用中把 MariaDBVectorStore 自动装配：

java

@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 提供：

yaml

spring:
  datasource:
    url: jdbc:mariadb://localhost/db
    username: myUser
    password: myPassword
  ai:
    vectorstore:
      mariadb:
        initialize-schema: true
        distance-type: COSINE
        dimensions: 1536

TIP

如果你通过 Docker Compose 把 MariaDB Vector 作为 Spring Boot dev service 运行

或 Testcontainers，你就无需配置 URL、用户名和密码，因为它们由 Spring Boot 自动配置。

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

属性	描述	默认值
`spring.ai.vectorstore.mariadb.initialize-schema`	是否初始化所需的模式	`false`
`spring.ai.vectorstore.mariadb.distance-type`	搜索距离类型。使用 `COSINE`（默认）或 `EUCLIDEAN`。若向量被归一化为长度 1，你可使用 `EUCLIDEAN` 以获得最佳性能。	`COSINE`
`spring.ai.vectorstore.mariadb.dimensions`	嵌入的维度。若未显式指定，将从所提供的 `EmbeddingModel` 获取维度。	`1536`
`spring.ai.vectorstore.mariadb.remove-existing-vector-store-table`	在启动时删除既有的向量库表。	`false`
`spring.ai.vectorstore.mariadb.schema-name`	向量库的模式名	`null`
`spring.ai.vectorstore.mariadb.table-name`	向量库的表名	`vector_store`
`spring.ai.vectorstore.mariadb.schema-validation`	启用模式与表名校验，以确保它们是有效且存在的对象。	`false`

TIP

如果你配置了自定义的模式和/或表名，建议通过设置 spring.ai.vectorstore.mariadb.schema-validation=true 启用模式校验。

这能确保名称的正确性并降低 SQL 注入攻击的风险。

手动配置

与其使用 Spring Boot 自动配置，不如手动配置 MariaDB 向量库。为此你需要把以下依赖添加到你的项目：

xml

<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>

TIP

参见依赖管理一节，把 Spring AI BOM 添加到你的构建文件。

然后使用构建器模式创建 MariaDBVectorStore bean：

java

@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 向量库上利用通用、可移植的元数据过滤器。

例如，你可以使用文本表达式语言：

java

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：

java

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

NOTE

这些过滤表达式会被自动转换为等价的 MariaDB JSON 路径表达式。

相似度分数

MariaDB 向量库会为相似度搜索返回的文档自动计算相似度分数。这些分数提供了对每个文档与你搜索查询匹配程度的归一化度量。

分数计算

相似度分数使用公式 score = 1.0 - distance 计算，其中：

分数：介于 0.0 与 1.0 之间的值，1.0 表示完全相似，0.0 表示毫不相似
距离：使用所配置的距离类型（COSINE 或 EUCLIDEAN）计算出的原始距离值

这意味着距离更小（更相似）的文档会有更高的分数，使结果更直观易读。

访问分数

你可以通过 getScore() 方法访问每个文档的相似度分数：

java

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

搜索结果排序

搜索结果会按相似度分数降序（最高分在前）自动排序。这确保了最相关的文档出现在你结果的顶部。

距离元数据

除相似度分数外，原始距离值仍可在文档元数据中获得：

java

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）而非距离：

java

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

这让阈值取值一致且直观——较高的值意味着更严格的搜索，只返回高度相似的文档。

访问原生客户端

MariaDB 向量库实现通过 getNativeClient() 方法提供对底层原生 JDBC 客户端（JdbcTemplate）的访问：

java

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
}

原生客户端让你得以访问那些可能未通过 VectorStore 接口暴露的 MariaDB 特定功能与操作。

Chat Client API

顾问（Advisor）API

结构化输出

模型

聊天模型 API

嵌入模型 API

Amazon Bedrock

VertexAI

图像模型 API

音频模型

转录 API

文本转语音（TTS）API

审核模型

工具调用

Model Context Protocol (MCP)

MCP 服务端 Boot Starter

MCP 注解

检索增强生成

向量数据库

MariaDB 向量库

前置条件

自动配置

配置属性

手动配置

元数据过滤

相似度分数

分数计算

访问分数

搜索结果排序

距离元数据

相似度阈值

访问原生客户端

友情链接