Évaluations Cortex Agent¶

Cortex Code¶

Pour que Cortex Code vous aide à créer un ensemble de données pour votre évaluation, utilisez la sous-compétence dataset-curation de la compétence cortex-agent Cortex Code. Pour plus d’informations sur les compétences de Cortex Code, voir:ref:Code CortexCLI - Compétences <label-extensibility_skills>.

Format de l’ensemble de données¶

La table utilisée pour créer un ensemble de données à des fins d’évaluation dispose d’une colonne de requête d’entrée de type VARCHAR qui représente votre requête, et une colonne de sortie de type VARIANT qui contient une description du comportement attendu de l’agent. Cette colonne de sortie unique est utilisée comme réalité de terrain par le LLM juge.

Les valeurs de la colonne de sortie ont une clé, ground_truth_output. La valeur de cette clé est utilisée pour évaluer l’exactitude des réponses. Les LLM juges utilisent la réalité de terrain pour évaluer la sortie de votre agent en l’incluant dans leur invite.

Pour apporter un ensemble de données JSON dans une table Snowflake, utilisez la fonction /sql-reference/functions/parse_json`SQL. L’exemple suivant crée une nouvelle table``agent_evaluation_data` à utiliser pour un ensemble de données d’évaluation, et insère une ligne pour la requête d’entrée``What was the temperature in San Francisco on August 2nd 2019?`` avec la réalité de terrain de The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019..

CREATE OR REPLACE TABLE agent_evaluation_data (
    input_query VARCHAR
);

