在 AI/BI Genie 空间中使用受信任资产

重要

此功能目前以公共预览版提供。 请参阅在工作区中启用 Genie 空间。

本文定义了受信任资产，并介绍了如何使用它们在 Genie 空间中提供经过验证的答案。

什么是受信任资产？

受信任资产是预定义的函数和示例查询，旨在为预期用户提出的问题提供经过验证的答案。 当用户提交调用受信任资产的问题时，响应中会指示它，为结果的准确性添加额外保证层。

受信任资产可以包括以下内容：

• 参数化示例 SQL 查询：使用参数化示例 SQL 查询生成响应时，响应会标记为受信任资产。 响应包括查询中用作参数的值。
• 用户定义的表函数 (UDF)：可以定义自定义函数并将其注册到 Unity Catalog。 然后，在 Genie 空间中设置说明时，可将这些函数添加为受信任资产。 请参阅创建 SQL 表函数和 Unity Catalog 中的用户定义函数 (UDF)。

注意

受信任资产不能替代所有其他指令。 Databricks 建议对已确定的重复出现的问题使用受信任资产。 它们对特定问题提供确切答案。

为什么创建受信任资产？

使用任何 AI 工具时，用户都应该评估生成的响应的准确性。 通常，他们通过考虑答案是否有意义并有效地解决其问题来执行此操作。 使用 Genie，响应将以结果表的形式提供。 用户可以查看创建结果集的生成的 SQL，但非技术用户可能没有解释 SQL 语句或评估答案正确性的背景知识。 受信任资产有助于减少这些用户遇到误导性、不正确或难以解释的响应的可能性。

当用户收到标记为受信任资产的响应时，他们可以确信域专家已评审了填充结果的 SQL 语句。

受信任资产和示例 SQL 查询之间之间有什么区别？

受信任资产为预期 Genie 空间用户提出的问题提供经过验证的答案。 当受信任资产可以回答用户的问题时，存储为受信任资产的指令将运行并返回指定的结果集。 指令中包含的所有 SQL 函数都被视为受信任资产。 还可以将包含参数的示例 SQL 查询视为受信任资产。

• SQL 函数：可以编写自定义 SQL 函数来处理数据并解决公司特定的问题。 Genie 在回答问题时不会考虑受信任资产的 SQL 内容。
• 示例 SQL 查询（含参数）：当参数化示例查询的确切文本用于生成响应时，响应会自动标记为受信任资产。 如果未使用查询的确切文本，或者示例查询不使用参数，则查询会提供上下文并指导 Genie 生成 SQL 语句来处理其他问题。

定义受信任资产

定义受信任资产首先要确定一个可能的问题。 例如，假设你正在使用销售管道数据集，销售经理可能会问的一个常见问题是：“我的管道中有哪些开放的销售机会？”

示例：使用 UDF

以下步骤概述了创建受信任资产（作为 UDF）以回答此问题的步骤：

1. 定义并测试回答问题的 SQL 查询。

   此查询联接两个表，并返回“管道”预测类别中列出的开放机会数据集。 在此步骤中，目标是编写返回预期结果的基本查询。

   SELECT
     o.id AS `OppId`,
     a.region__c AS `Region`,
     o.name AS `Opportunity Name`,
     o.forecastcategory AS `Forecast Category`,
     o.stagename,
     o.closedate AS `Close Date`,
     o.amount AS `Opp Amount`
   FROM
   users.user_name.opportunity o
   JOIN catalog.schema.accounts a ON o.accountid = a.id
   WHERE
   o.forecastcategory = 'Pipeline'
   AND o.stagename NOT LIKE '%closed%';
   

