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 (buď vestavěné, nebo s použitím vlastního převaděče)
Podporované typy vektorových vlastností	<plovoucí> readOnlyMemory 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 konektoru 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.