Azure DocumentDB

https://learn.microsoft.com/en-us/azure/documentdb/

Azure DocumentDB は、以前 Azure CosmosDB for MongoDB vCore と呼ばれていたサービスの新しい名称です。この統合は、従来の Azure CosmosDB Mongo vCore モジュールを置き換えるものです。そのモジュールを使用している場合は、移行を計画してください。

Maven の依存関係

LangChain4j では、通常の Java アプリケーションでも Spring Boot アプリケーションでも Azure DocumentDB を使用できます。

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-documentdb</artifactId>
    <version>${latest version here}</version>
</dependency>

設定

ベクトルインデックスの kind は、既存のインデックスを使用する場合も含めて必須です。 AzureDocumentDbEmbeddingStore.VectorIndexType.VECTOR_IVF または AzureDocumentDbEmbeddingStore.VectorIndexType.VECTOR_HNSW を使用してください。文字列 "vector-ivf" と "vector-hnsw" もサポートされています。

createIndex(true) を設定する場合は、dimensions(...) が必須であり、埋め込みモデルの出力次元数と一致している必要があります。デフォルトの次元数はありません。 HNSW を使用するには、Azure DocumentDB クラスターのティアが M30 以上である必要があります。

ストアはコサイン類似度でインデックスを作成し、検索スコアもコサイン類似度を前提として変換します。既存のインデックスを使用する場合は、 "similarity": "COS" で作成されたものでなければなりません。そうでない場合、関連度スコアと minScore によるフィルタリングが正しく動作しません。

クライアントのライフサイクル

AzureDocumentDbEmbeddingStore は AutoCloseable を実装しています。 connectionString(...) で構成した場合、ストアは MongoClient を作成して所有します。ストアが不要になったらクローズしてください。たとえば try-with-resources を使用します。

try (AzureDocumentDbEmbeddingStore embeddingStore = AzureDocumentDbEmbeddingStore.builder()
        .connectionString(System.getenv("AZURE_DOCUMENTDB_CONNECTION_STRING"))
        .databaseName("my-database")
        .collectionName("my-collection")
        .createIndex(true)
        .kind(AzureDocumentDbEmbeddingStore.VectorIndexType.VECTOR_HNSW)
        .dimensions(1536)
        .build()) {
    // Add and search embeddings using embeddingStore.
}

代わりに mongoClient(...) でクライアントを渡した場合、そのクライアントは呼び出し側の所有のままです。ストアをクローズしてもクライアントはクローズされません。そのクライアントを共有するすべてのストアが不要になった後で、自分でクライアントをクローズしてください。渡されたクライアントは、接続文字列よりも優先されます。

ストアがクライアントを作成した後で初期化に失敗した場合、そのクライアントは自動的にクローズされます。close() を繰り返し呼び出しても何も起こりません。

接続文字列から作成されたクライアントは MongoDB ドライバーのデフォルト設定を使用し、読み取りタイムアウトは含まれません。操作の待機時間に上限を設けるには、接続文字列にタイムアウトオプションを追加してください。たとえば ...&socketTimeoutMS=30000&serverSelectionTimeoutMS=10000 のようにします。

Spring Boot

使用している Spring Boot のバージョンに合ったスターターを選択してください。

Spring Boot 3:

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-documentdb-spring-boot-starter</artifactId>
    <version>${latest version here}</version>
</dependency>

Spring Boot 4:

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-azure-documentdb-spring-boot4-starter</artifactId>
    <version>${latest version here}</version>
</dependency>

どちらのスターターも同じ設定プロパティを使用します。

langchain4j.azure.documentdb.connection-string=${AZURE_DOCUMENTDB_CONNECTION_STRING}
langchain4j.azure.documentdb.database-name=my-database
langchain4j.azure.documentdb.collection-name=my-collection
langchain4j.azure.documentdb.kind=vector-hnsw
langchain4j.azure.documentdb.create-index=true
langchain4j.azure.documentdb.dimensions=1536

database-name、collection-name、kind は必須です。dimensions は埋め込みモデルに合わせて設定してください。create-index=true で dimensions を省略した場合、スターターは EmbeddingModel Bean から次元数を推測します。推測を行うには、曖昧さのない Bean が 1 つだけ存在するか、@Primary が付いた Bean が必要です。そうでない場合は設定に失敗します。明示的に指定した次元数が優先され、その場合は埋め込みモデルの Bean は不要です。 create-index=false（デフォルト）の場合、次元数は任意です。

デフォルトのインデックス名は引き続き defaultIndexAzureCosmos です。カスタムのインデックス名は langchain4j.azure.documentdb.index-name で設定できます。その他のデフォルト値は通常の Java ビルダーと同じです: application-name=LangChain4j、num-lists=1、m=16、 ef-construction=64、ef-search=40。

