Elasticsearch

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

This section walks you through setting up the Elasticsearch VectorStore to store document embeddings and perform similarity searches.

Elasticsearch 是一个基于 Apache Lucene 库的开源搜索和分析引擎。

Elasticsearch is an open source search and analytics engine based on the Apache Lucene library.

Prerequisites

一个正在运行的 Elasticsearch 实例。以下选项可用：

A running Elasticsearch instance. The following options are available:

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 为 Elasticsearch Vector Store 提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

Spring AI provides Spring Boot auto-configuration for the Elasticsearch Vector Store. To enable it, add the following dependency to your project’s Maven pom.xml or Gradle build.gradle build files:

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-elasticsearch</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-elasticsearch'
}

对于早于 3.3.0 的 spring-boot 版本，需要显式添加版本 > 8.13.3 的 elasticsearch-java 依赖项，否则使用的旧版本将与执行的查询不兼容：

For spring-boot versions pre 3.3.0 it’s necessary to explicitly add the elasticsearch-java dependency with version > 8.13.3, otherwise the older version used will be incompatible with the queries performed:
Maven
<dependency>
    <groupId>co.elastic.clients</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.13.3</version>
</dependency>
Gradle
dependencies {
    implementation 'co.elastic.clients:elasticsearch-java:8.13.3'
}

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

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

将Maven Central和/或Snapshot存储库添加到您的构建文件中，请参阅 Artifact Repositories 部分。

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

向量存储实现可以为您初始化所需的架构，但您必须通过在适当的构造函数中指定 initializeSchema 布尔值或在 application.properties 文件中设置 …​initialize-schema=true 来选择加入。或者，您可以选择退出初始化并使用Elasticsearch客户端手动创建索引，如果索引需要高级映射或附加配置，这将非常有用。

The vector store implementation can initialize the requisite schema for you, but you must opt-in by specifying the initializeSchema boolean in the appropriate constructor or by setting …​initialize-schema=true in the application.properties file. Alternatively you can opt-out the initialization and create the index manually using the Elasticsearch client, which can be useful if the index needs advanced mapping or additional configuration.

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

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

请查看向量存储的 configuration parameters 列表，以了解默认值和配置选项。这些属性也可以通过配置 ElasticsearchVectorStoreOptions bean来设置。

Please have a look at the list of elasticsearchvector-properties for the vector store to learn about the default values and configuration options. These properties can be also set by configuring the ElasticsearchVectorStoreOptions bean.

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

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

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

Now you can auto-wire the ElasticsearchVectorStore 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 Elasticsearch
vectorStore.add(documents);

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

Configuration Properties

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

To connect to Elasticsearch and use the ElasticsearchVectorStore, you need to provide access details for your instance. A simple configuration can either be provided via Spring Boot’s application.yml,

spring:
  elasticsearch:
    uris: <elasticsearch instance URIs>
    username: <elasticsearch username>
    password: <elasticsearch password>
  ai:
    vectorstore:
      elasticsearch:
        initialize-schema: true
        index-name: custom-index
        dimensions: 1536
        similarity: cosine

以 spring.elasticsearch.* 开头的Spring Boot属性用于配置Elasticsearch客户端：

The Spring Boot properties starting with spring.elasticsearch.* are used to configure the Elasticsearch client:

Property Description Default Value

spring.elasticsearch.connection-timeout

Connection timeout used when communicating with Elasticsearch.

1s

spring.elasticsearch.password

Password for authentication with Elasticsearch.

-

spring.elasticsearch.username

Username for authentication with Elasticsearch.

-

spring.elasticsearch.uris

Comma-separated list of the Elasticsearch instances to use.

http://localhost:9200

spring.elasticsearch.path-prefix

Prefix added to the path of every request sent to Elasticsearch.

-

spring.elasticsearch.restclient.sniffer.delay-after-failure

Delay of a sniff execution scheduled after a failure.

1m

spring.elasticsearch.restclient.sniffer.interval

Interval between consecutive ordinary sniff executions.

5m

spring.elasticsearch.restclient.ssl.bundle

SSL bundle name.

-

spring.elasticsearch.socket-keep-alive

