类别：: 表函数 (Cortex Agent)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

从 Cortex Agent 评估运行中检索单个追踪记录。

当您需要查看完整 Cortex Agent 评估中的某一条记录时，可调用此函数。有关更多信息，请参阅 Cortex Agent 评估。

另请参阅：: EXECUTE_AI_EVALUATION、GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL)、GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL)

语法¶

SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE( <database> , <schema> , <agent_name> , <agent_type> , <record_id> )

实参¶

database: 包含代理的数据库的名称。
schema: 包含代理的架构的名称。
agent_name: 要检索其记录的代理名称。
agent_type: 字符串常量 CORTEX AGENT。此值不区分大小写。
record_id: 要检索的记录标识符。

返回¶

一个包含所请求追踪信息的表，其列定义如下：


列	数据类型	描述
RECORD_ID	VARCHAR	Snowflake 为此评估记录分配的唯一标识符。
INPUT_ID	VARCHAR	Snowflake 为此评估输入分配的唯一标识符。
REQUEST_ID	VARCHAR	Snowflake 为此请求分配的唯一标识符。
TIMESTAMP	TIMESTAMP_TZ	请求发起的时间（以 UTC 为单位）。
DURATION_MS	INT	代理返回响应所花费的时间（以毫秒为单位）。
INPUT	VARCHAR	用作此评估记录输入的查询字符串。
OUTPUT	VARCHAR	Cortex Agent 为此评估记录返回的响应。
ERROR	VARCHAR	请求期间发生的任何错误的相关信息。
GROUND_TRUTH	VARCHAR	用于评估此记录 Cortex Agent 输出的真实基准信息。
METRIC_NAME	VARCHAR	为此记录评估的指标名称。
EVAL_AGG_SCORE	NUMBER	为此记录分配的评估分数。
METRIC_TYPE	VARCHAR	所评估指标的类型。对于内置指标，值为 `system`。对于自定义指标，值为 `custom`。
METRIC_STATUS	VARIANT	一个映射，包含有关此记录的代理 HTTP 响应的信息，包含以下键： `status`：选择使用时默认使用的角色和仓库。响应的 HTTP 状态码。 `message`：选择使用时默认使用的角色和仓库。状态响应中发送的 HTTP 消息。
METRIC_CALLS	ARRAY	一个 VARIANT 值数组，包含有关计算后指标的信息。数组中的每个条目包含该指标的判定标准、指标分数的说明以及元数据。每个条目的键包括： `criteria`：选择使用时默认使用的角色和仓库。LLM 评估器用于判断响应正确性的判定标准。 `explanation`：选择使用时默认使用的角色和仓库。对分数评定原因的解释。 `full_metadata`：选择使用时默认使用的角色和仓库。一个 VARIANT 值，包含有关此指标被 LLM 评估器处理时的元数据与信息。此映射的键包括： `completion_tokens`：选择使用时默认使用的角色和仓库。在此指标评估调用中，LLM 生成的输出令牌数量。 `guard_tokens`：选择使用时默认使用的角色和仓库。在此指标评估调用中，Cortex Guard 消耗的令牌数量。 `normalized_score`：选择使用时默认使用的角色和仓库。原始评估分数规范化至 [0.0, 1.0] 区间，四舍五入保留两位小数。 `original_score`：选择使用时默认使用的角色和仓库。此指标评估为该记录分配的原始分数。 `prompt_tokens`：选择使用时默认使用的角色和仓库。提供给 LLM 评估器的提示词所占用的令牌数量。 `total_tokens`：选择使用时默认使用的角色和仓库。LLM 评估器在此计算过程中使用的令牌总数。
TOTAL_INPUT_TOKENS	INT	用于处理输入查询的令牌总数。
TOTAL_OUTPUT_TOKENS	INT	Cortex Agent 生成的输出令牌总数。
LLM_CALL_COUNT	INT	统计代理或评估器调用任意 LLM 的次数。

访问控制要求¶

用于执行此操作的角色必须至少具有以下权限：


权限	对象	备注
CORTEX_USER	数据库角色
USAGE	Cortex Agent
MONITOR	Cortex Agent

对架构中的对象进行操作至少需要父数据库的一项权限和父架构的一项权限。

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

有关 Cortex Agent 评估所需的完整访问控制权限，请参阅 Cortex Agent 评估 – 访问控制要求。

示例¶

以下示例展示了记录 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'
));