Créer un index ScaNN

Cette page explique comment utiliser les embeddings stockés pour générer des index et interroger des embeddings à l'aide de l'index ScaNN avec AlloyDB pour PostgreSQL. Pour en savoir plus sur le stockage des embeddings, consultez Stocker des embeddings vectoriels.

AlloyDB alloydb_scann est une extension PostgreSQL développée par Google qui implémente un index des voisins les plus proches très efficace basé sur l'algorithme ScaNN.

L'index ScaNN est un index de quantification basé sur une arborescence pour la recherche approximative des plus proches voisins. Il permet de réduire le temps de création d'index et l'empreinte mémoire par rapport à HNSW. De plus, il peut offrir un nombre de requêtes par seconde plus élevé que HNSW en fonction de la charge de travail.

Avant de commencer

Avant de pouvoir commencer à créer des index, vous devez remplir les conditions préalables suivantes.

  • Les vecteurs d'embeddings sont ajoutés à une table de votre base de données AlloyDB.

  • L'extension vector basée sur pgvector, étendue par Google pour AlloyDB, et l'extension alloydb_scann sont installées :

    CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;

  • Si vous souhaitez créer des index ScaNN réglés automatiquement, assurez-vous que l'indicateur scann.enable_preview_features est activé. Si vous ne souhaitez pas activer les fonctionnalités en avant-première ou pour les instances de production, vous pouvez créer un index ScaNN avec des paramètres spécifiques.

Créer un index ScaNN réglé automatiquement

La fonctionnalité d'indexation automatique vous permet de simplifier la création d'index. Vous pouvez ainsi créer automatiquement des index optimisés pour les performances de recherche ou des index équilibrés en termes de temps de création et de performances de recherche.

Lorsque vous utilisez le mode AUTO, il vous suffit de spécifier le nom de la table et de la colonne d'embedding, ainsi que la fonction de distance que vous souhaitez utiliser. Vous pouvez optimiser l'index pour les performances de recherche ou trouver un équilibre entre les temps de création de l'index et les performances de recherche.

Vous pouvez également utiliser le mode MANUAL pour créer des index avec un contrôle précis sur d'autres paramètres d'optimisation des index.

Créer un index ScaNN en mode AUTO

Voici quelques points à noter avant de créer des index en mode AUTO :

  • AlloyDB ne peut pas créer d'index ScaNN pour les tables dont les données sont insuffisantes.
  • Vous ne pouvez pas définir de paramètres de création d'index, tels que num_leaves, lorsque vous créez des index en mode AUTO.
  • La maintenance automatique est activée par défaut pour tous les index créés en mode AUTO.

Pour créer un index en mode AUTO, activez le flag de fonctionnalité scann.enable_zero_knob_index_creation. Cela active la maintenance automatique. Après avoir activé le flag, exécutez la commande suivante :

  CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (mode='AUTO');

Remplacez les éléments suivants :

  • INDEX_NAME : nom de l'index que vous souhaitez créer, par exemple my-scann-index. Les noms d'index sont partagés dans toute votre base de données. Vérifiez que chaque nom d'index est unique pour chaque table de votre base de données.

  • TABLE : table à laquelle ajouter l'index.

  • EMBEDDING_COLUMN : colonne qui stocke les données vector.

  • DISTANCE_FUNCTION : fonction de distance à utiliser avec cet index. Choisissez l'une des options suivantes :

    • Distance L2 : l2

    • Produit scalaire : dot_product

    • Distance de cosinus : cosine

  • OPTIMIZATION (facultatif) : par défaut, un index optimisé pour la recherche est créé. Définissez l'une des options suivantes :

    • SEARCH_OPTIMIZED (par défaut) : pour optimiser à la fois le rappel et la latence de la recherche vectorielle, au détriment d'un temps de création d'index plus long.
    • BALANCED : pour créer un index qui équilibre le temps de création de l'index et les performances de recherche.

Créer un index ScaNN en mode MANUEL

Si vous avez activé l'indicateur scann.enable_preview_features et que vous souhaitez contrôler précisément les paramètres d'optimisation, vous pouvez créer l'index en mode MANUAL.

Pour créer un index ScaNN en mode MANUAL, exécutez la commande suivante :

  CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (mode='MANUAL', num_leaves=NUM_LEAVES_VALUE, quantizer =QUANTIZER, max_num_levels=MAX_NUM_LEVELS);

