AI/BI Genie スペースで信頼できるアセットを使用する

この記事では、信頼できるアセットを定義し、それらを使用して Genie スペースで検証済みの回答を提供する方法について説明します。

信頼できるアセットとは

信頼できるアセットとは、事前定義された関数やサンプル クエリのことで、ユーザーから予想される質問に対して検証済みの回答を提供するためのものです。 ユーザーが信頼できるアセットを呼び出す質問を送信すると、その質問が応答に示され、結果の正確性がさらに向上します。

信頼できるアセットには、次のものが含まれます。

• パラメーター化されたサンプル SQL クエリ: パラメーター化されたサンプル SQL クエリを使用して応答を生成すると、応答には「信頼できるアセット」というラベルが付けられます。 応答には、クエリの引数として使用される値が含まれます。
• ユーザー定義テーブル関数 (UDF): カスタム関数を定義し、Unity Catalog に登録できます。 その後、Genie スペースで命令を設定するときに、これらの関数を信頼できるアセットとして追加できます。 「SQL テーブル関数の作成」と「Unity Catalog のユーザー定義関数 (UDF) 」を参照してください。

Note

信頼できるアセットは、他のすべての命令に取って代わるものではありません。 Databricks では、定期的に繰り返される質問には信頼できるアセットを使用することをお勧めします。 信頼できるアセットは、特定の質問に対して正確な回答を提供します。

信頼できるアセットを作成する理由

AI ツールを使用する場合、ユーザーは生成された応答の正確性を評価する必要があります。 通常、評価を行うときは、回答が意味を成しているだけでなく、質問に効果的に対処しているかどうかを検討します。 Genie では、応答は結果のテーブルとして配信されます。 ユーザーは、結果セットを作成する生成済み SQL を確認できますが、技術者以外のユーザーには、SQL ステートメントを解釈したり、回答の正確性を評価したりする知識がない可能性があります。 信頼できるアセットは、これらのユーザーが誤解を招く、正しくない、あるいは解釈が困難な応答に遭遇する可能性を減らすのに役立ちます。

ユーザーが「信頼できるアセット」としてラベル付けされた応答を受け取ると、結果にデータを入力する SQL ステートメントをドメインの専門家がレビューしたと確信できます。

信頼できるアセットとサンプル SQL クエリの違い

信頼できるアセットは、Genie スペース ユーザーが尋ねると予想される質問に対して検証済みの回答を提供します。 ユーザーの質問に信頼できるアセットで回答できる場合、信頼できるアセットとして保存した命令が実行され、指定した結果セットが返されます。 命令に含めるすべての SQL 関数は、信頼できるアセットとして扱われます。 パラメーターを含むサンプル SQL クエリも、信頼できるアセットとして扱うことができます。

• SQL 関数: データを処理し、会社固有の質問に対処するように調整されたカスタム SQL 関数を記述できます。 Genie は、質問に応答するときに、信頼できるアセットの SQL コンテンツを考慮しません。
• サンプル SQL クエリ (パラメーター付き): パラメーター化されたサンプル クエリの正確なテキストを使用して応答を生成すると、その応答は「信頼できるアセット」として自動的にラベル付けされます。 クエリの正確なテキストが使用されていない場合、またはサンプル クエリでパラメーターが使用されていない場合、クエリはコンテキストを提供し、Genie が他の質問を処理するための SQL ステートメントを生成する際に役立つ仕組みになっています。

信頼できるアセットを定義する

信頼できるアセットを定義するには、まず、考えられる質問を特定します。 たとえば、営業パイプライン データセットを扱っているとします。営業マネージャーが尋ねる可能性のある一般的な質問として、「パイプライン内の未終了の営業案件は何ですか」が挙げられます。

例: UDF を使用する

以下の手順は、この質問に回答する信頼できるアセットを UDF として作成するための手順を概説しています。

1. その質問に回答する SQL クエリを定義してテストします。

   このクエリは、2 つのテーブルを結合し、"パイプライン" 予測カテゴリに一覧表示されている未終了の営業案件のデータセットを返します。 このステップの目標は、期待される結果を返す基本的なクエリを記述することです。

   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 スペースに対して少なくとも CAN EDIT アクセス許可を持つユーザーは、Genie スペースの [指示] タブで関数を追加できます。

必要なアクセス許可

Genie スペースに対して少なくとも CAN EDIT アクセス許可を持つユーザーは、信頼できるアセットを追加または削除できます。

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 値を明示的にチェックする

オプション パラメーターを含める場合、期待される値の 1 つとして NULL が考えられます。 NULL との比較では予測できない結果が生じる可能性があるため、NULL 値のチェックを関数に明示的に組み込む必要があります。 次の例は、サンプル構文です。

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