Vertrouwde assets gebruiken in AI/BI Genie-ruimten

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 reactie te generate, wordt de reactie gelabeld als een vertrouwd item. Het antwoord bevat de values die als argumenten in de query worden gebruikt.
• door de gebruiker gedefinieerde table functies (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 table-functie maken en door de gebruiker gedefinieerde functies (UDF's) 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 table van resultaten. Gebruikers kunnen de gegenereerde SQL controleren die het resultaat maakt set, 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 het opgegeven resultaat geretourneerd set. 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 geparameteriseerde voorbeeldquery wordt gebruikt om een antwoord te generate, wordt het antwoord automatisch gelabeld als een betrouwbaar activum. Als de exacte tekst van de query niet wordt gebruikt of als de voorbeeldquery geen gebruik maakt van parameters, 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.

   Deze query voegt twee tables samen en retourneert een gegevensset met openstaande kansen 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 het resultaat wil beperken set door te focussen op een bepaalde regio of groep regio's.

   In het volgende voorbeeld wordt een Unity-Catalog-functie gedefinieerd die een list van regio's als parameter gebruikt en een tableretourneert. 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 functie SQL table 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 de momenteel actieve schema. Zie door de gebruiker gedefinieerde functies (UDF's) in Unity Catalog. Zie Een SQL-table-functie 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 BEWERKEN-rechten op de Genie-ruimte deze toevoegen vanaf het tabblad Instructies van de Genie-ruimte.

Vereiste machtigingen

Gebruikers met ten minste bewerkrechten voor een Genie-ruimte kunnen vertrouwde activa toevoegen of remove.

Genie-ruimtegebruikers moeten CAN USE toestemming hebben voor de catalog en schema die de functie bevatten. Om een vertrouwde asset aan te roepen, moeten ze beschikken over EXECUTE machtiging voor de functie in Unity Catalog. Unity Catalog beveiligbare objecten 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 speciale schema te maken die 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()

Voorbeeldparameter opnemen values

Voor columns met een set opsomming van valuesvergroot u de nauwkeurigheid door deze duidelijk in de opmerking te definiëren. In het volgende voorbeeld ziet u een voorbeeld van list van values:

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, set u de standaardparameter NULL, 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'

Controleer expliciet op NULLvalues

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 NULLvalues in uw functie. Het volgende voorbeeld bevat een voorbeeldsyntaxis:

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