Utiliser l'assistance vectorielle

L'assistance vectorielle dans AlloyDB pour PostgreSQL fournit un framework SQL déclaratif qui vous permet de déployer, d'ajuster et de gérer les charges de travail de recherche vectorielle sur vos instances. Vous pouvez définir vos exigences de recherche vectorielle, générer et appliquer les configurations SQL recommandées, et surveiller les performances de la charge de travail. Pour en savoir plus sur le fonctionnement de l'assistance vectorielle, consultez Présentation de l'assistance vectorielle.

Avant de commencer

  • Vérifiez que votre instance utilise la bonne version de maintenance. L'assistance vectorielle nécessite un numéro de version de maintenance minimal de POSTGRES_17.20260128.03_06. Pour en savoir plus sur la maintenance en libre-service, consultez Maintenance en libre-service.

  • Activez l'extension d'assistance vectorielle à l'aide de la commande suivante dans la base de données que vous souhaitez utiliser :

    CREATE EXTENSION vector_assist CASCADE;

    Cela génère le schéma vector_assist, qui est utilisé par l'assistance vectorielle.

Utiliser l'assistant vectoriel pour déployer une charge de travail vectorielle

Pour utiliser l'assistance vectorielle afin de déployer et de gérer une charge de travail vectorielle, vous devez procéder comme suit :

Définir votre spécification de vecteur

La première étape pour utiliser l'assistance vectorielle consiste à définir la spécification vectorielle . Selon le type de charge de travail vectorielle, les champs que vous utilisez pour définir votre spécification vectorielle peuvent être différents.

Par exemple, si vous souhaitez activer la recherche sémantique sur une colonne spécifique d'une table, exécutez la fonction vector_assist.define_spec pour définir votre spécification vectorielle :

SELECT
  recommendation_id,
  REGEXP_REPLACE(query, 'SET hnsw.ef_search TO \d+', 'SET hnsw.ef_search TO') AS query_1,
  recommendation,
  vector_spec_id,
  table_name,
  applied,
  modified
FROM vector_assist.define_spec(
  table_name => 'TABLE_NAME',
  vector_column_name => 'VECTOR_COLUMN_NAME',
  target_recall => TARGET_RECALL,
  tune_vector_index => TUNE_INDEX
);

Remplacez les paramètres suivants :

  • TABLE_NAME : nom de la table que vous souhaitez utiliser dans votre charge de travail vectorielle.

  • (Facultatif) VECTOR_COLUMN_NAME : colonne sur laquelle vous souhaitez effectuer une recherche sémantique. Si votre table ne comporte qu'une seule colonne avec des vecteurs, vector_assist peut la définir automatiquement. S'il existe plusieurs tables avec des vecteurs, vous devez spécifier la colonne à utiliser.

  • (Facultatif) TARGET_RECALL : rappel cible que vous souhaitez que l'assistance vectorielle atteigne. Si cette option est spécifiée, vector_assist teste différentes valeurs ef_search, en comparant le rappel dans les recherches exactes des voisins les plus proches. vector_assist définit ef_search sur la valeur qui fournit le rappel cible le plus proche. La valeur par défaut est 0.95.

  • (Facultatif) TUNE_INDEX : valeur booléenne qui spécifie si l'assistant vectoriel ajuste les index vectoriels de votre charge de travail. La valeur par défaut est false, ce qui signifie que seuls les paramètres liés à la recherche (ef_search) sont réglés. Les paramètres de temps de compilation (m, ef_construction) ne sont pas réglés.

Pour afficher la liste complète de tous les paramètres disponibles pour la spécification vectorielle, consultez Documentation de référence sur les fonctions d'assistance vectorielle.

Après avoir exécuté la requête pour créer votre spécification vectorielle, l'assistance vectorielle génère automatiquement des étapes, appelées recommandations, que vous devez exécuter pour déployer votre charge de travail vectorielle.

Afficher les recommandations de Vector Assist

Pour afficher les recommandations générées par l'assistance vectorielle à l'aide de votre spécification vectorielle, exécutez la fonction vector_assist.get_recommendations :

SELECT vector_assist.get_recommendations(
  spec_id => 'SPEC_ID'
);

Remplacez SPEC_ID par l'ID de la spécification vectorielle pour laquelle vous souhaitez afficher des recommandations. Pour obtenir la liste des spécifications vectorielles disponibles, consultez Lister vos spécifications vectorielles.

