Menggunakan aset tepercaya di ruang AI/BI Genie

Artikel ini mendefinisikan aset tepercaya dan menjelaskan cara menggunakannya untuk memberikan jawaban terverifikasi dalam ruang Genie.

Apa itu aset tepercaya?

Aset tepercaya adalah fungsi yang telah ditentukan sebelumnya dan contoh kueri yang dimaksudkan untuk memberikan jawaban terverifikasi atas pertanyaan yang Anda antisipasi dari pengguna. Ketika pengguna mengirimkan pertanyaan yang memanggil aset tepercaya, itu ditunjukkan dalam respons, menambahkan lapisan jaminan tambahan ke akurasi hasil.

Aset tepercaya dapat mencakup yang berikut ini:

• Kueri SQL contoh berparameter: Saat contoh parameter kueri SQL digunakan untuk menghasilkan respons, respons diberi label aset tepercaya. Respons menyertakan nilai yang digunakan sebagai argumen dalam kueri.
• fungsi tabel yang ditentukan pengguna (UDF): Anda dapat menentukan fungsi kustom dan mendaftarkannya dengan Unity Catalog. Kemudian, Anda dapat menambahkan fungsi tersebut sebagai aset tepercaya saat menyiapkan instruksi di ruang Genie Anda. Lihat Membuat fungsi tabel SQL dan Fungsi yang didefinisikan pengguna (UDF) di Unity Catalog.

Mengapa membuat aset tepercaya?

Saat menggunakan alat AI apa pun, pengguna harus mengevaluasi akurasi respons yang dihasilkan. Biasanya, mereka melakukan ini dengan mempertimbangkan apakah jawabannya masuk akal dan secara efektif mengatasi pertanyaan mereka. Dengan Genie, respons dikirimkan sebagai tabel hasil. Pengguna dapat meninjau SQL yang dihasilkan yang membuat kumpulan hasil, tetapi pengguna non-teknis mungkin tidak memiliki latar belakang untuk menginterpretasikan pernyataan SQL atau menilai kebenaran jawaban. Aset tepercaya membantu mengurangi kemungkinan pengguna ini mengalami respons yang menyesatkan, salah, atau sulit ditafsirkan.

Saat pengguna menerima respons yang diberi label sebagai aset tepercaya, mereka dapat yakin bahwa pakar domain telah meninjau pernyataan SQL yang mengisi hasilnya.

Apa perbedaan antara aset tepercaya dan contoh kueri SQL?

Aset tepercaya memberikan jawaban terverifikasi atas pertanyaan yang Anda harapkan untuk diajukan oleh pengguna ruang Genie. Saat aset tepercaya dapat menjawab pertanyaan pengguna, instruksi yang telah Anda simpan sebagai aset tepercaya berjalan dan mengembalikan tataan hasil yang ditentukan. Semua Fungsi SQL yang Anda sertakan dalam instruksi diperlakukan sebagai aset tepercaya. Contoh Kueri SQL yang menyertakan parameter juga dapat diperlakukan sebagai aset tepercaya.

• Fungsi SQL: Anda dapat menulis fungsi SQL kustom yang disesuaikan untuk menangani data Anda dan menjawab pertanyaan khusus perusahaan. Genie tidak mempertimbangkan konten SQL aset tepercaya Anda saat menanggapi pertanyaan.
• Contoh Kueri SQL (dengan parameter): Saat contoh parameter teks tepat kueri digunakan untuk menghasilkan respons, respons secara otomatis diberi label sebagai aset tepercaya. Jika teks kueri yang tepat tidak digunakan, atau kueri contoh tidak menggunakan parameter, kueri menyediakan konteks dan panduan Genie dalam menghasilkan pernyataan SQL untuk memproses pertanyaan lain.

Menentukan aset tepercaya

Menentukan aset tepercaya dimulai dengan mengidentifikasi kemungkinan pertanyaan. Misalnya, Anda bekerja dengan himpunan data alur penjualan, dan pertanyaan umum yang mungkin ditanyakan manajer penjualan adalah, "Apa peluang penjualan terbuka di alur saya?"

Contoh: Menggunakan UDF

Langkah-langkah berikut menguraikan langkah-langkah untuk membuat aset tepercaya, sebagai UDF, yang menjawab pertanyaan ini:

1. Tentukan dan uji kueri SQL yang menjawab pertanyaan.

   Kueri ini menggabungkan dua tabel dan mengembalikan kumpulan data peluang terbuka yang terdaftar dalam kategori prakiraan "Pipeline". Dalam langkah ini, tujuannya adalah menulis kueri dasar yang mengembalikan hasil yang diharapkan.

   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. Tentukan fungsi Unity Catalog.

   Fungsi Katalog Unity Anda harus membuat parameter kueri dan menghasilkan hasil yang cocok dengan kondisi tertentu yang Anda harapkan untuk ditanyakan pengguna. Misalkan manajer penjualan ingin mempersempit hasil yang ditetapkan dengan berfokus pada wilayah atau grup wilayah tertentu.

   Contoh berikut mendefinisikan fungsi Katalog Unity yang mengambil daftar wilayah sebagai parameter dan mengembalikan tabel. Pengembalian fungsi hampir identik dengan pernyataan SQL di langkah sebelumnya, kecuali WHERE klausul telah dimodifikasi untuk memfilter hasil menurut wilayah jika suatu wilayah telah disediakan. Komentar yang diberikan dalam definisi fungsi sangat penting untuk menginstruksikan ruang Genie tentang kapan dan cara memanggil fungsi ini.

   • Komentar parameter: Fungsi open_opps_in_region mengharapkan array string sebagai parameter. Komentar menyertakan contoh input yang diharapkan. Jika tidak ada parameter yang disediakan, nilai defaultnya adalah NULL. Lihat Tips untuk menulis fungsi untuk informasi selengkapnya tentang menyertakan parameter dan komentar opsional.
   • Komentar fungsi: Komentar dalam fungsi tabel SQL memberikan penjelasan terperinci tentang apa yang dilakukan fungsi. Ini penting karena menginformasikan Genie kapan harus menggunakan fungsi sebagai respons terhadap pertanyaan pengguna. Komentar harus menjelaskan tujuan fungsi sesering mungkin. Informasi ini memandu Genie dalam mengenali relevansi fungsi dengan pertanyaan tertentu.

   
   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)
     );
   

   Saat Anda menjalankan kode untuk membuat fungsi, kode tersebut didaftarkan ke skema yang saat ini aktif secara default. Lihat Fungsi Buatan Pengguna (UDF) di Unity Catalog. Lihat Membuat fungsi tabel SQL untuk sintaks dan contoh.

3. Tambahkan aset tepercaya.

   Setelah fungsi dibuat di Unity Catalog, pengguna yang memiliki izin minimal DAPAT MENGEDIT pada ruang Genie bisa menambahkannya melalui tab Instruksi ruang Genie.

Izin yang diperlukan

Pengguna yang setidaknya memiliki izin Dapat Mengedit pada ruang Genie dapat menambahkan atau menghapus aset tepercaya.

Pengguna Genie space harus memiliki izin CAN USE pada katalog dan skema yang berisi fungsi. Untuk memanggil aset tepercaya, mereka harus memiliki izin EXECUTE pada fungsi di Katalog Unity. Objek yang diamankan dalam Katalog Unity mewarisi izin dari kontainer induknya. Lihat Objek yang Dapat Diamankan di Unity Catalog.

Untuk menyederhanakan berbagi di ruang Genie, Databricks merekomendasikan pembuatan skema khusus untuk berisi semua fungsi yang ingin Anda gunakan di ruang Genie Anda.

Tips untuk menulis fungsi

Tinjau contoh berikut untuk mempelajari cara membuat fungsi dinamis untuk aset tepercaya.

Menyertakan nilai parameter default

Anda dapat menentukan nilai default untuk parameter. DEFAULT Gunakan klausa dalam tanda tangan fungsi seperti yang ditunjukkan dalam contoh berikut:

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

Sertakan contoh nilai parameter

Untuk kolom dengan enumerasi nilai yang ditetapkan, tingkatkan akurasi dengan mendefinisikannya dengan jelas dalam komentar. Contoh berikut menyediakan daftar sampel nilai:

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

Membuat parameter opsional

Untuk membuat parameter opsional, atur parameter default ke NULL seperti yang ditunjukkan dalam contoh berikut:

min_date STRING DEFAULT NULL

Tentukan pemformatan dengan komentar

Anda dapat menentukan format yang tepat untuk parameter dengan menyertakannya dalam komentar, seperti yang ditunjukkan dalam contoh berikut:

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

Periksa nilai NULL secara eksplisit

Jika Anda menyertakan parameter opsional, salah satu nilai yang mungkin Anda harapkan adalah NULL. Karena perbandingan dengan NULL dapat menghasilkan hasil yang tidak dapat diprediksi, Anda harus secara eksplisit membangun pemeriksaan untuk nilai NULL ke dalam fungsi Anda. Contoh berikut menyediakan contoh sintaks:

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