Couchbase

このセクションでは、CouchbaseSearchVectorStore を設定してドキュメントの埋め込みを保存し、Couchbase を使用して類似性検索を実行する方法について説明します。

Couchbase (英語) は、リレーショナル DBMS に必要なすべての機能を備えた分散型 JSON ドキュメントデータベースです。他の機能の中でも、ベクトルベースのストレージと取得を使用して情報を照会できる機能があります。

前提条件

実行中の Couchbase インスタンス。次のオプションが利用可能です: Couchbase * Docker (英語) * Capella - Couchbase as a Service (英語) * Install Couchbase locally (英語) * Couchbase Kubernetes Operator (英語)

自動構成

Spring AI 自動構成、スターターモジュールのアーティファクト名に大きな変更がありました。詳細については、アップグレードノートを参照してください。

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 をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。
マイルストーンおよび / またはスナップショットリポジトリをビルドファイルに追加するには、リポジトリセクションを参照してください。

ベクトルストアの実装では、デフォルトのオプションを使用して、構成されたバケット、スコープ、コレクション、検索インデックスを初期化できますが、適切なコンストラクターで initializeSchema ブール値を指定してオプトインする必要があります。

これは重大な変更です。Spring AI の以前のバージョンでは、このスキーマの初期化はデフォルトで行われていました。

デフォルト値と構成オプションについては、ベクトルストアの構成パラメーターのリストを参照してください。

さらに、設定済みの 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://localhost>
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>

または、それらの組み合わせにすることもできます。例: パスワードを環境変数として保存し、残りをプレーンな application.yml ファイルに保存する場合。

将来の作業を容易にするためにシェルスクリプトを作成することを選択した場合は、ファイル (つまり source <your_script_name>.sh) を「ソース」してアプリケーションを開始する前に必ずシェルスクリプトを実行してください。

Spring Boot の Couchbase クラスターの自動構成機能により、CouchbaseSearchVectorStore で使用される Bean インスタンスが作成されます。

spring.couchbase.* で始まる Spring Boot プロパティは、Couchbase クラスターインスタンスを構成するために使用されます。

プロパティ 説明 デフォルト値

spring.couchbase.connection-string

Couchbase 接続文字列

couchbase://localhost

spring.couchbase.password

Couchbase での認証用のパスワード。

-

spring.couchbase.username

Couchbase での認証用のユーザー名。

-

spring.couchbase.env.io.minEndpoints

ノードあたりのソケットの最小数。

1

spring.couchbase.env.io.maxEndpoints

ノードあたりのソケットの最大数。

12

spring.couchbase.env.io.idleHttpConnectionTimeout

HTTP 接続が閉じられてプールから削除される前に、HTTP 接続がアイドル状態のままになる可能性がある時間の長さ。

1 秒

spring.couchbase.env.ssl.enabled

SSL サポートを有効にするかどうか。特に指定がない限り、「バンドル」が提供されている場合は自動的に有効になります。

-

spring.couchbase.env.ssl.bundle

SSL バンドル名。

-

spring.couchbase.env.timeouts.connect

バケット接続タイムアウト。

10 秒

spring.couchbase.env.timeouts.disconnect

バケット切断タイムアウト。

10 秒

spring.couchbase.env.timeouts.key-value

特定の Key-Value での操作のタイムアウト。

2500 ミリ秒

spring.couchbase.env.timeouts.key-value

耐久性レベルを持つ特定の Key-Value での操作のタイムアウト。

10 秒

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

耐久性レベルを持つ特定の Key-Value での操作のタイムアウト。

10 秒

spring.couchbase.env.timeouts.query

SQL++ クエリ操作がタイムアウトしました。

75 秒

spring.couchbase.env.timeouts.view

通常および地理空間ビュー操作のタイムアウト。

75 秒

spring.couchbase.env.timeouts.search

検索サービスのタイムアウト。

75 秒

spring.couchbase.env.timeouts.analytics

分析サービスのタイムアウト。

75 秒

spring.couchbase.env.timeouts.management

管理操作のタイムアウト。

75 秒

spring.ai.vectorstore.couchbase.* プレフィックスで始まるプロパティは、CouchbaseSearchVectorStore を構成するために使用されます。

プロパティ 説明 デフォルト値

spring.ai.vectorstore.couchbase.index-name

ベクトルを格納するインデックスの名前。

spring-ai-document-index

spring.ai.vectorstore.couchbase.bucket-name

スコープの親である Couchbase バケットの名前。

default

spring.ai.vectorstore.couchbase.scope-name

コレクションの親である Couchbase スコープの名前。検索クエリはスコープコンテキストで実行されます。

デフォルト

spring.ai.vectorstore.couchbase.collection-name

ドキュメントを保存する Couchbase コレクションの名前。

デフォルト

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

必要なスキーマを初期化するかどうか

false

次の類似度関数が利用可能です。

  • l2_ ノルム

  • dot_product

次のインデックス最適化が利用可能です。

  • 想起

  • レイテンシー

それぞれの詳細については、ベクトル検索の 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++ フィルターに変換されます。

手動構成

Spring Boot の自動構成を使用する代わりに、Couchbase ベクトルストアを手動で構成できます。そのためには、プロジェクトに 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 を作成します。カスタムクラスタインスタンスの構成に関する詳細については、Couchbase ドキュメント (英語) を参照してください。

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

次に、ビルダーパターンを使用して 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());
}

制限

It is mandatory to have the following Couchbase services activated: Data, Query, Index, Search. While Data and Search could be enough, Query and Index are necessary to support the complete metadata filtering mechanism.