Usando o conector do Repositório Vetorial NoSQL do Azure CosmosDB (Visualização)

Aviso

A funcionalidade Semantic Kernel Vetor Store está em pré-visualização, e melhorias que exigem alterações de quebra ainda podem ocorrer em circunstâncias limitadas antes do lançamento.

Descrição geral

O conector do Azure CosmosDB NoSQL Vetor Store pode ser usado para acessar e gerenciar dados no Azure CosmosDB NoSQL. O conector tem as seguintes características.

Área de funcionalidades	Suporte
Mapas da coleção para	Contêiner NoSQL do Azure Cosmos DB
Tipos de propriedade de chave suportados	string AzureCosmosDBNoSQLCompositeKey
Tipos de propriedade de dados suportados	string número inteiro long duplo flutuante booleano DateTimeOffset e enumeráveis de cada um destes tipos
Tipos de propriedade vetorial suportados	Float ReadOnlyMemory<> Byte ReadOnlyMemory<> Sbyte ReadOnlyMemory<> ReadOnlyMetade da memória<>
Tipos de índice suportados	Apartamento QuantizedFlat DiskAnn
Funções de distância suportadas	CossenoSimilaridade DotProductSimilarity Distância Euclidiana
Cláusulas de filtro suportadas	AnyTagEqualTo EqualTo
Suporta vários vetores em um registro	Sim
IsFilterable suportado?	Sim
IsFullTextSearchable suportado?	Sim
StoragePropertyName suportado?	Não, use JsonSerializerOptions e JsonPropertyNameAttribute em vez disso. Veja aqui mais informações.

Limitações

Ao inicializar CosmosClient manualmente, é necessário especificar CosmosClientOptions.UseSystemTextJsonSerializerWithOptions devido a limitações no serializador padrão. Essa opção pode ser definida como JsonSerializerOptions.Default ou personalizada com outras opções do serializador para atender às necessidades específicas de configuração.

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

Introdução

Adicione o pacote NuGet do conector do Azure CosmosDB NoSQL Vetor Store ao seu projeto.

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

Você pode adicionar o armazenamento vetorial ao contêiner de injeção de dependência disponível no KernelBuilder ou ao contêiner de IServiceCollection injeção de dependência usando métodos de extensão fornecidos pelo Semantic Kernel.

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

Métodos de extensão que não usam parâmetros também são fornecidos. Eles exigem que uma instância de seja registrada separadamente com o contêiner de injeção de Microsoft.Azure.Cosmos.Database dependência.

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

Você pode construir uma instância do Azure CosmosDB NoSQL Vetor Store diretamente.

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

É possível construir uma referência direta a uma coleção nomeada.

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

Mapeamento de dados

O conector do Azure CosmosDB NoSQL Vetor Store fornece um mapeador padrão ao mapear do modelo de dados para o armazenamento.

Esse mapeador faz uma conversão direta da lista de propriedades no modelo de dados para os campos no Azure CosmosDB NoSQL e usa System.Text.Json.JsonSerializer para converter para o esquema de armazenamento. Isso significa que o JsonPropertyNameAttribute uso do é suportado se um nome de armazenamento diferente para o nome da propriedade do modelo de dados for necessário. A única exceção é a chave do registro que é mapeada para um campo de banco de dados chamado id, já que todos os registros NoSQL do CosmosDB devem usar esse nome para ids.

Também é possível usar uma instância personalizada JsonSerializerOptions com uma política de nomenclatura de propriedade personalizada. Para permitir isso, o JsonSerializerOptions deve ser passado para a AzureCosmosDBNoSQLVectorStoreRecordCollection construção on.

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

Usando o costume JsonSerializerOptions acima que está usando SnakeCaseUpper, o modelo de dados a seguir será mapeado para o json abaixo.

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

Usando a chave de partição

No conector do Azure Cosmos DB para NoSQL, a propriedade da chave de partição assume como padrão a propriedade da chave - id. A propriedade PartitionKeyPropertyName em AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> classe permite especificar uma propriedade diferente como a chave de partição.

A classe AzureCosmosDBNoSQLVectorStoreRecordCollection suporta dois tipos de chave: string e AzureCosmosDBNoSQLCompositeKey. O AzureCosmosDBNoSQLCompositeKey consiste em RecordKey e PartitionKey.

Se a propriedade da chave de partição não estiver definida (e a propriedade de chave padrão for usada), string chaves poderão ser usadas para operações com registros de banco de dados. No entanto, se uma propriedade de chave de partição for especificada, é recomendável usar AzureCosmosDBNoSQLCompositeKey para fornecer tanto a chave quanto os valores da chave de partição.

Especifique o nome da propriedade da chave de partição:

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

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

Obter usando a chave de partição:

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

Brevemente

Mais informações em breve.

Brevemente

Mais informações em breve.