Référence de l'assistance vectorielle

MySQL | PostgreSQL | SQL Server

Preview — Vector Assist

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Vous pouvez traiter des données à caractère personnel lorsque vous utilisez cette fonctionnalité comme indiqué dans l'Avenant relatif au traitement des données dans le cloud, sous réserve de respecter les obligations et restrictions décrites dans le contrat en vertu duquel vous accédez à Google Cloud. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette page fournit des informations détaillées sur toutes les fonctions d'assistance vectorielle disponibles, ainsi que sur leurs paramètres obligatoires et facultatifs.

vector_assist.define_spec

Définit une nouvelle spécification de vecteur, ou spécification de vecteur, et renvoie les recommandations nécessaires pour intensifier la charge de travail du vecteur. Cette fonction applique les spécifications fournies par l'utilisateur pour générer les recommandations.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.define_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT,
    schema_name TEXT DEFAULT NULL,
    vector_column_name TEXT DEFAULT NULL,
    text_column_name TEXT DEFAULT NULL,
    vector_index_type TEXT DEFAULT NULL, -- Allowed: 'hnsw', 'ivfflat'
    embeddings_available BOOL DEFAULT NULL,
    embedding_model TEXT DEFAULT NULL,
    num_vectors INT DEFAULT NULL,
    dimensionality INT DEFAULT NULL,
    distance_func TEXT DEFAULT NULL, -- Allowed: 'cosine', 'ip', 'l2', 'l1'
    quantization TEXT DEFAULT NULL, -- Allowed: 'none', 'halfvec', 'bit'
    prefilter_column_names TEXT[] DEFAULT NULL,
    memory_budget_kb INT DEFAULT NULL, -- In KB
    target_recall FLOAT DEFAULT NULL,
    target_top_k INT DEFAULT NULL,
    tune_vector_index BOOL DEFAULT FALSE, -- Set to true if target_recall is set
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Paramètres

Paramètre	Obligatoire ?	Description
spec_id	Obligatoire (généré automatiquement)	ID unique de la spécification vectorielle que vous définissez.
table_name	Obligatoire ?	Nom de la table à utiliser dans la configuration de la charge de travail vectorielle.
schema_name	Facultatif	Schéma contenant la table à utiliser dans la charge de travail vectorielle. Le schéma est automatiquement déduit en fonction du chemin de recherche du schéma.
vector_column_name	Facultatif ou obligatoire	Nom de la colonne contenant les embeddings vectoriels. Cette colonne est obligatoire si vous utilisez plusieurs colonnes de vecteur et que text_column_name n'est pas déclaré. Si vous n'utilisez qu'une seule colonne de vecteur, ce paramètre est facultatif.
text_column_name	Facultatif ou obligatoire	Nom de la colonne de texte. Ce paramètre est obligatoire si votre charge de travail vectorielle nécessite la génération d'embeddings à partir d'une colonne de texte. Cette colonne est obligatoire si le paramètre vector_column_name est défini sur NULL et qu'il n'y a pas d'autres colonnes de vecteurs. Ce paramètre utilise l'extension google_ml_integration pour générer des embeddings à partir de la colonne de texte donnée.
vector_index_type	Facultatif	Type d'index vectoriel. Les valeurs acceptées incluent les suivantes : HNSW IVFFlat SCANN
embeddings_available	Facultatif	Valeur booléenne qui vérifie si des embeddings vectoriels existent dans la table sélectionnée. Ce champ est défini sur FALSE si aucune colonne vectorielle n'est détectée et que le paramètre text_column_name est défini.
embedding_model	Facultatif ou obligatoire	ID du modèle à partir de google_ml.models à utiliser pour générer les embeddings. Ce champ est facultatif, sauf si le paramètre embeddings_available est défini sur FALSE ou NULL.
num_vectors	Facultatif	Nombre de vecteurs dans la table.
dismensionality	Facultatif	Dimension des vecteurs donnés.
distance_func	Facultatif	Fonction de distance à utiliser pour comparer les vecteurs. Les valeurs acceptables incluent cosine, ip, l2 ou l1.
quantization	Facultatif	Quantification pour les index vectoriels. Les valeurs acceptables sont none, halfvec ou bit.
prefilter_column_names	Facultatif	Crée un index pour la colonne spécifiée pour le préfiltrage. Cela peut améliorer les performances des requêtes avec un filtre à sélectivité élevée sur la colonne.
memory_budget_kb	Facultatif	Mémoire maximale (en Ko) pour la création d'index.
target_recall	Facultatif	Rappel cible pour les requêtes vectorielles standards.
target_top_k	Facultatif	Les valeurs correspondantes top K à récupérer pour le calcul du rappel. Cette valeur est utilisée si le paramètre target_recall est spécifié.
tune_vector_index	Facultatif	Règle les index vectoriels de votre charge de travail. Si cette option est activée, l'assistance vectorielle ajuste automatiquement l'index vectoriel ou la requête de recherche à l'aide de la spécification vectorielle, et calcule les paramètres optimaux de la base de données et de l'index. Les valeurs acceptables incluent TRUE ou FALSE.

