Korzystanie z łącznika usługi Azure CosmosDB NoSQL Vector Store (wersja zapoznawcza)

Ostrzeżenie

Funkcja semantycznego magazynu wektorów jądra jest dostępna w wersji zapoznawczej, a ulepszenia wymagające zmian powodujących niezgodność mogą nadal występować w ograniczonych okolicznościach przed wydaniem.

Omówienie

Łącznik magazynu wektorów NoSQL usługi Azure CosmosDB może służyć do uzyskiwania dostępu do danych w usłudze Azure CosmosDB NoSQL i zarządzania nimi. Łącznik ma następujące cechy.

Obszar funkcji	Pomoc techniczna
Mapowania kolekcji na	Kontener NoSQL usługi Azure Cosmos DB
Obsługiwane typy właściwości kluczy	string AzureCosmosDBNoSQLCompositeKey
Obsługiwane typy właściwości danych	string int długi double liczba zmiennoprzecinkowa bool DateTimeOffset i wyliczalne każdego z tych typów
Obsługiwane typy właściwości wektorów	ReadOnlyMemory<float> Bajt ReadOnlyMemory<> ReadOnlyMemory<sbyte> ReadOnlyMemory<Połowa>
Obsługiwane typy indeksów	Spłaszcz Kwantyzowaneflat DiskAnn
Obsługiwane funkcje odległości	CosineSimilarity DotProductSimilarity EuclideanDistance
Obsługiwane klauzule filtru	AnyTagEqualTo EqualTo
Obsługuje wiele wektorów w rekordzie	Tak
Czy filtrowanie jest obsługiwane?	Tak
Czy jest obsługiwany element IsFullTextSearchable?	Tak
Obsługiwana nazwa_właściwości_magazynu?	Nie, użyj JsonSerializerOptions polecenia i JsonPropertyNameAttribute zamiast tego. Aby uzyskać więcej informacji, zobacz tutaj.

Ograniczenia

Podczas ręcznego inicjowania CosmosClient należy określić CosmosClientOptions.UseSystemTextJsonSerializerWithOptions z powodu ograniczeń w domyślnym serializatorze. Tę opcję można ustawić na JsonSerializerOptions.Default lub dostosować z innymi opcjami serializatora, aby spełnić określone potrzeby konfiguracyjne.

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

Wprowadzenie

Dodaj do projektu pakiet NuGet łącznika NoSQL Vector Store usługi Azure CosmosDB.

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

Magazyn wektorów można dodać do kontenera iniekcji zależności dostępnego w KernelBuilder kontenerze iniekcji zależności lub IServiceCollection przy użyciu metod rozszerzeń udostępnianych przez jądro semantyczne.

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

Dostępne są również metody rozszerzeń, które nie przyjmują parametrów. Wymagają one osobnego zarejestrowania Microsoft.Azure.Cosmos.Database wystąpienia w kontenerze wstrzykiwania zależności.

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

Wystąpienie usługi Azure CosmosDB NoSQL Vector Store można utworzyć bezpośrednio.

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

Istnieje możliwość utworzenia bezpośredniego odwołania do nazwanej kolekcji.

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

Mapowanie danych

Łącznik magazynu wektorów NoSQL usługi Azure CosmosDB zapewnia domyślny maper podczas mapowania z modelu danych na magazyn.

Ten maper wykonuje bezpośrednią konwersję listy właściwości modelu danych na pola w usłudze Azure CosmosDB NoSQL i używa System.Text.Json.JsonSerializer ich do konwersji na schemat magazynu. Oznacza to, że użycie elementu JsonPropertyNameAttribute jest obsługiwane, jeśli wymagana jest inna nazwa magazynu dla nazwy właściwości modelu danych. Jedynym wyjątkiem jest klucz rekordu mapowanego na pole bazy danych o nazwie id, ponieważ wszystkie rekordy NoSQL usługi CosmosDB muszą używać tej nazwy dla identyfikatorów.

Istnieje również możliwość użycia wystąpienia niestandardowego JsonSerializerOptions z dostosowanymi zasadami nazewnictwa właściwości. Aby to umożliwić, należy przekazać je JsonSerializerOptions do AzureCosmosDBNoSQLVectorStoreRecordCollection konstrukcji.

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

Przy użyciu powyższego niestandardowego, JsonSerializerOptions który używa SnakeCaseUppermetody , poniższy model danych zostanie zamapowany na poniższy kod 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],
}

Używanie klucza partycji

W łączniku usługi Azure Cosmos DB do baz NoSQL właściwość klucza partycji jest domyślnie ustawiona na właściwość klucza — id. Właściwość PartitionKeyPropertyName w klasie AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> umożliwia określenie innej właściwości jako klucza partycji.

Klasa AzureCosmosDBNoSQLVectorStoreRecordCollection obsługuje dwa typy kluczy: string i AzureCosmosDBNoSQLCompositeKey. AzureCosmosDBNoSQLCompositeKey składa się z RecordKey i PartitionKey.

Jeśli właściwość klucza partycji nie jest ustawiona (i jest używana właściwość klucza domyślnego), klucze string mogą być używane na potrzeby operacji z rekordami bazy danych. Jeśli jednak określono właściwość klucza partycji, zaleca się użycie AzureCosmosDBNoSQLCompositeKey w celu podania zarówno wartości klucza, jak i klucza partycji.

Określ nazwę właściwości klucza partycji:

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

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

Pobierz z kluczem partycji:

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

Wkrótce

Więcej informacji wkrótce.

Wkrótce

Więcej informacji wkrótce.