Utiliser des embeddings

Cette page explique comment interagir avec Cloud SQL pour créer des applications qui utilisent des représentations vectorielles continues.

Cloud SQL pour MySQL est compatible avec le stockage de représentations vectorielles continues. Vous pouvez ensuite créer des index de recherche vectorielle et effectuer des recherches de similarités sur ces représentations vectorielles continues avec le reste des données que vous stockez dans Cloud SQL.

Stockage de représentations vectorielles continues

Vous pouvez utiliser Cloud SQL pour MySQL pour stocker des représentations vectorielles continues en créant une colonne de représentations vectorielles continues dans une table. La colonne spéciale de représentations vectorielles continues correspond au type de données VARBINARY. Comme pour les autres données relationnelles de la table, vous pouvez accéder aux représentations vectorielles continues de la table avec les garanties transactionnelles existantes. Une table qui comporte une colonne de représentations vectorielles continues est une table InnoDB standard et est donc conforme aux propriétés d'atomicité, de cohérence, d'isolation et de durabilité (ACID). Les propriétés ACID ne diffèrent que pour les recherches dans l'index de recherche vectorielle.

Vous pouvez créer jusqu'à une colonne de représentations vectorielles continues dans une table et un index de recherche vectorielle par table. Chaque embedding stocké dans la même colonne doit avoir exactement les mêmes dimensions que celles que vous avez spécifiées lors de la définition de la colonne. Un embedding vectoriel a une limite supérieure de 16 000 dimensions. Si vous disposez de suffisamment d'espace de stockage et de mémoire, vous pouvez avoir des tables distinctes avec différentes colonnes de représentations vectorielles continues et des index de recherche vectorielle sur la même instance.

Bien qu'il n'existe aucune limite stricte au nombre de représentations vectorielles continues que vous pouvez stocker dans une table, les index de recherche vectorielle nécessitent de la mémoire. Pour cette raison, nous vous recommandons de ne pas stocker plus de 10 millions de représentations vectorielles continues dans une table.

La réplication fonctionne de la même manière pour la colonne de représentations vectorielles continues que pour les autres colonnes MySQL InnoDB.

Cloud SQL accepte la recherche de similarités à l'aide des requêtes de recherche des k plus proches voisins (KNN, K-nearest neighbors) et des plus proches voisins approximatifs (ANN, approximate nearest neighbors). Vous pouvez utiliser les deux types de recherches vectorielles dans vos instances Cloud SQL. Vous pouvez créer un index de recherche vectorielle pour les recherches ANN.

Cloud SQL accepte les requêtes exploitant la recherche vectorielle KNN, également appelée recherche de type plus proches voisins exacts. Une recherche vectorielle KNN offre un rappel parfait. Vous pouvez effectuer des recherches KNN sans avoir à créer un index de recherche vectorielle. La recherche KNN repose sur l'exécution d'un algorithme d'analyse de table.

Pour la recherche KNN, Cloud SQL accepte également les fonctions suivantes de recherche de distance vectorielle :

  • Cosinus
  • Produit scalaire
  • Distance L2 au carré

Pour en savoir plus sur l'utilisation des fonctions de distance de recherche vectorielle, consultez la section Interroger la distance d'un embedding vectoriel.

Cloud SQL permet de créer et d'interroger des recherches ANN via la création d'index de recherche vectorielle. Un index de recherche vectorielle ANN vous permet d'optimiser les performances rapides au lieu d'un rappel parfait. Pour la recherche ANN, Cloud SQL est compatible avec les types d'index suivants :

  • BRUTE_FORCE: type d'index de recherche vectorielle par défaut pour une table de base comportant moins de 10 000 lignes. Ce type est particulièrement adapté aux recherches effectuées dans un sous-ensemble restreint, au sein d'un ensemble de données d'origine. La mémoire utilisée par l'index est égale à la taille de l'ensemble de données. Ce type d'index n'est pas conservé sur disque.
  • TREE_SQ: type d'index de recherche vectorielle par défaut pour une table de base comportant au moins 10 000 lignes. Ce type utilise le moins de mémoire ou environ 25 % de la taille de l'ensemble de données. Les index TREE_SQ sont conservés sur disque.
  • TREE_AH: type d'index de recherche vectorielle qui fournit un algorithme de type de recherche de hachage asymétrique. Tel qu'il est mis en œuvre dans Cloud SQL, ce type d'index n'est pas optimisé pour l'espace mémoire utilisé et n'est pas conservé.

