Použití konektoru Azure CosmosDB NoSQL Vector Store (Preview)

Upozorňující

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 Azure CosmosDB NoSQL Vector Store je možné použít k přístupu k datům v NoSQL a jejich správě. Konektor má následující charakteristiky.

Oblast funkcí	Technická podpora
Kolekce map na	Kontejner NoSQL služby Azure Cosmos DB
Podporované typy vlastností klíče	string AzureCosmosDBNoSQLCompositeKey
Podporované typy datových vlastností	string int long double float (číslo s plovoucí řádovou čárkou) bool DateTimeOffset a výčty každého z těchto typů
Podporované typy vektorových vlastností	ReadOnlyMemory<float> Bajt ReadOnlyMemory<> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
Podporované typy indexů	Plochý QuantizedFlat DiskAnn
Podporované funkce vzdálenosti	KosineSimilarita DotProductSimilarity EuclideanDistance
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, použijte JsonSerializerOptions a JsonPropertyNameAttribute místo toho. Další informace najdete tady.

Omezení

Při inicializaci CosmosClient ručně je nutné zadat CosmosClientOptions.UseSystemTextJsonSerializerWithOptions kvůli omezením ve výchozím serializátoru. Tuto možnost můžete nastavit na JsonSerializerOptions.Default nebo přizpůsobit pomocí dalších možností serializátoru, aby vyhovovala konkrétním potřebám konfigurace.

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

Začínáme

Do projektu přidejte balíček NuGet konektoru NoSQL NoSQL Vector Store.

dotnet add package Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL --prerelease

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

using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel
    .CreateBuilder()
    .AddAzureCosmosDBNoSQLVectorStore(connectionString, databaseName);

using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAzureCosmosDBNoSQLVectorStore(connectionString, databaseName);

K dispozici jsou také metody rozšíření, které nepoužívají žádné parametry. Vyžadují samostatnou registraci instance Microsoft.Azure.Cosmos.Database kontejneru injektáže závislostí.

using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<Database>(
    sp =>
    {
        var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
        {
            // When initializing CosmosClient manually, setting this property is required 
            // due to limitations in default serializer. 
            UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
        });

        return cosmosClient.GetDatabase(databaseName);
    });
kernelBuilder.AddAzureCosmosDBNoSQLVectorStore();

using Microsoft.Azure.Cosmos;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<Database>(
    sp =>
    {
        var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
        {
            // When initializing CosmosClient manually, setting this property is required 
            // due to limitations in default serializer. 
            UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
        });

        return cosmosClient.GetDatabase(databaseName);
    });
builder.Services.AddAzureCosmosDBNoSQLVectorStore();

Instanci Azure CosmosDB NoSQL Vector Store můžete vytvořit přímo.

using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

var database = cosmosClient.GetDatabase(databaseName);
var vectorStore = new AzureCosmosDBNoSQLVectorStore(database);

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

using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = JsonSerializerOptions.Default,
});

var database = cosmosClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels");

Mapování dat

Konektor Azure CosmosDB NoSQL Vector Store poskytuje výchozí mapovač při mapování z datového modelu do úložiště.

Tento mapovač provede přímý převod seznamu vlastností datového modelu na pole v NoSQL služby Azure CosmosDB a používá System.Text.Json.JsonSerializer k převodu na schéma úložiště. To znamená, že použití tohoto objektu JsonPropertyNameAttribute se podporuje, pokud se vyžaduje jiný název úložiště s názvem vlastnosti datového modelu. Jedinou výjimkou je klíč záznamu, který je namapován na pole databáze s názvem id, protože všechny záznamy NoSQL služby Cosmos DB musí pro ID používat tento název.

Vlastní instanci je také možné použít JsonSerializerOptions s vlastní zásadou pojmenování vlastností. Aby to bylo možné, JsonSerializerOptions musí být předána AzureCosmosDBNoSQLVectorStoreRecordCollection do konstrukce.

using System.Text.Json;
using Microsoft.Azure.Cosmos;
using Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL;

var jsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseUpper };

var cosmosClient = new CosmosClient(connectionString, new CosmosClientOptions()
{
    // When initializing CosmosClient manually, setting this property is required 
    // due to limitations in default serializer. 
    UseSystemTextJsonSerializerWithOptions = jsonSerializerOptions
});

var database = cosmosClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels",
    new() { JsonSerializerOptions = jsonSerializerOptions });

Pomocí výše uvedeného vlastního JsonSerializerOptions modelu, který používá SnakeCaseUpper, se následující datový model namapuje na následující json.

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

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

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

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

    [JsonPropertyName("HOTEL_DESCRIPTION_EMBEDDING")]
    [VectorStoreRecordVector(4, DistanceFunction.EuclideanDistance, IndexKind.QuantizedFlat)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

{
    "id": 1,
    "HOTEL_NAME": "Hotel Happy",
    "DESCRIPTION": "A place where everyone can be happy.",
    "HOTEL_DESCRIPTION_EMBEDDING": [0.9, 0.1, 0.1, 0.1],
}

Použití klíče oddílu

Ve výchozím nastavení je vlastnost klíče oddílu v konektoru Azure Cosmos DB for NoSQL nastavena na vlastnost klíče – id. Vlastnost PartitionKeyPropertyName ve třídě AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> umožňuje zadat jinou vlastnost jako klíč oddílu.

Třída AzureCosmosDBNoSQLVectorStoreRecordCollection podporuje dva typy klíčů: string a AzureCosmosDBNoSQLCompositeKey. AzureCosmosDBNoSQLCompositeKey se skládá z RecordKey a PartitionKey.

Pokud vlastnost klíče oddílu není nastavená (a použije se výchozí vlastnost klíče), lze string klíče použít pro operace se záznamy databáze. Pokud je však zadána vlastnost klíče oddílu, doporučuje se použít AzureCosmosDBNoSQLCompositeKey k zadání hodnot klíče i klíče oddílu.

Zadejte název vlastnosti klíče oddílu:

var options = new AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<Hotel>
{
    PartitionKeyPropertyName = nameof(Hotel.HotelName)
};

var collection = new AzureCosmosDBNoSQLVectorStoreRecordCollection<Hotel>(database, "collection-name", options) 
    as IVectorStoreRecordCollection<AzureCosmosDBNoSQLCompositeKey, Hotel>;

Získat pomocí klíče oddílu:

var record = await collection.GetAsync(new AzureCosmosDBNoSQLCompositeKey("hotel-id", "hotel-name"));

Již brzy

Další informace budou brzy k dispozici.

Již brzy

Další informace budou brzy k dispozici.