Remplacez les éléments suivants :

  • INDEX_NAME : nom de l'index que vous souhaitez créer, par exemple my-scann-index. Les noms d'index sont partagés dans toute votre base de données. Vérifiez que chaque nom d'index est unique pour chaque table de votre base de données.

  • TABLE : table à laquelle ajouter l'index.

  • EMBEDDING_COLUMN : colonne qui stocke les données vector.

  • DISTANCE_FUNCTION : fonction de distance à utiliser avec cet index. Choisissez l'une des options suivantes :

    • Distance L2 : l2

    • Produit scalaire : dot_product

    • Distance de cosinus : cosine

  • NUM_LEAVES_VALUE : nombre de partitions à appliquer à cet index. Définissez une valeur comprise entre 1 et 10 millions. Pour savoir comment choisir cette valeur, consultez Régler un index ScaNN.

  • QUANTIZER : type de quantificateur à utiliser. Les options disponibles sont les suivantes :

    • SQ8 : offre un équilibre entre les performances des requêtes et une perte de rappel minimale, généralement inférieure à 1 % ou 2 %. Il s'agit de la valeur par défaut.
    • AH : à envisager pour potentiellement améliorer les performances des requêtes lorsque le moteur en colonnes est activé et que les données de votre index et de votre table sont renseignées dans le moteur en colonnes, en fonction de sa taille configurée. Notez que AH est jusqu'à quatre fois plus compressé que SQ8. Pour en savoir plus, consultez Bonnes pratiques pour ajuster ScaNN.
    • FLAT : offre le rappel le plus élevé (99 % ou plus) au détriment des performances de recherche.

  • MAX_NUM_LEVELS : nombre maximal de niveaux de l'arborescence de clustering en K-moyennes. Définissez la valeur sur 1(par défaut) pour la quantification arborescente à deux niveaux et sur 2 pour la quantification arborescente à trois niveaux.

Vous pouvez ajouter d'autres paramètres de création d'index ou d'exécution de requêtes pour ajuster votre index. Pour en savoir plus, consultez Régler un index ScaNN.

Créer un index ScaNN avec des paramètres spécifiques

Si votre application présente des exigences spécifiques concernant le rappel et les temps de création d'index, vous pouvez créer l'index manuellement. Vous pouvez créer un index arborescent à deux ou trois niveaux en fonction de votre charge de travail. Pour en savoir plus sur le réglage des paramètres, consultez Régler un index ScaNN.

Index arborescent à deux niveaux

Pour appliquer un index arborescent à deux niveaux à l'aide de l'algorithme ScaNN à une colonne contenant des embeddings vectoriels stockés, exécutez la requête LDD suivante :

CREATE INDEX INDEX_NAME ON TABLE
USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
WITH (num_leaves=NUM_LEAVES_VALUE, quantizer =QUANTIZER);

Remplacez les éléments suivants :

  • INDEX_NAME : nom de l'index que vous souhaitez créer, par exemple my-scann-index. Les noms d'index sont partagés dans toute votre base de données. Assurez-vous que chaque nom d'index est unique pour chaque table de votre base de données.

  • TABLE : table à laquelle ajouter l'index.

  • EMBEDDING_COLUMN : colonne qui stocke les données vector.

  • DISTANCE_FUNCTION : fonction de distance à utiliser avec cet index. Choisissez l'une des options suivantes :

    • Distance L2 : l2

    • Produit scalaire : dot_product

    • Distance de cosinus : cosine

  • NUM_LEAVES_VALUE : nombre de partitions à appliquer à cet index. Définissez une valeur comprise entre 1 et 10 millions. Pour savoir comment déterminer cette valeur, consultez Régler un index ScaNN.

  • QUANTIZER : type de quantificateur à utiliser. Les options disponibles sont les suivantes :

    • SQ8 : offre un équilibre entre les performances des requêtes et une perte de rappel minimale, généralement inférieure à 1 % ou 2 %. Il s'agit de la valeur par défaut.
    • AH : à envisager pour potentiellement améliorer les performances des requêtes lorsque le moteur en colonnes est activé et que les données de votre index et de votre table sont renseignées dans le moteur en colonnes, en fonction de sa taille configurée. Notez que AH est jusqu'à quatre fois plus compressé que SQ8. Pour en savoir plus, consultez Bonnes pratiques pour ajuster ScaNN.
    • FLAT : offre le rappel le plus élevé (99 % ou plus) au détriment des performances de recherche.

Index arborescent à trois niveaux

Pour créer un index arborescent à trois niveaux à l'aide de l'algorithme ScaNN dans une colonne contenant des embeddings vectoriels stockés, exécutez la requête LDD suivante :

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = 2);

Une fois l'index créé, vous pouvez exécuter des requêtes de recherche des voisins les plus proches qui l'utilisent en suivant les instructions de la section Envoyer une requête de type plus proches voisins avec un texte donné.

Les paramètres d'index doivent être définis de manière à trouver le juste équilibre entre les requêtes par seconde et le rappel. Pour en savoir plus sur le réglage de l'index ScaNN, consultez Régler un index ScaNN.