INSERT INTO agent_evaluation_data
  SELECT
    'What was the temperature in San Francisco on August 2nd 2019?',
    PARSE_JSON('
      {
        "ground_truth_output": "The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019.",
      }
    ');

Les données que vous fournissez dans la colonne ground_truth qui ne sont pas utilisées par une métrique sélectionnée sont ignorées. Lorsque vous effectuez une exécution d’évaluation avec uniquement des métriques sans référence, vous pouvez laisser la colonne de sortie vide.

Lors de l’exécution de votre première évaluation, vous aurez la possibilité de créer un nouvel ensemble de données à partir d’une table existante.

Cortex Code¶

Pour que Cortex Code exécute une évaluation, utilisez la sous-compétence evaluate-cortex-agent de la compétence Cortex Code cortex-agent. Pour plus d’informations sur les compétences de Cortex Code, voir:ref:Code CortexCLI - Compétences <label-extensibility_skills>.

Snowsight¶

Commencez votre évaluation d’un Cortex Agent en procédant comme suit :

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation, sélectionnez AI & ML » Agents.

3. Sélectionnez l’agent sur lequel vous souhaitez effectuer une évaluation.

4. Sélectionnez l’onglet Evaluations.

5. Sélectionnez New evaluation run.

   La fenêtre modale New evaluation run s’ouvre.

6. Dans le champ Name, indiquez un nom pour votre d’évaluation. Ce nom doit être unique pour l’agent en cours d’évaluation.

7. En option : Dans le champ Description, fournissez des commentaires pour l’évaluation.

8. Sélectionnez Next.

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

9. Sélectionnez l’ensemble de données utilisé pour évaluer votre agent. Vous pouvez choisir entre Existing dataset et Create new dataset.

   Pour utiliser un ensemble de données existant :

   1. Dans la liste Database and schema, sélectionnez la base de données et le schéma contenant votre ensemble de données.

   2. Dans la liste Select dataset, sélectionnez votre ensemble de données.

   Pour créer un nouvel ensemble de données :

   1. Dans la liste Source table - Database and schema, sélectionnez la base de données et le schéma contenant la table que vous souhaitez importer dans un ensemble de données.

   2. Dans la liste Select source table, sélectionnez votre tableau source.

   3. Dans la liste New dataset location - Database and schema, sélectionnez la base de données et le schéma où placer votre nouvel ensemble de données.

   4. Dans le champ Dataset name, saisissez le nom de votre ensemble de données. Ce nom doit être unique parmi les objets de niveau schéma de votre schéma sélectionné.

10. Sélectionnez Next.

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

11. Dans la liste Input query, sélectionnez la colonne de votre ensemble de données qui contient les requêtes d’entrée.

12. Pour chacune des System metrics, activez le bouton bascule pour toute métrique que vous souhaitez inclure dans votre évaluation. Sélectionnez la colonne de votre ensemble de données contenant la réalité de terrain de votre évaluation.

13. (Facultatif) Pour réaliser une évaluation personnalisée, basculez sur Custom metrics.

    1. Sélectionnez la base de données et le schéma contenant la zone de préparation dans laquelle votre configuration d’évaluation personnalisée est stockée.

    2. Sélectionnez la zone de préparation dans laquelle votre configuration d’évaluation personnalisée est stockée.

    3. Sélectionnez le fichier de configuration YAML pour votre évaluation personnalisée.

       Note

       Dans Snowsight, seules les définitions d’évaluation personnalisées sont chargées à partir de votre configuration YAML. Le reste du fichier YAML doit encore être valide. Pour la spécification du YAML de l’évaluation, voir:ref:label-cortex_agent_evaluation_yaml_spec.

    4. Pour chaque métrique personnalisée, activez le bouton bascule si vous souhaitez qu’elle soit incluse dans votre évaluation. Sélectionnez la colonne de votre ensemble de données contenant la réalité de terrain pour cette évaluation.

14. Sélectionnez Create pour créer l’évaluation et démarrer le processus d’évaluation.

À tout moment, vous pouvez sélectionner Cancel pour annuler la création de l’évaluation, ou sélectionnez Prev pour revenir à la fenêtre modale précédente.

SQL¶

Pour démarrer ou récupérer des informations sur une évaluation avec SQL, utilisez la fonction EXECUTE_AI_EVALUATION. Cette fonction a les arguments obligatoires suivants :

• evaluation_job : Une valeur de chaîne de “START” ou “STATUS”.

• 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. Ce chemin ne peut pas être une URL signée. Pour la spécification du YAML de l’évaluation, voir:ref:label-cortex_agent_evaluation_yaml_spec.

Utilisez la valeur evaluation_job “START “ pour démarrer une évaluation. L’exemple suivant démarre une exécution appelée run-1 à l’aide de la configuration d’évaluation de l’agent depuis``@eval_db.eval_schema.metrics/agent_evaluation_config.yaml`` :

CALL EXECUTE_AI_EVALUATION(
  'START',
  OBJECT_CONSTRUCT('run_name', 'run-1'),
  '@eval_db.eval_schema.metrics/agent_evaluation_config.yaml'
);

Après le démarrage d’une exécution, vous pouvez interroger sa progression à l’aide de la valeur evaluation_job “STATUS”. Cet appel renvoie une table au format utilisé pour les AI Exécutions de l’observabilité. L’exemple suivant interroge l’état de l’évaluation de l’agent lancée à partir de l’exemple précédent :

CALL EXECUTE_AI_EVALUATION(
  'STATUS',
  OBJECT_CONSTRUCT('run_name', 'run-1'),
  '@eval_db.eval_schema.metrics/agent_evaluation_config.yaml'
);

Cortex Code¶

Cortex Code propose deux sous-compétences de la compétence cortex-agent. Utilisez la sous-compétence investigate-cortex-agent-evals pour inspecter les évaluations et trouver des problèmes dans votre configuration ou vos données. Utilisez la sous-compétence optimize-cortex-agent pour prendre les résultats des évaluations terminées et améliorer les performances de votre agent.

Snowsight¶

L’onglet Evaluations pour un agent dans Snowsight vous donne une vue d’ensemble de chaque exécution d’évaluation et un résumé de ses résultats.

Pour voir les résultats de l’évaluation dans|sf-web-interface| :

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation, sélectionnez AI & ML » Agents.

3. Sélectionnez l’agent sur lequel vous souhaitez effectuer une évaluation.

4. Sélectionnez l’onglet Evaluations.

SQL¶

Pour récupérer des détails d’évaluation bruts, utilisez la fonction GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL). Cette fonction a les arguments obligatoires suivants :

• database : Base de données contenant l’agent.

• schema : Schéma contenant l’agent.

• agent_name : Nom de l’agent.

• agent_type : La constante de chaîne “CORTEX AGENT”. La valeur est insensible à la casse.

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

Cette fonction renvoie une table de données d’événements décrite dans Format de la table des résultats de l’évaluation . L’exemple suivant affiche les détails d’évaluation complets d’une exécution appelée run-1, où l’agent est nommé``evaluated_agent`` stocké sur le schéma``eval_db.eval_schema`` :

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT',
  'run-1')
);

Traces des requêtes pour un seul enregistrement¶

