Couchbase

本節將引導您設定 CouchbaseSearchVectorStore，以便使用 Couchbase 儲存文件嵌入並執行相似度搜索。

Couchbase 是一個分散式 JSON 文件資料庫，具備關係型資料庫管理系統 (DBMS) 的所有理想功能。在其他特性中，它允許使用者使用基於向量的儲存和檢索來查詢資訊。

前提條件

一個正在執行的 Couchbase 例項。以下選項可用：Couchbase * Docker * Capella - Couchbase 即服務 * 本地安裝 Couchbase * Couchbase Kubernetes Operator

自動配置

Spring AI 自動配置、starter 模組的 artifact 名稱發生了重大變化。有關詳細資訊，請參閱升級說明。

Spring AI 為 Couchbase 向量儲存提供了 Spring Boot 自動配置。要啟用它，請將以下依賴項新增到您的專案 Maven pom.xml 檔案中

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

或新增到您的 Gradle build.gradle 構建檔案中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-couchbase-store-spring-boot-starter'
}
Couchbase 向量搜尋僅在 7.6 及更高版本以及 Java SDK 3.6.0 及更高版本中可用。
有關將 Spring AI BOM 新增到構建檔案的資訊，請參閱依賴管理部分。
有關將 Milestone 和/或 Snapshot 倉庫新增到構建檔案的資訊，請參閱倉庫部分。

向量儲存實現可以為您使用預設選項初始化配置的 bucket、scope、collection 和 search index，但您必須透過在適當的建構函式中指定 initializeSchema 布林值來選擇啟用此功能。

這是一個重大變更！在早期版本的 Spring AI 中，此 schema 初始化是預設發生的。

請查看向量儲存的配置引數列表，以瞭解預設值和配置選項。

此外，您還需要一個配置好的 EmbeddingModel bean。有關詳細資訊，請參閱EmbeddingModel部分。

現在您可以將 CouchbaseSearchVectorStore 作為向量儲存自動注入到您的應用中。

@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 Qdrant
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));

配置屬性

要連線到 Couchbase 並使用 CouchbaseSearchVectorStore，您需要為您的例項提供訪問詳情。可以透過 Spring Boot 的 application.properties 提供簡單的配置，

spring.ai.openai.api-key=<key>
spring.couchbase.connection-string=<conn_string>
spring.couchbase.username=<username>
spring.couchbase.password=<password>

環境變數，

export SPRING_COUCHBASE_CONNECTION_STRINGS=<couchbase connection string like couchbase://>
export SPRING_COUCHBASE_USERNAME=<couchbase username>
export SPRING_COUCHBASE_PASSWORD=<couchbase password>
# API key if needed, e.g. OpenAI
export SPRING_AI_OPENAI_API_KEY=<api-key>

或者可以是這些方式的組合。例如，如果您想將密碼儲存為環境變數，而將其餘配置保留在 plain application.yml 檔案中。

如果您選擇建立一個 shell 指令碼以便將來工作輕鬆，請務必在啟動您的應用之前透過“source”該檔案來執行它，即 source <your_script_name>.sh。

Spring Boot 的 Couchbase 叢集自動配置特性將建立一個 bean 例項，該例項將由 CouchbaseSearchVectorStore 使用。

以 spring.couchbase.* 開頭的 Spring Boot 屬性用於配置 Couchbase 叢集例項

屬性 描述 預設值

spring.couchbase.connection-string

一個 Couchbase 連線字串

couchbase://

spring.couchbase.password

用於 Couchbase 認證的密碼。

-

spring.couchbase.username

用於 Couchbase 認證的使用者名稱。

-

spring.couchbase.env.io.minEndpoints

每個節點的最小 socket 數。

1

spring.couchbase.env.io.maxEndpoints

每個節點的最大 socket 數。

12

spring.couchbase.env.io.idleHttpConnectionTimeout

HTTP 連線在關閉並從連線池中移除之前可能保持空閒的時間長度。

1s

spring.couchbase.env.ssl.enabled

是否啟用 SSL 支援。如果提供了“bundle”，則會自動啟用，除非另有指定。

-

spring.couchbase.env.ssl.bundle

SSL bundle 名稱。

-

spring.couchbase.env.timeouts.connect

