Avaliações do Cortex Analyst¶

Como as consultas verificadas são usadas durante a avaliação¶

Quando você seleciona consultas verificadas para execução de uma avaliação, o Cortex Analyst cria uma cópia temporária da sua exibição semântica sem as consultas selecionadas. Em seguida, o Cortex Analyst gera o SQL usando essa cópia temporária, que não contém as consultas de avaliação. Isso impede que as consultas de avaliação influenciem a geração de SQL, garantindo que a avaliação meça o quanto o Cortex Analyst pode responder corretamente às perguntas sem usar as correspondências exatas das consultas verificadas.

As consultas verificadas que você não seleciona para avaliação permanecem na exibição semântica temporária e continuam a orientar o Cortex Analyst durante a execução de avaliação, assim como fazem durante o uso normal.

Snowsight¶

Inicie a avaliação de uma exibição semântica fazendo o seguinte:

1. Faça login no Snowsight.

2. No menu de navegação, selecione AI & ML » Cortex Analyst.

3. Na lista, selecione a exibição semântica na qual deseja executar a avaliação.

4. Selecione a guia Evaluations.

5. Selecione Create evaluation run.

6. No campo Name, forneça um nome para sua avaliação. O nome deve ser exclusivo para a exibição semântica que está sendo avaliada.

7. Selecione Next.

   Isso avança para o modal Select verified queries.

8. Selecione quais consultas verificadas devem ser incluídas na avaliação. Você pode selecionar todas as consultas verificadas ou um conjunto específico marcando as caixas correspondentes.

9. Selecione Run evaluation.

SQL¶

As execuções de avaliação do Cortex Analyst também podem ser iniciadas com SQL usando a função EXECUTE_AI_EVALUATION. Essa função aceita os seguintes valores evaluation_job:

• 'START': iniciar a execução de uma avaliação.

• 'STATUS': consultar o progresso da execução de uma avaliação.

• 'CANCEL': cancelar uma avaliação em andamento.

• 'DELETE': excluir uma execução de avaliação concluída e seus resultados.

Cada chamada requer os seguintes argumentos adicionais:

• run_parameters: um SQL OBJECT contendo a chave run_name, com o valor do nome da sua execução.

• config_file_path: um caminho de arquivo de área de preparação apontando para o seu arquivo YAML de configuração da execução. Para a especificação YAML, consulte Especificação YAML da avaliação do analista.

O exemplo a seguir inicia a execução de uma avaliação chamada Evaluation run 1:

CALL EXECUTE_AI_EVALUATION(
  'START',
  OBJECT_CONSTRUCT('run_name', 'Evaluation run 1'),
  '@EVAL_DB.EVAL_SCHEMA.METRICS/analyst_evaluation_config.yaml'
);

Após o início da execução, você poderá consultar o progresso:

CALL EXECUTE_AI_EVALUATION(
  'STATUS',
  OBJECT_CONSTRUCT('run_name', 'Evaluation run 1'),
  '@EVAL_DB.EVAL_SCHEMA.METRICS/analyst_evaluation_config.yaml'
);

Para cancelar ou excluir uma execução, substitua 'STATUS' por 'CANCEL' ou 'DELETE'.

Snowsight¶

A guia Evaluations para uma exibição semântica no Snowsight apresenta uma visão geral e um resumo de cada execução de avaliação, incluindo o número de regressões de consulta.

Para visualizar os resultados da avaliação:

1. Faça login no Snowsight.

2. No menu de navegação, selecione AI & ML » Cortex Analyst.

3. Na lista, selecione a exibição semântica com as avaliações que você deseja visualizar.

4. Selecione a guia Evaluations.

5. Selecione uma execução individual para ver os resultados detalhados.

A página de detalhes da execução mostra:

• Precisão: a porcentagem de consultas verificadas em que o SQL gerado foi considerado correto, com uma opção para Improve a exibição semântica.

• Regressões: o número de consultas verificadas que antes estavam corretas, mas agora estão falhando.

• Latência: tempo de resposta médio e por consulta do Cortex Analyst.

• Resultados por consulta: para cada consulta verificada: a pergunta em linguagem natural, o SQL esperado, o SQL gerado e se o resultado estava correto ou incorreto. Selecione uma consulta para ver a comparação detalhada.

SQL¶

Para recuperar os resultados de uma execução de avaliação, use a função GET_ANALYST_AI_EVALUATION_DATA. Essa função tem os seguintes argumentos obrigatórios:

• database: o banco de dados que contém a exibição semântica.

• schema: o esquema que contém a exibição semântica.

• object_name: o nome da exibição semântica.

• object_type: A constante de cadeia de caracteres 'SEMANTIC VIEW'.

• run_name: o nome da execução da avaliação a ser recuperada.

O exemplo a seguir exibe os detalhes completos da avaliação para uma execução chamada Evaluation run 1, em que o nome da exibição semântica é SEMANTIC_VIEW_EVAL, armazenada no esquema EVAL_DB.EVAL_SCHEMA:

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_ANALYST_AI_EVALUATION_DATA(
  'EVAL_DB',
  'EVAL_SCHEMA',
  'SEMANTIC_VIEW_EVAL',
  'SEMANTIC VIEW',
  'Evaluation run 1')
);

Formato YAML¶

evaluation:
  analyst_params:
    analyst_name: "SEMANTIC_VIEW_EVAL"
    analyst_type: "SEMANTIC VIEW"
  source_metadata:
    type: "verified_queries"
    # Optional: list specific verified queries by their question text.
    # If omitted, all verified queries are used.
    verified_queries:
      - "What are our top 10 customers from the last 30 days?"
      - "What is the total revenue by region for Q1 2025?"

metrics:
  - "sql_correctness"

analyst_params

• analyst_name: o nome da exibição semântica da qual executar a avaliação.

• analyst_type: A constante de cadeia de caracteres SEMANTIC VIEW.

source_metadata

• type: o tipo de fonte usado como os dados de avaliação. Para o Cortex Analyst, o único tipo de fonte compatível é verified_queries.

• verified_queries (opcional): uma lista de perguntas que correspondem ao campo question de cada consulta verificada que deve ser usada como verdade fundamental (ground truth) para a avaliação. Se não for fornecida, todas as consultas verificadas serão usadas.

metrics

As métricas a serem calculadas na avaliação. sql_correctness é a única métrica compatível com as avaliações do Cortex Analyst.

Carregar configuração para uma área de preparação¶

Carregue a configuração YAML em uma área de preparação do Snowflake. O exemplo a seguir cria um formato de arquivo, cria uma área de preparação e carrega um arquivo de configuração local:

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

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