Verwenden Sie vertrauenswürdige Assets in KI/BI-Genie-Bereichen

Diese Seite definiert vertrauenswürdige Ressourcen und erläutert, wie sie verwendet werden, um überprüfte Antworten in einem Genie-Raum bereitzustellen.

Was sind vertrauenswürdige Assets?

Vertrauenswürdige Ressourcen sind vordefinierte Funktionen und Beispielabfragen, die verifizierte Antworten auf Fragen liefern sollen, die Sie von Benutzern erwarten. Wenn ein Benutzer eine Frage sendet, die eine vertrauenswürdige Ressource aufruft, wird er in der Antwort angegeben und fügt der Genauigkeit der Ergebnisse eine zusätzliche Zuverlässigkeitsebene hinzu.

Vertrauenswürdige Ressourcen können die folgenden sein:

• Parametrisierte Beispiel-SQL-Abfragen: Wenn eine parametrisierte Beispiel-SQL-Abfrage verwendet wird, um eine Antwort zu generieren, wird die Antwort als vertrauenswürdige Ressource eingestuft. Die Antwort enthält die Werte, die als Argumente in der Abfrage verwendet wurden. Benutzer können den Parameterwert in der Antwort bearbeiten.
• Benutzerdefinierte Tabellenfunktionen (UDFs): Sie können benutzerdefinierte Funktionen definieren und sie im Unity-Katalog registrieren. Anschließend können Sie diese Funktionen als vertrauenswürdige Ressourcen hinzufügen, wenn Sie Anweisungen in Ihrem Genie-Raum einrichten. Siehe Erstellen einer SQL-Tabellenfunktion und Benutzerdefinierte Funktionen (UDFs) in Unity Catalog.

Warum sollten vertrauenswürdige Ressourcen erstellt werden?

Wenn Sie ein KI-Tool verwenden, sollten Sie die Genauigkeit der generierten Antworten bewerten. In der Regel tun sie dies, indem sie prüfen, ob die Antwort sinnvoll ist und ihre Frage effektiv beantwortet. Mit Genie wird eine Antwort in Form einer Ergebnistabelle geliefert. Benutzer können die generierte SQL-Anweisung, mit der die Ergebnismenge erstellt wird, überprüfen. Nicht-technische Benutzer verfügen jedoch möglicherweise nicht über den nötigen Hintergrund, um die SQL-Anweisung zu interpretieren oder die Richtigkeit der Antwort zu beurteilen. Vertrauenswürdige Ressourcen tragen dazu bei, die Wahrscheinlichkeit zu verringern, dass diese Benutzer auf Antworten stoßen, die irreführend, falsch oder schwer zu interpretieren sind.

Wenn ein Benutzer eine Antwort erhält, die als vertrauenswürdig bezeichnet wird, bedeutet dies, dass ein Domänenexperte die SQL-Anweisung hinzugefügt hat, die zum Generieren der Ergebnisse als Anweisung im Raum verwendet wird.

Was ist der Unterschied zwischen vertrauenswürdigen Ressourcen und BEISPIEL-SQL-Abfragen?

Vertrauenswürdige Ressourcen liefern verifizierte Antworten auf Fragen, die Sie von den Benutzern von Genie Space erwarten. Wenn eine vertrauenswürdige Ressource die Frage eines Benutzers beantworten kann, wird die Anweisung, die Sie als vertrauenswürdige Ressource gespeichert haben, ausgeführt und gibt das angegebene Resultset zurück. Beispiel-SQL-Abfragen , die Parameter und SQL-Funktionen enthalten, die Sie dem Kontext eines Bereichs hinzufügen, werden als vertrauenswürdige Ressourcen behandelt.

• Beispiel-SQL-Abfragen (mit Parametern): Wenn der genaue Text einer parametrisierten Beispielabfrage verwendet wird, um eine Antwort zu generieren, wird die Antwort automatisch als vertrauenswürdig bezeichnet. Space-Benutzer können den Parameterwert in einer Antwort bearbeiten und die Abfrage mithilfe des neuen Werts erneut ausführen.
• SQL-Funktionen: Sie können benutzerdefinierte SQL-Funktionen schreiben, die auf Ihre Daten zugeschnitten sind und unternehmensspezifische Fragen beantworten. Genie berücksichtigt bei der Beantwortung von Fragen nicht den SQL-Inhalt Ihrer vertrauenswürdigen Ressourcen.

Definieren einer vertrauenswürdigen Ressource

Die Definition einer vertrauenswürdigen Ressource beginnt mit der Identifizierung einer wahrscheinlichen Frage. Nehmen wir beispielsweise an, Sie arbeiten mit einem Dataset für Vertriebspipelinen und einer häufig gestellten Frage, die ein Vertriebsleiter stellen könnte, lautet: "Was sind die offenen Verkaufschancen in meiner Region?"

Beispiel: Erstellen einer UDF zur Beantwortung der Frage

In den folgenden Schritten wird beschrieben, wie Eine Testabfrage geschrieben und zum Erstellen einer UDF verwendet wird:

1. Verwenden Sie den SQL-Editor oder ein Notizbuch , um eine SQL-Abfrage zu definieren und zu testen, die die Frage beantwortet.