Mettre à jour les index de recherche vectorielle

Cloud SQL pour MySQL met à jour les index de recherche vectorielle en temps réel. Toute transaction effectuant des opérations LMD (langage de manipulation de données) sur la table de base propage également les modifications apportées aux index de recherche vectorielle associés. Les modifications d'un index de recherche vectorielle sont visibles immédiatement par toutes les autres transactions, ce qui correspond à un niveau d'isolation READ_UNCOMMITTED.

Si vous effectuez le rollback d'une transaction, les modifications de rollback correspondantes se produisent également dans l'index de recherche vectorielle.

Réplication des index de recherche vectorielle

Cloud SQL pour MySQL réplique les index de recherche vectorielle sur toutes les instances dupliquées avec accès en lecture. Les filtres de réplication et la réplication des index de recherche vectorielle sur des instances répliquées en cascade ne sont pas acceptés.

Configurer une instance pour qu'elle soit compatible avec les représentations vectorielles continues

Cette section explique comment configurer votre instance Cloud SQL pour qu'elle soit compatible avec le stockage, l'indexation et l'interrogation des représentations vectorielles continues.

Les instances Cloud SQL Enterprise et Cloud SQL Enterprise Plus sont toutes deux compatibles avec les représentations vectorielles continues.

Avant de commencer

  • Votre instance doit exécuter Cloud SQL pour MySQL version 8.0.36.R20240401.03_00 ou ultérieure.
  • Votre instance doit disposer de suffisamment d'espace disque et de mémoire pour allouer de la mémoire pour le nombre total de représentations vectorielles continues sur l'instance.

Activer la compatibilité avec les représentations vectorielles continues

Pour activer la compatibilité avec les représentations vectorielles continues de vecteurs, vous devez configurer des options de base de données MySQL.

gcloud sql instances patch INSTANCE_NAME \
  --database-flags=FLAGS

Remplacez INSTANCE_NAME par le nom de l'instance sur laquelle vous souhaitez activer la compatibilité avec les représentations vectorielles continues.

Dans FLAGS, configurez les options MySQL suivantes sur votre instance :

  • cloudsql_vector: définissez cette option sur on pour activer le stockage et la recherche de représentations vectorielles continues. Vous pouvez créer des colonnes de représentations vectorielles continues et des index de recherche vectorielle sur l'instance.
  • cloudsql_vector_max_mem_size : Facultatif. Spécifiez l'allocation maximale de mémoire en octets pour tous les index de recherche vectorielle de l'instance. Si vous ne spécifiez pas cette option, l'allocation de mémoire par défaut est de 1 Go, ce qui correspond à l'allocation minimale de mémoire. Pour en savoir plus sur le calcul de la quantité à spécifier, consultez la section Configurer l'allocation de mémoire pour les index de recherche vectorielle.

    Cette mémoire dédiée provient de la mémoire allouée à votre paramètre innodb_buffer_pool_size. Votre pool de mémoire tampon disponible est réduit de la même valeur. La valeur maximale autorisée pour cette option est de 50 % de la valeur innodb_buffer_pool_size totale.

    Si vous spécifiez une valeur supérieure à 50 % de la valeur innodb_buffer_pool_size totale, Cloud SQL réduit la valeur effective à 50 % de la taille disponible et enregistre un message d'avertissement pour l'instance.

Une fois que vous avez configuré les options, votre commande doit ressembler à ce qui suit :

gcloud sql instances patch my-instance \
  --database-flags=cloudsql_vector=on,cloudsql_vector_max_mem_size=4294967296

Les options permettant de configurer la compatibilité des représentations vectorielles continues dans Cloud SQL pour MySQL sont des options statiques. Une fois l'instance mise à jour avec les options, celle-ci redémarre automatiquement pour que les modifications de configuration entrent en vigueur.

Pour en savoir plus sur la configuration des options de base de données pour MySQL, consultez la page Configurer des options de base de données.

Désactiver la compatibilité avec les représentations vectorielles continues

Pour désactiver la compatibilité avec les représentations vectorielles continues, définissez l'option cloudsql_vector sur off.

Exemple :

gcloud sql instances patch INSTANCE_NAME \
  --database-flags=cloudsql_vector=off

Remplacez INSTANCE_NAME par le nom de l'instance sur laquelle vous désactivez la compatibilité avec les représentations vectorielles continues.

