Dépannage des Agents Genie

Résolvez les problèmes courants lors de la création et de la maintenance d’un Genie Agent : jargon métier incompris, utilisation incorrecte des tables ou des colonnes, erreurs de filtrage sur des valeurs spécifiques et troncation due à la limite de jetons dans les longues conversations. Chaque section ci-dessous traite du symptôme, de la cause et du correctif.

remarque

Les agents Genie étaient auparavant appelés Genie space.

Pour un grand nombre de ces problèmes, le chemin le plus rapide vers une solution est Genie Code. Décrivez le problème à Genie Code, et il suggère des changements de contexte que vous pouvez examiner et accepter. Pour diagnostiquer une seule réponse incorrecte, consultez Déboguer les réponses avec Genie Code. Pour examiner ensemble les échecs de benchmark, consultez Analyser une exécution de benchmark avec Genie Code.

Jargon métier mal compris

La plupart des entreprises ou des domaines ont une terminologie spécifique qu'ils utilisent pour communiquer sur des événements commerciaux spécifiques. Par exemple, lorsqu’il est fait référence à une année, il peut toujours s’agir de l’exercice fiscal, et cet exercice fiscal peut start en février ou en mars au lieu de janvier. Pour permettre à Genie de répondre à ces questions de manière naturelle et précise, incluez des instructions qui associent explicitement votre jargon métier aux mots et concepts que Genie peut comprendre. Consultez les instructions fournies.

Utilisation incorrecte de la table ou de la colonne

Si Genie tente d'extraire des données d'une table incorrecte ou d'exécuter une analyse sur des colonnes incorrectes, vous pouvez ajuster les données de l'une des manières suivantes :

• Fournissez des descriptions claires et précises : Vérifiez vos tables et les métadonnées associées pour vous assurer que la terminologie qui y est utilisée correspond à la terminologie des utilisateurs dans les questions soumises. Si ce n'est pas le cas, affinez la description ou ajoutez une instruction qui mappe la terminologie utilisée dans la table à la terminologie utilisée dans la question.
• Ajoutez des exemples de requêtes : Fournissez des exemples de requêtes SQL que Genie peut utiliser pour apprendre à répondre à certaines questions. Voir Fournir des instructions.
• **Supprimer des tables ou des colonnes de l’agent** : Certaines tables peuvent inclure des colonnes ou des concepts qui se chevauchent, ce qui peut empêcher Genie de savoir quelles données utiliser dans une réponse. Si possible, veuillez supprimer les tables ou colonnes inutiles ou redondantes. Pour masquer les colonnes de l’interface utilisateur de l’agent Genie sans modifier les objets de données sous-jacents, consultez Masquer ou afficher les colonnes pertinentes.

Filtrage des erreurs

Les query générées incluent souvent une clause WHERE pour filtrer les résultats en fonction d'une valeur spécifique. Lorsque Genie n'a pas de visibilité sur les valeurs des données, il peut définir la clause WHERE pour filtrer la mauvaise valeur. Par exemple, il peut tenter de correspondre au nom « California » lorsque la table utilise des abréviations comme « CA. »

Pour des situations comme celle-ci, vérifiez que les colonnes pertinentes ont les **Valeurs d'exemple** et les **Dictionnaires de valeurs** activés. Si de nouvelles données ont été ajoutées aux tables pertinentes, refresh les valeurs. Consultez Vue d'ensemble de la correspondance d'invite.

Jointures incorrectes

Si les références de clés étrangères ne sont pas définies dans Unity Catalog, votre agent pourrait ne pas savoir comment joindre différentes tables entre elles.

Veuillez essayer de mettre en œuvre une ou plusieurs des solutions suivantes :

• Définissez les références de clés étrangères dans votre Unity Catalog lorsque cela est possible. Consulter la clause de contrainte.
• Si les relations de clé étrangère de vos tables ne sont pas spécifiées dans Unity Catalog, définissez les relations de jointure dans le magasin de connaissances de votre Genie Agent. Cette stratégie est utile pour les scénarios de jointure plus complexes, tels que les auto-jointures, ou si vous n'avez pas l'autorisation suffisante pour modifier les tables sous-jacentes. Consultez Définir les relations de jointure.
• Fournissez des exemples de queries où vous joignez des tables de manière standard.

Si aucune de ces solutions ne résout le problème, pré-joignez la table dans une vue et utilisez cela comme entrée pour l'agent à la place.

Les commentaires de colonne ne se synchronisent pas à partir des tables étrangères

