De Elasticsearch-connector gebruiken (preview)

Waarschuwing

De functionaliteit van de Semantische Kernel Vector Store is in preview en verbeteringen waarvoor ingrijpende wijzigingen nodig zijn, kunnen in beperkte omstandigheden nog steeds optreden voordat ze worden gelanceerd.

Overzicht

De Elasticsearch Vector Store-connector kan worden gebruikt voor toegang tot en beheer van gegevens in Elasticsearch. De verbindingslijn heeft de volgende kenmerken.

Functiegebied	Ondersteuning
De verzameling wijst naar	Elasticsearch index
Ondersteunde belangrijke eigenschapssoorten	koord
Ondersteunde gegevenseigenschapstypen	Alle typen die worden ondersteund door System.Text.Json (ingebouwd of met behulp van een aangepast conversieprogramma)
Ondersteunde vectoreigenschappentypen	ReadOnlyMemory<float> IEnumerable<float>
Ondersteunde indextypen	HNSW (32, 8 of 4 bit) FLAT (32, 8 of 4 bit)
Ondersteunde afstandsfuncties	CosineSimilariteit DotProductSimilarity EuclideanDistance MaxInnerProduct
Ondersteunde filtercriteria	AnyTagEqualTo EqualTo
Ondersteunt meerdere vectoren in een record	Ja
Wordt Filterable ondersteund?	Ja
WordtFullTextSearchable ondersteund?	Ja
Wordt StoragePropertyName ondersteund?	Nee, gebruik in plaats daarvan JsonSerializerOptions en JsonPropertyNameAttribute. Zie hier voor meer informatie.

Aan de slag

Als u Elasticsearch lokaal wilt uitvoeren voor lokale ontwikkeling of testen, voert u het start-local-script uit met één opdracht:

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

Voeg het NuGet-pakket Elasticsearch Vector Store-connector toe aan uw project.

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

U kunt het vectorarchief toevoegen aan de container voor afhankelijkheidsinjectie die beschikbaar is op de KernelBuilder of aan de IServiceCollection afhankelijkheidsinjectiecontainer met behulp van extensiemethoden die worden geleverd door Semantische kernel.

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

Extensiemethoden waarvoor geen parameters worden gebruikt, worden ook opgegeven. Hiervoor moet een exemplaar van de Elastic.Clients.Elasticsearch.ElasticsearchClient-klasse afzonderlijk worden geregistreerd bij de container voor afhankelijkheidsinjectie.

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

U kunt rechtstreeks een Elasticsearch Vector Store-exemplaar maken.

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

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

Het is mogelijk om een directe verwijzing naar een benoemde verzameling te maken.

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

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

Datamapping

De Elasticsearch-connector gebruikt System.Text.Json.JsonSerializer om toewijzingen uit te voeren. Omdat Elasticsearch documenten met een afzonderlijke sleutel/id en waarde opslaat, serialiseert de mapper alle eigenschappen, met uitzondering van de sleutel naar een JSON-object en gebruikt deze als de waarde.

Het gebruik van de JsonPropertyNameAttribute wordt ondersteund als een andere opslagnaam voor de naam van de gegevensmodeleigenschap is vereist. Het is ook mogelijk om een aangepast JsonSerializerOptions exemplaar te gebruiken met een aangepast naamgevingsbeleid voor eigenschappen. Als u dit wilt inschakelen, moet een aangepaste bronserialisatie worden geconfigureerd.

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

Als alternatief kan de DefaultFieldNameInferrer lambda-functie worden geconfigureerd om hetzelfde resultaat te bereiken of om de naamgeving van eigenschappen verder aan te passen op basis van dynamische voorwaarden.

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

Aangezien een naamgevingsbeleid van snake case upper is gekozen, is hier een voorbeeld van hoe dit gegevenstype wordt ingesteld in Elasticsearch. Let ook op het gebruik van JsonPropertyNameAttribute in de eigenschap Description om de naamgeving van de opslag verder aan te passen.

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

Niet ondersteund

Niet ondersteund.

Niet ondersteund

Niet ondersteund.