Si vous définissez cloudsql_vector sur off, vous ne pouvez pas créer de colonnes d'embedding ni d'index de recherche vectorielle. Une fois que vous avez configuré cette option statique, l'instance redémarre automatiquement pour que la modification de configuration entre en vigueur.

Après le redémarrage de l'instance, Cloud SQL pour MySQL effectue les opérations suivantes:

  • Supprime tous les index de recherche vectorielle TREE_SQ persistants du disque persistant.
  • Conserve les entrées de la table du dictionnaire de données pour les index de recherche vectorielle qui ont été créés. Cependant, Cloud SQL pour MySQL ne recompile pas les index, et toutes les requêtes de recherche sur ces index renvoient une erreur.
  • Elle continue à stocker les représentations vectorielles continues dans les tables de base. Les représentations vectorielles continues restent accessibles.

Si vous réactivez ultérieurement l'option cloudsql_vector pour l'instance, Cloud SQL tente de recréer les index lors du redémarrage de l'instance, en se basant sur les entrées de la table du dictionnaire de données.

Configurer l'allocation de mémoire pour les index de recherche vectorielle

Cloud SQL crée et gère en mémoire les index de recherche vectorielle. Le type d'index TREE_SQ persiste lors d'un arrêt normal, et est rechargé au redémarrage de l'instance. Pendant l'exécution, tous les index de recherche vectorielle doivent rester en mémoire.

Pour vous assurer que Cloud SQL dispose de suffisamment de mémoire pour conserver tous les index de recherche vectorielle en mémoire, configurez l'instance Cloud SQL avec une option de base de données cloudsql_vector_max_mem_size. cloudsql_vector_max_mem_size régit la quantité de mémoire allouée par l'instance Cloud SQL aux index de recherche vectorielle. Tenez compte des points suivants lorsque vous configurez la valeur de l'option :

  • La valeur par défaut et minimale est de 1 Go. La limite supérieure est de 50 % de la taille du pool de mémoire tampon.
  • Une fois cette option définie, l'instance redémarre automatiquement pour que la modification de configuration entre en vigueur.
  • Si votre instance a utilisé toute sa mémoire configurée, vous ne pouvez pas créer ni modifier d'index de recherche vectorielle.

Pour mettre à jour la mémoire allouée aux index de recherche vectorielle sur l'instance, modifiez la valeur de l'option cloudsql_vector_max_mem_size.

gcloud sql instances patch INSTANCE_NAME \
  --database-flags= cloudsql_vector_max_mem_size=NEW_MEMORY_VALUE

Remplacez les éléments suivants :

  • INSTANCE_NAME: nom de l'instance sur laquelle vous modifiez l'allocation de mémoire.
  • NEW_MEMORY_VALUE: allocation de mémoire mise à jour, en octets, pour vos index de recherche vectorielle.

Cette modification entraîne le redémarrage automatique de votre instance pour que la modification entre en vigueur.

Calculer la mémoire requise