Pour accéder à un seul enregistrement d’une trace d’évaluation, utilisez la fonction GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL). Cette fonction a les arguments obligatoires suivants :

• database : Base de données contenant l’agent.

• schema : Schéma contenant l’agent.

• agent_name : Nom de l’agent.

• agent_type : La constante de chaîne “CORTEX AGENT”. La valeur est insensible à la casse.

• record_id : L’ID d’enregistrement pour filtrer.

Cette fonction renvoie une table de données d’événements décrite dans Format de la table des résultats de l’évaluation . L’exemple suivant affiche la trace de l’enregistrement 9346efc3-5dd6-4038-9b1a-72ca3d3b768c, où l’agent est nommé``evaluated_agent`` stocké sur le schéma``eval_db.eval_schema`` :

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT',
  '9346efc3-5dd6-4038-9b1a-72ca3d3b768c'
));

Erreurs et avertissements d’évaluation de la requête pour une exécution¶

Pour accéder aux journaux des avertissements et des erreurs qui se sont produits au cours d’une exécution d’évaluation, utilisez la fonction GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL). Cette fonction a les arguments obligatoires suivants :

• database : Base de données contenant l’agent.

• schema : Schéma contenant l’agent.

• agent_name : Nom de l’agent.

• agent_type : La constante de chaîne “CORTEX AGENT”. La valeur est insensible à la casse.

Cette fonction renvoie une table de données d’événements décrite dans Format de la table des résultats de l’évaluation . L’exemple suivant vérifie les erreurs et les avertissements pour une exécution appelée run-1, où l’agent est nommé``evaluated_agent`` stocké sur le schéma``eval_db.eval_schema``:

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_LOGS(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT')
)
  WHERE TRUE
  AND (record:"severity_text"='ERROR' or record:"severity_text"='WARN')
  AND record_attributes:"snow.ai.observability.run.name"='run-1';

Définition de l’ensemble de données¶

La valeur dataset définit un nouvel ensemble de données à partir des données de table existantes, des colonnes de mappage pour la requête d’entrée et de la réalité de terrain. Pour la structure nécessaire à votre colonne ground_truth, voir Format de l’ensemble de données. Les clés de la valeur dataset sont :

• dataset_type : La chaîne constante « CORTEX AGENT ». La valeur est insensible à la casse.

• table_name : Nom complet de la table à utiliser pour le contenu de l’ensemble de données.

• dataset_name : Le nom de l’ensemble de données créé.

• column_mapping : Le mappage de la colonne d’entrée d’évaluation requise``query_text`` et de la colonne de sortie``ground_truth`` aux colonnes de la table à partir de laquelle créer l’ensemble de données.

L’ensemble de données obtenu est stocké dans la même base de données et le même schéma que la table à partir de laquelle il est construit.

L’exemple de définition d’ensemble de données suivant montre un ensemble de données nommé evaluation_input créé à partir de la table evals_db.evals_schema.evaluation_data, en utilisant la user_question en entrée et``expected_outcome`` pour définir la réalité de terrain :

dataset:
 dataset_type: "CORTEX AGENT"
 table_name: "evals_db.evals_schema.evaluation_data"
 dataset_name: "evaluation_input"
 column_mapping:
   query_text: "user_question"
   ground_truth: "expected_outcome"

Configuration d’un agent¶

La valeur evaluation définit la configuration sur laquelle l’agent doit effectuer une évaluation. Les clés de la valeur evaluation sont :

• agent_params : Dictionnaire décrivant l’agent pour lequel l’évaluation doit être effectuée. Cette valeur utilise les clés :

  • agent_name : Le nom de l’agent à évaluer.

  • agent_type : La chaîne constante « CORTEX AGENT ». La valeur est insensible à la casse.

• (Facultatif) run_params : Métadonnées permettant d’identifier cette exécution d’évaluation. Cette valeur utilise les clés :

  • (Facultatif) label : L’étiquette pour cette évaluation.

  • (Facultatif) description : Une description détaillée de l’évaluation.

• source_metadata : Dictionnaire décrivant l’ensemble de données utilisé pour l’évaluation. Cette valeur utilise les clés :

  • type : La constante de chaîne « DATASET ». La valeur est insensible à la casse.

  • dataset_name : le nom de l’ensemble de données à utiliser.

L’exemple de configuration d’agent suivant exécute un agent nommé evaluated_agent avec l’étiquette Basic evaluation, utilisant l’ensemble de données evaluation_input :

