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

Avertissement

La fonctionnalité de magasin de vecteurs du noyau sémantique est en préversion, et des améliorations nécessitant des modifications conséquentes peuvent toujours se produire dans des circonstances limitées avant le déploiement.

Vue d’ensemble

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

Zone des fonctionnalités	Soutien
La collection correspond à	Azure Cosmos DB MongoDB (vCore) Collection + Index
Types de propriétés de clé pris en charge	chaîne
Types de propriétés de données pris en charge	chaîne int long double flotter décimal bool Date/Heure et éléments énumérables de chacun de ces types
Types de propriétés vectorielles pris en charge	ReadOnlyMemory ReadOnlyMemory<double>
Types d’index pris en charge	Hnsw IvfFlat
Fonctions de distance prises en charge	CosineDistance DotProductSimilarity EuclideanDistance
Clauses de filtre prises en charge	EqualTo
Prend en charge plusieurs vecteurs dans un enregistrement	Oui
La fonctionnalité IsFilterable est-elle prise en charge ?	Oui
IsFullTextSearchable pris en charge ?	Non
Est-ce que 'StoragePropertyName' est pris en charge ?	Non, utilisez BsonElementAttribute à la place. Pour plus d’informations, voir ici.
La recherche hybride est-elle prise en charge ?	Non

Zone des fonctionnalités	Support
La collection correspond à	Azure Cosmos DB MongoDB (vCore) Collection + Index
Types de biens clés pris en charge	chaîne
Types de propriétés de données pris en charge	chaîne int long double flotter decimal bool Date/Heure et itérables de chacun de ces types
Types de propriétés vectorielles pris en charge	liste[flottant] liste[int] ndarray
Types d’index pris en charge	Hnsw IvfFlat
Fonctions de distance prises en charge	CosineDistance DotProductSimilarity EuclideanDistance
Clauses de filtre prises en charge	EqualTo AnyTagsEqualTo
Prend en charge plusieurs vecteurs dans un enregistrement	Oui
La fonctionnalité IsFilterable est-elle prise en charge ?	Oui
Est-ce que IsFullTextSearchable est pris en charge ?	Non

Plus d’informations prochainement.

Limitations

Ce connecteur est compatible avec Azure Cosmos DB MongoDB (vCore) et n’est pas conçu pour être compatible avec Azure Cosmos DB MongoDB (RU).

Mise en route

Ajoutez le package NuGet du connecteur Azure CosmosDB MongoDB Vector Store à votre projet.

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

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

using Microsoft.SemanticKernel;

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

using Microsoft.SemanticKernel;

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

Les méthodes d’extension qui ne prennent aucun paramètre sont également fournies. Celles-ci nécessitent qu'une instance de MongoDB.Driver.IMongoDatabase soit inscrite séparément dans le conteneur d’injection de dépendances.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using MongoDB.Driver;

// Using Kernel Builder.
var kernelBuilder = Kernel.CreateBuilder();
kernelBuilder.Services.AddSingleton<IMongoDatabase>(
    sp =>
    {
        var mongoClient = new MongoClient(connectionString);
        return mongoClient.GetDatabase(databaseName);
    });
kernelBuilder.AddAzureCosmosDBMongoDBVectorStore();

using Microsoft.Extensions.DependencyInjection;
using Microsoft.SemanticKernel;
using MongoDB.Driver;

// Using IServiceCollection with ASP.NET Core.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IMongoDatabase>(
    sp =>
    {
        var mongoClient = new MongoClient(connectionString);
        return mongoClient.GetDatabase(databaseName);
    });
builder.Services.AddAzureCosmosDBMongoDBVectorStore();

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

using Microsoft.SemanticKernel.Connectors.AzureCosmosDBMongoDB;
using MongoDB.Driver;

var mongoClient = new MongoClient(connectionString);
var database = mongoClient.GetDatabase(databaseName);
var vectorStore = new AzureCosmosDBMongoDBVectorStore(database);

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

using Microsoft.SemanticKernel.Connectors.AzureCosmosDBMongoDB;
using MongoDB.Driver;

var mongoClient = new MongoClient(connectionString);
var database = mongoClient.GetDatabase(databaseName);
var collection = new AzureCosmosDBMongoDBVectorStoreRecordCollection<Hotel>(
    database,
    "skhotels");

Mappage de données

Le connecteur Azure CosmosDB MongoDB Vector Store fournit un mappeur par défaut lors du mappage des données 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 MongoDB et utilise MongoDB.Bson.Serialization pour convertir le schéma de stockage. Cela signifie que l’utilisation de l’objet MongoDB.Bson.Serialization.Attributes.BsonElement 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 MongoDB CosmosDB doivent utiliser ce nom pour les ID.

Remplacement du nom de propriété

Pour les propriétés de données et les propriétés vectorielles, vous pouvez fournir des noms de champs de remplacement à utiliser dans le stockage différent des noms de propriétés sur le modèle de données. Cela n’est pas pris en charge pour les clés, car une clé a un nom fixe dans MongoDB.

Le remplacement du nom de propriété est effectué en définissant l’attribut BsonElement sur les propriétés du modèle de données.

Voici un exemple de modèle de données avec BsonElement ensemble.

using Microsoft.Extensions.VectorData;

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

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

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

    [BsonElement("hotel_description_embedding")]
    [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }
}

Mise en route

Ajoutez les dépendances du magasin de vecteurs Azure CosmosDB MongoDB à votre environnement. Étant donné que le connecteur MongoDB Azure CosmosDB est basé sur le connecteur MongoDB Atlas et utilise le même client que celui-ci, vous devez installer avec ces extras :

pip install semantic-kernel[azure, mongo]

Vous pouvez ensuite créer le magasin vectoriel.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBStore

# If the right environment settings are set, namely AZURE_COSMOS_DB_MONGODB_CONNECTION_STRING and optionally AZURE_COSMOS_DB_MONGODB_DATABASE_NAME, this is enough to create the Store:
store = AzureCosmosDBforMongoDBStore()

Vous pouvez également passer votre propre client MongoDB si vous souhaitez avoir plus de contrôle sur la construction du client.

from pymongo import AsyncMongoClient
from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBStore

client = AsyncMongoClient(...)
store = AzureCosmosDBforMongoDBStore(mongo_client=client)

Lorsqu'un client est transmis, le noyau sémantique ne ferme pas la connexion pour vous. Vous devez donc vous assurer de la fermer, par exemple avec une instruction async with.

Vous pouvez également créer une collection directement, sans le magasin.

from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBCollection

# `hotel` is a class created with the @vectorstoremodel decorator
collection = AzureCosmosDBforMongoDBCollection(
    collection_name="my_collection",
    data_model_type=hotel
)

Sérialisation

Étant donné que le connecteur Azure CosmosDB pour MongoDB a besoin d’une dictée simple avec les champs correspondant à l’index en tant qu’entrée, la sérialisation est assez facile, elle utilise uniquement une clé prédéterminée _id, donc nous remplaçons la clé du modèle de données par celle-ci si ce n’est pas déjà _id.

Pour plus d’informations sur ce concept, consultez la documentation de sérialisation.

Bientôt disponible

Plus d’informations prochainement.