Valeur renvoyée

Renvoie un tableau de recommandations à appliquer pour configurer la charge de travail vectorielle demandée. Chaque ligne correspond à une recommandation unique qui contient une requête SQL exécutable et une explication détaillée des raisons pour lesquelles appliquer la recommandation. La recommandation peut être appliquée à l'aide de la fonction apply_recommendation().

Remarque : Cette fonction est une opération de longue durée. Si vous utilisez un client avec un délai d'expiration (par exemple, Cloud SQL Studio avec un délai d'expiration de cinq minutes), l'appel de fonction peut être interrompu. Pour résoudre ce problème, vous pouvez augmenter le seuil de délai avant expiration ou créer une copie de la table que vous utilisez avec uniquement un sous-ensemble de données afin de respecter les exigences de délai avant expiration.

Le tableau des recommandations contient les colonnes suivantes :

Nom de la colonne	Type	Description
recommendation_id	Texte	ID de la recommandation. La recommandation est appliquée à l'aide de cet ID.
vector_spec_id	Texte	ID de la spécification vectorielle associée à la recommandation.
table_name	Texte	Nom de la table associée à la recommandation.
schema_name	Texte	Nom du schéma contenant la table donnée.
query	Texte	Requête SQL exécutable à exécuter pour obtenir le résultat de la recommandation.
recommendation	Texte	Explication de la recommandation, y compris le résultat attendu une fois la recommandation appliquée. Cette colonne contient également la raison et la justification de la recommandation. Vous pouvez utiliser ce contexte pour ajuster la requête si nécessaire et générer de nouvelles recommandations.
applied	Booléen	Indique si la recommandation a été appliquée.
modified	Booléen	Indique si la recommandation a été modifiée par l'utilisateur.
created_at	Code temporel avec fuseau horaire	Heure à laquelle la recommandation a été générée, au format timestamp with time zone. Exemple : 2024-07-18 09:00:00-08.

vector_assist.list_specs

