Couchbase

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

This section will walk you through setting up the CouchbaseSearchVectorStore to store document embeddings and perform similarity searches using Couchbase.

Couchbase 是一个分布式 JSON 文档数据库，具有关系型 DBMS 的所有所需功能。除了其他功能外，它还允许用户使用基于向量的存储和检索来查询信息。

Couchbase is a distributed, JSON document database, with all the desired capabilities of a relational DBMS. Among other features, it allows users to query information using vector-based storage and retrieval.

Prerequisites

一个正在运行的 Couchbase 实例。以下选项可用：Couchbase * Docker * Capella - Couchbase as a Service * Install Couchbase locally * Couchbase Kubernetes Operator

A running Couchbase instance. The following options are available: Couchbase * Docker * Capella - Couchbase as a Service * Install Couchbase locally * Couchbase Kubernetes Operator

Auto-configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 为 Couchbase 向量存储提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您项目的 Maven pom.xml 文件中：

Spring AI provides Spring Boot auto-configuration for the Couchbase Vector Store. To enable it, add the following dependency to your project’s Maven pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-couchbase</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-couchbase-store-spring-boot-starter'
}

Couchbase 向量搜索仅在 7.6 及更高版本和 Java SDK 3.6.0 版本中可用。

Couchbase Vector search is only available in starting version 7.6 and Java SDK version 3.6.0"

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

请参阅 Artifact Repositories 部分以将里程碑和/或快照存储库添加到您的构建文件中。

Refer to the Artifact Repositories section to add Milestone and/or Snapshot Repositories to your build file.

向量存储实现可以初始化配置的桶、范围、集合和搜索索引，并使用默认选项，但您必须通过在相应的构造函数中指定 initializeSchema 布尔值来选择启用。

The vector store implementation can initialize the configured bucket, scope, collection and search index for you, with default options, but you must opt-in by specifying the initializeSchema boolean in the appropriate constructor.

这是一个重大更改！在早期版本的 Spring AI 中，此模式初始化是默认发生的。

This is a breaking change! In earlier versions of Spring AI, this schema initialization happened by default.

请查看向量存储的 configuration parameters 列表，以了解默认值和配置选项。

Please have a look at the list of couchbasevector-properties for the vector store to learn about the default values and configuration options.

此外，您还需要一个配置好的 EmbeddingModel bean。有关更多信息，请参阅 EmbeddingModel 部分。

Additionally, you will need a configured EmbeddingModel bean. Refer to the EmbeddingModel section for more information.

现在，您可以将 CouchbaseSearchVectorStore 作为向量存储在应用程序中自动装配。

Now you can auto-wire the CouchbaseSearchVectorStore as a vector store in your application.

@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));

Configuration Properties

要连接到 Couchbase 并使用 CouchbaseSearchVectorStore ，您需要提供实例的访问详细信息。可以通过 Spring Boot 的 application.properties 提供配置：

To connect to Couchbase and use the CouchbaseSearchVectorStore, you need to provide access details for your instance. Configuration can be provided via Spring Boot’s application.properties:

spring.ai.openai.api-key=<key>
spring.couchbase.connection-string=<conn_string>
spring.couchbase.username=<username>
spring.couchbase.password=<password>

如果您更喜欢使用环境变量来存储密码或 API 密钥等敏感信息，您有多种选择：

If you prefer to use environment variables for sensitive information like passwords or API keys, you have multiple options:

Option 1: Using Spring Expression Language (SpEL)

您可以使用自定义环境变量名称并在应用程序配置中使用 SpEL 引用它们：

You can use custom environment variable names and reference them in your application configuration using 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>

Option 2: Accessing Environment Variables Programmatically

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

Alternatively, you can access environment variables in your Java code:

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

这种方法使您在命名环境变量方面具有灵活性，同时将敏感信息排除在应用程序配置文件之外。

This approach gives you flexibility in naming your environment variables while keeping sensitive information out of your application configuration files.

如果您选择创建 Shell 脚本以方便以后的工作，请务必在通过“获取”文件来启动应用程序之前运行该脚本，即 source <your_script_name>.sh。

If you choose to create a shell script for ease in future work, be sure to run it prior to starting your application by "sourcing" the file, i.e. source <your_script_name>.sh.

Spring Boot 的 Couchbase 集群自动配置功能将创建一个 bean 实例，该实例将由 CouchbaseSearchVectorStore 使用。

Spring Boot’s auto-configuration feature for the Couchbase Cluster will create a bean instance that will be used by the CouchbaseSearchVectorStore.

以 spring.couchbase.* 开头的 Spring Boot 属性用于配置 Couchbase 集群实例：

The Spring Boot properties starting with spring.couchbase.* are used to configure the Couchbase cluster instance:

Property Description Default Value

spring.couchbase.connection-string

