沙发底座

本节将引导您完成设置CouchbaseSearchVectorStore使用 Couchbase 存储文档嵌入并执行相似性搜索。spring-doc.cadn.net.cn

Couchbase 是一个分布式 JSON 文档数据库,具有关系 DBMS 的所有所需功能。除其他功能外,它还允许用户使用基于矢量的存储和检索来查询信息。spring-doc.cadn.net.cn

前提条件

正在运行的 Couchbase 实例。以下选项可用:Couchbase* Docker * Capella - Couchbase 即服务 * 在本地安装 Couchbase * Couchbase Kubernetes Operatorspring-doc.cadn.net.cn

自动配置

Spring AI 自动配置、入门模块的工件名称发生了重大变化。 有关更多信息,请参阅升级说明spring-doc.cadn.net.cn

Spring AI 为 Couchbase Vector Store 提供 Spring Boot 自动配置。要启用它,请将以下依赖项添加到项目的 Mavenpom.xml文件:spring-doc.cadn.net.cn

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

或 Gradlebuild.gradle构建文件。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-couchbase-store-spring-boot-starter'
}
Couchbase 矢量搜索仅在 7.6 版和 Java SDK 3.6.0 版开始时可用”
请参阅依赖项管理部分,将 Spring AI BOM 添加到构建文件中。
请参阅 工件存储库(Artifact Repositories) 部分,将里程碑和/或快照存储库添加到构建文件中。

向量存储实现可以使用默认选项为您初始化配置的存储桶、范围、集合和搜索索引,但您必须通过指定initializeSchema布尔值。spring-doc.cadn.net.cn

这是一个重大变化!在早期版本的 Spring AI 中,默认情况下会发生此模式初始化。

请查看矢量存储的配置参数列表,了解默认值和配置选项。spring-doc.cadn.net.cn

此外,您还需要配置一个EmbeddingModel豆。有关详细信息,请参阅 EmbeddingModel 部分。spring-doc.cadn.net.cn

现在,您可以自动连接CouchbaseSearchVectorStore作为应用程序中的矢量存储。spring-doc.cadn.net.cn

@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-doc.cadn.net.cn

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

如果您更喜欢将环境变量用于密码或 API 密钥等敏感信息,您有多种选择:spring-doc.cadn.net.cn

选项 1:使用 Spring 表达式语言 (SpEL)

您可以使用自定义环境变量名称,并使用 SpEL 在应用程序配置中引用它们:spring-doc.cadn.net.cn

# 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 代码中的环境变量:spring-doc.cadn.net.cn

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

此方法使您可以灵活地命名环境变量,同时将敏感信息排除在应用程序配置文件之外。spring-doc.cadn.net.cn

如果您选择创建 shell 脚本以方便将来的工作,请务必在启动应用程序之前通过“采购”文件来运行它,即source <your_script_name>.sh.

Spring Boot 对 Couchbase 集群的自动配置功能将创建一个 bean 实例,该实例将由CouchbaseSearchVectorStore.spring-doc.cadn.net.cn

spring.couchbase.*用于配置 Couchbase 集群实例:spring-doc.cadn.net.cn

属性 描述 默认值

spring.couchbase.connection-stringspring-doc.cadn.net.cn

couchbase 连接字符串spring-doc.cadn.net.cn

couchbase://localhostspring-doc.cadn.net.cn

spring.couchbase.passwordspring-doc.cadn.net.cn

使用 Couchbase 进行身份验证的密码。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.couchbase.usernamespring-doc.cadn.net.cn

使用 Couchbase 进行身份验证的用户名。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.couchbase.env.io.minEndpointsspring-doc.cadn.net.cn

每个节点的最小套接字数。spring-doc.cadn.net.cn

1spring-doc.cadn.net.cn

spring.couchbase.env.io.maxEndpointsspring-doc.cadn.net.cn

每个节点的最大套接字数。spring-doc.cadn.net.cn

12spring-doc.cadn.net.cn

spring.couchbase.env.io.idleHttpConnectionTimeoutspring-doc.cadn.net.cn

HTTP 连接在关闭并从池中删除之前可能保持空闲状态的时间长度。spring-doc.cadn.net.cn