vector_assist.get_recommendations renvoie une table appelée vector_assist.RECOMMENDATIONS qui contient toutes les recommandations. Chaque recommandation est stockée dans une table avec le spec_id associé. Chaque recommandation contient généralement les informations suivantes :

  • Requête SQL à exécuter
  • Explication détaillée de la recommandation
  • Autres informations pertinentes expliquant la recommandation

Appliquer les recommandations de l'assistance vectorielle

Vous pouvez appliquer les recommandations générées individuellement ou toutes en même temps.

Pour appliquer une recommandation spécifique, exécutez la fonction vector_assist.apply_recommendation :

SELECT vector_assist.apply_recommendation(
  recommendation_id => 'RECOMMENDATION_ID'
);

Remplacez RECOMMENDATION_ID par l'ID de la recommandation d'assistance vectorielle que vous souhaitez appliquer à partir de la table vector_assist.RECOMMENDATIONS.

Pour appliquer toutes les recommandations en même temps, exécutez la fonction vector_assist.apply_spec avec le paramètre spec_id ou table_name :

SELECT vector_assist.apply_spec(
  spec_id => 'SPEC_ID'
);

Remplacez SPEC_ID par l'ID de la spécification vectorielle que vous souhaitez utiliser.

Vous pouvez également saisir les paramètres schema_name ou column_name. Pour en savoir plus sur tous les paramètres de requête disponibles, consultez la documentation de référence sur les fonctions d'assistance vectorielle.

Une fois que vous avez appliqué les recommandations générées par l'assistance vectorielle, l'index vectoriel est prêt à être utilisé.

Générer des requêtes de recherche

Vous pouvez utiliser l'assistance vectorielle pour créer des requêtes de recherche optimisées pour vos charges de travail vectorielles déployées à l'aide de la spécification vectorielle et de l'index vectoriel généré de la charge de travail. Pour générer une requête de recherche optimisée, exécutez la fonction vector_assist.generate_query :

SELECT vector_assist.generate_query(
  spec_id => 'SPEC_ID',
  search_vector => 'SEARCH_VECTOR',
  top_k => TOP_K,
  target_recall => TARGET_RECALL,
  filter_expressions => ARRAY['FILTER_EXPRESSION']
);

Remplacez les paramètres suivants :

  • SPEC_ID : ID de la spécification que vous souhaitez utiliser.

  • SEARCH_VECTOR : vecteur de votre requête de recherche. Exemple :[1, 2, 3]

  • (Facultatif) TOP_K : nombre de voisins les plus proches à renvoyer. Si aucune valeur n'est spécifiée, la valeur par défaut est 10.

  • (Facultatif) TARGET_RECALL : rappel cible que vous souhaitez que l'assistance vectorielle atteigne. Si cette option est spécifiée, vector_assist teste différentes valeurs ef_search, en comparant le rappel dans les recherches exactes des voisins les plus proches. vector_assist définit ef_search sur la valeur qui fournit le rappel cible le plus proche.

  • (Facultatif) FILTER_EXPRESSION : tous les filtres de la requête de recherche. Par exemple, filtrer en fonction d'autres colonnes.

Pour afficher la liste complète de tous les paramètres disponibles pour générer une requête de recherche, consultez Références des fonctions d'assistance vectorielle.

Le résultat de cette fonction renvoie du texte contenant une requête SQL. Vous pouvez exécuter ou enregistrer cette requête SQL si nécessaire.

Lister vos spécifications vectorielles

Si vous devez lister les spécifications vectorielles existantes d'une table, exécutez la fonction vector_assist.list_specs ou utilisez vector_assist.get_spec pour afficher une spécification vectorielle unique par ID :

SELECT vector_assist.list_specs(
  table_name => 'TABLE_NAME',
  column_name => 'COLUMN_NAME'
);

Remplacez les paramètres suivants :

  • TABLE_NAME : nom de la table que vous avez utilisée pour définir votre spécification vectorielle.

  • (Facultatif) COLUMN_NAME : nom de la colonne vectorielle dans la table. En cas d'omission, vector_assist.list_specs renvoie toutes les spécifications vectorielles définies sur la table spécifiée. Pour récupérer une spécification vectorielle spécifique par ID, appelez SELECT vector_assist.get_spec(spec_id => 'SPEC_ID');.

Étapes suivantes