Używanie zaufanych zasobów w przestrzeniach AI/BI Genie

W tym artykule zdefiniowano zaufane zasoby i wyjaśniono, jak używać ich do dostarczania zweryfikowanych odpowiedzi w przestrzeni Genie.

Co to są zaufane zasoby?

Zaufane zasoby to wstępnie zdefiniowane funkcje i przykładowe zapytania przeznaczone do zapewnienia zweryfikowanych odpowiedzi na pytania przewidywane przez użytkowników. Gdy użytkownik przesyła pytanie, które wywołuje zaufany zasób, jest wskazane w odpowiedzi, dodając dodatkową warstwę pewności do dokładności wyników.

Zaufane zasoby mogą obejmować następujące elementy:

• Przykładowe zapytania SQL sparametryzowane: Gdy sparametryzowane przykładowe zapytanie SQL jest używane do generowania odpowiedzi, odpowiedź jest oznaczona jako zaufany element. Odpowiedź zawiera wartości używane jako argumenty w zapytaniu.
• funkcje zdefiniowane przez użytkownika (UDF): można zdefiniować funkcje niestandardowe (UDF) i zarejestrować je w katalogu Unity. Następnie możesz dodać te funkcje jako zaufane zasoby podczas konfigurowania instrukcji w obszarze Genie. Zobacz Utwórz funkcję tabeli SQL i Funkcje zdefiniowane przez użytkownika (UDF) w katalogu Unity.

Uwaga

Zaufane zasoby nie są zastępowane wszystkimi innymi instrukcjami. Usługa Databricks zaleca używanie zaufanych zasobów w celu uzyskania dobrze ustalonych pytań cyklicznych. Zapewniają dokładne odpowiedzi na konkretne pytania.

Dlaczego warto tworzyć zaufane zasoby?

W przypadku korzystania z dowolnego narzędzia sztucznej inteligencji użytkownicy powinni ocenić dokładność wygenerowanych odpowiedzi. Zazwyczaj robią to, rozważając, czy odpowiedź ma sens i skutecznie rozwiązuje swoje pytanie. W przypadku usługi Genie odpowiedź jest dostarczana jako tabela wyników. Użytkownicy mogą przejrzeć wygenerowany kod SQL, który tworzy zestaw wyników, ale użytkownicy nietechniczni mogą nie mieć odpowiedniej wiedzy, aby zinterpretować instrukcję SQL lub ocenić poprawność odpowiedzi. Zaufane zasoby pomagają zmniejszyć prawdopodobieństwo wystąpienia odpowiedzi, które są mylące, nieprawidłowe lub trudne do zinterpretowania.

Gdy użytkownik otrzyma odpowiedź oznaczona jako zaufany zasób, może mieć pewność, że ekspert domeny przejrzy instrukcję SQL wypełnia wyniki.

Jaka jest różnica między zaufanymi elementami zawartości i przykładowych zapytań SQL?

Zaufane zasoby zapewniają zweryfikowane odpowiedzi na pytania, które mają zadawać użytkownicy obszaru Genie. Gdy zaufany zasób może odpowiedzieć na pytanie użytkownika, instrukcja przechowywana jako zaufany zasób jest uruchamiana i zwraca określony zestaw wyników. Wszystkie funkcje SQL uwzględnione w instrukcjach są traktowane jako zaufane zasoby. przykładowe zapytania SQL, które zawierają parametry, mogą być również traktowane jako zaufane zasoby.

• Funkcje SQL: możesz pisać niestandardowe funkcje SQL dostosowane do obsługi danych i radzić sobie z pytaniami specyficznymi dla firmy. Genie nie uwzględnia zawartości SQL zaufanych zasobów podczas odpowiadania na pytania.
• przykładowe zapytania SQL (z parametrami): gdy do wygenerowania odpowiedzi jest używany dokładny tekst zapytania przykładowego, odpowiedź jest automatycznie oznaczona jako zaufany zasób. Jeśli dokładny tekst zapytania nie jest używany lub przykładowe zapytanie nie używa parametrów, zapytanie zapewnia kontekst i prowadzi Genie w generowaniu instrukcji SQL do przetwarzania innych pytań.

Definiowanie zaufanego zasobu

Definiowanie zaufanego zasobu rozpoczyna się od zidentyfikowania prawdopodobnego pytania. Załóżmy na przykład, że pracujesz z zestawem danych potoku sprzedaży i często zadawanym pytaniem, które może zadać menedżer sprzedaży: "Jakie są otwarte możliwości sprzedaży w moim potoku?"

Przykład: używanie funkcji zdefiniowanej przez użytkownika

W poniższych krokach opisano kroki tworzenia zaufanego zasobu jako funkcji zdefiniowanej przez użytkownika, która odpowiada na następujące pytanie:

1. Zdefiniuj i przetestuj zapytanie SQL, które odpowiada na pytanie.

   To zapytanie łączy dwie tabele i zwraca zestaw danych otwartych możliwości wymienionych w kategorii prognozy "Potok". W tym kroku celem jest napisanie podstawowego zapytania zwracającego oczekiwane wyniki.

   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. Zdefiniuj funkcję katalogu Unity.

   Funkcja katalogu Unity powinna sparametryzować zapytanie i wygenerować wyniki zgodne z określonymi warunkami, o które oczekujesz, że użytkownik zapyta. Załóżmy, że menedżer sprzedaży chce zawęzić zestaw wyników, koncentrując się na określonym regionie lub grupie regionów.

   W poniższym przykładzie zdefiniowano funkcję w Unity Catalog, która przyjmuje listę regionów jako parametr i zwraca tabelę. Funkcja zwracana jest niemal identyczna z instrukcją SQL w poprzednim kroku, z wyjątkiem WHERE klauzuli została zmodyfikowana w celu filtrowania wyników według regionu, jeśli podano region. Komentarze podane w definicjach funkcji mają kluczowe znaczenie dla poinstruowania miejsca Genie, kiedy i jak wywołać tę funkcję.

   • Komentarze parametrów: open_opps_in_region funkcja oczekuje tablicy ciągów jako parametru. Komentarz zawiera przykład oczekiwanego danych wejściowych. Jeśli parametr nie zostanie podany, wartość domyślna to NULL. Aby uzyskać więcej informacji na temat dołączania parametrów opcjonalnych i komentarzy, zobacz Porady dotyczące pisania funkcji.
   • komentarze funkcji: komentarz w funkcji tabeli SQL zawiera szczegółowe wyjaśnienie działania funkcji. Jest to krytyczne, ponieważ informuje Genie, kiedy używać funkcji jako odpowiedzi na pytania użytkownika. Komentarz powinien opisywać cel funkcji tak dokładnie, jak to możliwe. Te informacje zawierają przewodniki Genie w rozpoznawaniu istotności funkcji do konkretnych pytań.

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

   Po uruchomieniu kodu w celu utworzenia funkcji jest on domyślnie zarejestrowany w aktualnie aktywnym schemacie. Zobacz funkcje zdefiniowane przez użytkownika (UDF) w katalogu Unity. Zobacz Tworzenie funkcji tabeli SQL dla składni i przykładów.

3. Dodaj zaufany zasób.

   Po utworzeniu funkcji w katalogu Unity użytkownik z co najmniej uprawnieniem CAN EDIT w obszarze Genie może dodać ją z karty Instrukcje w obszarze Genie.

Wymagane uprawnienia

Użytkownicy z co najmniej uprawnieniem CAN EDIT w obszarze Genie mogą dodawać lub usuwać zaufane zasoby.

Użytkownicy obszaru Genie muszą mieć uprawnienia CAN USE dla katalogu i schematu zawierającego funkcję. Aby wywołać zaufany zasób, muszą mieć EXECUTE uprawnienia do funkcji w katalogu Unity. Obiekty zabezpieczalne Katalogu Unity dziedziczą uprawnienia od swoich kontenerów nadrzędnych. Zobacz obiekty zabezpieczane w katalogu Unity.

Aby uprościć udostępnianie w przestrzeni Genie, usługa Databricks zaleca utworzenie dedykowanego schematu zawierającego wszystkie funkcje, których chcesz użyć w przestrzeni Genie.

Porady dotyczące pisania funkcji

Zapoznaj się z poniższymi przykładami, aby dowiedzieć się, jak tworzyć funkcje dynamiczne dla zaufanych zasobów.

Uwzględnij domyślną wartość parametru

Możesz określić wartość domyślną parametru. DEFAULT Użyj klauzuli w podpisie funkcji, jak pokazano w poniższym przykładzie:

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

Uwzględnij przykładowe wartości parametrów

W przypadku kolumn z zestawem wyliczenia wartości zwiększ dokładność, definiując je wyraźnie w komentarzu. Poniższy przykład zawiera przykładową listę wartości:

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

Tworzenie opcjonalnego parametru

Aby utworzyć opcjonalny parametr, ustaw parametr domyślny na NULL, jak pokazano w poniższym przykładzie:

min_date STRING DEFAULT NULL

Określanie formatowania z komentarzami

Możesz określić dokładny format parametru, dołączając go do komentarza, jak pokazano w poniższym przykładzie:

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

Wyraźnie sprawdzaj wartości NULL

Jeśli dołączysz opcjonalny parametr, jedną z możliwych wartości, której należy się spodziewać, jest NULL. Ponieważ porównanie z NULL może przynieść nieprzewidywalne wyniki, należy wyraźnie uwzględnić sprawdzanie wartości NULL w funkcji. W poniższym przykładzie przedstawiono przykładowe składnie:

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