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

GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL)¶

Retrieves evaluation data for a run for a Cortex Agent or for an External Agent application (see External Agent commands).

Call this function to inspect all recorded traces for an evaluation run. For more information on Cortex Agent evaluations, see Avaliações do Cortex Agent. For AI Observability applications, see Dados de observabilidade.

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

Sintaxe¶

SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA( <database> , <schema> , <agent_name> , <agent_type>, <run_name> )

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: The agent type string. Use CORTEX AGENT for a Cortex Agent or EXTERNAL AGENT for an External Agent object. This value is case-insensitive.
run_name: Nome da execução para a qual recuperar os dados de avaliação completos.

Retornos¶

Uma tabela contendo informações para a avaliação especificada, 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	The ground truth information used to evaluate this record’s Cortex Agent output. This column holds the JSON from your dataset’s ground truth column, serialized as a string. For how `{{ground_truth}}` in custom metrics relates to this value, see the notes under 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 or External Agent	Required on the object identified by `agent_name`. For `EXTERNAL AGENT`, USAGE on the External Agent is sufficient to call this function (MONITOR does not apply).
MONITOR	Cortex Agent	Required on the Cortex Agent identified by `agent_name` when `agent_type` is `CORTEX AGENT`. Does not apply when `agent_type` is `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.

When agent_type is EXTERNAL AGENT, only USAGE on that object is required to call this function. OWNERSHIP on the External Agent is required to modify or remove the object with ALTER EXTERNAL AGENT or DROP EXTERNAL AGENT.

For the full access control permissions required by Cortex Agent evaluations, see Cortex Agent evaluations – Access control requirements. For External Agent objects, see Dados de observabilidade.

Exemplos¶

O exemplo a seguir exibe os detalhes completos da avaliação para uma execução chamada run-1, em que o agente é chamado evaluated_agent e armazenado no esquema eval_db.eval_schema:

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