Couchbase

本节将引导您设置 CouchbaseSearchVectorStore，以便使用 Couchbase 存储文档嵌入并执行相似度搜索。

Couchbase 是一个分布式 JSON 文档数据库，具备关系型数据库管理系统 (DBMS) 的所有理想功能。在其他特性中，它允许用户使用基于向量的存储和检索来查询信息。

前提条件

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

自动配置

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 添加到构建文件的信息，请参阅依赖管理部分。
有关将 Milestone 和/或 Snapshot 仓库添加到构建文件的信息，请参阅仓库部分。

向量存储实现可以为您使用默认选项初始化配置的 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 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>

或者可以是这些方式的组合。例如，如果您想将密码存储为环境变量，而将其余配置保留在 plain application.yml 文件中。

如果您选择创建一个 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

每个节点的最小 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 名称。

-

spring.couchbase.env.timeouts.connect

Bucket 连接超时。

10s

spring.couchbase.env.timeouts.disconnect

Bucket 断开连接超时。

10s

spring.couchbase.env.timeouts.key-value

针对特定 key-value 操作的超时。

2500ms

spring.couchbase.env.timeouts.key-value

针对具有耐久性级别的特定 key-value 操作的超时。

10s

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

针对具有耐久性级别的特定 key-value 操作的超时。

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

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

存储 Documents 的 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

  • 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++ 过滤器。

手动配置

您可以手动配置 Couchbase 向量存储，而不是使用 Spring Boot 自动配置。为此，您需要将 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 对于支持完整的元数据过滤机制是必需的。