A couchbase connection string

couchbase://localhost

spring.couchbase.password

Password for authentication with Couchbase.

-

spring.couchbase.username

Username for authentication with Couchbase.

-

spring.couchbase.env.io.minEndpoints

Minimum number of sockets per node.

1

spring.couchbase.env.io.maxEndpoints

Maximum number of sockets per node.

12

spring.couchbase.env.io.idleHttpConnectionTimeout

Length of time an HTTP connection may remain idle before it is closed and removed from the pool.

1s

spring.couchbase.env.ssl.enabled

Whether to enable SSL support. Enabled automatically if a "bundle" is provided unless specified otherwise.

-

spring.couchbase.env.ssl.bundle

SSL bundle name.

-

spring.couchbase.env.timeouts.connect

Bucket connect timeout.

10s

spring.couchbase.env.timeouts.disconnect

Bucket disconnect timeout.

10s

spring.couchbase.env.timeouts.key-value

Timeout for operations on a specific key-value.

2500ms

spring.couchbase.env.timeouts.key-value

Timeout for operations on a specific key-value with a durability level.

10s

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

Timeout for operations on a specific key-value with a durability level.

10s

spring.couchbase.env.timeouts.query

SQL++ query operations timeout.

75s

spring.couchbase.env.timeouts.view

Regular and geospatial view operations timeout.

75s

spring.couchbase.env.timeouts.search

Timeout for the search service.

75s

spring.couchbase.env.timeouts.analytics

Timeout for the analytics service.

75s

spring.couchbase.env.timeouts.management

Timeout for the management operations.

75s

以 spring.ai.vectorstore.couchbase.* 前缀开头的属性用于配置 CouchbaseSearchVectorStore 。

Properties starting with the spring.ai.vectorstore.couchbase.* prefix are used to configure CouchbaseSearchVectorStore.

Property Description Default Value

spring.ai.vectorstore.couchbase.index-name

The name of the index to store the vectors.

spring-ai-document-index

spring.ai.vectorstore.couchbase.bucket-name

The name of the Couchbase Bucket, parent of the scope.

default

spring.ai.vectorstore.couchbase.scope-name

The name of the Couchbase scope, parent of the collection. Search queries will be executed in the scope context.

default

spring.ai.vectorstore.couchbase.collection-name

The name of the Couchbase collection to store the Documents.

default

spring.ai.vectorstore.couchbase.dimensions

The number of dimensions in the vector.

1536

spring.ai.vectorstore.couchbase.similarity

The similarity function to use.

dot_product

spring.ai.vectorstore.couchbase.optimization

The similarity function to use.

recall

spring.ai.vectorstore.couchbase.initialize-schema

whether to initialize the required schema

false

以下相似性函数可用：

The following similarity functions are available:

  • l2_norm

  • dot_product

以下索引优化可用：

The following index optimizations are available:

  • recall

  • latency

有关每个优化的更多详细信息，请参阅向量搜索上的 Couchbase Documentation 。

More details about each in the Couchbase Documentation on vector searches.

Metadata Filtering

您可以利用通用、可移植的 metadata filters 与 Couchbase 存储。

You can leverage the generic, portable metadata filters with the Couchbase store.

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

For example, you can use either the text expression language:

vectorStore.similaritySearch(
    SearchRequest.defaults()
    .query("The World")
    .topK(TOP_K)
    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));

或使用 Filter.Expression DSL 以编程方式：

or programmatically using the 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++ 过滤器。

These filter expressions are converted into the equivalent Couchbase SQL++ filters.

Manual Configuration

您可以手动配置 Couchbase 向量存储，而不是使用 Spring Boot 自动配置。为此，您需要将 spring-ai-couchbase-store 添加到您的项目中：

Instead of using the Spring Boot auto-configuration, you can manually configure the Couchbase vector store. For this you need to add the spring-ai-couchbase-store to your project:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-couchbase-store</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-couchbase-store'
}

创建一个 Couchbase Cluster bean。阅读 Couchbase Documentation 以获取有关自定义集群实例配置的更深入信息。

Create a Couchbase Cluster bean. Read the Couchbase Documentation for more in-depth information about the configuration of a custom Cluster instance.

@Bean
public Cluster cluster() {
    return Cluster.connect("couchbase://localhost", "username", "password");
}

然后使用构建器模式创建 CouchbaseSearchVectorStore bean：

and then create the CouchbaseSearchVectorStore bean using the builder pattern:

@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());
}

Limitations

必须激活以下 Couchbase 服务：数据、查询、索引、搜索。虽然数据和搜索可能就足够了，但查询和索引是支持完整元数据筛选机制所必需的。

It is mandatory to have the following Couchbase services activated: Data, Query, Index, Search. While Data and Search could be enough, Query and Index are necessary to support the complete metadata filtering mechanism.