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 中，此 schema 初始化是預設發生的。

此外，您還需要配置一個 EmbeddingModel bean。請參考EmbeddingModel部分了解更多資訊。

例如，要使用OpenAI EmbeddingModel，請新增以下依賴項：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
請參考Repositories部分將 Maven Central 和/或 Snapshot Repositories 新增到您的構建檔案。

現在您可以在您的應用程式中自動注入 (auto-wire) 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

是否初始化所需的 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

向量儲存 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 注入攻擊的風險。

手動配置

除了使用 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 新增到您的構建檔案。

然後使用 builder 模式建立 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 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 path 表示式。

訪問原生客戶端

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
}

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