Bucket 連線超時。

10s

spring.couchbase.env.timeouts.disconnect

Bucket 斷開連線超時。

10s

spring.couchbase.env.timeouts.key-value

針對特定 key-value 操作的超時。

2500ms

spring.couchbase.env.timeouts.key-value

針對具有耐久性級別的特定 key-value 操作的超時。

10s

spring.couchbase.env.timeouts.key-value-durable

針對具有耐久性級別的特定 key-value 操作的超時。

10s

spring.couchbase.env.timeouts.query

SQL++ 查詢操作超時。

75s

spring.couchbase.env.timeouts.view

常規和地理空間檢視操作超時。

75s

spring.couchbase.env.timeouts.search

搜尋服務超時。

75s

spring.couchbase.env.timeouts.analytics

Analytics 服務超時。

75s

spring.couchbase.env.timeouts.management

管理操作超時。

75s

以 spring.ai.vectorstore.couchbase.* 字首開頭的屬性用於配置 CouchbaseSearchVectorStore。

屬性 描述 預設值

spring.ai.vectorstore.couchbase.index-name

儲存向量的索引名稱。

spring-ai-document-index

spring.ai.vectorstore.couchbase.bucket-name

Couchbase Bucket 的名稱，是 scope 的父級。

default

spring.ai.vectorstore.couchbase.scope-name

Couchbase scope 的名稱，是 collection 的父級。搜尋查詢將在 scope 上下文中執行。

default

spring.ai.vectorstore.couchbase.collection-name

儲存 Documents 的 Couchbase collection 名稱。

default

spring.ai.vectorstore.couchbase.dimensions

向量的維度數量。

1536

spring.ai.vectorstore.couchbase.similarity

要使用的相似度函式。

dot_product

spring.ai.vectorstore.couchbase.optimization

要使用的相似度函式。

recall

spring.ai.vectorstore.couchbase.initialize-schema

是否初始化必需的 schema

false

以下相似度函式可用

  • l2_norm

  • dot_product

以下索引最佳化可用

  • recall

  • latency

有關更多詳細資訊，請參閱 Couchbase 文件中關於向量搜尋的部分。

元資料過濾

您可以在 Couchbase 儲存中使用通用、可移植的元資料過濾器。

例如，您可以使用文字表示式語言

vectorStore.similaritySearch(
    SearchRequest.defaults()
    .query("The World")
    .topK(TOP_K)
    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));

或使用 Filter.Expression DSL 進行程式設計配置

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.defaults()
    .query("The World")
    .topK(TOP_K)
    .filterExpression(b.and(
        b.in("author","john", "jill"),
        b.eq("article_type", "blog")).build()));
這些過濾器表示式將被轉換為等效的 Couchbase SQL++ 過濾器。

手動配置

您可以手動配置 Couchbase 向量儲存，而不是使用 Spring Boot 自動配置。為此，您需要將 spring-ai-couchbase-store 新增到您的專案依賴中

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-couchbase-store</artifactId>
</dependency>

或新增到您的 Gradle build.gradle 構建檔案中。

dependencies {
    implementation 'org.springframework.ai:spring-ai-couchbase-store'
}

建立一個 Couchbase Cluster bean。有關自定義 Cluster 例項配置的更深入資訊，請參閱Couchbase 文件。

@Bean
public Cluster cluster() {
    return Cluster.connect("couchbase://", "username", "password");
}

然後使用 builder 模式建立 CouchbaseSearchVectorStore bean

@Bean
public VectorStore couchbaseSearchVectorStore(Cluster cluster,
                                              EmbeddingModel embeddingModel,
                                              Boolean initializeSchema) {
    return CouchbaseSearchVectorStore
            .builder(cluster, embeddingModel)
            .bucketName("test")
            .scopeName("test")
            .collectionName("test")
            .initializeSchema(initializeSchema)
            .build();
}

// This can be any EmbeddingModel implementation.
@Bean
public EmbeddingModel embeddingModel() {
    return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(this.openaiKey).build());
}

限制

必須啟用以下 Couchbase 服務：Data、Query、Index、Search。雖然 Data 和 Search 可能已足夠，但 Query 和 Index 對於支援完整的元資料過濾機制是必需的。