Avaliações do Cortex Agent¶

Cortex Code¶

Para que Cortex Code auxilie você na criação de um conjunto de dados para sua avaliação, use a sub-habilidade dataset-curation da habilidade cortex-agent do Cortex Code. Para obter mais informações sobre habilidades do Cortex Code, consulte Cortex Code CLI – habilidades.

Formato do conjunto de dados¶

A tabela utilizada para criar um conjunto de dados para avaliação tem uma coluna de consulta de entrada do tipo VARCHAR que representa sua consulta e uma coluna de saída do tipo VARIANT que contém uma descrição do comportamento esperado do agente. Essa única coluna de saída é utilizada como os dados de referência pelo avaliador de LLM.

Os valores na coluna de saída têm uma chave, ground_truth_output. O valor dessa chave é utilizado na avaliação da correção da resposta. Os avaliadores de LLM usam os dados de referência para avaliar a saída do seu agente, incluindo-a no prompt.

Para trazer um conjunto de dados JSON para uma tabela Snowflake, use a função PARSE_JSON SQL. O exemplo a seguir cria uma nova tabela agent_evaluation_data para usar como conjunto de dados de avaliação e insere uma linha para a consulta de entrada What was the temperature in San Francisco on August 2nd 2019? com dados de referência de The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019..

CREATE OR REPLACE TABLE agent_evaluation_data (
    input_query VARCHAR
);

