Utiliser des ressources approuvées dans les espaces AI/BI Genie

Cet article définit les ressources approuvées et explique comment les utiliser pour fournir des réponses vérifiées dans un espace Genie.

Que sont les ressources approuvées ?

Les ressources approuvées sont des fonctions prédéfinies et des exemples de requêtes destinés à fournir des réponses vérifiées aux questions des utilisateurs que vous anticipez. Lorsqu’un utilisateur envoie une question qui appelle une ressource approuvée, il est indiqué dans la réponse, en ajoutant une couche supplémentaire d’assurance à la précision des résultats.

Voici des exemples de ressources approuvées :

• Exemples de requêtes SQL paramétrables : lorsqu’une requête SQL paramétrable est utilisée pour générer une réponse, la réponse est étiquetée comme ressource approuvée. La réponse inclut les valeurs utilisées comme arguments dans la requête. Les utilisateurs peuvent modifier la valeur du paramètre dans la réponse.
• Fonctions de table définies par l’utilisateur (UDF) : vous pouvez définir des fonctions personnalisées et les inscrire auprès Unity Catalog. Ensuite, vous pouvez ajouter ces fonctions en tant que ressources approuvées lorsque vous configurez des instructions dans votre espace Génie. Consultez Créer une fonction de table SQL et Fonctions définies par l’utilisateur (UDF) dans Unity Catalog.

Remarque

Les ressources approuvées ne remplacent pas toutes les autres instructions. Databricks recommande d’utiliser des ressources approuvées pour des questions récurrentes bien établies. Elles fournissent des réponses exactes à des questions spécifiques.

Pourquoi créer des ressources approuvées ?

Lorsqu’ils utilisent un outil IA, les utilisateurs doivent évaluer la précision des réponses générées. En règle générale, ils font cela en évaluant si la réponse est logique et répond efficacement à leur question. Avec Genie, une réponse est fournie sous la forme d’une table de résultats. Les utilisateurs peuvent passer en revue le code SQL généré qui crée le jeu de résultats, mais les utilisateurs non techniques peuvent ne pas avoir l’arrière-plan pour interpréter l’instruction SQL ou évaluer la justesse de la réponse. Les ressources approuvées permettent de réduire la probabilité que ces utilisateurs rencontrent des réponses trompeuses, incorrectes ou difficiles à interpréter.

Lorsqu’un utilisateur reçoit une réponse étiquetée comme approuvée, cela signifie qu’un expert de domaine a ajouté l’instruction SQL utilisée pour générer les résultats en tant qu’instruction dans l’espace.

Quelle est la différence entre les ressources approuvées et les exemples de requêtes SQL ?

Les ressources approuvées fournissent des réponses vérifiées aux questions auxquelles vous vous attendez de la part des utilisateurs de l’espace Genie. Lorsqu’une ressource approuvée peut répondre à la question d’un utilisateur, l’instruction que vous avez stockée en tant que ressource approuvée s’exécute et retourne le jeu de résultats spécifié. Toutes les fonctions SQL que vous incluez dans les instructions sont traitées comme des ressources approuvées. Les exemples de requêtes SQL qui incluent des paramètres peuvent également être traités comme des ressources approuvées.

• Fonctions SQL : vous pouvez écrire des fonctions SQL personnalisées adaptées pour gérer vos données et répondre à des questions spécifiques à l’entreprise. Genie ne considère pas le contenu SQL de vos ressources approuvées lors de la réponse aux questions.
• Exemples de requêtes SQL (avec paramètres) : lorsqu’un exemple paramétrable de texte exact de la requête est utilisé pour générer une réponse, la réponse est automatiquement étiquetée comme approuvée. Les utilisateurs d’espace peuvent modifier la valeur du paramètre dans une réponse et réexécuter la requête à l’aide de la nouvelle valeur.

Remarque

Si le texte exact de la requête n’est pas utilisé ou si l’exemple de requête n’utilise pas de paramètres, la requête fournit un contexte et guide Genie dans la génération des instructions SQL, mais n’est pas marquée comme approuvée.

Définir une ressource approuvée

La définition d’une ressource approuvée commence par identifier une question probable. Par exemple, supposons que vous travaillez avec un jeu de données de pipeline de vente et qu’une question courante qu’un responsable des ventes peut poser est « Quelles sont les opportunités de vente ouvertes dans ma région ? »

Exemple : Créer une fonction UDF pour répondre à la question

Les étapes suivantes décrivent comment écrire une requête de test et l’utiliser pour créer une fonction UDF :

