Categorias:: Funções de tabela (Cortex Agents)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Recuperar um único registro de rastreamento de uma execução de avaliação para um Cortex Agent ou para um aplicativo External Agent que armazena rastreamentos em AI_OBSERVABILITY_EVENTS (consulte:doc:/sql-reference/commands-external-agent).

Chame esta função quando quiser inspecionar um único registro de uma avaliação completa. Para obter mais informações, consulte Avaliações do Cortex Agent e Dados de observabilidade.

Consulte também:: EXECUTE_AI_EVALUATION , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL)

Sintaxe¶

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

Argumentos¶

database: Nome do banco de dados que contém o agente.
schema: Nome do esquema que contém o agente.
agent_name: Nome do agente do qual recuperar um registro.
agent_type: A cadeia de caracteres do tipo de agente. Use CORTEX AGENT para um Cortex Agent ou``EXTERNAL AGENT`` para um objeto External Agent. Esse valor não diferencia maiúsculas de minúsculas.
record_id: O identificador do registro a ser recuperado.

Retornos¶

Uma tabela contendo informações para o rastreamento solicitado, com as seguintes colunas:


Coluna	Tipo de dados	Descrição
RECORD_ID	VARCHAR	O identificador exclusivo atribuído pelo Snowflake para este registro de avaliação.
INPUT_ID	VARCHAR	O identificador exclusivo atribuído pelo Snowflake para esta entrada de avaliação.
REQUEST_ID	VARCHAR	O identificador exclusivo atribuído pelo Snowflake para esta solicitação.
TIMESTAMP	TIMESTAMP_TZ	A hora (em UTC) em que a solicitação foi feita.
DURATION_MS	INT	O tempo, em milissegundos, que o agente levou para retornar uma resposta.
INPUT	VARCHAR	A cadeia de caracteres de consulta usada como entrada para este registro de avaliação.
OUTPUT	VARCHAR	A resposta retornada pelo Cortex Agent para este registro de avaliação.
ERROR	VARCHAR	Informações sobre possíveis erros ocorridos durante a solicitação.
GROUND_TRUTH	VARCHAR	As informações de dados de referência usadas para avaliar a saída do Cortex Agent deste registro. Esta coluna contém o JSON da coluna de verdade fundamental do seu conjunto de dados, serializado como cadeia de caracteres. Para saber como `{{ground_truth}}` nas métricas personalizadas está relacionado a esse valor, consulte as notas em Formato da tabela de resultados da avaliação.
METRIC_NAME	VARCHAR	O nome da métrica avaliada para este registro.
EVAL_AGG_SCORE	NUMBER	A pontuação de avaliação atribuída a este registro.
METRIC_TYPE	VARCHAR	O tipo de métrica que está sendo avaliada. Para métricas internas, o valor é `system`. Para métricas personalizadas, o valor é `custom`.
METRIC_STATUS	VARIANT	Um mapa com informações sobre a resposta HTTP do agente para este registro, com as seguintes chaves: `status`: o código de status HTTP da resposta. `message`: a mensagem HTTP enviada na resposta de status.
METRIC_CALLS	ARRAY	Uma matriz de valores VARIANT que contêm informações sobre a métrica computada. Cada entrada da matriz contém os critérios da métrica, uma explicação da pontuação da métrica e os metadados. As chaves de cada entrada são: `criteria`: os critérios utilizados por um juiz de LLM para avaliar a exatidão da resposta. `explanation`: uma explicação do motivo pelo qual a pontuação foi atribuída. `full_metadata`: um valor VARIANT que contém metadados e informações sobre o processamento desta métrica pelo juiz de LLM. As chaves deste mapa incluem: `completion_tokens`: o número de tokens de saída gerados pelo LLM para esta chamada de avaliação de métrica. `normalized_score`: a pontuação de avaliação original normalizada para o intervalo [0,0, 1,0], arredondada para duas casas decimais. `original_score`: a pontuação original atribuída por esta avaliação de métrica para o registro. `prompt_tokens`: o número de tokens consumidos pelo prompt fornecido ao juiz de LLM. `total_tokens`: o número total de tokens usados pelo juiz de LLM para esta computação.
TOTAL_INPUT_TOKENS	INT	O número total de tokens usados para processar a consulta de entrada.
TOTAL_OUTPUT_TOKENS	INT	O número total de tokens de saída produzidos pelo Cortex Agent.
LLM_CALL_COUNT	INT	Conta quantas vezes um LLM foi chamado, seja pelo agente, seja por um juiz de avaliação.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:


Privilégio	Objeto	Notas
CORTEX_USER	Função de banco de dados
USAGE	Cortex Agent ou External Agent	Necessário no objeto identificado por `agent_name`. Para `EXTERNAL AGENT`, USAGE no External Agent é suficiente para chamar esta função (MONITOR não se aplica).
MONITOR	Cortex Agent	Necessário no Cortex Agent identificado por `agent_name` quando `agent_type` é `CORTEX AGENT`. Não se aplica quando `agent_type` é `EXTERNAL AGENT`.

Operar em um objeto em um esquema requer pelo menos um privilégio no banco de dados pai e pelo menos um privilégio no esquema pai.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Quando agent_type é EXTERNAL AGENT, somente USAGE nesse objeto é necessário para chamar esta função. OWNERSHIP no External Agent é necessário para modificar ou remover o objeto com ALTER EXTERNAL AGENT ou DROP EXTERNAL AGENT.

Para obter as permissões de controle de acesso completo exigidas pelas avaliações do Cortex Agent, consulte Avaliações do Cortex Agent – Requisitos de controle de acesso. Para consultar os objetos External Agent, veja Dados de observabilidade.

Exemplos¶

O exemplo a seguir exibe o rastreamento do registro 9346efc3-5dd6-4038-9b1a-72ca3d3b768c, em que o agente é chamado evaluated_agent e armazenado no esquema 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'
));