Couchbase

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

本节将指导你配置 CouchbaseSearchVectorStore，用于存储文档向量并通过 Couchbase 执行相似性搜索。

Couchbase 是分布式 JSON 文档数据库，具备关系型数据库的所有核心特性，支持基于向量的存储与查询等功能。

先决条件

运行中的 Couchbase 实例。可选方案包括：

自动配置

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 添加至构建文件。
请参考 “Artifact 仓库” 部分将 Milestone 和/或 Snapshot 仓库添加至构建文件。

向量存储实现可自动初始化配置的 bucket、scope、collection 及搜索索引（采用默认选项），但需通过在对应构造函数中指定 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>

若需通过环境变量配置敏感信息（如密码或 API Key），可选方案包括：

方案一：使用 Spring 表达式语言（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>

方案二：以编程方式访问环境变量

或者，在 Java 代码中直接访问环境变量：

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

此方案在确保敏感信息不暴露于配置文件的同时，提供了环境变量命名的灵活性。

若选择创建 shell 脚本以便后续操作，请确保在启动应用前通过 source <脚本名称>.sh 执行该脚本。

Spring Boot 针对 Couchbase Cluster（集群）的自动配置功能将创建一个 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

每个节点的最少 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 name.

-

spring.couchbase.env.timeouts.connect

Bucket 连接超时

10s

spring.couchbase.env.timeouts.disconnect

Bucket disconnect timeout.

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

常规及地理空间（GEO）视图操作超时设置。

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 的父级容器）。搜索查询将在该 scope 上下文中执行。

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

是否初始化必要表结构

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++ 过滤条件。

手动配置

若不使用 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 文档。

@Bean
public Cluster cluster() {
    return Cluster.connect("couchbase://localhost", "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 服务支持。