Renvoie la spécification vectorielle actuelle pour une table et une colonne données.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.list_specs(
  table_name      TEXT,
  column_name     TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS

Paramètres

Paramètre	Obligatoire ?	Description
table_name	Obligatoire ?	Nom de la table pour laquelle la spécification vectorielle est récupérée.
column_name	Facultatif	Nom de la colonne sur laquelle filtrer le tableau avant de renvoyer la spécification. Si le nom de la colonne est spécifié, les spécifications contenant des noms de colonnes de texte ou de vecteur correspondant à ce nom de colonne sont renvoyées.

Valeur renvoyée

Renvoie un tableau de spécifications pour la table et, éventuellement, le nom de la colonne.

vector_assist.modify_spec

Modifie une spécification vectorielle existante. Lorsque la spécification vectorielle est modifiée, les recommandations associées sont régénérées en fonction des nouvelles spécifications.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.modify_spec(
  spec_id                TEXT,
  table_name             TEXT DEFAULT NULL,
  schema_name            TEXT DEFAULT NULL,
  vector_column_name     TEXT DEFAULT NULL,
  text_column_name       TEXT DEFAULT NULL,
  vector_index_type      TEXT DEFAULT NULL,
  embeddings_available   BOOL DEFAULT NULL,
  num_vectors            INT DEFAULT NULL,
  dimensionality         INT DEFAULT NULL,
  embedding_model        TEXT DEFAULT NULL,
  prefilter_column_names TEXT[] DEFAULT NULL,
  distance_func          TEXT DEFAULT NULL,
  quantization           TEXT DEFAULT NULL,
  memory_budget_kb       INT DEFAULT NULL,
  target_recall          FLOAT DEFAULT NULL,
  target_top_k           INT DEFAULT NULL,
  tune_vector_index      BOOL DEFAULT NULL
)
RETURNS SETOF vector_assist.RECOMMENDATIONS

Paramètres

Paramètre	Obligatoire ?	Description
spec_id	Obligatoire (généré automatiquement)	ID unique de la spécification vectorielle que vous définissez.
table_name	Obligatoire ?	Nom de la table à utiliser dans la configuration de la charge de travail vectorielle.
schema_name	Facultatif	Schéma contenant la table à utiliser dans la charge de travail vectorielle. Le schéma est automatiquement déduit en fonction du chemin de recherche du schéma.
vector_column_name	Facultatif ou obligatoire	Nom de la colonne contenant les embeddings vectoriels. Cette colonne est obligatoire si vous utilisez plusieurs colonnes de vecteur et que text_column_name n'est pas déclaré. Si vous n'utilisez qu'une seule colonne de vecteur, ce paramètre est facultatif.
text_column_name	Facultatif ou obligatoire	Nom de la colonne de texte. Ce paramètre est obligatoire si votre charge de travail vectorielle nécessite la génération d'embeddings à partir d'une colonne de texte. Cette colonne est obligatoire si le paramètre vector_column_name est défini sur NULL et qu'il n'y a pas d'autres colonnes de vecteurs. Ce paramètre utilise l'extension google_ml_integration pour générer des embeddings à partir de la colonne de texte donnée.
vector_index_type	Facultatif	Type d'index vectoriel. Les valeurs acceptées incluent les suivantes : HNSW IVFFlat SCANN
embeddings_available	Facultatif	Valeur booléenne qui vérifie si des embeddings vectoriels existent dans la table sélectionnée. Ce champ est défini sur FALSE si aucune colonne vectorielle n'est détectée et que le paramètre text_column_name est défini.
embedding_model	Facultatif ou obligatoire	ID du modèle à partir de google_ml.models à utiliser pour générer les embeddings. Ce champ est facultatif, sauf si le paramètre embeddings_available est défini sur FALSE ou NULL.
num_vectors	Facultatif	Nombre de vecteurs dans la table.
dismensionality	Facultatif	Dimension des vecteurs donnés.
distance_func	Facultatif	Fonction de distance à utiliser pour comparer les vecteurs. Les valeurs acceptables incluent cosine, ip, l2 ou l1.
quantization	Facultatif	Quantification pour les index vectoriels. Les valeurs acceptables sont none, halfvec ou bit.
prefilter_column_names	Facultatif	Identifie les colonnes disponibles pour le préfiltrage dans les requêtes de recherche vectorielle.
memory_budget_kb	Facultatif	Mémoire maximale (en Ko) pour la création d'index.
target_recall	Facultatif	Rappel cible pour les requêtes vectorielles standards.
target_top_k	Facultatif	Les valeurs correspondantes top K à récupérer pour le calcul du rappel. Cette valeur est utilisée si le paramètre target_recall est spécifié.
tune_vector_index	Facultatif	Règle les index vectoriels de votre charge de travail. Si cette option est activée, l'assistance vectorielle ajuste automatiquement l'index vectoriel ou la requête de recherche à l'aide de la spécification vectorielle, et calcule les paramètres optimaux de la base de données et de l'index. Les valeurs acceptables incluent TRUE ou FALSE.

Valeur renvoyée

Renvoie un tableau de recommandations mis à jour qui doit être appliqué pour configurer la charge de travail vectorielle demandée. Chaque ligne correspond à une recommandation unique qui contient une requête SQL exécutable et une explication détaillée des raisons pour lesquelles appliquer la recommandation. La recommandation peut être appliquée à l'aide de la fonction apply_recommendation().

Le tableau des recommandations contient les colonnes suivantes :

Nom de la colonne	Type	Description
recommendation_id	Texte	ID de la recommandation. La recommandation est appliquée à l'aide de cet ID.
vector_spec_id	Texte	ID de la spécification vectorielle associée à la recommandation.
table_name	Texte	Nom de la table associée à la recommandation.
schema_name	Texte	Nom du schéma contenant la table donnée.
query	Texte	Requête SQL exécutable à exécuter pour obtenir le résultat de la recommandation.
recommendation	Texte	Explication de la recommandation, y compris le résultat attendu une fois la recommandation appliquée. Cette colonne contient également la raison et la justification de la recommandation. Vous pouvez utiliser ce contexte pour ajuster la requête si nécessaire et générer de nouvelles recommandations.
applied	Booléen	Indique si la recommandation a été appliquée.
modified	Booléen	Indique si la recommandation a été modifiée par l'utilisateur.
created_at	Code temporel avec fuseau horaire	Heure à laquelle la recommandation a été générée.

vector_assist.get_recommendations

Renvoie les recommandations associées à un vecteur spec_id spécifique.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Paramètres

Paramètre	Obligatoire ?	Description
spec_id	Obligatoire ?	Obtient des recommandations pour le vecteur spec_id spécifié.

Valeur renvoyée

Renvoie un tableau des recommandations demandées.

Le tableau des recommandations contient les colonnes suivantes :

Nom de la colonne	Type	Description
recommendation_id	Texte	ID de la recommandation. La recommandation est appliquée à l'aide de cet ID.
vector_spec_id	Texte	ID de la spécification vectorielle associée à la recommandation.
table_name	Texte	Nom de la table associée à la recommandation.
schema_name	Texte	Nom du schéma contenant la table donnée.
query	Texte	Requête SQL exécutable à exécuter pour obtenir le résultat de la recommandation.
recommendation	Texte	Explication de la recommandation, y compris le résultat attendu une fois la recommandation appliquée. Cette colonne contient également la raison et la justification de la recommandation. Vous pouvez utiliser ce contexte pour ajuster la requête si nécessaire et générer de nouvelles recommandations.
applied	Booléen	Indique si la recommandation a été appliquée.
modified	Booléen	Indique si la recommandation a été modifiée par l'utilisateur.
created_at	Code temporel avec fuseau horaire	Heure à laquelle la recommandation a été générée.

vector_assist.apply_recommendation

Applique une seule recommandation à l'aide de recommendation_id.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Paramètres

Paramètre	Obligatoire ?	Description
recommenation_id	Obligatoire ?	ID de la recommandation vectorielle à appliquer.

Valeur renvoyée

Renvoie une valeur booléenne qui confirme si une recommandation a bien été appliquée et met à jour la colonne applied de la table vector_assist.RECOMMENDATIONS sur TRUE.

Si l'assistance vectorielle ne parvient pas à appliquer la recommandation, un message d'erreur s'affiche.

vector_assist.apply_spec

Applique toutes les recommandations associées à un nom de table ou de vecteur spec_id spécifique. Cette fonction parcourt toutes les recommandations et exécute la fonction vector_assist.apply_recommendation sur chacune d'elles.

Vous devez spécifier un spec_id ou un table_name pour exécuter la fonction.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.apply_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL -- text_column_name or vector_column_name
)
RETURNS BOOLEAN;

