在 AI/BI Genie 空間中使用受信任的資產

重要

這項功能處於公開預覽狀態。 請參閱在工作區啟用 Genie 空間。

本文會定義受信任的資產，並說明如何使用，以便在 Genie 空間中提供已驗證的答案。

什麼是受信任的資產？

受信任的資產是預先定義的函式和範例查詢，旨在針對您預期使用者會提出的問題，提供經過驗證的解答。 當使用者提交叫用受信任資產的問題時，會在回覆中指出，為結果的正確性新增額外的保證層。

受信任的資產可以包含下列項目：

• 參數化範例 SQL 查詢：當參數化範例 SQL 查詢用來產生回覆時，回覆會標示為受信任的資產。 回覆包含用來作為查詢中引數的值。
• 使用者定義資料表函式 (UDF)：您可以定義自訂函式，並將其註冊至 Unity 目錄。 然後，當您在 Genie 空間中設定指示時，可將這些函式新增為受信任的資產。 請參閱建立 SQL 資料表函式和 Unity 目錄中的使用者定義函式 (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 目錄函式。

   您的 Unity 目錄函式應參數化查詢，並產生符合您預期使用者會詢問的特定條件的結果。 假設銷售經理想要將焦點放在特定區域或區域群組，以便縮小結果集的範圍。

   下列範例會定義 Unity 目錄函式，此函式會接受區域清單作為參數，並傳回資料表。 函式傳回與上一個步驟中的 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 目錄中的使用者定義函式 (UDF)。 如需語法和範例，請參閱建立 SQL 資料表函式。

3. 新增受信任的資產。

   在 Unity 目錄中建立函式之後，具有 Genie 空間至少 CAN EDIT 權限的使用者可以從 Genie 空間的 [指示] 索引標籤新增。

所需的權限

具有 Genie 空間至少 CAN EDIT 權限的使用者可以新增或移除受信任的資產。

Genie 空間使用者必須具有包含函式之目錄和結構描述的 CAN USE 權限。 若要叫用受信任的資產，必須具有 Unity 目錄中函式的 EXECUTE 權限。 Unity 目錄安全性實體物件會從其父容器繼承權限。 請參閱 Unity 目錄中的安全性實體物件。

為了簡化 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)