Databricks ne gère pas les métadonnées, les données ou la sémantique pour les écritures dans les tables étrangères. Selon la table source, les commentaires pourraient ne pas être accessibles depuis Databricks. Pour rendre les commentaires disponibles, Databricks vous recommande d'effectuer l'une des opérations suivantes :

• Modifiez les métadonnées de colonne dans l'IU de Genie Agent. Les métadonnées modifiées ne s'appliquent qu'à l'Genie Agent où elles sont écrites. Voir Modifier les métadonnées de colonne.
• Créez des vues matérialisées à partir de tables fédérées. Vous pouvez ajouter et modifier des commentaires sur une vue matérialisée comme vous le feriez sur une table gérée. Vous pouvez réutiliser cette vue sur plusieurs agents Genie. Pour plus de détails sur le chargement de données depuis des tables étrangères vers une vue matérialisée, veuillez consulter Charger des données depuis des tables étrangères avec des vues matérialisées. Pour en savoir plus sur l'utilisation des vues matérialisées, consultez Vues matérialisées.

Problèmes de calcul de métriques

La manière dont les métriques sont calculées et agrégées peut être arbitrairement compliquée et englober de nombreux détails commerciaux que votre agent ne comprend pas. Cela peut entraîner des rapports incorrects.

Veuillez essayer de mettre en œuvre une ou plusieurs des solutions suivantes :

• Définissez vos métriques en tant qu'expressions SQL dans le magasin de connaissances. Les expressions SQL fournissent des définitions réutilisables et précises pour les mesures, les filtres et les dimensions que Genie peut appliquer de manière cohérente. Voir Définir les expressions SQL.
• Si vos métriques sont agrégées à partir de tables de base, fournissez des exemples de requêtes SQL calculant chaque valeur agrégée.
• Si vos métriques ont été pré-calculées et se trouvent dans des tables agrégées, expliquez cela dans les commentaires de la table. Spécifiez les agrégations valides pour chaque métrique si les métriques de cette table peuvent être regroupées davantage.
• Si le SQL que vous essayez de générer est très compliqué, essayez de créer des vues qui ont déjà agrégé vos métriques pour votre agent.

Calculs incorrects basés sur le temps

Genie pourrait ne pas toujours être en mesure d'inférer le fuseau horaire représenté dans les données ou le fuseau horaire dans lequel votre analyse doit être effectuée, sauf si vous fournissez des indications supplémentaires de manière explicite.

Incluez des instructions plus explicites détaillant le fuseau horaire source d'origine, la fonction de conversion et le fuseau horaire cible. Les exemples suivants montrent comment modifier les instructions générales pour des conversions de fuseaux horaires plus fiables :

• Toujours convertir les heures vers un fuseau horaire spécifique : dans cet exemple, supposez que le timestamp source est UTC et que vous souhaitez des résultats dans le fuseau horaire America/Los_Angeles. Ajoutez ce qui suit aux instructions, en remplaçant <timezone-column> par le nom de colonne approprié :

  • Les fuseaux horaires des tables sont en UTC.
  • Convertir tous les fuseaux horaires en utilisant la fonction suivante : convert_timezone('UTC', 'America/Los_Angeles', <timezone-column>).

• Convertir les formats de date-heure non-UTC en UTC : Si le fuseau horaire par défaut du workspace est UTC, mais que les utilisateurs à Los Angeles doivent faire référence à aujourd'hui pour un ensemble spécifique d'enregistrements, ajoutez ce qui suit aux instructions générales de l'agent :

  • Pour faire référence à aujourd'hui , utilisez date(convert_timezone('UTC', 'America/Los_Angeles', current_timestamp())).

Consultez la convert_timezone fonction pour plus de détails et la syntaxe.

Ignorer les instructions

Même si vous avez expliqué vos tables et colonnes dans les commentaires et fourni des instructions générales, votre agent pourrait ne pas les utiliser correctement.

Essayez une ou plusieurs des stratégies suivantes :

• Fournissez des exemples de requêtes qui utilisent correctement vos tables. Les query d'exemple sont particulièrement efficaces pour apprendre à votre agent comment utiliser vos données.
• Masquez les colonnes non pertinentes dans le Genie Agent. Voir Masquer ou afficher les colonnes pertinentes.
• Créez des vues à partir de vos tables qui offrent une vue plus simple de vos données.
• Passez en revue vos instructions et essayez de concentrer l'agent en supprimant les tables ou les instructions non pertinentes.
• Essayez de démarrer une nouvelle discussion. Les interactions précédentes pourraient influencer les réponses de Genie dans n'importe quelle discussion, mais démarrer une nouvelle discussion vous donne un point de départ vierge pour tester de nouvelles instructions.