Whether to enable socket keep alive between client and Elasticsearch.

false

spring.elasticsearch.socket-timeout

Socket timeout used when communicating with Elasticsearch.

30s

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

Properties starting with spring.ai.vectorstore.elasticsearch.* are used to configure the ElasticsearchVectorStore:

Property Description Default Value

spring.ai.vectorstore.elasticsearch.initialize-schema

Whether to initialize the required schema

false

spring.ai.vectorstore.elasticsearch.index-name

The name of the index to store the vectors

spring-ai-document-index

spring.ai.vectorstore.elasticsearch.dimensions

The number of dimensions in the vector

1536

spring.ai.vectorstore.elasticsearch.similarity

The similarity function to use

cosine

以下相似性函数可用：

The following similarity functions are available:

  • cosine - 默认，适用于大多数用例。测量向量之间的余弦相似度。

  • cosine - Default, suitable for most use cases. Measures cosine similarity between vectors.

  • l2_norm - 向量之间的欧几里得距离。值越低表示相似度越高。

  • l2_norm - Euclidean distance between vectors. Lower values indicate higher similarity.

  • dot_product - 归一化向量（例如，OpenAI嵌入）的最佳性能。

  • dot_product - Best performance for normalized vectors (e.g., OpenAI embeddings).

有关每个内容的更多详细信息，请参阅关于稠密向量的 Elasticsearch Documentation 。

More details about each in the Elasticsearch Documentation on dense vectors.

Metadata Filtering

您也可以利用通用的、便携式的 metadata filters 与 Elasticsearch 配合使用。

You can leverage the generic, portable metadata filters with Elasticsearch as well.

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

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

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 以编程方式：

or programmatically using the 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());

这些（便携式）筛选表达式会自动转换为专有的 Elasticsearch Query string query 。

Those (portable) filter expressions get automatically converted into the proprietary Elasticsearch Query string query.

例如，此可移植的筛选器表达式：

For example, this portable filter expression:

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

被转换为专有的 Elasticsearch 过滤器格式：

is converted into the proprietary Elasticsearch filter format:

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

Manual Configuration

除了使用 Spring Boot 自动配置，您还可以手动配置 Elasticsearch 向量存储。为此，您需要将 spring-ai-elasticsearch-store 添加到您的项目中：

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

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

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

or to your Gradle build.gradle build file.

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

创建一个 Elasticsearch RestClient bean。阅读 Elasticsearch Documentation 以获取有关自定义 RestClient 配置的更深入信息。

Create an Elasticsearch RestClient bean. Read the Elasticsearch Documentation for more in-depth information about the configuration of a custom RestClient.

@Bean
public RestClient restClient() {
    return RestClient.builder(new HttpHost("<host>", 9200, "http"))
        .setDefaultHeaders(new Header[]{
            new BasicHeader("Authorization", "Basic <encoded username and password>")
        })
        .build();
}

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

Then create the ElasticsearchVectorStore bean using the builder pattern:

@Bean
public VectorStore vectorStore(RestClient restClient, EmbeddingModel embeddingModel) {
    ElasticsearchVectorStoreOptions options = new ElasticsearchVectorStoreOptions();
    options.setIndexName("custom-index");    // Optional: defaults to "spring-ai-document-index"
    options.setSimilarity(COSINE);           // Optional: defaults to COSINE
    options.setDimensions(1536);             // Optional: defaults to model dimensions or 1536

    return ElasticsearchVectorStore.builder(restClient, embeddingModel)
        .options(options)                     // Optional: use custom options
        .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")));
}

Accessing the Native Client

Elasticsearch 向量存储实现通过 getNativeClient() 方法提供对底层原生 Elasticsearch 客户端 ( ElasticsearchClient ) 的访问：

The Elasticsearch Vector Store implementation provides access to the underlying native Elasticsearch client (ElasticsearchClient) through the getNativeClient() method:

ElasticsearchVectorStore vectorStore = context.getBean(ElasticsearchVectorStore.class);
Optional<ElasticsearchClient> nativeClient = vectorStore.getNativeClient();

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

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

The native client gives you access to Elasticsearch-specific features and operations that might not be exposed through the VectorStore interface.