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

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Recupere um único registro de rastreamento de uma execução de avaliação do Cortex Agent.

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

Consulte também:: EXECUTE_AI_EVALUATION, GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL), GET_AI_OBSERVABILITY_LOGS (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 constante de cadeia de caracteres CORTEX AGENT. O 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 verdade fundamental usadas para avaliar a saída do Cortex Agent deste registro.
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. `guard_tokens`: o número de tokens consumidos pelo Cortex Guard 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
MONITOR	Cortex 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.

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.

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