Indexer et interroger des vecteurs dans Azure Cosmos DB for NoSQL dans .NET
Avant d’utiliser l’indexation et la recherche vectorielles, vous devez d’abord activer la fonctionnalité. Cet article couvre les étapes suivantes :
- Activation de la recherche vectorielle dans la fonctionnalité Azure Cosmos DB for NoSQL.
- Configuration du conteneur Azure Cosmos DB pour la recherche vectorielle
- Création de la stratégie d’incorporation de vecteurs
- Ajout d’index vectoriels à la stratégie d’indexation du conteneur
- Création d’un conteneur avec des index vectoriels et une stratégie d’incorporation de vecteurs
- Exécution d’une recherche vectorielle sur les données stockées
Ce guide décrit le processus de création de données vectorielles, d’indexation des données, et d’interrogation des données d’un conteneur.
Prérequis
- Un compte Azure Cosmos DB for NoSQL existant.
- Si vous n’avez pas d’abonnement Azure, essayez gratuitement Azure Cosmos DB for NoSQL.
- Si vous disposez d’un abonnement Azure, créez un compte Azure Cosmos DB for SQL.
- Dernière version du Kit de développement logiciel (SDK) .NET Azure Cosmos DB (Mise en production : 3.45.0 ou ultérieure, Préversion : 3.46.0-preview.0 ou ultérieure).
Activer la fonctionnalité
La recherche vectorielle pour Azure Cosmos DB for NoSQL nécessite l’activation de la fonctionnalité en effectuant les étapes suivantes :
- Accédez à votre page de ressource Azure Cosmos DB for NoSQL.
- Sélectionnez le volet « Fonctionnalités » sous l’élément de menu « Paramètres ».
- Sélectionnez « Recherche vectorielle dans Azure Cosmos DB for NoSQL ».
- Lisez la description de la fonctionnalité pour confirmer que vous souhaitez l’activer.
- Sélectionnez « Activer » pour activer la recherche vectorielle dans Azure Cosmos DB for NoSQL.
Conseil
Vous pouvez également utiliser Azure CLI pour mettre à jour les fonctionnalités de votre compte pour prendre en charge la recherche vectorielle NoSQL.
az cosmosdb update \
--resource-group <resource-group-name> \
--name <account-name> \
--capabilities EnableNoSQLVectorSearch
Remarque
La demande d’inscription est approuvée automatiquement, mais sa prise d’effet peut parfois prendre 15 minutes.
Présentation des étapes impliquées dans la recherche vectorielle
Prenons un exemple de création d’une base de données pour une librairie basée sur Internet où vous stockez le titre, l’auteur, l’ISBN et la description de chaque livre. Nous définissons également deux propriétés pour contenir des incorporations vectorielles. La première est la propriété « contentVector », qui contient les incorporations de texte générées à partir du contenu texte du livre (par exemple, en concaténant les propriétés « titre », « auteur », « isbn » et « description » avant de créer l’incorporation). Le second est la propriété « coverImageVector », qui est générée à partir d’images de la couverture du livre.
- Créez et stockez des incorporations de vecteurs pour les champs sur lesquels vous souhaitez effectuer une recherche vectorielle.
- Spécifiez les chemins d’accès d’incorporation de vecteurs dans la stratégie d’incorporation de vecteurs.
- Incluez les index vectoriels souhaités dans la stratégie d’indexation du conteneur.
Dans les sections suivantes de cet article, nous prenons en compte la structure ci-dessous pour les éléments stockés au sein de notre conteneur :
{
"title": "book-title",
"author": "book-author",
"isbn": "book-isbn",
"description": "book-description",
"contentVector": [2, -1, 4, 3, 5, -2, 5, -7, 3, 1],
"coverImageVector": [0.33, -0.52, 0.45, -0.67, 0.89, -0.34, 0.86, -0.78]
}
Création d’une stratégie d’incorporation de vecteurs pour votre conteneur
Vous devez ensuite définir une stratégie vectorielle de conteneur. Cette stratégie fournit des informations utilisées pour indiquer au moteur de requête Azure Cosmos DB comment gérer les propriétés vectorielles dans les fonctions système VectorDistance. Cette stratégie donne également à la stratégie d’indexation de vecteurs les informations nécessaires, si vous choisissez d’en spécifier une. Les informations suivantes sont incluses dans la stratégie de vecteur contenu :
- « path » : chemin d’accès de propriété qui contient les vecteurs
- « datatype » : type des éléments du vecteur (Float32 par défaut)
- « dimensions » : longueur de chaque vecteur du chemin d’accès (1536 par défaut)
- « distanceFunction » : la métrique utilisée pour calculer la distance par rapport à la similarité (cosinus par défaut)
Pour notre exemple avec des détails de livre, la stratégie vectorielle peut ressembler à l’exemple JSON ci-dessous :
Database db = await client.CreateDatabaseIfNotExistsAsync("vector-benchmarking");
List<Embedding> embeddings = new List<Embedding>()
{
new Embedding()
{
Path = "/coverImageVector",
DataType = VectorDataType.Float32,
DistanceFunction = DistanceFunction.Cosine,
Dimensions = 8,
},
new Embedding()
{
Path = "/contentVector",
DataType = VectorDataType.Float32,
DistanceFunction = DistanceFunction.Cosine,
Dimensions = 10,
}
};
Création d’un index vectoriel dans la stratégie d’indexation
Une fois les chemins d’incorporation de vecteurs décidés, les index vectoriels doivent être ajoutés à la stratégie d’indexation. Actuellement, la fonctionnalité de recherche vectorielle pour Azure Cosmos DB for NoSQL est prise en charge uniquement sur les nouveaux conteneurs. Vous devez donc appliquer la stratégie vectorielle pendant la création du conteneur et elle ne peut pas être modifiée ultérieurement. Pour cet exemple, la stratégie d’indexation ressemblerait à cela :
Collection<Embedding> collection = new Collection<Embedding>(embeddings);
ContainerProperties properties = new ContainerProperties(id: "vector-container", partitionKeyPath: "/id")
{
VectorEmbeddingPolicy = new(collection),
IndexingPolicy = new IndexingPolicy()
{
VectorIndexes = new()
{
new VectorIndexPath()
{
Path = "/vector",
Type = VectorIndexType.QuantizedFlat,
}
}
},
};
properties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
properties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/vector/*" });
Important
Chemin vectoriel ajouté à la section « excludedPaths » de la stratégie d’indexation pour garantir un niveau de performance optimisé pour l’insertion. Ne pas ajouter le chemin vectoriel à « excludedPaths » entraîne une charge RU et une latence plus élevées pour les insertions vectorielles.
Exécution d’une requête de recherche de similarité vectorielle
Une fois que vous avez créé un conteneur avec la stratégie vectorielle souhaitée, et que vous avez inséré des données vectorielles dans le conteneur, vous pouvez effectuer une recherche vectorielle à l’aide de la fonction système Distance vectorielle dans une requête. Supposons que vous souhaitiez rechercher des livres sur les recettes de cuisine en consultant la description, vous devez tout d’abord obtenir les incorporations pour votre texte de requête. Dans ce cas, vous pouvez être amené à générer des incorporations pour le texte de requête « recette de cuisine ». Une fois que vous disposez de l’incorporation pour votre requête de recherche, vous pouvez l’utiliser dans la fonction VectorDistance de la requête de recherche vectorielle, et obtenir tous les éléments similaires à votre requête, comme indiqué ici :
SELECT TOP 10 c.title, VectorDistance(c.contentVector, [1,2,3,4,5,6,7,8,9,10]) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.contentVector, [1,2,3,4,5,6,7,8,9,10])
Cette requête récupère les titres de livres ainsi que les scores de similarité par rapport à votre requête. Voici un exemple en .NET :
float[] embedding = {1f,2f,3f,4f,5f,6f,7f,8f,9f,10f};
var queryDef = new QueryDefinition(
query: $"SELECT c.title, VectorDistance(c.contentVector,@embedding) AS SimilarityScore FROM c ORDER BY VectorDistance(c.contentVector,@embedding)"
).WithParameter("@embedding", embedding);
using FeedIterator<Object> feed = container.GetItemQueryIterator<Object>(
queryDefinition: queryDef
);
while (feed.HasMoreResults)
{
FeedResponse<Object> response = await feed.ReadNextAsync();
foreach ( Object item in response)
{
Console.WriteLine($"Found item:\t{item}");
}
}