evaluation:
 agent_params:
   agent_name: "evaluated_agent"
   agent_type: "CORTEX AGENT"
  run_params:
   label: "Basic evaluation"
  source_metadata:
   type: "DATASET"
   dataset_name: "evaluation_input"

Sélection de métriques¶

La valeur metrics est une séquence de métriques à évaluer, y compris vos propres définitions de métriques personnalisées. Les valeurs acceptées pour les métriques prédéfinies sont les suivantes :

• answer_correctness : Mesurez la correction de la réponse de l’agent par rapport à la sortie de la réalité de terrain.

• logical_consistency : Mesurez la cohérence des instructions de l’agent, de la planification et des appels d’outils. Cette métrique est sans référence et n’utilise pas d’ensemble de données.

metrics:
  # Built-in metrics
  - "answer_correctness"
  - "logical_consistency"
  # Custom metric with prompt
  - name: "relevance"
    score_ranges:
      min_score: [1, 3]
      median_score: [4, 6]
      max_score: [7, 10]
    prompt: |
      Evaluate the relevance of the agent's response to the user's query.
      Rate from 1-10 where:
      1 = Completely irrelevant
      4 = Somewhat irrelevant
      6 = Neutral
      8 = Mostly relevant
      10 = Highly relevant and on-topic

      You can compare the {{output}} with the {{ground_truth}} to help you understand if the contents are relevant or not

      Consider:
      - Does the response address the user's question?
      - Is the information provided appropriate to the context?
      - Are there any tangential or off-topic elements?

Exemple de configuration complet¶

La combinaison de toutes les sections d’exemple précédentes donne une configuration complète de l’évaluation de l’agent :

# Optional: Create dataset before running evaluation
dataset:
  dataset_type: "CORTEX AGENT"
  table_name: "EVALS_DB.EVALS_SCHEMA.EVALUATION_DATA"
  dataset_name: "EVALUATION_INPUT"
  column_mapping:
    query_text: "user_question"
    ground_truth: "expected_outcome"

# Evaluation task configuration
evaluation:
 agent_params:
   agent_name: "evaluated_agent"
   agent_type: "CORTEX AGENT"
  run_params:
   label: "Basic evaluation"
  source_metadata:
   type: "DATASET"
   dataset_name: "EVALUATION_INPUT"

  # Built-in metrics (simple strings)
  - "answer_correctness"
  - "logical_consistency"

  # Custom metric definition
  - name: "relevance"
    score_ranges:
      min_score: [1, 3]
      median_score: [4, 6]
      max_score: [7, 10]
    prompt: |
      Evaluate the relevance of the agent's response to the user's query.
      Rate from 1-10 where:
      1 = Completely irrelevant
      4 = Somewhat irrelevant
      6 = Neutral
      8 = Mostly relevant
      10 = Highly relevant and on-topic

      You can compare the {{output}} with the {{ground_truth}} to help you understand if the contents are relevant or not

      Consider:
      - Does the response address the user's question?
      - Is the information provided appropriate to the context?
      - Are there any tangential or off-topic elements?

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

Les configurations d’évaluation d’agent doivent disposer d’un format de fichier spécifique pour que Snowflake puisse les analyser. L’extrait suivant montre la création du yaml_file_format nécessaire sur le schéma evals_db.evals_schema, puis crée la zone de préparation evaluation_config pour charger une configuration d’agent vers :

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.evaluation_config
  FILE_FORMAT = evals_db.evals_schema.yaml_file_format;

Chargez votre configuration vers une zone de préparation créée via|sf-web-interface| en accédant au menu de navigation, sélectionnez Ingestion`|raa|:ui:`Add Data et sélectionnez Load files into a Stage. Vous pouvez également utiliser la commande SQL:doc:/sql-reference/sql/put pour charger un fichier YAML local. L’exemple suivant illustre la copie du fichier local``/Users/dev/evaluation_config.yaml`` vers la zone de préparation``evals_db.evals_schema.evaluation_config`` :

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

Si vous créez votre YAML dans un espace de travail, vous pouvez le copier de votre espace de travail actif vers une zone de préparation. L’exemple suivant copie le fichier evaluation_config.yaml de votre espace de travail vers la zone de préparation``evals_db.evals_schema.evaluation_config`` :

COPY FILES INTO @evals_db.evals_schema.evaluation_config
  FROM 'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live'
  FILES=('custom_metric_config.yaml');