La quantité de mémoire requise par un index dépend du type d'index, du nombre de représentations vectorielles continues et de la dimensionnalité des représentations vectorielles continues. Deux exigences de mémoire sont à prendre en compte :

  • Mémoire de temps de compilation: la mémoire requise lors de la création de l'index
  • Index memory (Mémoire d'index): mémoire occupée par l'index après sa création

Pour un index donné, la taille de son ensemble de données est la mémoire nécessaire pour lire toutes les représentations vectorielles continues en mémoire. Étant donné que chaque dimension est représentée par un nombre à virgule flottante qui utilise 4 octets de mémoire, vous pouvez déterminer le champ dataset_size comme suit:

dataset_size = <num_embeddings> * (4 * <dimensions>)

Par exemple, si vous avez 1 million de représentations vectorielles continues de 768 dimensions, votre dataset_size est de 3 Go.

Sur la base de l'exemple précédent, les besoins en mémoire pour les différents types d'index sont les suivants :

Type d'index Mémoire de temps de compilation Mémoire nécessaire pour l'index
TREE_SQ 4 GB 1 Go
TREE_AH 3,5 Go 3,5 Go
BRUTE_FORCE 3 GB 3 GB

Si vous utilisez des index de recherche vectorielle TREE_SQ, vous devez également prendre en compte la mémoire requise pour la persistance lors de l'exécution. À la quantité totale de mémoire dans votre configuration, ajoutez la quantité de mémoire d'index utilisée par le plus grand index de recherche vectorielle TREE_SQ actif.

Chaque fois que la table de base dans laquelle les représentations vectorielles continues sont stockées subit des opérations LMD, l'index de recherche vectorielle est mis à jour en temps réel. Ces mises à jour modifient l'espace mémoire utilisé de l'index, qui peut la réduire ou l'étendre en fonction de l'opération LMD. Vous pouvez surveiller l'espace mémoire utilisé par un index en interrogeant la table information_schema.innodb_vector_indexes. Pour en savoir plus sur la surveillance de la taille de votre index de recherche vectorielle, consultez la page Surveiller les index de recherche vectorielle.

Configuration de l'instance dupliquée avec accès en lecture

Si l'instance répond aux critères d'activation de la version de maintenance et de l'option, Cloud SQL est entièrement compatible avec les représentations vectorielles continues sur une instance dupliquée avec accès en lecture.

Si vous créez une instance dupliquée à partir d'une instance principale pour laquelle la compatibilité avec l'embedding vectoriel est activée, l'instance dupliquée avec accès en lecture hérite des paramètres de compatibilité de l'instance principale. Vous devez activer la compatibilité avec les représentations vectorielles continues de manière individuelle sur les instances dupliquées avec accès en lecture existantes.

En termes d'impact sur le délai de réplication, la création et la gestion des index de recherche vectorielle fonctionnent de la même manière que les index MySQL classiques.

Les index de recherche vectorielle ne sont pas compatibles avec les instances répliquées en cascade.

Exemple: index et requête de recherche vectorielle ANN simples

L'exemple de tutoriel suivant décrit la procédure à suivre pour créer un index de recherche vectorielle et une requête basés sur ANN dans Cloud SQL.

  1. Générer des représentations vectorielles continues Vous pouvez créer des embeddings vectoriels manuellement ou utiliser l'API d'embedding de texte de votre choix. Pour obtenir un exemple utilisant Vertex AI, consultez la section Générer des représentations vectorielles continues basées sur des données de ligne.

  2. Créez une table dans Cloud SQL pour MySQL contenant une colonne de représentations vectorielles continues à trois dimensions.

    CREATE TABLE books (
    id   INTEGER PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(60),
    embedding VECTOR(3) USING VARBINARY
    );
    
  3. Insérez un embedding vectoriel dans la colonne.

    INSERT INTO books VALUES (
    1,
    'book title',
     string_to_vector('[1,2,3]')
    );
    
  4. Effectuez un commit sur les modifications :

    commit;
    
  5. Créer l'index de Vector Search. Si vous créez un index TREE_SQ ou TREE_AH, votre table doit contenir au moins 1 000 lignes.

    CALL mysql.create_vector_index('vectorIndex',
                                   'dbname.books',
                                   'embedding',
                                   'index_type=BRUTE_FORCE, distance_measure=L2_SQUARED'
                                   );
    
  6. Trouvez les plus proches voisins.

    SELECT title FROM books
    WHERE
    NEAREST(embedding) TO (string_to_vector('[1,2,3]'));
    

Générer des représentations vectorielles continues basées sur des données de ligne

Vous pouvez générer un embedding vectoriel pour les données d'une ligne spécifique, à l'aide d'une API d'embedding de texte telle que Vertex AI ou OpenAI. Vous pouvez utiliser n'importe quelle API d'embedding de texte avec des mbeddings vectoriels Cloud SQL. Toutefois, vous devez utiliser la même API d'embedding de texte pour la génération de vecteurs de chaîne de requête. Vous ne pouvez pas combiner différentes API pour les données sources et la vectorisation des requêtes.

Par exemple, vous pouvez générer un embedding vectoriel à partir de Vertex AI :

from vertexai.language_models import TextEmbeddingModel

def text_embedding() -> list:
    """Text embedding with a Large Language Model."""
    model = TextEmbeddingModel.from_pretrained("textembedding-gecko@001")
    embeddings = model.get_embeddings(["What is life?"])
    for embedding in embeddings:
        vector = embedding.values
        print(f"Length of Embedding Vector: {len(vector)}")
    return vector

if __name__ == "__main__":
    text_embedding()

Stocker les représentations vectorielles continues

Cette section fournit des exemples d'instructions permettant de stocker des représentations vectorielles continues dans Cloud SQL.

Créer une table avec une colonne de représentations vectorielles continues

CREATE TABLE books (
  id INTEGER PRIMARY KEY AUTO_INCREMENT,
  title VARCHAR(60),
  embedding VECTOR(3) USING VARBINARY
  );

Ajouter une colonne de représentations vectorielles continues à une table existante

ALTER TABLE books
ADD COLUMN embedding
VECTOR(3) USING VARBINARY;

Insérer un embedding vectoriel

INSERT INTO books (
  title,
  embedding
  ) VALUES (
    'book title',
    string_to_vector('[1,2,3]')
);

Insérer plusieurs représentations vectorielles continues

INSERT INTO books (
  title,
  embedding
  ) VALUES (
    'book title',
    string_to_vector('[1,2,3]')),
     ('book title', string_to_vector('[4,5,6]')
);

Effectuer une opération upsert sur un embedding vectoriel

INSERT INTO books (
  id,
  title,
  embedding
  ) VALUES (
    1,
    'book title',
     string_to_vector('[1,2,3]')
     )
ON DUPLICATE KEY UPDATE embedding = string_to_vector('[1,2,3]');

Mettre à jour un embedding vectoriel

UPDATE books
SET embedding = string_to_vector('[1,2,3]')
WHERE id = 1;

Supprimer embedding vectoriel

DELETE FROM books
WHERE embedding = string_to_vector('[1,2,3]');

Exploiter les index de recherche vectorielle

Par défaut, vous pouvez effectuer la recherche des plus proches voisins exacts, qui fournit un rappel parfait. Vous pouvez également ajouter un index pour utiliser la recherche ANN, ce qui altère légèrement la qualité du rappel au profit de la vitesse d'exécution. Contrairement aux index classiques, après l'ajout d'un index approximatif, des résultats différents s'affichent pour les requêtes.

Recommandations

Cette section présente les bonnes pratiques relatives à l'utilisation des index de recherche vectorielle. Chaque charge de travail est différente, et vous devrez peut-être procéder à des ajustements en conséquence.

  • Avant de créer un index de recherche vectorielle, vous devez charger des données dans la table. Votre table de base doit contenir au moins 1 000 lignes. Ces exigences ne s'appliquent qu'aux types d'index de recherche TREE_SQ et TREE_AH. Si vous avez davantage de points de données disponibles, le partitionnement et l'entraînement de l'index seront améliorés.
  • Surveillez l'utilisation de mémoire des index. Si l'instance arrive à court de mémoire, vous ne pouvez pas créer ni générer des index. Pour les index existants, une fois le seuil atteint, Cloud SQL écrit régulièrement des avertissements dans le journal d'erreurs MySQL. Vous pouvez consulter l'utilisation de mémoire dans la table information_schema.innodb_vector_indexes.
  • Si la table de base sous-jacente a subi des modifications LMD majeures, recréez les index de recherche vectorielle. Pour obtenir la taille initiale de l'index au moment de la compilation et sa taille actuelle, interrogez la table information_schema.innodb_vector_indexes.
  • En règle générale, il est acceptable de laisser le nombre de partitions être calculé en interne. Si vous souhaitez spécifier le nombre de partitions dans le cas d'une utilisation, vous devez disposer au moins de 100 points de données par partition.

Table de base en lecture seule lors des opérations d'index de recherche vectorielle

Pendant la durée des trois opérations d'index de recherche vectorielle (création, modification et suppression), la table de base est mise en mode lecture seule. Pendant ces opérations, aucune opération LMD n'est autorisée sur la table de base.

Persistance, arrêt et impact sur la maintenance

Seuls les index de recherche vectorielle qui utilisent le type TREE_SQ persistent sur le disque lors d'un arrêt normal d'une instance. Les index de recherche vectorielle qui utilisent les types TREE_AH et BRUTE_FORCE ne sont qu'en mémoire.

Après un arrêt normal d'une instance, Cloud SQL actualise les index de recherche vectorielle au redémarrage de l'instance. Toutefois, après un plantage ou un arrêt incorrect, Cloud SQL doit recréer les index de recherche vectorielle. Par exemple, chaque fois que votre instance subit un plantage et une récupération à partir d'une sauvegarde et d'une restauration, de la récupération à un moment précis (PITR) ou d'un basculement de haute disponibilité, Cloud SQL recompile vos index de recherche vectorielle. Voici ce qui se produit lors de tels événements :

  • La recompilation s'effectue automatiquement en arrière-plan.
  • Lors de la recompilation, la table de base est en mode lecture seule.
  • Si la recompilation automatique ne peut pas verrouiller la table dans un délai spécifique, la recompilation échoue. Vous devrez peut-être recompiler l'index manuellement.

Le temps nécessaire à la recompilation d'un index peut augmenter le temps nécessaire à un arrêt, ce qui peut également augmenter le temps nécessaire à la maintenance et à la mise à jour d'une instance.

Créer un index de recherche vectorielle

L'instruction permettant de créer un index de recherche vectorielle utilise la syntaxe suivante:

CALL mysql.create_vector_index('INDEX_NAME',
                                'DB_NAME.TABLE_NAME',
                                'COLUMN_NAME',
                                'PARAMETERS'
                              );

Exemple :

CALL mysql.create_vector_index('vectorIndex',
                                'db.books',
                                'embedding',
                                'index_type=TREE_SQ, distance_measure=l2_squared'
                               );

Le nom d'index que vous spécifiez doit être unique dans la base de données.

Paramètres de l'index de recherche vectorielle

Les fonctions de création d'index de recherche (et de modification d'index de recherche) acceptent plusieurs paramètres que vous pouvez spécifier avec des paires clé/valeur séparées par des virgules. Tous les paramètres de la fonction de création d'index de recherche sont facultatifs. Si vous spécifiez une chaîne vide ou la valeur NULL, les valeurs de paramètre par défaut sont configurées pour l'index.

  • distance_measure (mesure de distance): les valeurs acceptées sont L2_SQUARED, COSINE et DOT_PRODUCT. L2_SQUARED est la valeur par défaut.
  • num_neighbors : nombre de voisins à renvoyer par défaut lors des requêtes ANN. Vous pouvez également remplacer ce paramètre lorsque vous exécutez la requête de recherche. La valeur par défaut est 10.
  • index_type : spécifie le type d'index à créer. Les valeurs valides sont BRUTE_FORCE, TREE_SQ et TREE_AH.

    • BRUTE_FORCE est la valeur par défaut pour une table comportant moins de 10 000 lignes.
    • TREE_SQ est la valeur par défaut pour une table comportant 10 000 lignes ou plus.

    Pour spécifier le type d'index TREE_AH ou TREE_SQ, la taille de votre table de base doit être supérieure à 1 000 lignes.

  • num_parititions : spécifie le nombre de clusters en k-moyennes à créer. Ce paramètre n'est autorisé que si vous avez configuré un index_type. Cette option ne s'applique pas à BRUTE_FORCE. Si vous spécifiez le type d'index TREE_SQ ou TREE_AH, la taille de votre table de base doit être supérieure ou égale à la valeur num_partitions * 100.