スターターは AzureDocumentDbEmbeddingStore Bean を作成し、アプリケーションコンテキストのシャットダウン時にそれをクローズします。connection-string が設定されている場合、ストアは MongoClient Bean が存在していても、独自のクライアントを作成して所有します。設定されていない場合は、ストアはあなたの MongoClient Bean を使用し、それをクローズすることはありません。その Bean のライフサイクルは、通常は Spring である所有者が管理します。複数のクライアント Bean がある場合は、 @Primary が付いたものなど、曖昧さのない候補が必要です。Spring Boot の MongoDB 自動構成が作成するデフォルトのクライアントは決して使用されないため、独自の MongoClient Bean を定義しない限り、 connection-string を設定してください。

Spring Boot 3 では、クラスパス上の MongoDB ドライバーにより、Spring Boot 自身の MongoDB 自動構成も有効になり、localhost:27017 向けのデフォルトのクライアントが作成されます。ストアがそのクライアントを使用することはありません。アプリケーションが他に MongoDB を使用していない場合は、これを除外してください。

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration

自動構成を無効にするには、langchain4j.azure.documentdb.enabled=false を設定します。独自の AzureDocumentDbEmbeddingStore Bean を定義した場合も、そちらが優先されます。

Bean を手動で設定する

スターターを使わずにストアを構成するには、通常の Java 用の依存関係を使用し、 Spring の設定クラスで明示的に登録します。

@Bean(destroyMethod = "close")
AzureDocumentDbEmbeddingStore embeddingStore() {
    return AzureDocumentDbEmbeddingStore.builder()
            .connectionString(System.getenv("AZURE_DOCUMENTDB_CONNECTION_STRING"))
            .databaseName("my-database")
            .collectionName("my-collection")
            .createIndex(true)
            .kind(AzureDocumentDbEmbeddingStore.VectorIndexType.VECTOR_HNSW)
            .dimensions(1536)
            .build();
}

アプリケーションコンテキストのシャットダウン時に、Spring はこのストアと、その内部で作成されたクライアントをクローズします。

API

AzureDocumentDbEmbeddingStore

Azure CosmosDB Mongo vCore からの移行

以前に langchain4j-azure-cosmos-mongo-vcore モジュールを使用していた場合、移行の手順は次のとおりです。

アーティファクト ID langchain4j-azure-cosmos-mongo-vcore を langchain4j-azure-documentdb に置き換えます。
AzureCosmosDbMongoVCoreEmbeddingStore への参照を AzureDocumentDbEmbeddingStore に置き換え、インポートを dev.langchain4j.store.embedding.azure.documentdb パッケージに更新します。
ベクトルインデックスの kind を設定し、インデックスを作成する場合は、埋め込みモデルに合わせた次元数を明示的に設定します。
上記のとおりにクライアントのライフサイクルを管理します。

Spring Boot アプリケーションでは、対応する置き換え用のスターターを使用してください。

Spring Boot のバージョン	従来のアーティファクト	置き換え後のアーティファクト
3	`langchain4j-azure-cosmos-mongo-vcore-spring-boot-starter`	`langchain4j-azure-documentdb-spring-boot-starter`
4	`langchain4j-azure-cosmos-mongo-vcore-spring-boot4-starter`	`langchain4j-azure-documentdb-spring-boot4-starter`

プロパティのプレフィックスを langchain4j.azure.cosmos-mongo-vcore から langchain4j.azure.documentdb に変更し、接続、データベース、コレクション、およびカスタムのインデックス設定は引き継いでください。kind は明示的に設定してください。従来のスターターのデフォルトは vector-ivf だったため、これまで設定していなかった場合は、既存のインデックスを引き続き使用するために langchain4j.azure.documentdb.kind=vector-ivf を設定します。インデックスを作成する場合は、 dimensions を設定するか、EmbeddingModel Bean を提供してください。従来のデフォルト値である 1536 は適用されなくなりました。

新しいスターターを追加するときは、従来のスターターを削除してください。そうしないと、両方が埋め込みストア Bean を登録してしまいます。

以前に DocumentDB ストアの Bean を手動で登録していた場合は、その Bean を削除してスターターに設定を任せるか、そのまま残して独自の設定を使い続けることができます。

接続文字列、データベース、コレクション、保存されるドキュメントの形式、およびデフォルトのインデックス名（defaultIndexAzureCosmos）は変更されません。既存のデータとインデックスを書き直す必要はありません。

Maven の依存関係​

設定​

クライアントのライフサイクル​

Spring Boot​

Bean を手動で設定する​

API​

Azure CosmosDB Mongo vCore からの移行​

Maven の依存関係

設定

クライアントのライフサイクル

Spring Boot

Bean を手動で設定する

API

Azure CosmosDB Mongo vCore からの移行