Azure DocumentDB

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

Azure DocumentDB 是该服务此前的名称 Azure CosmosDB for MongoDB vCore 更名后的称呼。本集成取代了已弃用的 Azure CosmosDB Mongo vCore 模块；现有用户应规划迁移。

Maven 依赖

你可以在纯 Java 或 Spring Boot 应用中将 Azure DocumentDB 与 LangChain4j 一起使用。

<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 需要 M30 或更高档的 Azure DocumentDB 集群层级。

该存储以余弦相似度创建索引，并假定余弦相似度来转换搜索分数。若你使用已有索引，它必须以 "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 版本匹配的 starter。

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>

两个 starter 使用相同的配置属性：

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，starter 会从一个 EmbeddingModel bean 推断它。推断要求有一个无歧义的 bean，或被标记为 @Primary 的 bean；否则配置会失败。显式指定的维度优先，且不需要嵌入模型 bean。当 create-index=false（默认）时，维度是可选的。

默认索引名仍为 defaultIndexAzureCosmos；可用 langchain4j.azure.documentdb.index-name 设置自定义索引名。其他默认值与纯 Java builder 一致：application-name=LangChain4j、num-lists=1、m=16、ef-construction=64 与 ef-search=40。

starter 会创建一个 AzureDocumentDbEmbeddingStore bean，并在应用上下文关闭时将其关闭。当设置了 connection-string 时，即使存在 MongoClient bean，存储也会创建并持有自己的客户端。否则，存储使用你的 MongoClient bean 且从不关闭它；该 bean 的所有者（通常是 Spring）负责其生命周期。多个客户端 bean 需要一个无歧义的候选，例如标记为 @Primary 的那个。由 Spring Boot 的 MongoDB 自动配置创建的默认客户端永不被使用，因此请设置 connection-string，除非你自己定义了 MongoClient bean。

在 Spring Boot 3 上，classpath 上的 MongoDB 驱动还会激活 Spring Boot 自己的 MongoDB 自动配置，它为 localhost:27017 创建一个默认客户端。该存储永不使用那个客户端。如果你的应用不以其他方式使用 MongoDB，请排除它：

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

设置 langchain4j.azure.documentdb.enabled=false 可禁用自动配置。定义你自己的 AzureDocumentDbEmbeddingStore bean 也会优先。

手动 bean 配置

要在不用 starter 的情况下配置存储，请使用纯 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 模块，迁移包含：

1. 将 artifact ID langchain4j-azure-cosmos-mongo-vcore 替换为 langchain4j-azure-documentdb。
2. 将对 AzureCosmosDbMongoVCoreEmbeddingStore 的引用替换为 AzureDocumentDbEmbeddingStore，并将 import 更新到 dev.langchain4j.store.embedding.azure.documentdb 包。
3. 设置向量索引 kind，并在创建索引时显式设置维度以匹配你的嵌入模型。
4. 按上文所述管理客户端生命周期。

对于 Spring Boot 应用，使用对应的替换 starter：

Spring Boot 版本	旧 artifact	替换 artifact
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：旧 starter 默认 为 vector-ivf，因此若你从未配置过，请设置 langchain4j.azure.documentdb.kind=vector-ivf，以继续使用你的现有索引。创建索引时，请设置 dimensions 或提供一个 EmbeddingModel bean；旧的默认值 1536 不再适用。

在添加新 starter 时请移除旧 starter。否则二者都会注册一个嵌入存储 bean。

如果你之前手动注册过 DocumentDB 存储 bean，请移除那个 bean 以让 starter 来配置，或保留它以继续使用你自己的配置。

连接字符串、数据库、集合、存储文档结构与默认索引名（defaultIndexAzureCosmos）保持不变。现有数据与索引无需重写。