Pour créer cet index sur une colonne d'embeddings qui utilise le type de données real[] au lieu de vector, convertissez le type de données de la colonne en vector :

CREATE INDEX INDEX_NAME ON TABLE
USING scann (CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)) DISTANCE_FUNCTION)
WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);

Remplacez DIMENSIONS par la largeur dimensionnelle de la colonne d'embeddings. Pour savoir comment trouver les dimensions, examinez la fonction vector_dims dans Fonctions vectorielles.

Pour obtenir une expérience de recherche cohérente, activez la maintenance automatique lorsque vous créez un index ScaNN. Pour en savoir plus, consultez Gérer les index vectoriels. Cette fonctionnalité est disponible en version preview.

Pour afficher la progression de l'indexation, utilisez la vue pg_stat_progress_create_index :

SELECT * FROM pg_stat_progress_create_index;

La colonne phase indique l'état actuel de la création de votre index. Une fois la phase de création de l'index terminée, la ligne correspondante n'est plus visible.

Pour régler votre index afin d'obtenir un équilibre entre le rappel et les RPS moyens, consultez Régler un index ScaNN.

Forcer la création d'index sur des tables vides ou de petite taille

AlloyDB dispose de validations pour empêcher la création d'un index ScaNN sur une table vide ou comportant très peu de lignes, car cela pourrait entraîner des performances sous-optimales. Toutefois, dans certains scénarios de développement ou de test, vous devrez peut-être créer un index sur une table vide ou de petite taille. Dans ce cas, vous pouvez forcer la création d'index.

Pour forcer la génération d'index, procédez comme suit :

  1. Définissez le paramètre scann.allow_blocked_operations creation au niveau de la session sur true dans la base de données :

    SET scann.allow_blocked_operations = true;

  2. Attribuez le droit SUPERUSER à l'utilisateur qui exécute ces requêtes sur la base de données :

    CREATE USER USER_NAME WITH SUPERUSER PASSWORD PASSWORD;

    Remplacez les éléments suivants :

    • USER_NAME : nom de l'utilisateur auquel vous souhaitez accorder le privilège.
    • PASSWORD : mot de passe de l'utilisateur.

Créer des index en parallèle

Pour créer votre index plus rapidement, AlloyDB peut générer automatiquement plusieurs nœuds de calcul parallèles, en fonction de votre ensemble de données et du type d'index que vous choisissez.

La création d'index en parallèle est souvent déclenchée si vous créez un index ScaNN à trois niveaux ou si votre ensemble de données dépasse 100 millions de lignes.

Bien qu'AlloyDB optimise automatiquement le nombre de nœuds de calcul en parallèle, vous pouvez les ajuster à l'aide des paramètres de planification des requêtes PostgreSQL max_parallel_maintenance_workers, max_parallel_workers et min_parallel_table_scan_size.

Exécuter une requête

Une fois que vous avez stocké et indexé les embeddings dans votre base de données, vous pouvez commencer à interroger vos données. Vous ne pouvez pas exécuter de requêtes de recherche groupées à l'aide de l'extension alloydb_scann.

Pour trouver les voisins sémantiques les plus proches d'un vecteur d'embedding, vous pouvez exécuter l'exemple de requête suivant, dans lequel vous définissez la même fonction de distance que celle utilisée lors de la création de l'index.

  SELECT * FROM TABLE
  ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY 'EMBEDDING'
  LIMIT ROW_COUNT

Remplacez les éléments suivants :

  • TABLE : table contenant l'embedding auquel comparer le texte.

  • INDEX_NAME : nom de l'index que vous souhaitez utiliser (par exemple, my-scann-index).

  • EMBEDDING_COLUMN : colonne contenant les embeddings stockés.

  • DISTANCE_FUNCTION_QUERY : fonction de distance à utiliser avec cette requête. Choisissez l'une des options suivantes, selon la fonction de distance utilisée lors de la création de l'index :

    • Distance L2 : <->

    • Produit interne : <#>

    • Distance de cosinus : <=>

  • EMBEDDING : vecteur d'embedding pour lequel vous souhaitez trouver les plus proches voisins sémantiques qui sont stockés.

  • ROW_COUNT : nombre de lignes à afficher.

    Spécifiez 1 si vous souhaitez n'obtenir que la meilleure correspondance.

Vous pouvez également utiliser la fonction embedding() pour traduire le texte en un vecteur. Comme embedding() renvoie un tableau real, vous devez convertir explicitement l'appel embedding() en type de données vector avant de l'appliquer à l'un des opérateurs de k-plus proches voisins (par exemple, <-> pour la distance L2). Ces opérateurs peuvent ensuite utiliser l'index ScaNN pour rechercher les lignes de la base de données présentant les embeddings les plus similaires sur le plan de la sémantique.

Étapes suivantes