Snowflake AI 可观察性参考¶

本文档为使用 Snowflake Cortex AI 可观察性来评估和监控生成式 AI 应用程序性能提供了全面参考。

本文档涵盖了以下概念：

数据集和属性
评估指标
运行
访问控制和存储

数据集和属性¶

数据集是一组用于测试应用程序的输入。它还可以包含一组预期的输出（基本事实）。

您可以使用 TruLens Python SDK 将数据集指定为 Snowflake 表或 Pandas 数据框 (https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html)。数据集中的每列都必须映射到以下保留属性之一：

保留的属性¶
输入属性	描述
RECORD_ROOT.INPUT	将提示输入到 LLM。类型：字符串
RECORD_ROOT.INPUT_ID	输入提示的唯一标识符。如果您不提供输入 ID，则 ID 会自动生成并分配给每个输入。类型：字符串
RETRIEVAL.QUERY_TEXT	RAG 应用程序的用户查询类型：字符串
RECORD_ROOT.GROUND_TRUTH_OUTPUT	输入提示的预期响应。类型：字符串

要对应用程序进行检测，必须将检测函数（或方法）的输入和输出参数映射到相关的输入和输出属性。使用 @instrument 装饰器映射参数并计算指标。除了作为数据集一部分指定的输入属性外，还可以使用以下输出属性来检测相关函数：

输出属性¶
输出属性	描述
RETRIEVAL.RETRIEVED_CONTEXTS	LLM 生成的输出。类型：列表 [字符串]
RECORD_ROOT.OUTPUT	从 LLM 生成的响应。类型：字符串

评估指标¶

评估指标为衡量应用程序的准确性和性能提供了一种可量化的方法。这些指标是使用应用程序的特定输入、LLM 生成的输出以及任何中间信息（例如，从 RAG 应用程序检索到的结果）进行计算的。您还可以使用实况数据集来计算指标。

您可以使用“LLM-as-a-judge”方法计算指标。通过这种方法，使用 LLM 来根据所提供的信息生成一个分数（介于 0 到 1 之间），并对应用程序输出进行解释。您可以选择 Cortex AI 中可用的任何 LLM 作为裁判。如果未指定 LLM 裁判，则使用 llama3.1-70b 作为默认裁判。AI 可观察性支持各种评估指标。

上下文相关性¶

上下文相关性可确定从检索器或搜索服务检索到的上下文是否与用户查询相关。根据用户查询和检索到的上下文，使用 LLM 裁判根据查询来确定检索到的上下文的相关性。

必要属性：

RETRIEVAL.QUERY_TEXT：RAG 或搜索应用程序中的用户查询
RETRIEVAL.RETRIEVED_CONTEXTS：从搜索服务或检索器中检索到的上下文

锚定性¶

锚定性决定生成的响应是否得到检索器或搜索服务的检索上下文的支持和依据。根据生成的响应和检索到的上下文，使用 LLM 裁判来确定锚定性。底层实现会在生成锚定性分数时使用思维链推理。

必要属性：

RETRIEVAL.RETRIEVED_CONTEXTS：RAG 或搜索应用程序中的用户查询
RECORD_ROOT.OUTPUT：由 LLM 生成的最终响应

答案相关性¶

答案相关性决定生成的响应是否与用户查询相关。根据用户的查询和生成的响应，使用 LLM 裁判来确定回答用户查询时响应的相关性。请注意，这不依赖于真实答案参考，因此这并不等同于评估答案的正确性。

必要属性：

RECORD_ROOT.INPUT：RAG 或搜索应用程序中的用户查询
RECORD_ROOT.OUTPUT：由 LLM 生成的最终响应

正确性¶

正确性决定了生成的响应与真实情况的一致程度。正确性分数越高表示响应越准确，与真实情况的对应度越大。

必要属性：

RECORD_ROOT.INPUT：用户查询或对 LLM 的提示
RECORD_ROOT.GROUND_TRUTH_OUTPUT：基于用户查询的预期响应
RECORD_ROOT.OUTPUT：由 LLM 生成的响应

连贯性¶

连贯性用于衡量模型生成的响应是否具有连贯性，是否不存在逻辑漏洞、不一致之处或矛盾之处。较高的连贯性分数表示的是高度连贯的响应。

必要属性：

RECORD_ROOT.OUTPUT：由 LLM 生成的响应

成本和延迟¶

使用量成本¶

每次调用依赖于 Cortex LLMs 的 LLM，都会根据 COMPLETE (SNOWFLAKE.CORTEX) 函数返回的词元使用量信息（输入的 prompt_tokens 和输出的 completion_tokens）来计算成本。在跟踪信息中，可以查看词元使用量以及与每次 LLM 调用相关的相应成本。