Modifier un index de recherche vectorielle

CALL mysql.alter_vector_index('DB_NAME.INDEX_NAME', 'PARAMETERS');

La fonction alter_vector_index est utilisée explicitement pour reconstruire un index de recherche vectorielle. Pour utiliser cette fonction, l'index doit déjà exister. Vous pouvez recompiler un index pour les cas d'utilisation suivants :

  • Vous souhaitez recompiler l'index avec des options différentes. Par exemple, vous souhaitez utiliser un autre type d'index ou une autre mesure de distance.
  • Vous souhaitez recompiler l'index, car la table de base a subi des modifications LMD importantes. Par exemple, vous devez réentraîner l'index de recherche vectorielle en fonction des données actuelles de la table de base.

Tous les paramètres de recompilation de l'index sont identiques à ceux disponibles pour la création de l'index et sont également facultatifs. Si vous spécifiez une chaîne vide ou la valeur NULL lorsque vous recompilez l'index, celui-ci va être recompilé en se basant sur les paramètres spécifiés au moment de la création de l'index. Si aucun paramètre n'est fourni au moment de la création de l'index, les valeurs de paramètre par défaut sont utilisées.

L'index de recherche vectorielle existant est disponible pendant l'opération de modification. Vous pouvez toujours effectuer des requêtes de recherche sur l'index.