Paramètres

Paramètre	Obligatoire ?	Description
spec_id	Facultatif	Applique toutes les recommandations pour le vecteur spec_id donné.
table_name	Facultatif	Applique toutes les recommandations pour la table donnée.
schema_name	Facultatif	Schéma contenant la table spécifiée.
column_name	Facultatif	Identifie le text_column_name ou le vector_column_name à utiliser si la table contient plusieurs spécifications de vecteur.

Valeur renvoyée

Renvoie une valeur booléenne qui confirme si toutes les recommandations ont été appliquées et définit la valeur dans la colonne vector_assist.RECOMMENDATIONS de la table applied sur TRUE pour toutes les recommandations.

Si l'assistance vectorielle ne parvient pas à appliquer la recommandation, un message d'erreur s'affiche.

vector_assist.modify_recommendation

Modifie la requête pour une recommandation spécifique et définit le champ modified dans la table vector_assist.RECOMMENDATIONS pour la recommandation associée sur TRUE.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
    recommendation_id TEXT,
    modified_query TEXT
)
RETURNS BOOLEAN;

Paramètres

Paramètre	Obligatoire ?	Description
recommendation_id	Obligatoire ?	ID de la recommandation à modifier.
modified_query	Obligatoire ?	Requête SQL modifiée par l'utilisateur pour la recommandation.

Valeur renvoyée

Renvoie une valeur booléenne qui confirme si une recommandation a été mise à jour et définit la colonne modified de la table vector_assist.RECOMMENDATIONS sur TRUE.

Si l'assistance vectorielle ne parvient pas à mettre à jour la recommandation, un message d'erreur s'affiche.

vector_assist.generate_query

