Évaluations Cortex Analyst¶

Comment les requêtes vérifiées sont utilisées lors de l’évaluation¶

Lorsque vous sélectionnez des requêtes vérifiées pour une exécution d’évaluation, Cortex Analyst crée une copie temporaire de votre vue sémantique avec les requêtes sélectionnées supprimées. Cortex Analyst génère alors du SQL en utilisant cette copie temporaire, qui ne contient pas les requêtes d’évaluation. Cela empêche les requêtes d’évaluation d’influencer la génération SQL, en veillant à ce que l’évaluation mesure la capacité de Cortex Analyst à répondre aux questions sans s’appuyer sur des correspondances exactes provenant de requêtes vérifiées.

Les requêtes vérifiées que vous ne sélectionnez pas pour l’évaluation restent dans la vue sémantique temporaire et continuent de guider Cortex Analyst pendant l’exécution de l’évaluation, exactement comme elles le feraient lors d’une utilisation normale.

Snowsight¶

Commencez votre évaluation d’une vue sémantique en procédant comme suit :

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation, sélectionnez AI & ML > Cortex Analyst.

3. Dans la liste, sélectionnez la vue sémantique sur laquelle vous souhaitez exécuter l’évaluation.

4. Sélectionnez l’onglet Evaluations.

5. Sélectionnez Create evaluation run.

6. Dans le champ Name, indiquez un nom pour votre d’évaluation. Ce nom doit être unique pour la vue sémantique en cours d’évaluation.

7. Sélectionnez Next.

   Cette action vous permet de passer à la fenêtre modale Select verified queries.

8. Sélectionnez les requêtes vérifiées à inclure dans l’évaluation. Vous pouvez soit sélectionner toutes les requêtes vérifiées, soit un ensemble spécifique en cochant les cases correspondantes.

9. Sélectionnez Run evaluation.

SQL¶

Les exécutions d’évaluation Cortex Analyst peuvent également être lancées avec SQL en utilisant la fonction EXECUTE_AI_EVALUATION. Cette fonction accepte les valeurs evaluation_job suivantes :

• 'START' : Démarrez une exécution d’évaluation.

• 'STATUS' : Interrogez la progression d’une exécution d’évaluation.

• 'CANCEL' : Annulez une évaluation en cours.

• 'DELETE' : Supprimez une exécution d’évaluation terminée et ses résultats.

Chaque appel nécessite les arguments supplémentaires suivants :

• run_parameters : Un SQL:ref:OBJECT<label-data_type_object> contenant la clé run_name, avec une valeur du nom de votre exécution.

• config_file_path : Un chemin d’accès au fichier de zone de préparation pointant vers le fichier YAML de configuration de votre exécution. Pour la spécification YAML, consultez Spécification YAML pour l’évaluation des analystes.

L’exemple suivant démarre une exécution d’évaluation appelée``Evaluation run 1`` :

CALL EXECUTE_AI_EVALUATION(
  'START',
  OBJECT_CONSTRUCT('run_name', 'Evaluation run 1'),
  '@EVAL_DB.EVAL_SCHEMA.METRICS/analyst_evaluation_config.yaml'
);

Après le démarrage d’une exécution, vous pouvez interroger sa progression :

CALL EXECUTE_AI_EVALUATION(
  'STATUS',
  OBJECT_CONSTRUCT('run_name', 'Evaluation run 1'),
  '@EVAL_DB.EVAL_SCHEMA.METRICS/analyst_evaluation_config.yaml'
);

Pour annuler ou supprimer une exécution, remplacez 'STATUS' par 'CANCEL' ou 'DELETE'.

Snowsight¶

L’onglet Evaluations pour une vue sémantique dans l’Snowsight donne un aperçu de chaque exécution d’évaluation ainsi qu’un résumé de chacune d’entre elles, y compris le nombre de régressions de requêtes.

Pour voir les résultats de l’évaluation :

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation, sélectionnez AI & ML > Cortex Analyst.

3. Dans la liste, sélectionnez la vue sémantique pour laquelle vous souhaitez voir les évaluations.

