Använda betrodda tillgångar i AI/BI Genie-utrymmen

Den här sidan definierar betrodda tillgångar och förklarar hur du använder dem för att tillhandahålla verifierade svar i ett Genie-utrymme.

Vad är betrodda tillgångar?

Betrodda tillgångar är fördefinierade funktioner och exempelfrågor som är avsedda att ge verifierade svar på frågor som du förväntar dig av användarna. När en användare skickar en fråga som anropar en betrodd tillgång anges den i svaret och lägger till ett extra säkerhetslager för att säkerställa att resultaten är korrekta.

Betrodda tillgångar kan innehålla följande:

• Parameteriserade SQL-exempelfrågor: När en parameteriserad SQL-exempelfråga används för att generera ett svar, märks reponse som en betrodd tillgång. Svaret innehåller de värden som används som argument i frågan. Användare kan redigera parametervärdet i svaret.
• Användardefinierade tabellfunktioner (UDF:er): Du kan definiera anpassade funktioner och registrera dem med Unity Catalog. Sedan kan du lägga till dessa funktioner som betrodda tillgångar när du konfigurerar instruktioner i ditt Genie-utrymme. Se Skapa en SQL-tabellfunktion och användardefinierade funktioner (UDF:er) i Unity Catalog.

Anteckning

Betrodda tillgångar ersätter inte andra instruktioner. Databricks rekommenderar att du använder betrodda tillgångar för återkommande och väletablerade frågor. De ger exakta svar på specifika frågor.

Varför skapa betrodda tillgångar?

När du använder ai-verktyg bör användarna utvärdera noggrannheten för genererade svar. Vanligtvis gör de detta genom att överväga om svaret är meningsfullt och effektivt adresserar deras fråga. Med Genie levereras ett svar som en resultattabell. Användare kan granska den genererade SQL som skapar resultatuppsättningen, men icke-tekniska användare kanske inte har bakgrunden för att tolka SQL-instruktionen eller utvärdera svarets korrekthet. Betrodda tillgångar bidrar till att minska sannolikheten för att dessa användare får svar som är vilseledande, felaktiga eller svåra att tolka.

När en användare får ett svar som är märkt som Trustedinnebär det att en domänexpert har lagt till SQL-instruktionen som används för att generera resultatet som en instruktion i utrymmet.

Vad är skillnaden mellan betrodda tillgångar och sql-exempelfrågor?

Betrodda tillgångar ger verifierade svar på frågor som du förväntar dig att Genie-utrymmesanvändare ska ställa. När en betrodd tillgång kan besvara en användares fråga körs instruktionen som du har lagrat som en betrodd tillgång och returnerar den angivna resultatuppsättningen. Exempel på SQL-frågor som innehåller parametrar och SQL Functions som du lägger till i ett utrymmes kontext behandlas som betrodda tillgångar.

• Exempel på SQL-frågor (med parametrar): När en parameteriserad exempelfrågas exakta text används för att generera ett svar märks svaret automatiskt som Betrott. Utrymmesanvändare kan redigera parametervärdet i ett svar och köra frågan igen med det nya värdet.
• SQL Functions: Du kan skriva anpassade SQL-funktioner som är skräddarsydda för att hantera dina data och hantera företagsspecifika frågor. Genie tar inte hänsyn till SQL-innehållet i dina betrodda tillgångar när du svarar på frågor.

Anteckning

Om den exakta texten i frågan inte används, eller om exempelfrågan inte använder parametrar, ger exempelfrågorna kontext och guide Genie vid generering av SQL-uttryck, men markeras inte som Betrodda.

Definiera en betrodd tillgång

Att definiera en betrodd tillgång börjar med att identifiera en sannolik fråga. Anta till exempel att du arbetar med en datauppsättning för försäljningspipelines, och en vanlig fråga som en säljchef kan ställa sig är: "Vilka är de öppna försäljningsmöjligheterna i min region?"

Exempel: Skapa en UDF för att besvara frågan

Följande steg beskriver hur du skriver en testfråga och använder den för att skapa en UDF:

1. Använd SQL-redigeraren eller en notebook- för att definiera och testa en SQL-fråga som besvarar frågan.

