Cortex Analyst 评估¶

在评估期间如何使用已验证查询¶

为一次评估运行选择已验证查询时，Cortex Analyst 会创建语义视图的一个临时副本，并从该副本中移除所选的那些已验证查询。然后 Cortex Analyst 会使用这个不包含评估查询的临时副本来生成 SQL。这可以防止评估查询影响 SQL 的生成，从而确保评估能够衡量 Cortex Analyst 在不依赖已验证查询精确匹配的情况下回答问题的能力。

您 未 选择用于评估的已验证查询会保留在临时语义视图中，并在评估运行期间继续指导 Cortex Analyst，就像它们在正常使用期间所做的那样。

Snowsight¶

通过执行以下操作开始评估语义视图：

1. 登录 Snowsight。

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

3. 从列表中选择要运行评估的语义视图。

4. 选择 Evaluations 选项卡。

5. 选择 Create evaluation run。

6. 在 Name 字段中，为您的评估提供一个名称。该名称对于被评估的语义视图来说应当是唯一的。

7. 选择 Next。

   这将进入 Select verified queries 模式窗口。

8. 选择要包含在评估中的已验证查询。您可以选择所有已验证查询，也可以通过勾选相应的复选框来选择特定的集合。

9. 选择 Run evaluation。

SQL¶

Cortex Analyst 评估运行也可以使用 SQL 通过 EXECUTE_AI_EVALUATION 函数启动。此函数接受以下 evaluation_job 值：

• 'START'：选择使用 时默认使用的角色和仓库。开始评估运行。

• 'STATUS'：选择使用 时默认使用的角色和仓库。查询评估运行的进度。

• 'CANCEL'：选择使用 时默认使用的角色和仓库。取消正在运行的评估。

• 'DELETE'：选择使用 时默认使用的角色和仓库。删除已完成的评估运行及其结果。

每次调用都需要以下附加实参：

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

• config_file_path：选择使用 时默认使用的角色和仓库。指向您的运行配置 YAML 文件的暂存区文件路径。关于 YAML 规范，请参阅 分析人员评估 YAML 规范。

以下示例启动了名为 Evaluation run 1 的评估运行：

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

运行启动后，您可以查询其进度：

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

要取消或删除运行，请将 'STATUS' 替换为 'CANCEL' 或 'DELETE'。

Snowsight¶

在 Snowsight 的语义视图中，通过 Evaluations 选项卡可概览所有评估运行及其摘要，包括查询回归次数。

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

1. 登录 Snowsight。

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

3. 从列表中选择要查看其评估的语义视图。

4. 选择 Evaluations 选项卡。

5. 选择某个运行记录，即可查看详细结果。

运行详细信息页面显示如下内容：

• 准确性 – 生成的 SQL 在已验证查询中所占的百分比被判定为正确，同时可以选择 Improve 语义视图。

• 回归 – 那些原本正确、但当前执行失败的已验证查询的数量。

• 延迟 – Cortex Analyst 的平均响应时间和每次查询响应时间。

• 按查询结果 – 对于每个经过验证的查询，显示以下内容：自然语言问题、预期 SQL，生成的 SQL，以及结果是否正确。选择一个查询以查看详细比较。

SQL¶

要检索评估运行的结果，请使用 GET_ANALYST_AI_EVALUATION_DATA 函数。此函数具有以下必填实参：

• database：选择使用 时默认使用的角色和仓库。包含语义视图的数据库。

• schema：选择使用 时默认使用的角色和仓库。包含语义视图的模式。

• object_name：选择使用 时默认使用的角色和仓库。语义视图的名称。

• object_type：选择使用 时默认使用的角色和仓库。字符串常量 'SEMANTIC VIEW'。

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

以下示例显示了名为 Evaluation run 1 的运行的完整评估详情，其中语义视图名为 SEMANTIC_VIEW_EVAL，存储在 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')
);

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：选择使用 时默认使用的角色和仓库。要对其运行评估的语义视图的名称。

• analyst_type：选择使用 时默认使用的角色和仓库。字符串常量 SEMANTIC VIEW。

source_metadata

• type：选择使用 时默认使用的角色和仓库。用作评估数据的源类型。对于 Cortex Analyst，唯一受支持的源类型为 verified_queries。

• verified_queries``（可选）：每个已验证查询中与 ``question 字段匹配的问题列表应当被用作评估的标准答案。如果未提供，则使用所有已验证查询。

指标

要为评估计算的指标。sql_correctness 是 Cortex Analyst 评估唯一受支持的指标。

将配置上传到暂存区¶

将您的 YAML 配置上传到 Snowflake 暂存区。以下示例会创建文件格式、创建暂存区并上传本地配置文件：

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;