Cortex Agent 评估¶

Cortex Code¶

要由 Cortex Code 协助您创建评估数据集，请使用 Cortex Code cortex-agent 技能的 dataset-curation 子技能。有关 Cortex Code 技能的更多信息，请参阅 Cortex Code CLI – 技能。

数据集格式¶

用于创建评估数据集的表有一个类型为 VARCHAR 的输入查询列（表示您的查询），以及一个类型为 VARIANT 的输出列（包含对预期代理行为的描述）。该单一输出列被 LLM 评估器用作标准答案。

输出列中的值只有一个键，ground_truth_output。该键的值用于评估答案的正确性。LLM 评估器通过将标准答案纳入其提示中来评估代理的输出。

要将 JSON 数据集导入 Snowflake 表，请使用 PARSE_JSON SQL 函数。以下示例创建一个新表 agent_evaluation_data 用于评估数据集，并为输入查询 What was the temperature in San Francisco on August 2nd 2019? 插入一行，其标准答案为 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.",
      }
    ');

您在 ground_truth 列中提供的、未被所选指标使用的数据将被忽略。当仅使用无参考指标进行评估运行时，您可以将输出列留空。

在运行首次评估时，您将可以选择从现有表创建新数据集。

Cortex Code¶

要由 Cortex Code 运行评估，请使用 Cortex Code cortex-agent 技能的 evaluate-cortex-agent 子技能。有关 Cortex Code 技能的更多信息，请参阅 Cortex Code CLI – 技能。

Snowsight¶

通过执行以下操作开始评估 Cortex Agent：

1. 登录 Snowsight。

2. 在导航菜单中，选择 AI & ML » Agents。

3. 选择要进行评估的代理。

4. 选择 Evaluations 选项卡。

5. 选择 New evaluation run。

   New evaluation run 模式窗口打开。

6. 在 Name 字段中，为您的评估提供一个名称。对于正在评估的代理，此名称应该是唯一的。

7. 可选：在 Description 字段中，为评估提供任意注释。

8. 选择 Next。

   这将进入 Select dataset 模式窗口。

9. 选择用于评估代理的数据集。您可以选择 Existing dataset 或 Create new dataset。

   要使用现有数据集，请执行以下操作：

   1. 在 Database and schema 列表中，选择包含数据集的数据库和架构。

   2. 在 Select dataset 列表中，选择您的数据集。

   要创建新数据集，请执行以下操作：

   1. 在 Source table - Database and schema 列表中，选择包含您要导入到数据集中的表的数据库和架构。

   2. 在 Select source table 列表中，选择源表。

   3. 在 New dataset location - Database and schema 列表中，选择用于放置新数据集的数据库和架构。

   4. 在 Dataset name 字段中，输入数据集名称。此名称在所选架构的架构级对象中必须唯一。

10. 选择 Next。

    这将进入 Select metrics 模式窗口。

11. 在 Input query 列表中，选择包含输入查询的数据集列。

12. 对于每个 System metrics，将您希望在评估中包含的任何指标的开关切换为启用状态。选择数据集中包含评估标准答案的列

13. （可选）要进行自定义评估，请打开 Custom metrics。

    1. 选择包含存储自定义评估配置的暂存区的数据库和架构。

    2. 选择存储自定义评估配置的暂存区。

    3. 选择自定义评估的 YAML 配置文件。

       备注

       在 Snowsight 中，仅从您的 YAML 配置加载自定义评估定义。YAML 文件的其余部分必须仍然有效。有关评估 YAML 规范，请参阅 代理评估 YAML 规范。

    4. 对于每个自定义指标，如果您希望将其包含在评估中，请将开关切换为启用状态。选择数据集中包含本次评估标准答案的列。

14. 选择 Create 以创建评估并开始评估过程。

您随时可以选择 Cancel 来取消创建评估，或选择 Prev 返回上一个模式窗口。

SQL¶

要使用 SQL 启动评估或检索评估信息，请使用 EXECUTE_AI_EVALUATION 函数。此函数具有以下必填实参：

• evaluation_job：选择使用 时默认使用的角色和仓库。“START”或“STATUS”的字符串值

• run_parameters：选择使用 时默认使用的角色和仓库。一个 SQL OBJECT，包含键 run_name，其值为您的运行名称。

• config_file_path: 指向您的运行配置 YAML 文件的暂存区文件路径。此路径不能是已签名 URL。有关评估 YAML 规范，请参阅 代理评估 YAML 规范。

使用 evaluation_job 值“START”开始评估。以下示例使用来自 @eval_db.eval_schema.metrics/agent_evaluation_config.yaml 的代理评估配置启动名为 run-1 的运行：

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

运行启动后，您可以使用 evaluation_job 值“STATUS”查询其进度。此调用返回一个采用 AI 可观测性运行 所用格式的表。以下示例展示如何查询在前一个示例中启动的代理评估的状态。

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

Cortex Code¶

Cortex Code 提供了 cortex-agent 技能的两个子技能。使用 investigate-cortex-agent-evals 子技能检查评估并发现配置或数据中的任何问题。使用 optimize-cortex-agent 子技能从已完成的评估中获取结果并改进您的代理的性能。

Snowsight¶

Snowsight 中代理的 Evaluations 选项卡为您提供每次评估运行及其摘要结果的概览。

要在 Snowsight 中查看评估结果，请执行以下操作：

1. 登录 Snowsight。

2. 在导航菜单中，选择 AI & ML » Agents。

3. 选择要进行评估的代理。

4. 选择 Evaluations 选项卡。

SQL¶

要检索原始评估详细信息，请使用 GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) 函数。此函数具有以下必填实参：

