跳到主要内容

OpenSearch

Deepseek 3.2 中英对照 OpenSearch

本节将引导您配置 OpenSearchVectorStore 来存储文档嵌入向量并执行相似性搜索。

OpenSearch 是一款源自 Elasticsearch 分支的开源搜索与分析引擎，采用 Apache License 2.0 协议分发。它通过简化 AI 生成资产的集成与管理，增强了 AI 应用程序的开发能力。OpenSearch 支持向量搜索、词法搜索以及混合搜索功能，并利用先进的向量数据库功能来实现低延迟查询和相似性搜索，具体细节可参阅向量数据库页面。

OpenSearch k-NN 功能允许用户从大型数据集中查询向量嵌入。嵌入是数据对象（如文本、图像、音频或文档）的数值表示。嵌入可以存储在索引中，并使用各种相似度函数进行查询。

先决条件​

自动配置​

备注

Spring AI 自动配置和 starter 模块的 artifact 名称发生了重大变化。更多信息请参阅升级说明。

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

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

或添加到您的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-opensearch'
}
提示

对于自托管版本和 Amazon OpenSearch 服务，请使用相同的依赖项。请参考依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

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

此外，你还需要一个配置好的 EmbeddingModel bean。更多信息请参阅EmbeddingModel章节。

现在，你可以在应用程序中自动装配 OpenSearchVectorStore 作为向量存储：