4. Sélectionnez l’onglet Evaluations.

5. Sélectionnez une exécution individuelle pour voir des résultats détaillés.

La page de détails de l’exécution montre :

• Précision : le pourcentage de requêtes vérifiées où le SQL généré a été jugé correct, avec une option pour Improve la vue sémantique.

• Régressions : le nombre de requêtes vérifiées qui étaient correctes auparavant, mais qui échouent désormais.

• Latence : les temps de réponse moyens et par requête pour Cortex Analyst.

• Résultats par requête : pour chaque requête vérifiée, la question en langage naturel, le SQL attendu, le SQL généré, et si le résultat était correct ou incorrect. Sélectionnez une requête pour voir la comparaison détaillée.

SQL¶

Pour récupérer les résultats d’une exécution d’évaluation, utilisez la fonction GET_ANALYST_AI_EVALUATION_DATA. Cette fonction a les arguments obligatoires suivants :

• database : La base de données contenant la vue sémantique.

• schema : Le schéma contenant la vue sémantique.

• object_name : Le nom du modèle sémantique.

• object_type : La constante de chaîne 'SEMANTIC VIEW'.

• run_name : Le nom de l’exécution de l’évaluation à récupérer.

L’exemple suivant affiche les détails d’évaluation complets d’une exécution appelée Evaluation run 1, où la vue sémantique est nommée SEMANTIC_VIEW_EVAL, stockée sur le schéma EVAL_DB.EVAL_SCHEMA :

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_ANALYST_AI_EVALUATION_DATA(
  'EVAL_DB',
  'EVAL_SCHEMA',
  'SEMANTIC_VIEW_EVAL',
  'SEMANTIC VIEW',
  'Evaluation run 1')
);

Format YAML¶

evaluation:
  analyst_params:
    analyst_name: "SEMANTIC_VIEW_EVAL"
    analyst_type: "SEMANTIC VIEW"
  source_metadata:
    type: "verified_queries"
    # Optional: list specific verified queries by their question text.
    # If omitted, all verified queries are used.
    verified_queries:
      - "What are our top 10 customers from the last 30 days?"
      - "What is the total revenue by region for Q1 2025?"

metrics:
  - "sql_correctness"

analyst_params

• analyst_name : Le nom de la vue sémantique sur laquelle l’évaluation doit être exécutée.

• analyst_type : La constante de chaîne SEMANTIC VIEW.

source_metadata

• type : Le type de source utilisée comme données d’évaluation. Pour Cortex Analyst, le seul type de source pris en charge est verified_queries.

• verified_queries (facultatif) : remplace la fréquence d’actualisation de mise à jour définie pour toutes les annonces qui utilisent la même base de données. Une liste de questions correspondant au champ question de chaque requête vérifiée qui doit être utilisé comme réalité de terrain pour l’évaluation. Si elles ne sont pas fournies, toutes les requêtes vérifiées sont utilisées.

metrics

Les métriques à calculer pour l’évaluation. sql_correctness est la seule métrique prise en charge pour les évaluations Cortex Analyst.

Chargement d’une configuration vers une zone de préparation¶

Chargez votre configuration YAML dans une zone de préparation Snowflake. L’exemple suivant crée un format de fichier, crée une zone de préparation, et charge un fichier de configuration local :

CREATE OR REPLACE FILE FORMAT evals_db.evals_schema.yaml_file_format
  TYPE = 'CSV'
  FIELD_DELIMITER = NONE
  RECORD_DELIMITER = '\n'
  SKIP_HEADER = 0
  FIELD_OPTIONALLY_ENCLOSED_BY = NONE
  ESCAPE_UNENCLOSED_FIELD = NONE;

CREATE OR REPLACE STAGE evals_db.evals_schema.metrics
  FILE_FORMAT = evals_db.evals_schema.yaml_file_format;

PUT file:///Users/dev/analyst_evaluation_config.yaml @evals_db.evals_schema.metrics
  AUTO_COMPRESS='false'
  OVERWRITE=TRUE;