1秒spring-doc.cadn.net.cn

spring.couchbase.env.ssl.enabledspring-doc.cadn.net.cn

是否启用 SSL 支持。除非另有说明,否则如果提供“捆绑包”,则自动启用。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.couchbase.env.ssl.bundlespring-doc.cadn.net.cn

SSL 捆绑包名称。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.connectspring-doc.cadn.net.cn

存储桶连接超时。spring-doc.cadn.net.cn

10秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.disconnectspring-doc.cadn.net.cn

存储桶断开超时。spring-doc.cadn.net.cn

10秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.key-valuespring-doc.cadn.net.cn

对特定键值进行作的超时。spring-doc.cadn.net.cn

2500毫秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.key-valuespring-doc.cadn.net.cn

对具有持久性级别的特定键值进行作的超时。spring-doc.cadn.net.cn

10秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.key-value-durablespring-doc.cadn.net.cn

对具有持久性级别的特定键值进行作的超时。spring-doc.cadn.net.cn

10秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.queryspring-doc.cadn.net.cn

SQL++ 查询作超时。spring-doc.cadn.net.cn

75秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.viewspring-doc.cadn.net.cn

常规和地理空间视图作超时。spring-doc.cadn.net.cn

75秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.searchspring-doc.cadn.net.cn

搜索服务超时。spring-doc.cadn.net.cn

75秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.analyticsspring-doc.cadn.net.cn

分析服务的超时。spring-doc.cadn.net.cn

75秒spring-doc.cadn.net.cn

spring.couchbase.env.timeouts.managementspring-doc.cadn.net.cn

管理作超时。spring-doc.cadn.net.cn

75秒spring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.*prefix 用于配置CouchbaseSearchVectorStore.spring-doc.cadn.net.cn

属性 描述 默认值

spring.ai.vectorstore.couchbase.index-namespring-doc.cadn.net.cn

用于存储向量的索引的名称。spring-doc.cadn.net.cn

Spring-ai-文档索引spring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.bucket-namespring-doc.cadn.net.cn

Couchbase Bucket 的名称,作用域的父级。spring-doc.cadn.net.cn

默认值spring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.scope-namespring-doc.cadn.net.cn

Couchbase 作用域的名称,集合的父级。搜索查询将在作用域上下文中执行。spring-doc.cadn.net.cn

默认值spring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.collection-namespring-doc.cadn.net.cn

用于存储文档的 Couchbase 集合的名称。spring-doc.cadn.net.cn

默认值spring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.dimensionsspring-doc.cadn.net.cn

向量中的维数。spring-doc.cadn.net.cn

1536spring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.similarityspring-doc.cadn.net.cn

要使用的相似性函数。spring-doc.cadn.net.cn

dot_productspring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.optimizationspring-doc.cadn.net.cn

要使用的相似性函数。spring-doc.cadn.net.cn

recallspring-doc.cadn.net.cn

spring.ai.vectorstore.couchbase.initialize-schemaspring-doc.cadn.net.cn

是否初始化所需的模式spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

可以使用以下相似性函数:spring-doc.cadn.net.cn

可以使用以下索引优化:spring-doc.cadn.net.cn

有关每个的更多详细信息,请参阅有关向量搜索的 Couchbase 文档spring-doc.cadn.net.cn

元数据过滤

您可以利用 Couchbase 存储的通用可移植元数据过滤器spring-doc.cadn.net.cn

例如,您可以使用文本表达式语言:spring-doc.cadn.net.cn

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

或以编程方式使用Filter.ExpressionDSL:spring-doc.cadn.net.cn

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到你的项目:spring-doc.cadn.net.cn

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

或 Gradlebuild.gradle构建文件。spring-doc.cadn.net.cn

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

创建 CouchbaseCluster豆。 阅读 Couchbase 文档,了解有关自定义集群实例配置的更多深入信息。spring-doc.cadn.net.cn

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

,然后创建CouchbaseSearchVectorStorebean 使用构建器模式:spring-doc.cadn.net.cn

@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 服务:数据、查询、索引、搜索。虽然数据和搜索就足够了,但查询和索引对于支持完整的元数据过滤机制是必要的。