Couchbase

QWen 3.8 中英对照 Couchbase

本部分将指导您配置 CouchbaseSearchVectorStore，以使用 Couchbase 存储文档嵌入并执行相似度搜索。

Couchbase 是一款分布式 JSON 文档数据库，具备关系型 DBMS 所需的所有功能。除此之外，它还支持用户利用基于向量的存储与检索技术来查询信息。

前提条件

一个正在运行的 Couchbase 实例。可用选项如下：Couchbase * Docker * Capella - Couchbase 云服务 * 在本地安装 Couchbase * Couchbase Kubernetes Operator

自动配置

备注

Spring AI 自动配置及 starter 模块的构件名称（artifact names）发生了重大变更。请参阅升级说明以获取更多信息。

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-starter-vector-store-couchbase'
}

备注

Couchbase 向量搜索要求 Couchbase Server 7.6 或更高版本，以及 Java SDK 3.6.0 或更高版本。

提示

请参考 Dependency Management 章节，以在你的构建文件中添加 Spring AI BOM。

提示

请参见 Artifact Repositories 部分，以在构建文件中添加 Milestone 和/或 Snapshot Repositories。

向量存储实现可以为你初始化配置好的桶（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 Couchbase
vectorStore.add(documents);

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

配置属性

要连接 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>

如果您希望使用环境变量来存储密码或 API 密钥等敏感信息，您可以选择以下多种方案：

选项 1：使用 Spring Expression Language (SpEL)

您可以使用自定义的环境变量名称，并在您的应用程序配置中使用 SpEL 对其进行引用：

# In application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
  couchbase:
    connection-string: ${COUCHBASE_CONN_STRING}
    username: ${COUCHBASE_USER}
    password: ${COUCHBASE_PASSWORD}

# In your environment or .env file
export OPENAI_API_KEY=<api-key>
export COUCHBASE_CONN_STRING=<couchbase connection string like couchbase://localhost>
export COUCHBASE_USER=<couchbase username>
export COUCHBASE_PASSWORD=<couchbase password>

选项 2：以编程方式访问环境变量

或者，您可以在 Java 代码中访问环境变量：

String apiKey = System.getenv("OPENAI_API_KEY");

这种方法使你在命名环境变量时更加灵活，同时避免在应用配置文件中存储敏感信息。

备注

如果您选择创建一个 shell 脚本以方便后续工作，请务必在启动应用程序之前通过“source”方式执行该文件，例如 source <your_script_name>.sh。

Spring Boot 针对 Couchbase 集群的自动配置功能会创建一个 bean 实例，供 CouchbaseSearchVectorStore 使用。

以 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 连接在被关闭并从连接池中移除前，允许保持空闲的时间长度。	1s
spring.couchbase.env.ssl.enabled	是否启用 SSL 支持。除非另有说明，否则提供 "bundle" 时会自动启用。	-
spring.couchbase.env.ssl.bundle	SSL 捆绑包名称。	-
spring.couchbase.env.timeouts.connect	Bucket 连接超时。	10s
spring.couchbase.env.timeouts.disconnect	Bucket 断开连接超时。	10s
spring.couchbase.env.timeouts.key-value	针对特定键值操作操作的超时时间。	2500ms
spring.couchbase.env.timeouts.key-value	针对具有持久性级别的特定键值操作的超时时间。	10s
spring.couchbase.env.timeouts.key-value-durable	针对具有持久性级别的特定键值操作的超时时间。	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	分析服务的超时时间。	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）的父级。搜索查询将在作用域上下文中执行。	default
spring.ai.vectorstore.couchbase.collection-name	用于存储文档的 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

• 延迟

有关向量搜索中每一项的更多详细信息，请参阅 Couchbase Documentation。

元数据过滤

您可以利用通用且可移植的 metadata filters 与 Couchbase store 配合使用。

例如，您可以使用文本表达式语言：

vectorStore.similaritySearch(
    SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .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)
    .filterExpression(b.and(
        b.in("author","john", "jill"),
        b.eq("article_type", "blog")).build())
    .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。有关自定义 Cluster 实例配置的更深入信息，请参阅 Couchbase Documentation。

@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 OpenAiEmbeddingModel.builder()
            .options(OpenAiEmbeddingOptions.builder().apiKey(this.openaiKey).build())
            .build();
}

局限性

备注

必须激活以下 Couchbase 服务：Data、Query、Index、Search。虽然 Data 和 Search 可能已经足够，但 Query 和 Index 对于支持完整的元数据过滤机制是必需的。