1. Utilisez l’éditeur SQL ou un notebook pour définir et tester une requête SQL qui répond à la question.

Cette requête joint deux tables et retourne un jeu de données d’opportunités ouvertes répertoriées dans la “Pipeline” catégorie prévision. Dans cette étape, l’objectif est d’écrire une requête de base qui retourne les résultats attendus.

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. Définissez une fonction de catalogue Unity.

Votre fonction Unity Catalog doit paramétrer la requête et produire des résultats correspondant aux conditions spécifiques auxquelles vous vous attendez de la part des utilisateurs. Par exemple, supposons que le responsable des ventes souhaite affiner le jeu de résultats en se concentrant sur une région ou un groupe particulier de régions.

L’exemple suivant définit une fonction Unity Catalog qui prend une liste de régions en tant que paramètre et retourne une table. Le retour de la fonction est presque identique à l’instruction SQL de l’étape précédente, sauf que la clause WHERE a été modifiée pour filtrer les résultats par région si une région a été fournie. Les commentaires fournis dans les définitions de fonction sont essentiels pour indiquer à l’espace Génie quand et comment appeler cette fonction.

• Commentaires de paramètre : la fonction open_opps_in_region attend un tableau de chaînes en tant que paramètre. Le commentaire inclut un exemple de l’entrée attendue. Si aucun paramètre n’est fourni, la valeur par défaut est NULL. Consultez Conseils pour écrire des fonctions pour plus d’informations sur l’inclusion de paramètres et de commentaires facultatifs.
• Commentaires de fonction : le commentaire dans la fonction de table SQL fournit une explication détaillée de ce que fait la fonction. Cette explication est essentielle, car elle informe Genie quand utiliser la fonction comme réponse aux questions des utilisateurs. Le commentaire doit décrire l’objectif de la fonction aussi précisément que possible. Ces informations guideNt Genie dans la reconnaissance de la pertinence de la fonction à des questions spécifiques.

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

Lorsque vous exécutez le code pour créer une fonction, il est inscrit au schéma actif par défaut. Consultez les Fonctions définies par l’utilisateur (UDF) dans Unity Catalog. Consultez Créer une fonction de table SQL pour obtenir une syntaxe et des exemples.

1. Ajoutez une ressource approuvée.

   Une fois que la fonction est créée dans Unity Catalog, un utilisateur disposant au moins d’une autorisation CAN EDIT sur l’espace Genie peut l’ajouter depuis l’onglet Instructions de l’espace Genie.

Autorisations requises

Les utilisateurs disposant au moins d’une autorisation CAN EDIT sur un espace Genie peuvent ajouter ou supprimer des ressources approuvées.

Les utilisateurs de l’espace Genie doivent disposer de l’autorisation CAN USE sur le catalogue et le schéma qui contient la fonction. Pour invoquer une ressource approuvée, ils doivent disposer de l’autorisation EXECUTE sur la fonction dans Unity Catalog. Les objets sécurisables du catalogue Unity héritent des autorisations de leurs conteneurs parents. Consultez Objets sécurisables dans le catalogue Unity.

Pour simplifier le partage dans un espace Genie, Databricks recommande de créer un schéma dédié pour contenir toutes les fonctions que vous souhaitez utiliser dans votre espace Genie.

Conseils pour écrire des fonctions

Passez en revue les exemples suivants pour découvrir comment créer des fonctions dynamiques pour les ressources approuvées.

Inclure une valeur de paramètre par défaut

Vous pouvez spécifier une valeur par défaut pour un paramètre. Utilisez la clause DEFAULT dans la signature de fonction, comme indiqué dans l’exemple suivant :

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

Inclure des exemples de valeurs de paramètres

Pour les colonnes avec une énumération définie de valeurs, augmentez la précision en les définissant clairement dans le commentaire. L’exemple suivant fournit une liste d’exemples de valeurs :

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

Créer un paramètre facultatif

Pour créer un paramètre facultatif, définissez le paramètre par défaut sur NULL, comme indiqué dans l’exemple suivant :

min_date STRING DEFAULT NULL

Spécifier la mise en forme avec des commentaires

Vous pouvez spécifier le format exact d’un paramètre en l’incluant dans un commentaire, comme illustré dans l’exemple suivant :

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

Vérifier explicitement les valeurs NULL

Si vous incluez un paramètre facultatif, NULL est une valeur possible à laquelle vous devez vous attendre. Étant donné que la comparaison avec NULL peut générer des résultats imprévisibles, vous devez générer explicitement une vérification des valeurs NULL dans votre fonction. L’exemple suivant fournit un exemple de syntaxe :

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