Elasticsearch コネクタの使用 (プレビュー)

警告

セマンティック カーネル ベクター ストア機能はプレビュー段階であり、破壊的変更を必要とする機能強化は、リリース前の限られた状況で引き続き発生する可能性があります。

概要

Elasticsearch Vector Store コネクタを使用して、Elasticsearch のデータにアクセスして管理できます。 コネクタには次の特性があります。

機能領域	サポート
コレクションは〜にマップされる	Elasticsearch インデックス
サポートされているキー プロパティの種類	string long Guid
サポートされているデータ プロパティ型	System.Text.Jsonでサポートされているすべての型 (etiher 組み込みまたはカスタム コンバーターを使用)
サポートされているベクター プロパティ型	ReadOnlyMemory<float> IEnumerable<float> IReadOnlyCollection<float> ICollection<float> IReadOnlyList<float> IList<float> float[]
サポートされているインデックスの種類	HNSW (32、8、または 4 ビットまたはバーベキュー) FLAT (32、8、または 4 ビットまたはバーベキュー)
サポートされている距離関数	コサイン類似度 ドット積類似度 (DotProductSimilarity) EuclideanDistance MaxInnerProduct
サポートされているフィルター条件	AnyTagEqualTo EqualTo
レコード内の複数のベクターをサポートします	はい
IsIndexed はサポートされていますか?	はい
IsFullTextIndexed がサポートされていますか?	はい
StoragePropertyName がサポートされていますか?	いいえ。代わりに JsonSerializerOptions と JsonPropertyNameAttribute を使用してください。 詳細については、こちらを参照してください。
HybridSearch はサポートされていますか?	はい

始めに

ローカルで開発またはテスト Elasticsearch をローカルで実行するには、次の 1 つのコマンドを使用して start-local スクリプトを実行します。

curl -fsSL https://elastic.co/start-local | sh

Elasticsearch Vector Store コネクタ NuGet パッケージをプロジェクトに追加します。

dotnet add package Elastic.SemanticKernel.Connectors.Elasticsearch --prerelease

セマンティック カーネルによって提供される拡張メソッドを使用して、KernelBuilder で使用できる依存関係挿入コンテナーまたは IServiceCollection 依存関係挿入コンテナーにベクター ストアを追加できます。

using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddElasticsearchVectorStore(new ElasticsearchClientSettings(new Uri("http://localhost:9200")));

using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddElasticsearchVectorStore(new ElasticsearchClientSettings(new Uri("http://localhost:9200")));

パラメーターを受け取たない拡張メソッドも提供されます。 これらには、Elastic.Clients.Elasticsearch.ElasticsearchClient クラスのインスタンスを依存関係挿入コンテナーに個別に登録する必要があります。

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<ElasticsearchClient>(sp =>
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))));
kernelBuilder.AddElasticsearchVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using Elastic.Clients.Elasticsearch;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ElasticsearchClient>(sp =>
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))));
builder.Services.AddElasticsearchVectorStore();

Elasticsearch Vector Store インスタンスを直接構築できます。

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;

var vectorStore = new ElasticsearchVectorStore(
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))));

名前付きコレクションへの直接参照を構築できます。

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;

var collection = new ElasticsearchVectorStoreRecordCollection<Hotel>(
    new ElasticsearchClient(new ElasticsearchClientSettings(new Uri("http://localhost:9200"))),
    "skhotels");

データ マッピング

Elasticsearch コネクタは、マッピングを行うために System.Text.Json.JsonSerializer を使用します。 Elasticsearch は個別のキー/ID と値を持つドキュメントを格納するため、マッパーはキーを除くすべてのプロパティを JSON オブジェクトにシリアル化し、その値として使用します。

データ モデルのプロパティ名とは異なるストレージ名が必要な場合は、JsonPropertyNameAttribute の使用がサポートされます。 カスタマイズされたプロパティの名前付けポリシーを使用して、カスタム JsonSerializerOptions インスタンスを使用することもできます。 これを有効にするには、カスタム ソース シリアライザーを構成する必要があります。

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;
using Elastic.Clients.Elasticsearch.Serialization;
using Elastic.Transport;

var nodePool = new SingleNodePool(new Uri("http://localhost:9200"));
var settings = new ElasticsearchClientSettings(
    nodePool,
    sourceSerializer: (defaultSerializer, settings) =>
        new DefaultSourceSerializer(settings, options => 
            options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper));
var client = new ElasticsearchClient(settings);

var collection = new ElasticsearchVectorStoreRecordCollection<Hotel>(
    client,
    "skhotelsjson");

別の方法として、DefaultFieldNameInferrer ラムダ関数を構成して同じ結果を得るか、動的条件に基づいてプロパティの名前付けをさらにカスタマイズすることもできます。

using Elastic.SemanticKernel.Connectors.Elasticsearch;
using Elastic.Clients.Elasticsearch;

var settings = new ElasticsearchClientSettings(new Uri("http://localhost:9200"));
settings.DefaultFieldNameInferrer(name => JsonNamingPolicy.SnakeCaseUpper.ConvertName(name));
var client = new ElasticsearchClient(settings);

var collection = new ElasticsearchVectorStoreRecordCollection<Hotel>(
    client,
    "skhotelsjson");

スネーク ケースの上位の名前付けポリシーが選択されたため、Elasticsearch でこのデータ型を設定する方法の例を次に示します。 また、ストレージの名前付けをさらにカスタマイズするために、JsonPropertyNameAttribute プロパティでの Description の使用にも注意してください。

using System.Text.Json.Serialization;
using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public string HotelId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string HotelName { get; set; }

    [JsonPropertyName("HOTEL_DESCRIPTION")]
    [VectorStoreRecordData(IsFullTextSearchable = true)]
    public string Description { get; set; }

    [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
  "_index" : "skhotelsjson",
  "_id" : "h1",
  "_source" : {
    "HOTEL_NAME" : "Hotel Happy",
    "HOTEL_DESCRIPTION" : "A place where everyone can be happy.",
    "DESCRIPTION_EMBEDDING" : [
      0.9,
      0.1,
      0.1,
      0.1
    ]
  }
}

サポートされていません

サポートされていません。

サポートされていません

サポートされていません。