Vertrouwde assets gebruiken in AI/BI Genie-ruimten

Belangrijk

Deze functie is beschikbaar als openbare preview. Zie Genie-ruimten inschakelen in uw werkruimte.

In dit artikel worden vertrouwde assets gedefinieerd en wordt uitgelegd hoe u deze kunt gebruiken om geverifieerde antwoorden te geven in een Genie-ruimte.

Wat zijn vertrouwde assets?

Vertrouwde assets zijn vooraf gedefinieerde functies en voorbeeldquery's die zijn bedoeld om geverifieerde antwoorden te bieden op vragen die u van gebruikers verwacht. Wanneer een gebruiker een vraag indient die een vertrouwde asset aanroept, wordt deze aangegeven in het antwoord, waardoor een extra zekerheidslaag wordt toegevoegd aan de nauwkeurigheid van de resultaten.

Vertrouwde assets kunnen het volgende omvatten:

• Geparameteriseerde SQL-query's: Wanneer een geparameteriseerde SQL-query wordt gebruikt om een antwoord te genereren, wordt de aanvraag een vertrouwde asset gelabeld. Het antwoord bevat de waarden die worden gebruikt als argumenten in de query.
• Door de gebruiker gedefinieerde tabelfuncties (UDF's): u kunt aangepaste functies definiëren en registreren bij Unity Catalog. Vervolgens kunt u deze functies toevoegen als vertrouwde assets wanneer u instructies instelt in uw Genie-ruimte. Zie Een SQL-tabelfunctie en door de gebruiker gedefinieerde functies (UDF's) maken in Unity Catalog.

Notitie

Vertrouwde assets zijn geen vervanging voor alle andere instructies. Databricks raadt aan vertrouwde assets te gebruiken voor bekende terugkerende vragen. Ze bieden exacte antwoorden op specifieke vragen.

Waarom vertrouwde assets maken?

Wanneer gebruikers een AI-hulpprogramma gebruiken, moeten ze de nauwkeurigheid van gegenereerde antwoorden evalueren. Normaal gesproken doen ze dit door na te gaan of het antwoord zinvol is en hun vraag effectief beantwoordt. Met Genie wordt een antwoord geleverd als een tabel met resultaten. Gebruikers kunnen de gegenereerde SQL controleren die de resultatenset maakt, maar niet-technische gebruikers hebben mogelijk niet de achtergrond om de SQL-instructie te interpreteren of de juistheid van het antwoord te beoordelen. Vertrouwde assets helpen de kans te verminderen dat deze gebruikers reacties tegenkomen die misleidend, onjuist of moeilijk te interpreteren zijn.

Wanneer een gebruiker een antwoord ontvangt dat is gelabeld als een vertrouwde asset, kunnen ze erop vertrouwen dat een domeinexpert de SQL-instructie heeft gecontroleerd die de resultaten bevat.

Wat is het verschil tussen vertrouwde assets en voorbeeld-SQL-query's?

Vertrouwde assets bieden geverifieerde antwoorden op vragen die u verwacht dat Genie-ruimtegebruikers vragen stellen. Wanneer een vertrouwde asset de vraag van een gebruiker kan beantwoorden, wordt de instructie die u hebt opgeslagen als een vertrouwde asset uitgevoerd en wordt de opgegeven resultatenset geretourneerd. Alle SQL-functies die u in de instructies opneemt, worden beschouwd als vertrouwde assets. Voorbeeld van SQL-query's die parameters bevatten, kunnen ook worden behandeld als vertrouwde assets.

• SQL Functions: u kunt aangepaste SQL-functies schrijven die zijn afgestemd op uw gegevens en bedrijfsspecifieke vragen afhandelen. Genie beschouwt de SQL-inhoud van uw vertrouwde assets niet bij het beantwoorden van vragen.
• Voorbeeld van SQL-query's (met parameters):wanneer de exacte tekst van een voorbeeldquery wordt gebruikt om een antwoord te genereren, wordt het antwoord automatisch gelabeld als een vertrouwde asset. Als de exacte tekst van de query niet wordt gebruikt of als de voorbeeldquery geen parameters gebruikt, biedt de query context en begeleidt Genie bij het genereren van de SQL-instructies om andere vragen te verwerken.

Een vertrouwde asset definiëren

Het definiëren van een vertrouwde asset begint met het identificeren van een waarschijnlijke vraag. Stel dat u met een gegevensset voor een verkooppijplijn werkt en een veelvoorkomende vraag die een verkoopmanager kan stellen is: 'Wat zijn de openstaande verkoopkansen in mijn pijplijn?'

Voorbeeld: Een UDF gebruiken

In de volgende stappen worden de stappen beschreven voor het maken van een vertrouwde asset, als UDF, die deze vraag beantwoordt:

1. Definieer en test een SQL-query die de vraag beantwoordt.

   Met deze query worden twee tabellen samengevoegd en wordt een gegevensset met geopende verkoopkansen geretourneerd die worden vermeld in de prognosecategorie Pijplijn. In deze stap is het doel om een basisquery te schrijven die de verwachte resultaten retourneert.

   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. Definieer een Unity Catalog-functie.

   Uw Unity Catalog-functie moet de query parameteriseren en resultaten produceren die overeenkomen met de specifieke voorwaarden waarover de gebruiker wordt gevraagd. Stel dat de verkoopmanager de resultatenset wil beperken door zich te richten op een bepaalde regio of groep regio's.

   In het volgende voorbeeld wordt een Unity Catalog-functie gedefinieerd die een lijst met regio's als parameter gebruikt en een tabel retourneert. De functie return is bijna identiek aan de SQL-instructie in de vorige stap, behalve dat de WHERE component is gewijzigd om de resultaten te filteren op regio als er een regio is opgegeven. De opmerkingen in de functiedefinities zijn essentieel voor het instrueren van de Genie-ruimte over wanneer en hoe u deze functie aanroept.

   • Parameteropmerkingen: de open_opps_in_region functie verwacht een matrix met tekenreeksen als een parameter. De opmerking bevat een voorbeeld van de verwachte invoer. Als er geen parameter wordt opgegeven, is NULLde standaardwaarde . Zie Tips voor het schrijven van functies voor meer informatie over het opnemen van optionele parameters en opmerkingen.
   • Functieopmerkingen: de opmerking in de SQL-tabelfunctie biedt een gedetailleerde uitleg van wat de functie doet. Dit is essentieel omdat het Genie informeert wanneer de functie moet worden gebruikt als reactie op vragen van gebruikers. In de opmerking moet het doel van de functie zo nauwkeurig mogelijk worden beschreven. Deze informatie begeleidt Genie bij het herkennen van de relevantie van de functie voor specifieke vragen.

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

   Wanneer u de code uitvoert om een functie te maken, wordt deze standaard geregistreerd bij het huidige actieve schema. Zie Aangepaste SQL-functies in Unity Catalog. Zie Een SQL-tabelfunctie maken voor syntaxis en voorbeelden.

3. Voeg een vertrouwde asset toe.

   Nadat de functie is gemaakt in Unity Catalog, kan een gebruiker met ten minste DE MACHTIGING BEWERKEN voor de Genie-ruimte deze toevoegen vanaf het tabblad Instructies van de Genie-ruimte.

Vereiste machtigingen

Gebruikers met ten minste DE MACHTIGING BEWERKEN voor een Genie-ruimte kunnen vertrouwde assets toevoegen of verwijderen.

Genie-ruimtegebruikers moeten gemachtigd zijn CAN USE voor de catalogus en het schema dat de functie bevat. Als u een vertrouwde asset wilt aanroepen, moeten ze gemachtigd zijn EXECUTE voor de functie in Unity Catalog. Beveiligbare objecten van Unity Catalog nemen machtigingen over van hun bovenliggende containers. Zie Beveiligbare objecten in Unity Catalog.

Om het delen in een Genie-ruimte te vereenvoudigen, raadt Databricks aan om een speciaal schema te maken dat alle functies bevat die u in uw Genie-ruimte wilt gebruiken.

Tips voor het schrijven van functies

Bekijk de volgende voorbeelden voor meer informatie over het maken van dynamische functies voor vertrouwde assets.

Een standaardparameterwaarde opnemen

U kunt een standaardwaarde voor een parameter opgeven. Gebruik de DEFAULT component in de functiehandtekening, zoals wordt weergegeven in het volgende voorbeeld:

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

Voorbeeldparameterwaarden opnemen

Voor kolommen met een set opsomming van waarden vergroot u de nauwkeurigheid door ze duidelijk in de opmerking te definiëren. In het volgende voorbeeld ziet u een voorbeeldlijst met waarden:

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

Een optionele parameter maken

Als u een optionele parameter wilt maken, stelt u de standaardparameter NULL in op zoals wordt weergegeven in het volgende voorbeeld:

min_date STRING DEFAULT NULL

Opmaak opgeven met opmerkingen

U kunt een exacte indeling voor een parameter opgeven door deze op te geven in een opmerking, zoals wordt weergegeven in het volgende voorbeeld:

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

Explictly controleren op NULL waarden

Als u een optionele parameter opneemt, is NULLéén mogelijke waarde die u moet verwachten. Omdat vergelijking met NULL onvoorspelbare resultaten kan opleveren, moet u expliciet een controle bouwen op NULL waarden in uw functie. Het volgende voorbeeld bevat een voorbeeldsyntaxis:

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