此页面定义受信任的资产，并说明如何使用它们在 Genie 空间中提供已验证的答案。
什么是受信任资产？
受信任资产是预定义的函数和示例查询，旨在为你预计用户会提出的问题提供经过验证的答案。 当用户提交一个涉及受信任资产的问题时，系统会在响应中标明这一点，为结果的准确性增添一层额外的保障。
受信任资产可以包括以下内容：
- 参数化示例 SQL 查询：使用参数化示例 SQL 查询生成响应时，响应会被标记为受信任资产。 响应包括查询中用作参数的值。 用户可以在响应中编辑参数值。
- 用户定义的表函数 (UDF)：可以定义自定义函数并将其注册到 Unity Catalog。 然后，您可以在 Genie 空间设置说明时，将这些功能添加为受信任的资产。 请参阅创建 SQL 表函数和 Unity Catalog 中的用户定义函数 (UDF)。
注意
受信任的资产不能替代其他指令。 Databricks 建议对已确定的重复问题使用受信任资产。 它们提供特定问题的确切答案。
为什么要创建受信任资产？
使用任何 AI 工具时，用户都应该评估生成的响应的准确性。 通常，他们通过考虑答案是否有意义并有效地解决其问题来执行此操作。 有了 Genie，将以结果表的形式提供响应。 用户可以查看创建结果集的生成的 SQL，但非技术用户可能没有解释 SQL 语句或评估答案正确性的背景知识。 受信任资产有助于减少这些用户遇到误导性、不正确或难以解释的响应的可能性。
当用户收到标记为 “受信任的”的响应时，这意味着域专家已添加用于在空间中生成结果的 SQL 语句。
受信任资产和示例 SQL 查询之间的区别是什么？
受信任资产为你预料 Genie 空间用户会提出的问题提供经过验证的答案。 当受信任的资产可以回答用户的问题时，存储为受信任资产的指令将运行并返回指定的结果集。 包含添加到空间上下文的参数和 SQL 函数 的示例 SQL 查询被视为受信任资产。
- 示例 SQL 查询（含参数）：当参数化示例查询的确切文本用于生成响应时，响应将自动标记为 “受信任”。 空间用户可以在响应中编辑参数值，并使用新值重新运行查询。
- SQL 函数：你可以编写自定义 SQL 函数来处理数据并解决公司特定的问题。 Genie 在回答问题时不会考虑受信任资产的 SQL 内容。
注意
如果未使用查询的确切文本，或者示例查询不使用参数，则示例查询提供生成 SQL 语句的上下文和指南 Genie，但未标记为 “受信任”。
定义受信任资产
定义受信任资产首先要确定一个可能的问题。 例如，假设你正在使用销售管道数据集，而销售经理可能会问的一个常见问题是：“我的区域中有哪些开放式销售机会？
示例：创建 UDF 以回答问题
以下步骤概述了如何编写测试查询并将其用于创建 UDF：
此查询联接两个表，并返回预测类别中列出的 “Pipeline” 开放机会数据集。 在此步骤中，目标是编写返回预期结果的基本查询。
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%';
- 定义 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 表函数。
添加受信任资产。
在 Unity 目录中创建函数后，对 Genie 空间具有至少 CAN EDIT 权限的用户可以将其添加到 Genie 空间。 单击“ 配置>上下文>SQL 查询”。 然后，单击“添加” 。
所需的权限
对 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)