Génère une requête de recherche vectorielle optimisée en fonction de la spécification vectorielle et des paramètres de recherche définis. Cette fonction peut ajuster la valeur ef_search pour répondre à la valeur target_recall définie, le cas échéant.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.generate_query(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL, -- text_column_name or vector_column_name of the spec
    search_text TEXT DEFAULT NULL,
    search_vector VECTOR DEFAULT NULL, -- e.g. '[1.0,2.0,3.0]'::vector
   output_column_names TEXT[] DEFAULT NULL, -- Columns to retrieve, NULL for SELECT *
    top_k INT DEFAULT NULL,
    filter_expressions TEXT[] DEFAULT NULL,
    target_recall FLOAT DEFAULT NULL, -- Inherited from spec, can be overridden
    iterative_index_search BOOL DEFAULT NULL
)
RETURNS TEXT; -- Returns the text representing the search query

Paramètres

Paramètre	Obligatoire ?	Description
spec_id	Facultatif	Spécifie le spec_id pour lequel générer la requête.
table_name	Facultatif	Spécifie le nom de la table pour laquelle générer la requête de recherche si spec_id n'est pas fourni. Si une table contient plusieurs spécifications, le paramètre renvoie une erreur.
column_name	Facultatif	Spécifie le nom de la colonne pour laquelle générer la requête de recherche si spec_id n'est pas fourni. Si la colonne contient plusieurs spécifications, le paramètre renvoie une erreur. column_name peut être text_column_name ou vector_column_name.
output_column_name	Facultatif	Noms des colonnes à récupérer dans la requête de sortie. Pour récupérer toutes les colonnes, définissez ce paramètre sur NULL.
search_text	Facultatif	Texte de recherche pour lequel générer des embeddings. Nécessite embedding_model dans la spécification du vecteur. L'embedding est généré à l'aide du modèle de la spécification. Vous ne pouvez définir que le paramètre search_text ou search_vector.
search_vector	Facultatif	Vecteur de la requête de recherche. Vous ne pouvez définir que le paramètre search_text ou le paramètre search_vector.
top_k	Facultatif	Nombre de voisins les plus proches à renvoyer.
filter_expressions	Facultatif	Expressions de filtre à appliquer dans la requête de recherche. Les filtres peuvent être appliqués aux champs du tableau, par exemple "prix < 100".
iterative_index_search	Facultatif	Indique s'il faut effectuer une recherche d'index itérative pour les requêtes filtrées.Ce paramètre remplace les paramètres de la spécification vectorielle.
target_recall	Facultatif	Rappel cible pour la requête de recherche uniquement. Ce paramètre remplace les paramètres de la spécification du vecteur et ajuste ef_search.

Valeur renvoyée

Renvoie un texte contenant la requête de recherche vectorielle pour les paramètres donnés. Vous pouvez exécuter cette requête ou l'enregistrer pour l'exécuter ultérieurement.

vector_assist.evaluate_query_recall

Évalue le rappel de l'index vectoriel pour une requête donnée. Cette fonction utilise les configurations de base de données et d'index dans une chaîne JSON comme entrées.

Fonction

CREATE OR REPLACE FUNCTION vector_assist.evaluate_query_recall(
  IN ann_query text,
  IN vector_search_configurations json DEFAULT NULL,
  OUT recall float,
  OUT ann_execution_time float,
  OUT ground_truth_execution_time float,
  OUT index_type text)
RETURNS RECORD

Paramètres

Paramètre	Obligatoire ?	Description
ann_query	Obligatoire ?	Requête SQL pour laquelle le rappel doit être évalué. Cette requête doit être une requête ANN pgvector.
vector_search_configurations	Facultatif	Configurations pouvant être définies pour la requête ANN. Ce paramètre doit être au format JSON.

Valeur renvoyée

Renvoie un tableau qui évalue le rappel de l'index vectoriel pour la requête donnée.

Le tableau contient les colonnes suivantes :

Nom de la colonne	Type	Description
recall	Float	Pourcentage de vecteurs renvoyés par l'index qui sont de vrais voisins les plus proches. Cette métrique permet de quantifier la qualité de la recherche. Cette fonction vous permet d'ajuster les paramètres pour renvoyer les résultats de rappel de requête vectorielle attendus.
ann_execution_time	Float	Temps nécessaire à l'exécution d'une requête vectorielle à l'aide d'analyses d'index.
ground_truth_execution_time	Float	Temps nécessaire à l'exécution de la requête à l'aide d'une analyse séquentielle.

Exemple

L'exemple suivant évalue le rappel pour un index HNSW et remplace le paramètre de configuration HNSW.ef_search :

SELECT * FROM vector_assist.evaluate_query_recall(
  ann_query => 'SELECT id FROM items ORDER BY embedding <=> ''[1,2,3]'' LIMIT 10',
  vector_search_configurations => '{"hnsw.ef_search": 30}'
);