@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("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 OpenSearch
vectorStore.add(documents);

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

配置属性​

要连接到 OpenSearch 并使用 OpenSearchVectorStore，你需要提供实例的访问详细信息。可以通过 Spring Boot 的 application.yml 提供一个简单的配置：

spring:
  ai:
    vectorstore:
      opensearch:
        uris: <opensearch instance URIs>
        username: <opensearch username>
        password: <opensearch password>
        index-name: spring-ai-document-index
        initialize-schema: true
        similarity-function: cosinesimil
        read-timeout: <time to wait for response>
        connect-timeout: <time to wait until connection established>
        path-prefix: <custom path prefix>
        ssl-bundle: <name of SSL bundle>
        aws:  # Only for Amazon OpenSearch Service
          host: <aws opensearch host>
          service-name: <aws service name>
          access-key: <aws access key>
          secret-key: <aws secret key>
          region: <aws region>

以 spring.ai.vectorstore.opensearch.* 开头的属性用于配置 OpenSearchVectorStore：

属性描述默认值
spring.ai.vectorstore.opensearch.urisOpenSearch 集群端点的 URI-
spring.ai.vectorstore.opensearch.username访问 OpenSearch 集群的用户名-
spring.ai.vectorstore.opensearch.password指定用户名对应的密码-
spring.ai.vectorstore.opensearch.index-name存储向量的索引名称spring-ai-document-index
spring.ai.vectorstore.opensearch.initialize-schema是否初始化所需的模式false
spring.ai.vectorstore.opensearch.similarity-function要使用的相似度函数 (cosinesimil, l1, l2, linf, innerproduct)cosinesimil
spring.ai.vectorstore.opensearch.use-approximate-knn是否使用近似 k-NN 以进行更快的搜索。如果为 true，则使用基于 HNSW 的近似搜索。如果为 false，则使用精确的暴力 k-NN。参见 近似 k-NN 和 精确 k-NNfalse
spring.ai.vectorstore.opensearch.dimensions向量嵌入的维度数。在创建近似 k-NN 的索引映射时使用。如果未设置，则使用嵌入模型的维度。1536
spring.ai.vectorstore.opensearch.mapping-json索引的自定义 JSON 映射。覆盖默认的映射生成。-
spring.ai.vectorstore.opensearch.read-timeout等待对端响应的超时时间。0 表示无限。-
spring.ai.vectorstore.opensearch.connect-timeout等待建立连接的超时时间。0 表示无限。-
spring.ai.vectorstore.opensearch.path-prefixOpenSearch API 端点的路径前缀。当 OpenSearch 位于具有非根路径的反向代理之后时很有用。-
spring.ai.vectorstore.opensearch.ssl-bundle在 SSL 连接情况下要使用的 SSL Bundle 名称-
spring.ai.vectorstore.opensearch.aws.hostOpenSearch 实例的主机名-
spring.ai.vectorstore.opensearch.aws.service-nameAWS 服务名称-
spring.ai.vectorstore.opensearch.aws.access-keyAWS 访问密钥-
spring.ai.vectorstore.opensearch.aws.secret-keyAWS 密钥-
spring.ai.vectorstore.opensearch.aws.regionAWS 区域-
备注

您可以通过 spring.ai.vectorstore.opensearch.aws.enabled 属性来控制是否启用 AWS 特定的 OpenSearch 自动配置。

  • 如果此属性设置为 false，则会激活非 AWS 的 OpenSearch 配置，即使类路径上存在 AWS SDK 类。这允许您在为了其他服务而存在 AWS SDK 的环境中，使用自管理或第三方的 OpenSearch 集群。

  • 如果 AWS SDK 类不存在，则始终使用非 AWS 配置。

  • 如果 AWS SDK 类存在，并且该属性未设置或设置为 true，则默认使用 AWS 特定的配置。

这种回退逻辑确保用户能够明确控制 OpenSearch 集成的类型，防止在不需要时意外激活 AWS 特定的逻辑。

备注

path-prefix 属性允许您在 OpenSearch 运行于使用非根路径的反向代理之后时，指定自定义路径前缀。例如，如果您的 OpenSearch 实例可通过 [example.com/opensearch/](https://example.com/opensearch/) 访问，而不是 [example.com/](https://example.com/)，您需要设置 path-prefix: /opensearch。

以下相似度函数可供使用：

  • cosinesimil - 默认选项，适用于大多数场景。计算向量间的余弦相似度。

  • l1 - 向量间的曼哈顿距离。

  • l2 - 向量间的欧几里得距离。

  • linf - 向量间的切比雪夫距离。

手动配置​

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

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

或添加到您的 Gradle build.gradle 构建文件：

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

:::提示
参考 依赖管理 部分，将 Spring AI BOM 添加到你的构建文件中。
:::

创建一个 OpenSearch 客户端 Bean：

@Bean
public OpenSearchClient openSearchClient() {
    RestClient restClient = RestClient.builder(
        HttpHost.create("http://localhost:9200"))
        .build();

    return new OpenSearchClient(new RestClientTransport(
        restClient, new JacksonJsonpMapper()));
}

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

@Bean
public VectorStore vectorStore(OpenSearchClient openSearchClient, EmbeddingModel embeddingModel) {
    return OpenSearchVectorStore.builder(openSearchClient, embeddingModel)
        .index("custom-index")                // Optional: defaults to "spring-ai-document-index"
        .similarityFunction("l2")             // Optional: defaults to "cosinesimil"
        .useApproximateKnn(true)              // Optional: defaults to false (exact k-NN)
        .dimensions(1536)                     // Optional: defaults to 1536 or embedding model's dimensions
        .initializeSchema(true)               // Optional: defaults to false
        .batchingStrategy(new TokenCountBatchingStrategy()) // Optional: defaults to TokenCountBatchingStrategy
        .build();
}

// This can be any EmbeddingModel implementation
@Bean
public EmbeddingModel embeddingModel() {
    return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY")));
}

元数据筛选​

你也可以在OpenSearch中使用通用的、可移植的元数据过滤器。

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

vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .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)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression(b.and(
        b.in("author", "john", "jill"),
        b.eq("article_type", "blog")).build()).build());
备注

这些（可移植的）过滤器表达式会自动转换为专有的 OpenSearch 查询字符串查询。

例如，这个可移植的过滤表达式：

author in ['john', 'jill'] && 'article_type' == 'blog'

会转换为专有的 OpenSearch 筛选格式：

(metadata.author:john OR jill) AND metadata.article_type:blog

访问原生客户端​

OpenSearch Vector Store 实现通过 getNativeClient() 方法提供了对底层原生 OpenSearch 客户端 (OpenSearchClient) 的访问：

OpenSearchVectorStore vectorStore = context.getBean(OpenSearchVectorStore.class);
Optional<OpenSearchClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    OpenSearchClient client = nativeClient.get();
    // Use the native client for OpenSearch-specific operations
}

原生客户端允许您访问可能未通过VectorStore接口公开的OpenSearch特定功能和操作。