MariaDB 向量儲存

本節將引導您設定 MariaDBVectorStore 來儲存文件嵌入並執行相似性搜尋。

MariaDB Vector 是 MariaDB 11.7 的一部分，它支援儲存和搜尋機器學習生成的嵌入。它利用向量索引提供高效的向量相似性搜尋功能，支援餘弦相似性和歐幾里得距離度量。

先決條件

自動配置

Spring AI 自動配置、啟動模組的工件名稱發生了重大變化。請參閱 升級說明 以獲取更多資訊。

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>
請參閱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:///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

是否初始化所需的模式

假

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

在啟動時刪除現有的向量儲存表。

假

spring.ai.vectorstore.mariadb.schema-name

向量儲存模式名稱

null

spring.ai.vectorstore.mariadb.table-name

向量儲存表名稱

vector_store

spring.ai.vectorstore.mariadb.schema-validation

啟用模式和表名驗證，以確保它們是有效且存在的物件。

假
如果您配置了自定義模式和/或表名，請考慮透過設定 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);
}

搜尋結果排序

搜尋結果會自動按相似性分數降序排列（最高分在前）。這確保了最相關的文件出現在結果頂部。

距離元資料

除了相似性分數，原始距離值仍然在文件元資料中可用：

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

這使得閾值保持一致且直觀——值越高意味著搜尋越嚴格，只返回高度相似的文件。

訪問原生客戶端

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
}

原生客戶端讓您可以訪問可能未透過 VectorStore 介面公開的 MariaDB 特定功能和操作。

© . This site is unofficial and not affiliated with VMware.