INSERT INTO agent_evaluation_data
  SELECT
    'What was the temperature in San Francisco on August 2nd 2019?',
    PARSE_JSON('
      {
        "ground_truth_output": "The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019.",
      }
    ');

Os dados fornecidos na coluna ground_truth que não forem utilizados ​​por uma métrica selecionada serão ignorados. Ao realizar uma avaliação usando apenas métricas sem referência, você pode deixar a coluna de saída vazia.

Ao executar sua primeira avaliação, você terá a opção de criar um novo conjunto de dados a partir de uma tabela existente.

Cortex Code¶

Para que o Cortex Code execute uma avaliação, use a sub-habilidade evaluate-cortex-agent da habilidade cortex-agent do Cortex Code. Para obter mais informações sobre habilidades do Cortex Code, consulte Cortex Code CLI – habilidades.

Snowsight¶

Inicie a avaliação de um Cortex Agent fazendo o seguinte:

1. Faça login no Snowsight.

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

3. Selecione o agente que deseja avaliar.

4. Selecione a guia Evaluations.

5. Selecione New evaluation run.

   O modal New evaluation run ​​será aberto.

6. No campo Name, forneça um nome para sua avaliação. Esse nome deve ser exclusivo para o agente que está sendo avaliado.

7. Opcional: no campo Description, forneça quaisquer comentários para a avaliação.

8. Selecione Next.

   Isso avança para o modal Select dataset.

9. Selecione o conjunto de dados utilizado para avaliar seu agente. Você pode escolher Existing dataset ou Create new dataset.

   Para usar um conjunto de dados existente:

   1. Na lista Database and schema, selecione o banco de dados e o esquema que contêm seu conjunto de dados.

   2. Na lista Select dataset, selecione seu conjunto de dados.

   Para criar um novo conjunto de dados:

   1. Na lista Source table - Database and schema, selecione o banco de dados e o esquema que contêm a tabela que você deseja importar para um conjunto de dados.

   2. Na lista Select source table, selecione sua tabela de origem.

   3. Na lista New dataset location - Database and schema, selecione o banco de dados e o esquema onde deseja inserir seu novo conjunto de dados.

   4. No campo Dataset name, insira o nome do seu conjunto de dados. Esse nome precisa ser exclusivo entre os objetos de nível de esquema no esquema selecionado.

10. Selecione Next.

    Isso avança para o modal Select metrics.

11. Na lista Input query, selecione a coluna do seu conjunto de dados que contém as consultas de entrada.

12. Para cada uma das System metrics, ative a opção para qualquer métrica que você queira incluir na sua avaliação. Selecione a coluna do seu conjunto de dados que contém os valores de referência para sua avaliação.

13. (Opcional) Para realizar uma avaliação personalizada, ative Custom metrics.

    1. Selecione o banco de dados e o esquema que contêm a área de preparação onde sua configuração de avaliação personalizada está armazenada.

    2. Selecione a área de preparação onde sua configuração de avaliação personalizada está armazenada.

    3. Selecione o arquivo de configuração YAML para sua avaliação personalizada.

       Nota

       No Snowsight, somente as definições de avaliação personalizada são carregadas da sua configuração YAML. O restante do arquivo YAML ainda deve ser válido. Para a especificação de avaliação de YAML, consulte Especificação de YAML da avaliação de agentes.

    4. Para cada métrica personalizada, ative a opção se desejar incluí-la na sua avaliação. Selecione a coluna do seu conjunto de dados que contém os valores de referência para essa avaliação.

14. Selecione Create para criar a avaliação e iniciar o processo de avaliação.

A qualquer momento, você pode selecionar Cancel para cancelar a criação da avaliação ou Prev para retornar ao modal anterior.

SQL¶

Para iniciar ou recuperar informações sobre uma avaliação com SQL, use a função EXECUTE_AI_EVALUATION. Essa função tem os seguintes argumentos obrigatórios:

• evaluation_job: um valor de cadeia de caracteres “START” ou “STATUS”.

• 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 de execução. Esse caminho não pode ser um URL assinado. Para a especificação de avaliação de YAML, consulte Especificação de YAML da avaliação de agentes.

Use o valor evaluation_job “START” para iniciar uma avaliação. O exemplo a seguir inicia uma execução chamada run-1 usando a configuração de avaliação do agente de @eval_db.eval_schema.metrics/agent_evaluation_config.yaml:

CALL EXECUTE_AI_EVALUATION(
  'START',
  OBJECT_CONSTRUCT('run_name', 'run-1'),
  '@eval_db.eval_schema.metrics/agent_evaluation_config.yaml'
);

Após o início de uma execução, você pode consultar seu progresso com o valor evaluation_job “STATUS”. Essa chamada retorna uma tabela no formato utilizado para execuções do AI Observability. O exemplo a seguir consulta o status da avaliação do agente iniciada no exemplo anterior:

CALL EXECUTE_AI_EVALUATION(
  'STATUS',
  OBJECT_CONSTRUCT('run_name', 'run-1'),
  '@eval_db.eval_schema.metrics/agent_evaluation_config.yaml'
);

Cortex Code¶

O Cortex Code oferece duas sub-habilidades da habilidade cortex-agent. Use a sub-habilidade investigate-cortex-agent-evals para inspecionar avaliações e encontrar quaisquer problemas em sua configuração ou dados. Use a sub-habilidade optimize-cortex-agent para aproveitar os resultados das avaliações concluídas e melhorar o desempenho do seu agente.

Snowsight¶

A guia Evaluations de um agente no Snowsight fornece uma visão geral de cada execução de avaliação e seus resultados resumidos.

Para visualizar os resultados da avaliação no Snowsight:

1. Faça login no Snowsight.

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

3. Selecione o agente que deseja avaliar.

4. Selecione a guia Evaluations.

SQL¶

Para recuperar detalhes brutos da avaliação, use a função GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL). Essa função tem os seguintes argumentos obrigatórios:

• database: o banco de dados que contém o agente.

• schema: o esquema que contém o agente.

• agent_name: O nome do agente.

• agent_type: a constante de cadeia de caracteres “CORTEX AGENT”. Esse valor não diferencia maiúsculas de minúsculas.

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

Essa função retorna uma tabela de dados de eventos descrita em Formato da tabela de resultados da avaliação. 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')
);

Consultar rastreamentos para um único registro¶

Para acessar um único registro de um rastreamento de avaliação, use a função GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL). Essa função tem os seguintes argumentos obrigatórios:

