Ajouter une ressource Genie Agent à une application Databricks

Ajoutez des agents Genie en tant que ressources Databricks Apps pour activer l’interrogation en langage naturel dans vos applications. Les agents Génie fournissent une interface conversationnelle pour l’exploration des données, ce qui permet aux utilisateurs de poser des questions professionnelles en anglais brut et de recevoir des insights sql de vos jeux de données organisés.

Quand vous ajoutez un Agent Genie en tant que ressource, votre application peut :

  • Convertir des requêtes en langage naturel provenant des utilisateurs en SQL
  • Accéder au contexte et aux métadonnées métier préconfigurés
  • Utiliser des exemples de requêtes organisés et des définitions de données
  • Générer des réponses en fonction des jeux de données de votre organisation

Ajouter une ressource Genie Agent

Avant d’ajouter un Agent Genie en tant que ressource, passez en revue les conditions préalables à la ressource d’application.

  1. Dans la section Ressources de l’application, lorsque vous créez ou modifiez une application, cliquez sur + Ajouter une ressource>Genie Agent.
  2. Choisissez un Agent Genie dans la liste des espaces disponibles dans votre espace de travail.
  3. Sélectionnez le niveau d’autorisation de votre application :
    • Peut afficher : Octroie à l’application l’autorisation de lire la configuration et les métadonnées de l’Agent Genie.
    • Peut s’exécuter : Octroie à l’application l’autorisation d’envoyer des requêtes à l’Agent Genie et de recevoir des réponses.
    • Peut modifier : Octroie à l’application l’autorisation de modifier la configuration de l’agent Genie.
    • Peut gérer : Accorde à l’application un accès administratif complet à l’agent Genie.
  4. (Facultatif) Spécifiez une clé de ressource personnalisée, c’est-à-dire la façon dont vous référencez l’agent Genie dans la configuration de votre application. La clé par défaut est genie-space.

Lorsque vous ajoutez une ressource Génie Agent :

  • Azure Databricks accorde au principal de service de votre application les autorisations spécifiées sur l'agent Genie sélectionné.
  • L’application peut envoyer des requêtes en langage naturel à l’agent et recevoir des réponses structurées avec des requêtes et des résultats SQL.
  • L’application accède au contexte métier organisé de l’agent, notamment les métadonnées, les exemples de requêtes et les définitions de données.
  • L’accès est limité à l’agent sélectionné uniquement. Votre application ne peut pas accéder à d’autres agents Genie, sauf si vous les ajoutez en tant que ressources distinctes.

Note

Le principal de service de l’application a également besoin d’autorisations appropriées sur les sources de données sous-jacentes que l’agent Genie interroge. Cela inclut généralement USE CATALOG, USE SCHEMA et SELECT les autorisations sur les tables et vues pertinentes du Unity Catalog.

Variables d’environnement

Lorsque vous déployez une application avec une ressource Genie Agent, Azure Databricks expose l’ID d’espace via des variables d’environnement que vous pouvez référencer à l’aide du valueFrom champ dans votre app.yaml configuration.

Exemple de configuration :

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space # Use your custom resource key if different

Utilisation de l’ID d’espace dans votre application :

import os
from databricks.sdk import WorkspaceClient

# Access the Genie Agent using the injected environment variable
space_id = os.getenv("GENIE_SPACE_ID")

# Initialize the workspace client
w = WorkspaceClient()

# Start a conversation with a natural language query
response = w.genie.start_conversation_and_wait(
    space_id=space_id,
    content="What were our top-selling products last quarter?"
)

# Process the response (responses contain attachments with text, queries, and so on)
for attachment in response.attachments:
    print(f"Genie response: {attachment.text.content}")

# Continue the conversation with additional questions
follow_up = w.genie.create_message_and_wait(
    space_id=space_id,
    conversation_id=response.conversation_id,
    content="Can you break that down by product category?"
)

Pour plus d’informations, consultez Les variables d’environnement Access à partir de ressources.

Supprimer une ressource Genie Agent

Lorsque vous supprimez une ressource d’agent Genie d’une application, le principal de service de l’application perd l’accès à cet agent. L’agent Genie lui-même reste inchangé et continue d’être disponible pour d’autres utilisateurs et applications disposant d’autorisations appropriées.

Combiner des agents Genie avec d’autres ressources d’application

Combinez les agents Genie avec d’autres ressources Databricks Apps pour créer des applications de données plus sophistiquées. Les modèles d’intégration courants sont les suivants :

Tableau de bord d’analytique du langage naturel

Utilisez les ressources suivantes ensemble pour exécuter des analyses interactives :

  • Agent Genie : Convertit les questions utilisateur en requêtes SQL
  • SQL Warehouse : Exécute les requêtes et retourne des résultats pour la visualisation
  • Secrets: Stocke les clés API pour les outils de visualisation externes

Exemple de configuration :

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space
  - name: SQL_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: EXTERNAL_API_KEY
    valueFrom: viz-secret

Intelligence décisionnelle améliorée par l’IA

Utilisez les ressources suivantes pour intégrer des modèles IA :

  • Agent Genie : Génère le contexte initial de requête et de données
  • Interface de service de modèle : Fournit des résumés et des recommandations générés par l’IA
  • SQL Warehouse : Exécute des requêtes analytiques complexes

Autorisations du principal de service

Accordez au principal de service de votre application les autorisations suivantes lors de l’intégration avec d’autres ressources d’application :

  • CAN RUN sur l’agent Genie
  • CAN USE sur l’entrepôt SQL (si vous en utilisez un distinct de celui de l’agent Génie)
  • CAN QUERY sur les endpoints du service de modèle
  • USE CATALOG et USE SCHEMA sur les objets de catalogue Unity pertinents
  • SELECT sur les tables que l'application interroge directement

Meilleures pratiques

Suivez ces bonnes pratiques lorsque vous travaillez avec les ressources de l’Agent Genie :

  • Accordez des autorisations minimales. Fournissez uniquement l’accès aux agents Génie spécifiques dont votre application a besoin pour fonctionner.
  • Assurez-vous que l’agent Genie contient des jeux de données et des métadonnées bien organisés pour améliorer la qualité des réponses aux requêtes en langage naturel.
  • Testez les requêtes de votre application sur l’agent Genie pour vérifier qu’elle peut générer des résultats précis pour les questions utilisateur attendues.
  • Surveillez les performances des requêtes et ajustez les modèles d’interaction de votre application avec l’agent Genie pour optimiser les temps de réponse.
  • Implémentez la gestion des erreurs pour les cas où l’agent Genie ne peut pas interpréter ou répondre efficacement aux requêtes utilisateur.
  • Last updated on