Uso del connettore Elasticsearch (anteprima)

Panoramica

Il connettore Elasticsearch Vector Store può essere usato per accedere e gestire i dati in Elasticsearch. Il connettore presenta le caratteristiche seguenti.

Introduzione

Per eseguire Elasticsearch localmente per lo sviluppo locale o il test, eseguire lo script start-local con un comando:

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

Aggiungi il pacchetto NuGet del connettore Elasticsearch Vector Store al tuo progetto.

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

È possibile aggiungere l'archivio vettoriale al contenitore di inserimento delle dipendenze disponibile nel KernelBuilder o al contenitore di inserimento delle dipendenze IServiceCollection usando i metodi di estensione forniti dal kernel semantico.

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

Vengono forniti anche metodi di estensione che non accettano parametri. Questi richiedono che un'istanza della classe Elastic.Clients.Elasticsearch.ElasticsearchClient sia registrata separatamente con il contenitore di inserimento delle dipendenze.

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

È possibile costruire direttamente un'istanza di 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"))));

È possibile costruire un riferimento diretto a una raccolta denominata.

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

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

Mapping dei dati

Il connettore Elasticsearch userà System.Text.Json.JsonSerializer per eseguire il mapping. Poiché Elasticsearch archivia i documenti con una chiave/ID e un valore separati, il mapper serializzerà tutte le proprietà ad eccezione della chiave in un oggetto JSON e lo userà come valore.

L'utilizzo del JsonPropertyNameAttribute è supportato se è necessario un nome di archiviazione diverso per il nome della proprietà del modello di dati. È anche possibile usare un'istanza di JsonSerializerOptions personalizzata con un criterio di denominazione delle proprietà personalizzato. Per abilitare questa operazione, è necessario configurare un serializzatore di origine personalizzato.

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

In alternativa, la funzione lambda DefaultFieldNameInferrer può essere configurata per ottenere lo stesso risultato o per personalizzare ulteriormente la denominazione delle proprietà in base alle condizioni dinamiche.

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

Poiché è stato scelto un criterio di denominazione snake_case maiuscolo, ecco un esempio di come questo tipo di dato verrà configurato in Elasticsearch. Si noti anche l'uso di JsonPropertyNameAttribute nella proprietà Description per personalizzare ulteriormente la denominazione di archiviazione.

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

Non supportato

Non supportato.

Non supportato

Non supportato.