延迟¶

延迟是通过测量完成应用程序中每个函数调用所花费的时间来确定的。应用程序跟踪提供了对使用 TruLens SDK 检测的每个函数延迟的精细可见性。汇总各个函数的延迟，以计算与每个输入对应的整个应用程序的总体延迟。每次运行还提供所有输入的平均延迟，以便在多个应用程序配置之间进行比较。

运行¶

运行是一项评估任务，用于衡量应用程序的准确性和性能。它可以帮助您选择最佳的应用程序配置。构建生成式 AI 应用程序需要尝试各种 LLMs、提示和推理参数。您可以衡量其准确性、延迟和使用情况，以找到最佳的生产组合。每种组合对应一个应用程序版本。

运行使用您指定的数据集对应用程序版本执行批量评估。对于不同的版本，您可以使用相同的数据集触发多次运行。您可以比较各版本之间的汇总差异和记录级别差异，以确定需要进行的改进，并选择最佳版本进行部署。

创建和执行运行包括四个主要步骤：

创建：创建应用程序和版本后，通过指定数据集为版本添加新的运行版本。
调用：开始运行，从数据集中读取输入，为每个输入调用应用程序，生成跟踪，并将信息存储在 Snowflake 账户中。
计算：调用后，通过指定要计算的指标来触发计算。您可以触发多次计算，并稍后为现有运行添加新指标。
可视化：登录 Snowflake 账户，在 Snowsight 中可视化运行结果。在 AI & ML 的相关应用程序内的 Evaluations 下列出运行。

您可以对每次运行进行标记，以便对具有相同数据集的不同应用程序版本之间的可比运行进行分类。使用标签来管理和筛选运行。

运行可能具有以下状态之一：

运行状态¶
状态	描述
CREATED	运行已创建但尚未启动。
INVOCATION_IN_PROGRESS	运行调用正在生成输出和跟踪。
INVOCATION_COMPLETED	运行调用已完成，所有输出和跟踪均已创建。
INVOCATION_PARTIALLY_COMPLETED	由于应用程序调用和跟踪生成出现故障，运行调用已部分完成。
COMPUTATION_IN_PROGRESS	正在进行指标计算。
COMPLETED	指标计算已完成，并附有详细的输出和跟踪。
PARTIALLY_COMPLETED	由于指标计算期间出现故障，运行已部分完成。
CANCELLED	运行已取消。

访问控制和存储¶

所需权限¶

需要以下权限才能使用 AI 可观察性。

要使用 AI 可观察性，您的角色必须具有 CORTEX_USER 数据库角色。CORTEX_USER 角色是数据库函数所必需的。有关授予和撤销此角色的信息，请参阅 Cortex LLM privileges。
要注册应用程序，您的角色必须具有对架构的 CREATE EXTERNAL AGENT 权限。有关更多信息，请参阅应用程序。
要创建和执行运行，您的角色必须：
- 为应用程序创建的外部代理对象的 USAGE 权限。
- 具有对注册应用程序的架构的 CREATE TASK 权限。
- 具有对执行运行应用程序的任务的 EXECUTE TASK 全局权限。
  
  有关更多信息，请参阅运行和可观察性数据。

以下示例使用 ACCOUNTADMIN 角色向用户 some_user 授予以下角色：

CORTEX_USER 数据库角色
app_schema 架构的 CREATE EXTERNAL AGENT 权限
app_schema 架构的 CREATE TASK 权限
EXECUTE TASK 全局权限。

USE ROLE ACCOUNTADMIN;

CREATE ROLE observability_user_role;

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE observability_user_role;

GRANT CREATE EXTERNAL AGENT ON SCHEMA app_schema TO ROLE observability_user_role;

GRANT CREATE TASK ON SCHEMA app_schema TO ROLE observability_user_role;

GRANT EXECUTE TASK ON ACCOUNT TO ROLE observability_user_role;

GRANT ROLE observability_user_role TO USER some_user;

应用程序¶

创建用于评估的应用程序会在 Snowflake 中创建一个外部代理对象来代表该应用程序。您也可以直接使用 SQL 命令来管理外部代理。有关更多信息，请参阅外部代理命令。

重要

外部代理对象与模型对象共享命名空间。您无法创建与同一模式中现有模型同名的外部代理。如果发生名称冲突（例如，通过 log_model() 记录的模型与某个评估对象同名），则必须重命名或删除冲突的对象。

创建和修改应用程序所需的角色必须具有以下访问控制要求。

用于创建应用程序的角色必须具有以下权限：


