Použití konektoru Elasticsearch (Preview)

Varování

Funkce sémantického úložiště vektorů jádra je ve verzi Preview a vylepšení, která vyžadují zásadní změny, se můžou vyskytovat za omezených okolností před vydáním.

Přehled

Konektor Elasticsearch Vector Store lze použít pro přístup k datům v Elasticsearch a jejich správě. Konektor má následující charakteristiky.

Oblast funkcí	Podpora
Mapy kolekce	Index Elasticsearchu
Podporované typy vlastností klíče	řetězec
Podporované typy datových vlastností	Všechny typy, které podporuje System.Text.Json (integrované nebo pomocí vlastního převaděče)
Podporované typy vektorových vlastností	ReadOnlyMemory<plovoucí> IEnumerable<float>
Podporované typy indexů	HNSW (32, 8 nebo 4 bitů) FLAT (32, 8 nebo 4 bitů)
Podporované funkce vzdálenosti	KosineSimilarita DotProductSimilarity EuclideanDistance MaxInnerProduct
Podporované klauzule filtru	AnyTagEqualTo EqualTo
Podporuje více vektorů v záznamu.	Ano
Je podporováno Filtrování?	Ano
Podporuje se IsFullTextSearchable?	Ano
StoragePropertyName se podporuje?	Ne, místo toho použijte JsonSerializerOptions a JsonPropertyNameAttribute. Další informace najdete tady.

Začínáme

Pokud chcete spustit Elasticsearch místně pro místní vývoj nebo testování, spusťte skript start-local jedním příkazem:

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

Přidejte balíček NuGet s konektorem Elasticsearch Vector Store do svého projektu.

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

Úložiště vektorů můžete přidat do kontejneru injektáže závislostí dostupného v KernelBuilder nebo do kontejneru injektáže závislostí IServiceCollection pomocí rozšiřujících metod poskytovaných sémantickým jádrem.

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

K dispozici jsou také metody rozšíření, které nepoužívají žádné parametry. Vyžadují, aby instance třídy Elastic.Clients.Elasticsearch.ElasticsearchClient byla zvlášť registrována v kontejneru pro injektáž závislostí.

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();

Instanci Elasticsearch Vector Store můžete vytvořit přímo.

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

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

Je možné vytvořit přímý odkaz na pojmenovanou kolekci.

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

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

Mapování dat

Konektor Elasticsearch použije k mapování System.Text.Json.JsonSerializer. Vzhledem k tomu, že Elasticsearch ukládá dokumenty se samostatným klíčem/ID a hodnotou, mapovač serializuje všechny vlastnosti s výjimkou klíče k objektu JSON a použije ho jako hodnotu.

Pokud se vyžaduje jiný název úložiště s názvem vlastnosti datového modelu, je použití JsonPropertyNameAttribute podporováno. Je také možné použít vlastní instanci JsonSerializerOptions s vlastní zásadou pojmenování vlastností. Pokud to chcete povolit, musí být nakonfigurovaný vlastní serializátor zdroje.

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

Jako alternativu je možné nakonfigurovat funkci DefaultFieldNameInferrer lambda tak, aby dosáhla stejného výsledku nebo ještě více přizpůsobila pojmenování vlastností na základě dynamických podmínek.

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

Vzhledem k tomu, že byla vybrána zásada pojmenování ve formátu snake case s velkými písmeny, zde je příklad, jak bude tento datový typ nastaven v Elasticsearch. Všimněte si také použití JsonPropertyNameAttribute ve vlastnosti Description k dalšímu přizpůsobení pojmenování úložiště.

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
    ]
  }
}

Nepodporováno

Nepodporuje se.

Nepodporováno

Nepodporuje se.