Partager via

Index et vecteurs de requête dans Azure Cosmos DB for NoSQL en Java

  • Article

S’APPLIQUE À : NoSQL

La recherche vectorielle dans Azure Cosmos DB for NoSQL est actuellement une fonctionnalité en préversion. Vous devez vous inscrire à la préversion avant l’utilisation. Cet article couvre les étapes suivantes :

  1. Inscription à la préversion de la recherche vectorielle dans Azure Cosmos DB for NoSQL
  2. Configuration du conteneur Azure Cosmos DB pour la recherche vectorielle
  3. Création de la stratégie d’incorporation de vecteurs
  4. Ajout d’index vectoriels à la stratégie d’indexation du conteneur
  5. Création d’un conteneur avec des index vectoriels et une stratégie d’incorporation de vecteurs
  6. Exécution d’une recherche vectorielle sur les données stockées.
  7. 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

Inscription à la préversion

La recherche vectorielle pour Azure Cosmos DB for NoSQL nécessite une inscription aux fonctionnalités en préversion. Suivez les étapes ci-dessous pour vous inscrire :

  1. Accédez à votre page de ressource Azure Cosmos DB for NoSQL.

  2. Sélectionnez le volet « Fonctionnalités » sous l’élément de menu « Paramètres ».

  3. Sélectionnez « Recherche vectorielle dans Azure Cosmos DB for NoSQL ».

  4. Lisez la description de la fonctionnalité pour confirmer que vous souhaitez vous inscrire à la préversion.

  5. Sélectionnez « Activer » pour vous inscrire avec la préversion.

Remarque

La demande d’inscription est approuvée automatiquement, mais l’opération peut prendre parfois plusieurs minutes.

Les étapes suivantes partent du principe que vous savez configurer un compte NoSQL Cosmos DB et créer une base de données. La fonctionnalité de recherche vectorielle n’est pas prise en charge sur les conteneurs existants. Vous devez donc créer un conteneur, et spécifier la stratégie d’incorporation de vecteurs au niveau du conteneur ainsi que la stratégie d’indexation vectorielle au moment de la création du conteneur.

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.

  1. Créez et stockez des incorporations de vecteurs pour les champs sur lesquels vous souhaitez effectuer une recherche vectorielle.
  2. Spécifiez les chemins d’accès d’incorporation de vecteurs dans la stratégie d’incorporation de vecteurs.
  3. Incluez les index vectoriels souhaités dans la stratégie d’indexation du conteneur.

Pour les sections suivantes de cet article, nous considérons la structure ci-dessous pour les éléments stockés dans 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] 
}

D’abord, créez l’objet CosmosContainerProperties.

CosmosContainerProperties collectionDefinition = new CosmosContainerProperties(UUID.randomUUID().toString(), "Partition_Key_Def");

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 qui sont 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. Cela permet également d’indiquer les informations nécessaires à la stratégie d’indexation vectorielle, si vous choisissez d’en spécifier une. Les informations suivantes sont incluses dans la stratégie vectorielle contenue :

  • « 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 » : métrique utilisée pour calculer la distance/similarité (cosinus par défaut)

Pour notre exemple avec les détails du livre, la stratégie vectorielle peut ressembler à l’exemple JSON :

// Creating vector embedding policy
CosmosVectorEmbeddingPolicy cosmosVectorEmbeddingPolicy = new CosmosVectorEmbeddingPolicy();

CosmosVectorEmbedding embedding1 = new CosmosVectorEmbedding();
embedding1.setPath("/coverImageVector");
embedding1.setDataType(CosmosVectorDataType.FLOAT32);
embedding1.setDimensions(8L);
embedding1.setDistanceFunction(CosmosVectorDistanceFunction.COSINE);

CosmosVectorEmbedding embedding2 = new CosmosVectorEmbedding();
embedding2.setPath("/contentVector");
embedding2.setDataType(CosmosVectorDataType.FLOAT32);
embedding2.setDimensions(10L);
embedding2.setDistanceFunction(CosmosVectorDistanceFunction.DOT_PRODUCT);

cosmosVectorEmbeddingPolicy.setCosmosVectorEmbeddings(Arrays.asList(embedding1, embedding2, embedding3));

collectionDefinition.setVectorEmbeddingPolicy(cosmosVectorEmbeddingPolicy);

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 à ceci :

IndexingPolicy indexingPolicy = new IndexingPolicy();
indexingPolicy.setIndexingMode(IndexingMode.CONSISTENT);
ExcludedPath excludedPath1 = new ExcludedPath("/coverImageVector/*");
ExcludedPath excludedPath2 = new ExcludedPath("/contentVector/*");
indexingPolicy.setExcludedPaths(ImmutableList.of(excludedPath1, excludedPath2));

IncludedPath includedPath1 = new IncludedPath("/*");
indexingPolicy.setIncludedPaths(Collections.singletonList(includedPath1));

// Creating vector indexes
CosmosVectorIndexSpec cosmosVectorIndexSpec1 = new CosmosVectorIndexSpec();
cosmosVectorIndexSpec1.setPath("/coverImageVector");
cosmosVectorIndexSpec1.setType(CosmosVectorIndexType.QUANTIZED_FLAT.toString());

CosmosVectorIndexSpec cosmosVectorIndexSpec2 = new CosmosVectorIndexSpec();
cosmosVectorIndexSpec2.setPath("/contentVector");
cosmosVectorIndexSpec2.setType(CosmosVectorIndexType.DISK_ANN.toString());

indexingPolicy.setVectorIndexes(Arrays.asList(cosmosVectorIndexSpec1, cosmosVectorIndexSpec2, cosmosVectorIndexSpec3));

collectionDefinition.setIndexingPolicy(indexingPolicy);

Enfin, créez le conteneur avec la stratégie d’index de conteneur et la stratégie d’index vectoriel.

database.createContainer(collectionDefinition).block();

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.

Important

Pour le moment, la recherche vectorielle dans Azure Cosmos DB for NoSQL est prise en charge uniquement sur les nouveaux conteneurs. Vous devez définir à la fois la stratégie vectorielle du conteneur et une stratégie d’indexation vectorielle au moment de la création du conteneur, car aucune modification n’est possible par la suite. Les deux stratégies seront modifiables dans une prochaine amélioration de la fonctionnalité en préversion.

Exécuter 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 insérez 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 de recettes de cuisine en examinant la description. Pour cela, vous devez 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 Java :

float[] embedding = new float[10];
for (int i = 0; i < 10; i++) {
    array[i] = i + 1;
}
ArrayList<SqlParameter> paramList = new ArrayList<SqlParameter>();
  paramList.add(new SqlParameter("@embedding", embedding));
  SqlQuerySpec querySpec = new SqlQuerySpec("SELECT c.title, VectorDistance(c.contentVector,@embedding) AS SimilarityScore  FROM c ORDER BY VectorDistance(c.contentVector,@embedding)", paramList);
  CosmosPagedIterable<Family> filteredFamilies = container.queryItems(querySpec, new CosmosQueryRequestOptions(), Family.class);

  if (filteredFamilies.iterator().hasNext()) {
      Family family = filteredFamilies.iterator().next();
      logger.info(String.format("First query result: Family with (/id, partition key) = (%s,%s)",family.getId(),family.getLastName()));
  }

Étapes suivantes