• database：选择使用 时默认使用的角色和仓库。包含代理的数据库。

• schema：选择使用 时默认使用的角色和仓库。包含代理的架构。

• agent_name：选择使用 时默认使用的角色和仓库。代理的名称。

• agent_type：选择使用 时默认使用的角色和仓库。字符串常量“CORTEX AGENT”。此值不区分大小写。

• run_name：选择使用 时默认使用的角色和仓库。要检索的评估运行的名称。

此函数返回 评估结果表格式 中所述的事件数据表。以下示例显示了名为 run-1 的运行的完整评估详情，其中代理名为 evaluated_agent，存储在 eval_db.eval_schema 架构中：

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

单个记录的查询追踪¶

要访问评估跟踪中的单个记录，请使用 GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL) 函数。此函数具有以下必填实参：

• database：选择使用 时默认使用的角色和仓库。包含代理的数据库。

• schema：选择使用 时默认使用的角色和仓库。包含代理的架构。

• agent_name：选择使用 时默认使用的角色和仓库。代理的名称。

• agent_type：选择使用 时默认使用的角色和仓库。字符串常量“CORTEX AGENT”。此值不区分大小写。

• record_id：选择使用 时默认使用的角色和仓库。用于筛选的记录 ID。

此函数返回 评估结果表格式 中所述的事件数据表。以下示例展示了记录 9346efc3-5dd6-4038-9b1a-72ca3d3b768c 的追踪信息，其中代理名为 evaluated_agent，存储于架构 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'
));

查询运行的评估错误和警告¶

要访问评估运行期间发生的警告和错误的日志，请使用 GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) 函数。此函数具有以下必填实参：

• database：选择使用 时默认使用的角色和仓库。包含代理的数据库。

• schema：选择使用 时默认使用的角色和仓库。包含代理的架构。

• agent_name：选择使用 时默认使用的角色和仓库。代理的名称。

• agent_type：选择使用 时默认使用的角色和仓库。字符串常量“CORTEX AGENT”。此值不区分大小写。

此函数返回 评估结果表格式 中所述的事件数据表。以下示例检查名为 run-1 的运行中的错误和警告，其中代理名为 evaluated_agent，存储在架构 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';

数据集定义¶

dataset 值根据现有表数据定义一个新数据集，映射输入查询列和标准答案列。有关 ground_truth 列所需的结构，请参阅 数据集格式。dataset 值的键为：

• dataset_type：选择使用 时默认使用的角色和仓库。字符串常量“CORTEX AGENT”。此值不区分大小写。

• table_name：选择使用 时默认使用的角色和仓库。用于数据集内容的表的完全限定名称。

• dataset_name：选择使用 时默认使用的角色和仓库。创建的数据集的名称。

• column_mapping：选择使用 时默认使用的角色和仓库。将所需的评估输入列 query_text 和输出列 ground_truth 映射到用于创建数据集的表的列。

生成的数据集存储在与构建它所依据的表相同的数据库和架构中。

以下示例数据集定义显示了一个名为 evaluation_input 的数据集，该数据集由 evals_db.evals_schema.evaluation_data 表创建，使用 user_question 作为输入，使用 expected_outcome 定义标准答案：

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 值设置用于进行评估的代理的配置。evaluation 值的键为：

• agent_params：选择使用 时默认使用的角色和仓库。描述要评估的代理的字典。此值使用以下键：

  • agent_name：选择使用 时默认使用的角色和仓库。要评估的代理的名称。

  • agent_type：选择使用 时默认使用的角色和仓库。字符串常量“CORTEX AGENT”。此值不区分大小写。

• （可选）``run_params``：用于标识此评估运行的元数据。此值使用以下键：

  • （可选）``label``：此评估的标签。

  • （可选）``description``：对评估的详细描述。

• source_metadata：选择使用 时默认使用的角色和仓库。描述要评估的代理的字典。此值使用以下键：

  • type：选择使用 时默认使用的角色和仓库。字符串常量“DATASET”。此值不区分大小写。

  • dataset_name：选择使用 时默认使用的角色和仓库。要使用的数据集的名称。

以下示例代理配置运行一个名为 evaluated_agent、标签为 Basic evaluation 的代理，使用数据集 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"

指标选择¶

metrics 值是要评估的指标序列，包括您自己的自定义指标定义。预定义指标的可接受值为：

• answer_correctness：选择使用 时默认使用的角色和仓库。根据标准答案输出衡量代理的响应正确性。

• logical_consistency：选择使用 时默认使用的角色和仓库。衡量代理指令、规划和工具调用之间的一致性。此指标是 无参考的，不使用数据集。

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?

完整示例配置¶

结合前面的所有示例部分，可以得到完整的代理评估配置：

# 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?

将配置上传到暂存区¶

代理评估配置需要具有特定的文件格式，以便 Snowflake 解析它们。以下代码片段演示了在架构 evals_db.evals_schema 上创建所需的 yaml_file_format，然后创建暂存区 evaluation_config 以将代理配置上传至：

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;

通过 Snowsight 将您的配置上传到已创建的暂存区：在导航菜单中，选择 Ingestion » Add Data，然后选择 Load files into a Stage。您还可以使用 SQL PUT 命令上传本地 YAML 文件。以下示例演示如何将本地文件 /Users/dev/evaluation_config.yaml 复制到暂存区 evals_db.evals_schema.evaluation_config：

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

如果您在 工作区 中创建 YAML，则可以将其从活动工作区复制到暂存区。以下示例将文件 evaluation_config.yaml 从您的工作区复制到暂存区 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');