Elasticsearch

本節將引導您設定 Elasticsearch VectorStore，以儲存文件嵌入 (document embeddings) 並執行相似性搜尋。

Elasticsearch 是一個基於 Apache Lucene 函式庫的開源搜尋與分析引擎。

先決條件

一個正在運行的 Elasticsearch 實例。以下選項可供選擇：

自動配置

Spring AI 為 Elasticsearch Vector Store 提供 Spring Boot 自動配置。若要啟用它，請將以下依賴項新增至您專案的 Maven pom.xml 或 Gradle build.gradle 建置檔案中：

  • Maven

  • Gradle

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

對於 spring-boot 3.3.0 之前的版本，必須明確新增 elasticsearch-java 依賴項，且版本需高於 8.13.3，否則使用的舊版本將與執行的查詢不相容。

  • Maven

  • Gradle

<dependency>
    <groupId>co.elastic.clients</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.13.3</version>
</dependency>
dependencies {
    implementation 'co.elastic.clients:elasticsearch-java:8.13.3'
}
請參閱依賴項管理章節，將 Spring AI BOM 新增至您的建置檔案。
請參閱儲存庫章節，將 Milestone 和/或 Snapshot 儲存庫新增至您的建置檔案。

向量儲存庫實作可以為您初始化必要的 schema，但您必須選擇加入，方法是在適當的建構子中指定 initializeSchema 布林值，或在 application.properties 檔案中設定 …​initialize-schema=true。或者，您可以選擇不進行初始化，並使用 Elasticsearch 用戶端手動建立索引，如果索引需要進階映射或額外配置，這會很有用。

這是一個重大變更！在 Spring AI 的早期版本中，此 schema 初始化是預設發生的。

請查看組態參數列表，以瞭解向量儲存庫的預設值和組態選項。這些屬性也可以透過配置 ElasticsearchVectorStoreOptions bean 來設定。

此外，您還需要一個已配置的 EmbeddingModel bean。請參閱EmbeddingModel 章節以取得更多資訊。

現在，您可以在您的應用程式中自動注入 ElasticsearchVectorStore 作為向量儲存庫。

@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 = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));

組態屬性

若要連線到 Elasticsearch 並使用 ElasticsearchVectorStore，您需要提供您實例的存取詳細資訊。可以透過 Spring Boot 的 application.yml 提供簡單的組態，

spring:
  elasticsearch:
    uris: <elasticsearch instance URIs>
    username: <elasticsearch username>
    password: <elasticsearch password>
# API key if needed, e.g. OpenAI
  ai:
    openai:
      api:
        key: <api-key>

環境變數，

export SPRING_ELASTICSEARCH_URIS=<elasticsearch instance URIs>
export SPRING_ELASTICSEARCH_USERNAME=<elasticsearch username>
export SPRING_ELASTICSEARCH_PASSWORD=<elasticsearch password>
# API key if needed, e.g. OpenAI
export SPRING_AI_OPENAI_API_KEY=<api-key>

或可以是兩者的組合。例如，如果您想將密碼儲存為環境變數，但將其餘內容保留在純 application.yml 檔案中。

如果您選擇建立 shell 腳本以方便日後工作，請務必在啟動應用程式之前「source」該檔案，例如 source <your_script_name>.sh。

Spring Boot 的 Elasticsearch RestClient 自動配置功能將建立一個 bean 實例，該實例將由 ElasticsearchVectorStore 使用。

以 spring.elasticsearch.* 開頭的 Spring Boot 屬性用於配置 Elasticsearch 用戶端

屬性 描述 預設值

spring.elasticsearch.connection-timeout

與 Elasticsearch 通訊時使用的連線逾時。

1 秒

spring.elasticsearch.password

用於 Elasticsearch 驗證的密碼。

-

spring.elasticsearch.username

用於 Elasticsearch 驗證的使用者名稱。

-

spring.elasticsearch.uris

要使用的 Elasticsearch 實例的逗號分隔列表。

localhost:9200

spring.elasticsearch.path-prefix

新增至傳送至 Elasticsearch 的每個請求路徑的前綴。

-

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

在失敗後排定的嗅探執行延遲。

1 分鐘

spring.elasticsearch.restclient.sniffer.interval

連續普通嗅探執行之間的間隔。

5 分鐘

spring.elasticsearch.restclient.ssl.bundle

SSL bundle 名稱。

-

spring.elasticsearch.socket-keep-alive

是否啟用用戶端和 Elasticsearch 之間的 socket keep alive。

false

spring.elasticsearch.socket-timeout

與 Elasticsearch 通訊時使用的 Socket 逾時。

30 秒

以 spring.ai.vectorstore.elasticsearch.* 前綴開頭的屬性用於配置 ElasticsearchVectorStore。

屬性 描述 預設值

spring.ai.vectorstore.elasticsearch.initialize-schema

是否初始化所需的 schema

false

spring.ai.vectorstore.elasticsearch.index-name

儲存向量的索引名稱。

spring-ai-document-index

spring.ai.vectorstore.elasticsearch.dimensions

向量中的維度數量。

1536

spring.ai.vectorstore.elasticsearch.similarity

要使用的相似度函數。

cosine

以下是可用的相似度函數：

  • cosine

  • l2_norm

  • dot_product

有關每個函數的更多詳細資訊，請參閱 Elasticsearch 文件中關於 dense vectors 的說明。

元數據過濾

您也可以將通用的、可移植的 元數據過濾器 與 Elasticsearch 一起使用。

例如，您可以使用文字表達式語言

vectorStore.similaritySearch(SearchRequest.defaults()
        .withQuery("The World")
        .withTopK(TOP_K)
        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
        .withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));

或以程式設計方式使用 Filter.Expression DSL

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.defaults()
        .withQuery("The World")
        .withTopK(TOP_K)
        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
        .withFilterExpression(b.and(
                b.in("john", "jill"),
                b.eq("article_type", "blog")).build()));
這些（可移植的）過濾器表達式會自動轉換為專有的 Elasticsearch Query string query。

例如，這個可移植的過濾器表達式：

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

會轉換為專有的 Elasticsearch 過濾器格式：

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

手動配置

除了使用 Spring Boot 自動配置之外，您還可以手動配置 Elasticsearch 向量儲存庫。為此，您需要將 spring-ai-elasticsearch-store 新增至您的專案

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

或您的 Gradle build.gradle 建置檔案。

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

建立一個 Elasticsearch RestClient bean。請閱讀 Elasticsearch 文件，以取得有關自訂 RestClient 配置的更深入資訊。

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

然後建立 ElasticsearchVectorStore bean

@Bean
public ElasticsearchVectorStore vectorStore(EmbeddingModel embeddingModel, RestClient restClient) {
    return new ElasticsearchVectorStore( restClient, embeddingModel);
}

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