Supprimer un index de recherche vectorielle

Vous ne pouvez pas effectuer d'opération LDD sur une table dotée d'un index de recherche vectorielle. Avant d'effectuer l'opération LDD sur la table, vous devez supprimer l'index de recherche vectorielle.

CALL mysql.drop_vector_index('DB_NAME.INDEX_NAME');

Interroger les représentations vectorielles continues de vecteurs

Cette section fournit des exemples des différentes manières d'interroger des représentations vectorielles continues.

Afficher les représentations vectorielles continues

SELECT vector_to_string(embedding) FROM books;

Obtenir la recherche des voisins exacts dans un embedding vectoriel

SELECT id,cosine_distance(embedding,
   string_to_vector('[1,2,3]')) dist
FROM books
ORDER BY dist
LIMIT 10;

Obtenir la recherche des voisins approximatifs dans un embedding vectoriel

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'), 'num_neighbors=10');

L'exécution d'une recherche ANN accepte deux paramètres, qui sont tous deux facultatifs.

  • num_partitions: spécifie le nombre de partitions à vérifier pour une recherche vectorielle ANN. Si vous ne spécifiez pas le nombre de partitions, la recherche utilise une valeur générée en fonction de la taille de la table, du nombre de partitions dans l'index de recherche vectorielle et d'autres facteurs.
  • num_neighbors : spécifie le nombre de voisins à renvoyer. Cette valeur remplace la valeur définie au moment de la création de l'index de recherche vectorielle.