Den här frågan kopplar ihop två tabeller och returnerar en datauppsättning med öppna affärsmöjligheter som anges i kategorin “Pipeline” prognos. I det här steget är målet att skriva en grundläggande fråga som returnerar det förväntade resultatet.

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. Definiera en Unity Catalog-funktion.

Funktionen Unity Catalog ska parametrisera frågan och skapa resultat som matchar de specifika villkor som du förväntar dig att användaren ska fråga om. Anta till exempel att säljchefen vill begränsa resultatuppsättningen genom att fokusera på en viss region eller grupp med regioner.

I följande exempel definieras en Unity Catalog-funktion som tar en lista över regioner som en parameter och returnerar en tabell. Funktionsreturen är nästan identisk med SQL-instruktionen i föregående steg, förutom WHERE att satsen har ändrats för att filtrera resultatet efter region om en region har angetts. Kommentarerna i funktionsdefinitionerna är viktiga för att instruera Genie-utrymmet om när och hur du anropar den här funktionen.

• Parameterkommenterar: Funktionen open_opps_in_region förväntar sig en matris med strängar som en parameter. Kommentaren innehåller ett exempel på förväntade indata. Om ingen parameter anges är NULLstandardvärdet . Mer information om hur du inkluderar valfria parametrar och kommentarer finns i Tips för att skriva funktioner .
• Funktionskommentare: Kommentaren i SQL-tabellfunktionen ger en detaljerad förklaring av vad funktionen gör. Detta är viktigt eftersom det informerar Genie när funktionen ska användas som svar på användarfrågor. Kommentaren bör beskriva funktionens syfte så exakt som möjligt. Den här informationen vägleder Genie när det gäller att identifiera funktionens relevans för specifika frågor.

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

När du kör koden för att skapa en funktion registreras den som standard i det aktiva schemat. Se Användardefinierade funktioner (UDF: er) i Unity Catalog. Se Skapa en SQL-tabellfunktion för syntax och exempel.

1. Lägg till en betrodd tillgång.

   När funktionen har skapats i Unity Catalog kan en användare med minst behörigheten KAN REDIGERA i Genie-utrymmet lägga till den i Genie-utrymmet. Klicka på Konfigurera>SQL-kontextfrågor>. Klicka sedan på Lägg till.

Behörigheter som krävs

Användare med minst behörigheten KAN REDIGERA på ett Genie-utrymme kan lägga till eller ta bort betrodda resurser.

Genie space-användare måste ha CAN USE behörighet för katalogen och schemat som innehåller funktionen. För att anropa en betrodd tillgång måste de ha EXECUTE behörighet för funktionen i Unity Catalog. Skyddsbara objekt i Unity Catalog ärver behörigheter från sina överordnade containrar. Se Skyddsbara objekt i Unity Catalog.

För att förenkla delning i ett Genie-utrymme rekommenderar Databricks att du skapar ett dedikerat schema som innehåller alla funktioner som du vill använda i ditt Genie-utrymme.

Tips för att skriva funktioner

Granska följande exempel för att lära dig hur du skapar dynamiska funktioner för betrodda tillgångar.

Inkludera ett standardparametervärde

Du kan ange ett standardvärde för en parameter. DEFAULT Använd -satsen i funktionssignaturen enligt följande exempel:

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

Inkludera exempelparametervärden

För kolumner med en angiven uppräkning av värden ökar du noggrannheten genom att definiera dem tydligt i kommentaren. I följande exempel finns en exempellista med värden:

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

Skapa en valfri parameter

Om du vill skapa en valfri parameter anger du standardparametern enligt NULL följande exempel:

min_date STRING DEFAULT NULL

Ange formatering med kommentarer

Du kan ange ett exakt format för en parameter genom att inkludera den i en kommentar, som du ser i följande exempel:

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

Kontrollera uttryckligen efter NULL värden

Om du inkluderar en valfri parameter är NULLett möjligt värde som du kan förvänta dig . Eftersom jämförelse med NULL kan ge oförutsägbara resultat bör du uttryckligen skapa en kontroll av NULL värden i din funktion. I följande exempel finns exempelsyntax:

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