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

Den här artikeln 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ä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.

Kommentar

Betrodda tillgångar ersätter inte alla andra instruktioner. Databricks rekommenderar att du använder betrodda tillgångar för väletablerade återkommande 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 en betrodd tillgång kan de vara säkra på att en domänexpert har granskat SQL-instruktionen som fyller i resultaten.

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. Alla SQL Functions som du inkluderar i instruktionerna behandlas som betrodda tillgångar. Exempel på SQL-frågor som innehåller parametrar kan också behandlas som betrodda tillgångar.

• 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.
• Exempel på SQL-frågor (med parametrar): När en parameteriserad exempelfrågas exakta text används för att generera ett svar, etiketteras svaret automatiskt som en betrodd tillgång. Om den exakta texten i frågan inte används, eller om exempelfrågan inte använder parametrar, ger frågan kontext och vägleder Genie när sql-uttryck genereras för att bearbeta andra frågor.

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 pipeline?"

Exempel: Använda en UDF

Följande steg beskriver stegen för att skapa en betrodd tillgång, som en UDF, som svarar på den här frågan:

1. 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 prognoskategorin "Pipeline". 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%';
   

2. 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 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.

3. 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 på Genie-utrymmet lägga till den från fliken Instruktioner i Genie-utrymmet.

Behörigheter som krävs

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

Genie space-användare måste ha CAN USE behörighet för katalogen och schemat som innehåller funktionen. Om du vill 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'

Sök efter värden på ett oförklarligt sätt NULL

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)