权限	对象	备注
OWNERSHIP	External Agent	OWNERSHIP 是对象上的特殊权限，会自动授予创建该对象的角色，但也可以通过拥有者角色或任何具有 MANAGE GRANTS 权限的角色，使用 GRANT OWNERSHIP 命令将权限转移给其他角色。
CREATE EXTERNAL AGENT	架构

要对架构中的任何对象执行操作，需要对父数据库和架构具有 USAGE 权限。

需要对外部代理对象的 OWNERSHIP 权限才能修改和删除应用程序。

如果用户的角色对某个应用程序 (外部代理) 拥有 USAGE 或 OWNERSHIP 权限，该应用程序会出现在 Snowsight 中 AI & ML 下的 Evaluations 中。

运行¶

用于对应用程序进行运行任务添加、修改或删除的角色需具备以下权限：


权限	对象	备注
USAGE	External Agent	将外部代理对象的 USAGE 或 OWNERSHIP 权限，授予给那个在 Snowflake 中创建了代表应用的对象的角色。
CREATE TASK	架构	有关创建任务所需权限的信息，请参阅访问控制要求。
EXECUTE TASK	账户	有关执行任务所需的权限的信息，请参阅 EXECUTE TASK。

删除运行会删除与运行相关联的元数据。运行过程中创建的记录不会删除，并会继续存储。有关记录和跟踪存储的更多信息，请参阅“可观察性数据”。

有关创建具有指定权限集的自定义角色的说明，请参阅“创建自定义角色”。有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

重要

无法修改已引入到事件表中的 AI 可观察性数据。有关哪些应用程序角色可以读取或删除 SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS 中的行，请参阅可观察性数据。

LLMs 作为裁判¶

AI 可观察性使用 Cortex LLMs 作为裁判来计算评估应用程序的指标。要成功计算这些指标，需要拥有访问 Cortex LLMs 的权限。要授予用户角色访问 Cortex LLMs 的权限，请参阅“所需权限”。用户必须有权访问配置为 LLM 裁判的模型。用于 LLM 裁判的默认模型是 llama3.1-70b。默认的 LLM 裁判模型将来可能会发生变化。

可观察性数据¶

AI 可观察性数据表示包含生成式 AI 应用程序的输入、输出、评估分数和相关跟踪的记录。所有记录都存储在账户中的 SNOWFLAKE.LOCAL 架构下的专用事件表 AI_OBSERVABILITY_EVENTS 中。

对于 Cortex Agents 以及与 AI Observability 一起使用的外部代理对象，您可以通过 SQL 使用 GET_AI_OBSERVABILITY_EVENTS 表函数来查询可观察性事件。传入 CORTEX AGENT 或 EXTERNAL AGENT 作为代理类型（有关 Cortex Agent 监控示例，请参阅监控 Cortex Agent 请求）。本主题的以下段落介绍了外部应用程序的访问要求。

在通过 Snowsight 中的 Cortex Agent 监控，以及通过应用该逻辑的 ``SNOWFLAKE.LOCAL`` 可观察性 用户定义表函数 读取 AI_OBSERVABILITY_EVENTS 时，可能需要账户级权限 READ UNREDACTED AI OBSERVABILITY EVENTS TABLE 才能查看 未脱敏 的原始字段。它不会改变 Cortex Agent 评估 运行或 外部代理评估 的体验。有关详细信息，请参阅账户权限 READ UNREDACTED AI OBSERVABILITY EVENTS TABLE 和监控 Cortex Agent 请求。

无法修改已引入到事件表中的 AI 可观察性数据。SNOWFLAKE.AI_OBSERVABILITY_READER 应用程序角色授予对 SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS 的只读访问权限。具有 SNOWFLAKE.AI_OBSERVABILITY_ADMIN 应用程序角色的管理员拥有删除 SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS 事件表中数据的专属权限。

可以使用 Trulens Python SDK 或 Snowsight 访问 AI 可观察性数据。要查看应用程序和相关运行的记录，需要具有以下权限：

用户角色必须对代表该应用程序的外部代理对象具有 USAGE 权限。

例如，要查看外部检测的 RAG 应用程序的运行情况，用户角色需要对“my-db.my-schema.rag-application1”具有 USAGE 权限，其中 rag-application1 是在 Snowflake 中代表外部 RAG 应用程序的外部代理对象。

当您针对外部代理(agent_type EXTERNAL AGENT) 调用 SNOWFLAKE.LOCAL 可观察性表函数时，对该对象拥有 USAGE 权限就足够了；MONITOR 权限不适用。要使用 SQL 修改或删除外部代理对象，必须对其拥有 OWNERSHIP 权限。更多信息，请参阅外部代理命令。

与运行和外部代理相关联的元数据（如运行名称、描述、数据集名称等）被归类为元数据。