Diese Abfrage verknüpft zwei Tabellen und gibt einen Datensatz mit offenen Chancen zurück, die in der “Pipeline” Prognosekategorie aufgeführt sind. In diesem Schritt geht es darum, eine einfache Abfrage zu schreiben, die die erwarteten Ergebnisse liefert.

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. Definieren Sie eine Unity Catalog-Funktion.

Ihre Unity Catalog-Funktion sollte die Abfrage parametrisieren und Ergebnisse liefern, die den spezifischen Bedingungen entsprechen, nach denen Sie den Benutzer fragen möchten. Angenommen, der Vertriebsleiter möchte die Ergebnismenge einschränken, indem er sich auf eine bestimmte Region oder eine Gruppe von Regionen konzentriert.

Das folgende Beispiel definiert eine Unity Catalog-Funktion, die eine Liste von Regionen als Parameter annimmt und eine Tabelle zurückgibt. Die Funktionsrückgabe ist fast identisch mit der SQL-Anweisung im vorherigen Schritt, außer dass die WHERE-Klausel geändert wurde, um die Ergebnisse nach Region zu filtern, wenn eine Region angegeben wurde. Die in den Funktionsdefinitionen enthaltenen Kommentare sind entscheidend, um den Genie-Raum anzuweisen, wann und wie diese Funktion aufgerufen werden kann.

• Kommentare zu den Parametern: Die open_opps_in_region-Funktion erwartet ein Array von Strings als Parameter. Der Kommentar enthält ein Beispiel für die erwartete Eingabe. Wenn kein Parameter angegeben wird, ist der Standardwert NULL. Mehr über die Einbeziehung optionaler Parameter und Kommentare finden Sie unter Tipps zum Schreiben von Funktionen.
• Kommentare zur Funktion: Der Kommentar in der SQL-Tabellenfunktion enthält eine ausführliche Erklärung, was die Funktion tut. Dies ist wichtig, weil Genie dadurch weiß, wann es die Funktion als Antwort auf die Fragen des Benutzers verwenden soll. Der Kommentar sollte den Zweck der Funktion so genau wie möglich beschreiben. Diese Information führt Genie dazu, die Relevanz der Funktion auf bestimmte Fragen zu erkennen.

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

Wenn Sie den Code ausführen, um eine Funktion zu erstellen, wird er standardmäßig für das derzeit aktive Schema registriert. Weitere Informationen finden Sie unter Benutzerdefinierte Funktionen (UDFs, user-defined functions) in Unity Catalog. Weitere Informationen zur Syntax und Beispiele finden Sie unter Erstellen einer SQL-Tabellenfunktion.

1. Hinzufügen einer vertrauenswürdigen Ressource.

   Nachdem die Funktion im Unity-Katalog erstellt wurde, kann ein Benutzer mit mindestens CAN EDIT-Berechtigung für den Genie-Raum sie dem Genie-Raum hinzufügen. Klicken Sie auf Konfigurieren>, Kontext>, SQL-Abfragen. Klicken Sie anschließend auf Hinzufügen.

Erforderliche Berechtigungen

Benutzer mit mindestens der Berechtigung CAN EDIT für einen Genie-Bereich können vertrauenswürdige Ressourcen hinzufügen oder entfernen.

Genie Space-Benutzer müssen über die Berechtigung CAN USE für den Katalog und das Schema verfügen, das die Funktion enthält. Um eine vertrauenswürdige Ressource aufzurufen, müssen Sie über eine EXECUTE-Berechtigung für die Funktion in Unity Catalog verfügen. Objekte, die in Unity Catalog gesichert werden können, erben Berechtigungen von ihren übergeordneten Containern. Siehe Sicherungsfähige Objekte in Unity Catalog.

Um die gemeinsame Nutzung in einem Genie-Bereich zu vereinfachen, empfiehlt Databricks, ein eigenes Schema zu erstellen, das alle Funktionen enthält, die Sie in Ihrem Genie-Bereich verwenden möchten.

Tipps für das Schreiben von Funktionen

Sehen Sie sich die folgenden Beispiele an, um zu erfahren, wie Sie dynamische Funktionen für vertrauenswürdige Ressourcen erstellen können.

Einfügen eines Standardparameterwerts

Sie können für einen Parameter keinen Standardwert angeben. Verwenden Sie die DEFAULT-Klausel in der Funktionssignatur wie im folgenden Beispiel gezeigt:

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

Einbeziehen von Beispiel-Parameterwerten

Bei Spalten mit einer Aufzählung von Werten erhöhen Sie die Genauigkeit, indem Sie diese in einem Kommentar klar definieren. Das folgende Beispiel zeigt eine Beispielliste von Werten:

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

Erstellen eines optionalen Parameters

Um einen optionalen Parameter zu erstellen, setzen Sie den Standardparameter auf NULL, wie im folgenden Beispiel gezeigt:

min_date STRING DEFAULT NULL

Festlegen der Formatierung mit Kommentaren

Sie können ein genaues Format für einen Parameter angeben, indem Sie ihn in einen Kommentar einschließen, wie im folgenden Beispiel gezeigt:

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

Explizite Überprüfung auf NULL-Werte

Wenn Sie einen optionalen Parameter angeben, ist ein möglicher Wert, den Sie erwarten sollten, NULL. Da der Vergleich mit NULL zu unvorhersehbaren Ergebnissen führen kann, sollten Sie in Ihre Funktion ausdrücklich eine Überprüfung auf NULL-Werte einbauen. Das folgende Beispiel zeigt eine Beispielsyntax:

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