Filtrer les représentations vectorielles continues

Utilisez des colonnes supplémentaires comme prédicats pour affiner le filtrage des résultats de votre requête d'embedding. Par exemple, si vous ajoutez une colonne printyear, vous pouvez ajouter une année spécifique comme valeur de filtrage pour votre requête.

SELECT title FROM books
WHERE
NEAREST(embedding) TO (string_to_vector('[1,2,3]'))
AND printyear > 1991;

Interroger la distance d'un embedding vectoriel

Cette section fournit des exemples de fonctions de distance vectorielle disponibles pour la recherche KNN.

Obtenir la distance de cosinus

SELECT cosine_distance(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

Obtenir la distance de produit scalaire

SELECT dot_product(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

Obtenir la distance L2 au carré

SELECT l2_squared_distance(embedding, string_to_vector('[3,1,2]'))
AS distance FROM books WHERE id=10;

Obtenir les lignes correspondant à une certaine distance

SELECT * FROM books
WHERE l2_squared_distance(embedding, string_to_vector('[1,2,3]')) < 10;

Vous pouvez combiner cette fonction avec ORDER BY et LIMIT.

SELECT id, vector_to_string(embedding),
       l2_squared_distance(embedding, string_to_vector('[1,2,3]')) dist
FROM books ORDER BY dist LIMIT 10;

Surveiller les index de recherche vectorielle

Pour obtenir des informations en temps réel sur tous les index de recherche vectorielle de l'instance, utilisez la table information_schema.innodb_vector_indexes.

Exécutez la commande suivante pour afficher la table :

SELECT * FROM information_schema.innodb_vector_indexes;

Voici un exemple de résultat :

*************************** 1. row ***************************
       INDEX_NAME: test.t4_index
       TABLE_NAME: test.t4_bf
       INDEX_TYPE: BRUTE_FORCE
     DIST_MEASURE: SquaredL2Distance
           STATUS: Ready
            STATE: INDEX_READY_TO_USE
       PARTITIONS: 0
SEARCH_PARTITIONS: 0
     INITIAL_SIZE: 40000
     CURRENT_SIZE: 40000
          QUERIES: 0
        MUTATIONS: 0
     INDEX_MEMORY: 160000
   DATASET_MEMORY: 0

La table information_schema.innodb_vector_indexes vous permet d'afficher les éléments suivants :

  • Les options qui sont potentiellement générées. En d'autres termes, num_partitions ou le nombre de partitions à vérifier pour une requête.
  • Les colonnes STATE et STATUS indiquent l'état actuel de l'index. Pendant la phase de compilation, la colonne d'état fournit des informations sur l'avancement de l'index de recherche vectorielle dans la phase de compilation.
  • La colonne INITIAL_SIZE indique la taille de la table lors de la création de l'index. Vous pouvez comparer cette taille avec CURRENT_SIZE pour avoir une idée de l'évolution de l'index depuis sa création, en raison des opérations LMD effectuées sur la table de base.
  • Les colonnes QUERIES et MUTATIONS vous fournissent des insights en temps réel sur l'activité de l'index.
  • Les colonnes INDEX_MEMORY et DATASET_MEMORY fournissent des informations sur la consommation de mémoire de l'index. INDEX_MEMORY

    indique la quantité de mémoire utilisée par l'index, et DATASET_MEMORY indique la quantité de mémoire supplémentaire utilisée pendant la compilation.

Pour obtenir la liste des index de recherche vectorielle créés sur l'instance, vous pouvez afficher la table du dictionnaire de données mysql.vector_indexes.

Exécutez la commande suivante pour afficher la table :

SELECT * FROM mysql.vector_indexes;

Exemple de résultat :

*************************** 1. row ***************************
   index_name: test.index1
   table_name: test.t1
  column_name: j
index_options: index_type=BRUTE_FORCE, distance_measure=L2_SQUARED
       status: ACTIVE
  create_time: 2024-04-08 22:46:21
  update_time: 2024-04-08 22:46:21
1 row in set (0.00 sec)

Limites

  1. Il ne peut y avoir qu'une seule colonne de représentations vectorielles continues par table.
  2. Il ne peut y avoir qu'un seul index de recherche vectorielle par table.
  3. Un embedding vectoriel peut comporter jusqu'à 16 000 dimensions.
  4. Le partitionnement au niveau de la table InnoDB sur les tables comportant des colonnes de représentations vectorielles continues n'est pas accepté.
  5. Si l'instance redémarre suite à un arrêt incorrect, Cloud SQL recrée automatiquement l'index de recherche vectorielle.
    1. Lors de la reconstruction de l'index de recherche vectorielle, la table de base est en lecture seule.
    2. Si Cloud SQL ne peut pas valider le verrouillage de la table dans le délai spécifié, la recompilation automatique de l'index risque d'échouer.
    3. Si la recompilation automatique de l'index échoue, vous devrez recompiler l'index manuellement.
  6. Pour ajouter une colonne de représentations vectorielles continues, la table doit avoir une clé primaire. Cloud SQL n'est pas compatible avec les clés primaires de type BIT, BINARY, VARBINARY, JSON, BLOB et TEXT, ou de type données spatiales. Les clés primaires composites ne peuvent inclure aucun de ces types.
  7. Si un index de recherche vectorielle est présent sur une table, les opérations LDD ne sont pas autorisées. L'index de recherche vectorielle doit être supprimé avant d'effectuer des opérations LDD sur la table de base.
  8. Les représentations vectorielles continues ne sont pas compatibles avec les tables autres qu'InnoDB ou avec les tables temporaires.
  9. La colonne de représentations vectorielles continues ne peut pas être une colonne générée.
  10. Le prédicat NEAREST..TO peut être combiné à d'autres prédicats "scalaires" à l'aide des opérateurs AND ou OR. Les prédicats scalaires de la table sont évalués après l'application des prédicats vectoriels.
  11. Le prédicat NEAREST..TO n'est accepté que dans une instruction SELECT. Les autres instructions LMD ne sont pas compatibles avec l'instruction NEAREST..TO.
  12. Les sous-requêtes ne sont pas compatibles avec NEAREST..TO. Une contrainte ne peut pas être ajoutée à la clé primaire de la table de base si un index de recherche vectorielle est présent.
  13. Le préfiltrage n'est possible que via des fonctions de distance et en utilisant ORDER BY avec LIMIT.

    Par exemple, si vous créez la table suivante :

    CREATE TABLE books
    (
    bookid          INT PRIMARY KEY,
    title           VARCHAR(1000),
    author          VARCHAR(100),
    printyear       int,
    country         VARCHAR(100),
    bvector         VECTOR(1536) USING VARBINARY
    //bvector is embedding vector of book's plot,genre,reviews etc
    );
    

    Vous pouvez ensuite effectuer le préfiltrage à l'aide de la requête suivante.

    //select query to obtain books by specific author and having similar plot-genre-reviews
    SELECT bookid, title, author,l2_squared_distance(bvector, qvector) dist
    FROM books where author='cloudsql' ORDER BY dist LIMIT 10
    

    Le post-filtrage est compatible avec l'instruction NEAREST..TO et avec les fonctions de distance.

Résoudre les problèmes

En cas de plantage, l'index est recompilé automatiquement. Deux restrictions s'appliquent lorsqu'une recompilation est en cours :

  1. Lors de la création de l'index, la table de base est en mode lecture seule.
  2. Lors de la recréation de l'index, les requêtes ANN sur les index existants échouent.

Étapes suivantes