Udostępnij za pośrednictwem

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

Ta strona definiuje zaufane zasoby i wyjaśnia, 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 oznaczone w odpowiedzi, dodając dodatkowy poziom 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. Użytkownicy mogą edytować wartość parametru w odpowiedzi.
  • 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.

Przykładowe pytanie, odpowiedź udzielona za pomocą zaufanego zasobu.

Uwaga

Zaufane zasoby nie zastępują innych instrukcji. Usługa Databricks zaleca używanie zaufanych zasobów do dobrze zdefiniowanych, powtarzających się pytań. 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 Zaufana, oznacza to, że ekspert domeny dodał instrukcję SQL używaną do generowania wyników jako instrukcji w przestrzeni.

Jaka jest różnica między zaufanymi zasobami a przykładowymi zapytaniami SQL?

Zaufane zasoby zapewniają zweryfikowane odpowiedzi na pytania, których mogą się spodziewać użytkownicy przestrzeni 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. Przykładowe zapytania SQL zawierające parametry i funkcje SQL dodawane do kontekstu przestrzeni są traktowane jako zaufane zasoby.

  • Przykładowe zapytania SQL (z parametrami): gdy dokładny tekst zapytania przykładowego sparametryzowanego jest używany do generowania odpowiedzi, odpowiedź jest automatycznie oznaczona jako Zaufana. Użytkownicy obszaru mogą edytować wartość parametru w odpowiedzi i ponownie uruchomić zapytanie przy użyciu nowej wartości.
  • 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.

Uwaga

Jeśli dokładny tekst zapytania nie jest używany lub przykładowe zapytanie nie używa parametrów, przykładowe zapytania dostarczają kontekst i przewodnik Genie podczas generowania instrukcji SQL, ale nie są oznaczone jako Zaufane.

Definiowanie zaufanego zasobu

Definiowanie zaufanego zasobu zaczyna się od zidentyfikowania możliwego pytania. Załóżmy na przykład, że pracujesz z danymi dotyczącymi lejka sprzedażowego, a częstym pytaniem, które może zadać menedżer, jest: "Jakie są otwarte możliwości sprzedaży w moim regionie?"

Przykład: tworzenie funkcji zdefiniowanej przez użytkownika w celu udzielenia odpowiedzi na pytanie

W poniższych krokach opisano sposób pisania zapytania testowego i używania go do utworzenia funkcji zdefiniowanej przez użytkownika:

  1. Użyj edytora SQL lub notesu , aby zdefiniować i przetestować zapytanie SQL, które odpowiada na pytanie.

To zapytanie łączy dwie tabele i zwraca zestaw danych otwartych szans wymienionych w kategorii prognozy “Pipeline”. 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%';
  1. 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 na przykład, że menedżer sprzedaży chce zawęzić zestaw wyników, koncentrując się na konkretnym 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 instruowania przestrzeni Genie, kiedy i jak wywołać tę funkcję.

  • Komentarze dotyczące parametrów: funkcja open_opps_in_region oczekuje tablicy stringów jako parametru. Komentarz zawiera przykład oczekiwanego danego wejściowego. 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. Ta informacja pomaga Genie w rozpoznawaniu znaczenia funkcji dla 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.

  1. Dodaj zaufany zasób.

    Po utworzeniu funkcji w Unity Catalog użytkownik z co najmniej uprawnieniem CAN EDIT w obszarze Genie może dodać ją do obszaru Genie. Kliknij pozycję Konfiguruj>kontekstu>zapytania SQL. Następnie kliknij przycisk Dodaj.

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. Użyj klauzuli DEFAULT 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)