Catégories :: Fonctions de table (Cortex Agents)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Récupérez un seul enregistrement de trace d’un cycle d’évaluation pour un Cortex Agent ou pour une application Agent externe qui stocke des traces dans AI_OBSERVABILITY_EVENTS (voir:doc:/sql-reference/commands-external-agent).

Appelez cette fonction lorsque vous souhaitez inspecter un seul enregistrement d’une évaluation complète. Pour plus d’informations, voir Évaluations Cortex Agent et Données d’observabilité.

Voir aussi :: EXECUTE_AI_EVALUATION , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL)

Syntaxe¶

SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE( <database> , <schema> , <agent_name> , <agent_type> , <record_id> )

Arguments¶

database: Nom de la base de données contenant l’agent.
schema: Nom du schéma contenant l’agent.
agent_name: Nom de l’agent pour lequel récupérer un enregistrement.
agent_type: La chaîne du type d’agent. Utilisez CORTEX AGENT pour un Agent Cortex ou EXTERNAL AGENT pour un objet Agent Externe. La valeur est insensible à la casse.
record_id: L’identificateur d’enregistrement à récupérer.

Renvoie¶

Table contenant des informations pour la trace demandée, avec les colonnes suivantes :


Colonne	Type de données	Description
RECORD_ID	VARCHAR	L’identificateur unique attribué par Snowflake pour cet enregistrement d’évaluation.
INPUT_ID	VARCHAR	L’identificateur unique attribué par Snowflake pour cette entrée d’évaluation.
REQUEST_ID	VARCHAR	L’identificateur unique attribué par Snowflake pour cette demande.
TIMESTAMP	TIMESTAMP_TZ	L’heure (en UTC ) à laquelle la requête a été faite.
DURATION_MS	INT	Temps, en millisecondes, nécessaire à l’agent pour renvoyer une réponse.
INPUT	VARCHAR	La chaîne de requête utilisée en entrée pour cet enregistrement d’évaluation.
OUTPUT	VARCHAR	La réponse renvoyée par Cortex Agent pour cet enregistrement d’évaluation.
ERROR	VARCHAR	Informations sur les erreurs éventuelles pouvant survenir lors de la requête.
GROUND_TRUTH	VARCHAR	Les informations de réalité de terrain utilisées pour évaluer la sortie de Cortex Agent de cet enregistrement. Cette colonne contient le JSON de la colonne de réalité de terrain de votre ensemble de données, sérialisé sous forme de chaîne. Pour savoir comment `{{ground_truth}}`, dans les métriques personnalisées, est liée à cette valeur, consultez les remarques sous Format de la table des résultats de l’évaluation.
METRIC_NAME	VARCHAR	Le nom de la métrique évaluée pour cet enregistrement.
EVAL_AGG_SCORE	NUMBER	Score d’évaluation attribué à cet enregistrement.
METRIC_TYPE	VARCHAR	Le type de métrique en cours d’évaluation. Pour les métriques intégrées, la valeur est `system`. Pour les métriques personnalisées, la valeur est `custom`.
METRIC_STATUS	VARIANT	Carte contenant des informations sur la réponse HTTP de l’agent pour cet enregistrement, avec les clés suivantes : `status` : Le code de statut HTTP de la réponse. `message` : Le message HTTP envoyé dans la réponse de statut.
METRIC_CALLS	ARRAY	Un tableau de valeurs VARIANT qui contiennent des informations sur la métrique calculée. Chaque entrée de tableau contient les critères de la métrique, une explication du score de la métrique et des métadonnées. Les clés de chaque entrée sont les suivantes : `criteria` : Les critères utilisés par un LLM juge pour évaluer l’exactitude d’une réponse. `explanation` : Une explication de la raison pour laquelle le score a été attribué. `full_metadata` : Une valeur VARIANT qui contient des métadonnées et des informations sur le traitement de cette métrique par le LLM juge. Les clés de cette carte incluent : `completion_tokens` : Le nombre de jetons de sortie générés par le LLM pour cette appel d’évaluation de métrique. `normalized_score` : Le score d’évaluation original normalisé sur l’intervalle [0,0, 1,0], arrondi à deux décimales. `original_score` : Le score d’origine attribué par cette évaluation de métrique pour l’enregistrement. `prompt_tokens` : Le nombre de jetons consommés par l’invite fournie au LLM juge. `total_tokens` : Le nombre total de jetons utilisés par le LLM juge pour ce calcul.
TOTAL_INPUT_TOKENS	INT	Le nombre total de jetons utilisés pour traiter la requête d’entrée.
TOTAL_OUTPUT_TOKENS	INT	Le nombre total de jetons de sortie produits par Cortex Agent.
LLM_CALL_COUNT	INT	Compte le nombre de fois où un LLM a été appelé, soit par l’agent, soit par un juge d’évaluation.

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :


Privilège	Objet	Remarques
CORTEX_USER	Rôle de la base de données
USAGE	Agent Cortex ou Agent Externe	Requis sur l’objet identifié par `agent_name`. Pour `EXTERNAL AGENT`, USAGE sur l’Agent externe suffit pour appeler cette fonction (MONITOR ne s’applique pas).
MONITOR	Agent Cortex	Requis sur l’Agent Cortex identifié par `agent_name` lorsque `agent_type` est `CORTEX AGENT`. Ne s’applique pas lorsque `agent_type` est `EXTERNAL AGENT`.

Pour effectuer une opération sur un objet dans un schéma, il est nécessaire de disposer d’au moins un privilège sur la base de données parente et d’au moins un privilège sur le schéma parent.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Lorsque agent_type est EXTERNAL AGENT, seul USAGE sur cet objet est nécessaire pour appeler cette fonction. OWNERSHIP sur l’Agent Externe est nécessaire pour modifier ou supprimer l’objet avec ALTER EXTERNAL AGENT ou DROP EXTERNAL AGENT.

Pour connaître les autorisations de contrôle d’accès complètes requises par les évaluations des Agents Cortex, consultez Évaluations des Agents Cortex — Exigences en matière de contrôle d’accès. Pour les objets Agents Externes, consultez Données d’observabilité.

Exemples¶

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'
));