Elasticsearch

このセクションでは、ドキュメントの埋め込みを保存し、類似性検索を実行するための Elasticsearch VectorStore の設定について説明します。

Elasticsearch (英語) は、Apache Lucene ライブラリをベースにしたオープンソースの検索および分析エンジンです。

前提条件

実行中の Elasticsearch インスタンス。次のオプションが利用可能です。

自動構成

Spring AI は、Elasticsearch ベクトルストアの Spring Boot 自動構成を提供します。これを有効にするには、プロジェクトの Maven pom.xml ファイルに次の依存関係を追加します。

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

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.ai:spring-ai-elasticsearch-store-spring-boot-starter'
}
3.3.0 より前の spring-boot バージョンの場合、バージョン> 8.13.3 で elasticsearch-java 依存関係を明示的に追加する必要があります。そうしないと、使用される古いバージョンは実行されるクエリと互換性がなくなります。
<dependency>
    <groupId>co.elastic.clients</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.13.3</version>
</dependency>
Spring AI BOM をビルドファイルに追加するには、"依存関係管理" セクションを参照してください。
マイルストーンおよび / またはスナップショットリポジトリをビルドファイルに追加するには、リポジトリセクションを参照してください。

ベクトルストアの実装では必要なスキーマを初期化できますが、適切なコンストラクターで initializeSchema ブール値を指定するか、application.properties ファイルで …​initialize-schema=true を設定することでオプトインする必要があります。または、初期化をオプトアウトし、Elasticsearch クライアントを使用して手動でインデックスを作成することもできます。これは、インデックスに高度なマッピングや追加の構成が必要な場合に役立ちます。

これは重大な変更です。Spring AI の以前のバージョンでは、このスキーマの初期化はデフォルトで行われていました。

デフォルト値と構成オプションについては、ベクトルストアの構成パラメーターのリストを参照してください。これらのプロパティは、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 = 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 ファイルに保存する場合。

将来の作業を容易にするためにシェルスクリプトを作成することを選択した場合は、ファイル (つまり source <your_script_name>.sh) を「ソース」してアプリケーションを開始する前に必ずシェルスクリプトを実行してください。

Elasticsearch RestClient の Spring Boot の自動構成機能により、ElasticsearchVectorStore で使用される Bean インスタンスが作成されます。

spring.elasticsearch.* で始まる Spring Boot プロパティは、Elasticsearch クライアントを構成するために使用されます。

プロパティ 説明 デフォルト値

spring.elasticsearch.connection-timeout

Elasticsearch と通信するときに使用される接続タイムアウト。

1s

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

失敗後にスケジュールされたスニフ実行の遅延。

1m

spring.elasticsearch.restclient.sniffer.interval

連続する通常のスニフ実行間の間隔。

5m

spring.elasticsearch.restclient.ssl.bundle

SSL バンドル名。

-

spring.elasticsearch.socket-keep-alive

クライアントと Elasticsearch 間のソケットキープアライブを有効にするかどうか。

false

spring.elasticsearch.socket-timeout

Elasticsearch と通信するときに使用されるソケットタイムアウト。

30s

spring.ai.vectorstore.elasticsearch.* プレフィックスで始まるプロパティは、ElasticsearchVectorStore を構成するために使用されます。

プロパティ 説明 デフォルト値

spring.ai.vectorstore.elasticsearch.initialize-schema

必要なスキーマを初期化するかどうか

false

spring.ai.vectorstore.elasticsearch.index-name

ベクトルを格納するインデックスの名前。

spring-ai-document-index

spring.ai.vectorstore.elasticsearch.dimensions

ベクトルの次元数。

1536

spring.ai.vectorstore.elasticsearch.similarity

使用する類似度関数。

cosine

spring.ai.vectorstore.elasticsearch.initialize-schema

必要なスキーマを初期化するかどうか

false

次の類似度関数が利用可能です。

  • 余弦

  • l2_ ノルム

  • dot_product

それぞれの詳細については、密なベクトルに関する Elasticsearch ドキュメント (英語) を参照してください。

メタデータフィルタリング

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 クエリ文字列クエリ (英語) に自動的に変換されます。

例: この移植可能なフィルター式:

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 を作成します。カスタム RestClient の構成に関する詳細については、Elasticsearch ドキュメント (英語) を参照してください。

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