2. 定义 Unity Catalog 函数。

   Unity Catalog 函数应对查询进行参数化处理，并生成与预计用户提出的特定条件相匹配的结果。 假设销售经理想要通过关注特定区域或区域组来缩小结果集的范围。

   以下示例定义了一个 Unity Catalog 函数，该函数采用区域列表作为参数并返回表。 函数返回的内容与上一步中的 SQL 语句几乎相同，只是 WHERE 子句已修改为如果提供了区域则按区域筛选结果。 函数定义中提供的注释对于指示 Genie 空间何时以及如何调用此函数至关重要。

   • 参数注释：open_opps_in_region 函数需要一个字符串数组作为参数。 注释包含预期输入的示例。 如果未提供任何参数，则默认值为 NULL。 有关包括可选参数和注释的详细信息，请参阅有关编写函数的提示。
   • 函数注释：SQL 表函数中的注释详细解释了该函数的作用。 这一点至关重要，因为它告知 Genie 何时使用函数来回答用户的问题。 注释应该尽可能准确地描述函数的目的。 此信息指导 Genie 识别该函数与特定问题的相关性。

   
   CREATE
   OR REPLACE FUNCTION users.user_name.open_opps_in_region (
     regions ARRAY < STRING >
     COMMENT 'List of regions.  Example: ["APAC", "EMEA"]' DEFAULT NULL
   ) RETURNS TABLE
   COMMENT 'Addresses questions about the pipeline in the specified regions by returning
    a list of all the open opportunities. If no region is specified, returns all open opportunities.
    Example questions: "What is the pipeline for APAC and EMEA?", "Open opportunities in
    APAC"'
   RETURN
     SELECT
     o.id AS `OppId`,
     a.region__c AS `Region`,
     o.name AS `Opportunity Name`,
     o.forecastcategory AS `Forecast Category`,
     o.stagename,
     o.closedate AS `Close Date`,
     o.amount AS `Opp Amount`
     FROM
     catalog.schema.opportunity o
     JOIN catalog.schema.accounts a ON o.accountid = a.id
     WHERE
     o.forecastcategory = 'Pipeline'
     AND o.stagename NOT LIKE '%closed%'
     AND (
       isnull(open_opps_in_region.regions)
       OR array_contains(open_opps_in_region.regions, region__c)
     );
   

   当你运行代码以创建函数时，它将默认注册到当前处于活动状态的架构。 请参阅 Unity Catalog 中的用户定义函数 (UDF)。 有关语法和示例，请参阅创建 SQL 表函数。

3. 添加受信任资产。

   在 Unity Catalog 中创建函数后，对 Genie 空间具有至少“可编辑”权限的用户可以在 Genie 空间的“说明”选项卡中添加它。

所需的权限

对 Genie 空间具有至少“可编辑”权限的用户可以添加或删除受信任资产。

Genie 空间用户必须对包含该函数的目录和架构具有 CAN USE 权限。 若要调用受信任的资产，他们必须对 Unity Catalog 中的函数具有 EXECUTE 权限。 Unity Catalog 安全对象将从其父容器继承权限。 请参阅 Unity Catalog 中的安全对象。

为了简化 Genie 空间中的共享，Databricks 建议创建一个专用架构，用于包含要在 Genie 空间中使用的所有函数。

有关编写函数的提示

查看以下示例，了解如何为受信任资产创建动态函数。

包含默认参数值

可以为参数指定默认值。 使用函数签名中的 DEFAULT 子句，如以下示例所示：

countries ARRAY<STRING> COMMENT 'List of countries' DEFAULT ARRAY()

包含示例参数值

对于具有一组枚举值的列，请在注释中明确定义它们来提高准确性。 以下示例提供了一个示例值列表：

regions ARRAY < STRING > COMMENT 'List of regions. Values: ["AF","AN","AS", "EU", "NA", "OC", "SA", NULL]'

创建可选参数

若要创建可选参数，请将默认参数设置为 NULL，如以下示例所示：

min_date STRING DEFAULT NULL

使用注释指定格式

可以通过在注释中包含参数来指定其确切格式，如以下示例所示：

min_date STRING COMMENT 'minimum date (included) for a transaction, in `yyyy-mm-dd` format'

明确检查 NULL 值

如果包含可选参数，应得到的一个可能值是 NULL。 由于与 NULL 的比较可能会产生不可预测的结果，因此应在函数中明确构建 NULL 值检查。 以下示例提供了示例语法：

WHERE (isnull(min_date) OR created_date >= min_date)