• database: o banco de dados que contém o agente.

• schema: o esquema que contém o agente.

• agent_name: O nome do agente.

• agent_type: a constante de cadeia de caracteres “CORTEX AGENT”. Esse valor não diferencia maiúsculas de minúsculas.

• record_id: O ID do registro para filtrar.

Essa função retorna uma tabela de dados de eventos descrita em Formato da tabela de resultados da avaliação. 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'
));

Consultar erros e avisos de avaliação para uma execução¶

Para acessar os logs de avisos e erros que ocorreram durante uma execução de avaliação, use a função GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL). Essa função tem os seguintes argumentos obrigatórios:

• database: o banco de dados que contém o agente.

• schema: o esquema que contém o agente.

• agent_name: O nome do agente.

• agent_type: a constante de cadeia de caracteres “CORTEX AGENT”. Esse valor não diferencia maiúsculas de minúsculas.

Essa função retorna uma tabela de dados de eventos descrita em Formato da tabela de resultados da avaliação. O exemplo a seguir verifica erros e avisos 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_OBSERVABILITY_LOGS(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT')
)
  WHERE TRUE
  AND (record:"severity_text"='ERROR' or record:"severity_text"='WARN')
  AND record_attributes:"snow.ai.observability.run.name"='run-1';

Definição do conjunto de dados¶

O valor dataset define um novo conjunto de dados a partir de dados de tabela existentes, mapeando colunas para a consulta de entrada e dados de referência. Para obter a estrutura necessária para sua coluna ground_truth, consulte Formato do conjunto de dados. As chaves para o valor dataset são:

• dataset_type: a constante de cadeia de caracteres «CORTEX AGENT». Esse valor não diferencia maiúsculas de minúsculas.

• table_name: o nome totalmente qualificado da tabela a ser utilizada para o conteúdo do conjunto de dados.

• dataset_name: o nome do conjunto de dados criado.

• column_mapping: o mapeamento da coluna de entrada de avaliação necessária query_text e da coluna de saída ground_truth para as colunas da tabela a partir da qual o conjunto de dados será criado.

O conjunto de dados resultante é armazenado no mesmo banco de dados e esquema da tabela a partir da qual foi construído.

A seguinte definição de conjunto de dados de exemplo mostra um conjunto de dados chamado evaluation_input criado a partir da tabela evals_db.evals_schema.evaluation_data, usando user_question como entrada e expected_outcome para definir dados de referência:

dataset:
 dataset_type: "CORTEX AGENT"
 table_name: "evals_db.evals_schema.evaluation_data"
 dataset_name: "evaluation_input"
 column_mapping:
   query_text: "user_question"
   ground_truth: "expected_outcome"

Configuração do agente¶

O valor evaluation define a configuração para o agente realizar uma avaliação. As chaves para o valor evaluation são:

• agent_params: um dicionário descrevendo o agente para realizar a avaliação. Esse valor usa as chaves:

  • agent_name: o nome do agente a ser avaliado.

  • agent_type: a constante de cadeia de caracteres «CORTEX AGENT». Esse valor não diferencia maiúsculas de minúsculas.

• (Opcional) run_params: metadados para identificar essa execução de avaliação. Esse valor usa as chaves:

  • (Opcional) label: o rótulo para essa avaliação.

  • (Opcional) description: uma descrição detalhada da avaliação.

• source_metadata: um dicionário que descreve o conjunto de dados utilizado para a avaliação. Esse valor usa as chaves:

  • type: a constante de cadeia de caracteres «DATASET». Esse valor não diferencia maiúsculas de minúsculas.

  • dataset_name: o nome do conjunto de dados a ser utilizado.

O exemplo de configuração de agente a seguir executa um agente chamado evaluated_agent com o rótulo Basic evaluation, usando o conjunto de dados evaluation_input:

evaluation:
 agent_params:
   agent_name: "evaluated_agent"
   agent_type: "CORTEX AGENT"
  run_params:
   label: "Basic evaluation"
  source_metadata:
   type: "DATASET"
   dataset_name: "evaluation_input"