Problèmes de performance

Lorsque Genie doit générer des queries ou des réponses textuelles exceptionnellement longues, la réponse peut prendre beaucoup de temps, voire expirer pendant la phase de réflexion.

Essayez une ou plusieurs des actions suivantes pour améliorer les performances :

• Vérifiez l'historique des requêtes pour identifier les requêtes à exécution lente. De nombreux problèmes de performance peuvent être résolus en optimisant les requêtes SQL générées plutôt qu'en modifiant la configuration du Genie Agent. Passez en revue les temps d'exécution des requêtes et les plans de requête dans l'historique des requêtes de votre SQL Warehouse pour identifier les goulots d'étranglement et les opportunités d'optimisation.
• Utilisez des assets de confiance ou des vues pour encapsuler les requêtes complexes. Voir Assets de confiance.
• Réduisez la longueur de vos exemples de requêtes SQL chaque fois que possible.
• start un nouveau chat si Genie commence à générer des réponses lentes ou échouées.

Réponses peu fiables aux questions critiques pour la mission

Utilisez des assets fiables pour fournir des réponses vérifiées aux questions spécifiques que vous vous attendez à ce que les utilisateurs posent. Voir Assets de confiance.

Avertissement de limite de jeton

Les jetons sont les unités de texte de base que Genie utilise pour traiter et comprendre le langage. Les instructions textuelles et les métadonnées d'un Genie Agent sont converties en jetons. Si votre agent approche la limite de jetons, un avertissement apparaît. Genie utilise le filtrage contextuel pour prioriser les jetons qu'il considère les plus pertinents pour une question. Bien que les réponses devraient toujours être générées lorsqu'un avertissement apparaît, la qualité peut être réduite si un contexte important est filtré. Lorsque la limite de jetons est dépassée, vous ne pouvez plus envoyer ni recevoir de messages dans le Genie Agent.

Considérez les pratiques suivantes pour réduire le nombre de jetons :

• Supprimer les colonnes inutiles : Les colonnes inutiles dans vos tables peuvent contribuer de manière significative à l'utilisation des jetons. Lorsque cela est possible, créez des vues pour exclure les champs redondants ou non essentiels de vos tables brutes. Vous pouvez également masquer les colonnes inutiles dans un Genie Agent. Voir Masquer ou afficher les colonnes pertinentes.
• Rationalisez les descriptions de colonne : Bien que les descriptions de colonne soient importantes, évitez de dupliquer les informations déjà véhiculées par les noms de colonne. Par exemple, si une colonne est nommée account_name, une description telle que « le nom de votre compte » pourrait être redondante et peut être omise.
• Modifier les métadonnées de colonne dans le Genie Agent : consultez Modifier les métadonnées de colonne pour savoir comment modifier les descriptions et fournir des synonymes dans les métadonnées de colonne.
• Élaguez les exemples de requêtes SQL : Incluez une gamme variée d'exemples de requêtes SQL pour couvrir divers types de questions, mais supprimez les exemples redondants ou qui se chevauchent.
• **Simplifier les instructions** : Vérifiez que vos instructions sont claires et concises. Évitez les mots inutiles.

Votre compte n'est pas activé pour le traitement inter-géographique

Genie est un service désigné géré par Databricks. Les services désignés utilisent Databricks Geos pour gérer la résidence des données. Les données ne peuvent pas être traitées dans la même Geo que le workspace pour certaines régions. Si votre Workspace se trouve dans l'une de ces régions, le traitement inter-géographique doit être activé par l'administrateur de votre compte.

Le dernier auteur d'agent est supprimé du workspace

Un Genie Agent traite toutes les queries à l'aide des identifiants de compute intégrés par l'auteur qui a configuré le plus récemment le SQL Warehouse de l'agent. Si cet auteur est supprimé du Workspace, ses identifiants intégrés ne sont plus valides, et les queries échouent pour tous les utilisateurs de l’agent.

Pour restaurer l'agent, demandez à un autre utilisateur disposant au moins de l'autorisation CAN EDIT sur l'agent Genie de reconfigurer le SQL Warehouse de l'agent. L'enregistrement d'une sélection de warehouse intègre les identifiants de compute de l'utilisateur qui modifie à la place de ceux de l'auteur supprimé. Consultez Configurer les paramètres.