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

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

什麼是受信任的資產？

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

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

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

3. 新增受信任的資產。

   在 Unity Catalog 中建立函數後，具有 Genie 空間中至少「編輯權限」的使用者可以從 Genie 空間的 說明 索引標籤新增它。

所需的權限

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

Genie 空間用戶必須在包含該函式的目錄和結構上擁有 CAN USE 許可權。 若要調用可信資產，它們必須在 Unity Catalog 中的函式具有 EXECUTE 權限。 Unity 目錄的可保護物件會從其父容器繼承權限。 請參閱 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)