Seleção de métricas¶

O valor metrics é uma sequência de métricas a serem avaliadas, incluindo suas próprias definições de métricas personalizadas. Os valores aceitos para métricas predefinidas são:

• answer_correctness: avalie a exatidão da resposta do agente em relação a uma saída de referência.

• logical_consistency: Avalie a consistência entre instruções do agente, planejamento e chamadas de ferramentas. Essa métrica não depende de referência e não usa um conjunto de dados.

metrics:
  # Built-in metrics
  - "answer_correctness"
  - "logical_consistency"
  # Custom metric with prompt
  - name: "relevance"
    score_ranges:
      min_score: [1, 3]
      median_score: [4, 6]
      max_score: [7, 10]
    prompt: |
      Evaluate the relevance of the agent's response to the user's query.
      Rate from 1-10 where:
      1 = Completely irrelevant
      4 = Somewhat irrelevant
      6 = Neutral
      8 = Mostly relevant
      10 = Highly relevant and on-topic

      You can compare the {{output}} with the {{ground_truth}} to help you understand if the contents are relevant or not

      Consider:
      - Does the response address the user's question?
      - Is the information provided appropriate to the context?
      - Are there any tangential or off-topic elements?

Exemplo de configuração completa¶

A combinação de todas as seções de exemplo anteriores resulta em uma configuração completa de avaliação do agente:

# Optional: Create dataset before running evaluation
dataset:
  dataset_type: "CORTEX AGENT"
  table_name: "EVALS_DB.EVALS_SCHEMA.EVALUATION_DATA"
  dataset_name: "EVALUATION_INPUT"
  column_mapping:
    query_text: "user_question"
    ground_truth: "expected_outcome"

# Evaluation task configuration
evaluation:
 agent_params:
   agent_name: "evaluated_agent"
   agent_type: "CORTEX AGENT"
  run_params:
   label: "Basic evaluation"
  source_metadata:
   type: "DATASET"
   dataset_name: "EVALUATION_INPUT"

  # Built-in metrics (simple strings)
  - "answer_correctness"
  - "logical_consistency"

  # Custom metric definition
  - name: "relevance"
    score_ranges:
      min_score: [1, 3]
      median_score: [4, 6]
      max_score: [7, 10]
    prompt: |
      Evaluate the relevance of the agent's response to the user's query.
      Rate from 1-10 where:
      1 = Completely irrelevant
      4 = Somewhat irrelevant
      6 = Neutral
      8 = Mostly relevant
      10 = Highly relevant and on-topic

      You can compare the {{output}} with the {{ground_truth}} to help you understand if the contents are relevant or not

      Consider:
      - Does the response address the user's question?
      - Is the information provided appropriate to the context?
      - Are there any tangential or off-topic elements?

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

As configurações de avaliação do agente precisam ter um formato de arquivo específico para que o Snowflake as analise. O snippet a seguir demonstra a criação do yaml_file_format necessário no esquema evals_db.evals_schema e, em seguida, cria a área de preparação evaluation_config para carregar uma configuração de agente:

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

Carregue sua configuração para uma área de preparação criada por meio do Snowsight indo até o menu de navegação, selecionando Ingestion » Add Data e depois Load files into a Stage. Você também pode usar o comando SQL PUT para carregar um arquivo YAML local. O exemplo a seguir demonstra a cópia do arquivo local /Users/dev/evaluation_config.yaml para a área de preparação evals_db.evals_schema.evaluation_config:

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

Se você criar seu YAML em um espaço de trabalho, poderá copiá-lo do seu espaço de trabalho ativo para uma área de preparação. O exemplo a seguir copia o arquivo evaluation_config.yaml do seu espaço de trabalho para a área de preparação evals_db.evals_schema.evaluation_config:

COPY FILES INTO @evals_db.evals_schema.evaluation_config
  FROM 'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live'
  FILES=('custom_metric_config.yaml');