Utilisation du connecteur NoSQL Vector Store Azure CosmosDB (préversion)

Article
01/23/2025

Avertissement

La fonctionnalité de magasin de vecteurs du noyau sémantique est en préversion et des améliorations nécessitant des modifications cassants peuvent toujours se produire dans des circonstances limitées avant la mise en production.

Vue d’ensemble

Le connecteur Azure CosmosDB NoSQL Vector Store peut être utilisé pour accéder aux données et les gérer dans Azure CosmosDB NoSQL. Le connecteur présente les caractéristiques suivantes.

Zone Fonctionnalités	Support
Mappages de collection à	Conteneur NoSQL Azure Cosmos DB
Types de propriétés de clé pris en charge	string AzureCosmosDBNoSQLCompositeKey
Types de propriétés de données pris en charge	string int long double virgule flottante bool DateTimeOffset et énumérables de chacun de ces types
Types de propriétés vectorielles pris en charge	Float ReadOnlyMemory<> Octet ReadOnlyMemory<> ReadOnlyMemory<sbyte> ReadOnlyMemory<Half>
Types d’index pris en charge	Plat QuantizedFlat DiskAnn
Fonctions de distance prises en charge	CosineSimilarity DotProductSimilarity EuclideanDistance
Clauses de filtre prises en charge	AnyTagEqualTo EqualTo
Prend en charge plusieurs vecteurs dans un enregistrement	Oui
Est-il pris en charge ?	Oui
IsFullTextSearchable pris en charge ?	Oui
StoragePropertyName pris en charge ?	Non, utilisez et `JsonSerializerOptions` à `JsonPropertyNameAttribute` la place. Pour plus d’informations, voir ici.

Limitations

Lors de l’initialisation CosmosClient manuellement, il est nécessaire de spécifier CosmosClientOptions.UseSystemTextJsonSerializerWithOptions en raison de limitations dans le sérialiseur par défaut. Cette option peut être définie sur JsonSerializerOptions.Default ou personnalisée avec d’autres options de sérialiseur pour répondre à des besoins de configuration spécifiques.

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

Mise en route

Ajoutez le package NuGet du connecteur NoSQL Vector Store à votre projet.

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

Vous pouvez ajouter le magasin de vecteurs au conteneur d’injection de dépendances disponible sur le KernelBuilder conteneur ou au conteneur d’injection de dépendances à l’aide IServiceCollection de méthodes d’extension fournies par le noyau sémantique.

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

Les méthodes d’extension qui ne prennent aucun paramètre sont également fournies. Celles-ci nécessitent une instance d’être Microsoft.Azure.Cosmos.Database inscrite séparément auprès du conteneur d’injection de dépendances.

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

Vous pouvez construire directement une instance Azure CosmosDB NoSQL Vector Store.

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

Il est possible de construire une référence directe à une collection nommée.

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

Mappage de données

Le connecteur NoSQL Vector Store Azure CosmosDB fournit un mappeur par défaut lors du mappage du modèle de données au stockage.

Ce mappeur effectue une conversion directe de la liste des propriétés sur le modèle de données vers les champs dans Azure CosmosDB NoSQL et utilise System.Text.Json.JsonSerializer pour convertir le schéma de stockage. Cela signifie que l’utilisation de l’objet JsonPropertyNameAttribute est prise en charge si un nom de stockage différent du nom de propriété du modèle de données est requis. La seule exception est la clé de l’enregistrement mappé à un champ de base de données nommé id, car tous les enregistrements NoSQL CosmosDB doivent utiliser ce nom pour les ID.

Il est également possible d’utiliser une instance personnalisée JsonSerializerOptions avec une stratégie d’affectation de noms de propriété personnalisée. Pour l’activer, le JsonSerializerOptions doit être transmis à la AzureCosmosDBNoSQLVectorStoreRecordCollection construction.

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

À l’aide de la personnalisée JsonSerializerOptions ci-dessus, SnakeCaseUpperle modèle de données suivant est mappé au json ci-dessous.

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

Utilisation de la clé de partition

Dans le connecteur Azure Cosmos DB pour NoSQL, la propriété de la clé de partition est par défaut la propriété clé - id. La propriété PartitionKeyPropertyName dans AzureCosmosDBNoSQLVectorStoreRecordCollectionOptions<TRecord> classe permet de spécifier une propriété différente en tant que clé de partition.

La classe AzureCosmosDBNoSQLVectorStoreRecordCollection prend en charge deux types de clés : string et AzureCosmosDBNoSQLCompositeKey. Le AzureCosmosDBNoSQLCompositeKey se compose de RecordKey et de PartitionKey.

Si la propriété de clé de partition n’est pas définie (et que la propriété de clé par défaut est utilisée), string clés peuvent être utilisées pour les opérations avec des enregistrements de base de données. Toutefois, si une propriété de clé de partition est spécifiée, il est recommandé d’utiliser AzureCosmosDBNoSQLCompositeKey pour fournir à la fois les valeurs de la clé et de la clé de partition.

Spécifiez le nom de la propriété de clé de partition :

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

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

Obtenir avec la clé de partition :

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

Bientôt disponible

Plus d’informations prochainement.

Bientôt disponible

Plus d’informations prochainement.

Partager via

Utilisation du connecteur NoSQL Vector Store Azure CosmosDB (préversion)

Vue d’ensemble

Limitations

Mise en route

Mappage de données

Utilisation de la clé de partition

Bientôt disponible

Bientôt disponible

Ressources supplémentaires