Analysez les fichiers dans les volumes avec un Genie Agent
Un Genie Agent peut analyser les fichiers non structurés stockés dans les volumes Unity Catalog, tels que les fichiers PDF, Word, les présentations et les images. Un auteur d’agent associe des volumes à l’agent, et les utilisateurs métier posent des questions sur leur contenu ainsi que sur les données structurées de l’agent au cours d’une seule et même conversation.
Aperçu
Cette fonctionnalité est en préversion publique. Les administrateurs de workspace peuvent contrôler l’accès à Analyser des fichiers dans des volumes avec des agents Genie à partir de la page Préaperçus . Consultez Gérer les aperçus Databricks.
Les agents Genie étaient auparavant appelés Genie space.
Ce que vous pouvez demander à un agent Genie Agent concernant vos fichiers
En attachant des volumes à un agent, les utilisateurs professionnels peuvent combiner les données de documents tels que les tickets d'assistance, les Logs d'appels de Ventes et les fichiers de politiques avec les données des tables structurées de l'agent. Les utilisateurs peuvent ensuite répondre à des questions telles que :
- Quels problèmes de support prennent le plus de temps à résoudre, et que disent les clients dans les demandes d’escalade ?
- Pourquoi les opportunités de ventes tardives sont-elles bloquées et quelles sont les objections qui apparaissent le plus souvent dans les logs d'appels de ventes ?
- Quelles régions sont sous-performantes, et quelles politiques d’escalade internes s’appliquent ?
Quand utiliser l’analyse de fichiers dans un Genie Agent
Attach volumes to a Genie Agent when you want a specialized agent for a specific domain. Choose a different approach when your needs are broader:
- Utilisez Genie One comme point d’entrée unifié pour toutes les questions concernant vos données structurées. Genie One peut faire appel à un Genie Agent pour répondre à des questions concernant des fichiers.
- Créez un agent personnalisé dans le code avec l'Agent Bricks CLI uniquement lorsque vous avez besoin d'un contrôle précis du comportement de l'agent, tel que la sélection du modèle, la stratégie de découpage ou l'orchestration de plusieurs sous-agents.
- Utilisez l’ upload de fichiers pour intégrer un fichier CSV ou Excel local dans une conversation unique au lieu d’analyser des fichiers stockés dans des volumes.
Comment un agent Genie Agent analyse les fichiers
Lorsqu’un utilisateur pose une question qui nécessite le contexte d’un volume, l’agent Genie Agent récupère le contenu du fichier le plus pertinent pour la question et l’ajoute au contexte de l’agent. L’agent raisonne ensuite sur ce contenu ainsi que sur toute donnée structurée pour générer une réponse avec des citations. Ces citations peuvent pointer vers la page spécifique du fichier source.
L'analyse de fichiers ne s'exécute qu'en mode Agent, qui utilise un raisonnement multi-étapes pour récupérer et analyser les fichiers pertinents. Consultez le mode Agent.
L’agent Genie Agent utilise toujours les autorisations de l’utilisateur qui pose la question. Si un utilisateur ne dispose pas d’au moins l’autorisation READ VOLUME sur certains des volumes attachés, l’agent répond en utilisant uniquement les volumes accessibles à l’utilisateur. Voir Gérer les objets de données. Les utilisateurs peuvent poser des questions sur un volume spécifique, sur plusieurs volumes et sur des données structurées au cours de la même conversation.
Exigences
Les exigences suivantes s’appliquent à l’agent et à ses utilisateurs :
- Unity Catalog activé dans votre Workspace.
- Le mode Agent est disponible dans votre région. Découvrez les services désignés de Databricks : services désignés Databricks.
- Un Genie Agent bien préparé avec des instructions claires et des métadonnées de table. Voir Organiser un Genie Agent efficace.
- Un ou plusieurs volumes Unity Catalog qui contiennent des fichiers pertinents.
- Au moins une permission
READ VOLUMEsur un volume attaché pour chaque utilisateur qui pose des questions sur ses fichiers. - Lakebase,
ai_parse_documentet APIs du modèle de fondation disponibles dans votre région. Consultez la page Régions prises en charge pour la recherche de contenu.
Attacher des volumes à un Genie Agent
Avant de commencer, veuillez examiner les Exigences.
Pour attacher des volumes à un Genie Agent :
- Ouvrez le Genie Agent auquel vous souhaitez ajouter des fichiers.
- Ouvrez l'onglet Sources , puis cliquez sur Ajouter .
- Sélectionnez un ou plusieurs volumes. Le Genie Agent traite le volume entier. Vous ne pouvez pas joindre un sous-ensemble des dossiers ou des fichiers dans un volume.
- Ajoutez une description claire dans le champ Description . Consultez Optimiser votre agent pour les questions sur les fichiers.
Vous pouvez attacher un volume en tant que source même lorsque son catalogue n'est pas accessible depuis ce Workspace par default, comme un catalogue qui est lié à des workspaces spécifiques.
Lorsque vous attachez un volume, Databricks active automatiquement la recherche de contenu.
How content search works
La recherche de contenu analyse et indexe vos fichiers afin que le Genie Agent puisse analyser un plus grand ensemble de fichiers, s’appuyer sur des passages spécifiques répartis dans de nombreux fichiers et répondre aux questions avec une latence réduite. Pour connaître les limites relatives aux fichiers et aux volumes, consultez la rubrique Limitations.
La recherche de contenu se synchronise automatiquement avec votre volume. Lorsque vous ajoutez, modifiez ou supprimez des fichiers, Databricks met à jour l’index pour refléter vos modifications, afin que l’agent Genie Agent analyse le contenu actuel sans aucune étape manuelle.
Optimisez votre agent pour les questions de fichiers
Après avoir attaché vos volumes, suivez ces recommandations pour aider le Genie Agent à utiliser leur contenu :
- Ajoutez une description claire : Décrivez le contenu du volume, son organisation et la façon dont l’agent doit l’utiliser. L’agent utilise cette description pour récupérer les fichiers pertinents.
- Évitez le contenu dupliqué : attacher plusieurs volumes qui contiennent des informations superposées rend plus difficile pour l’agent de récupérer les documents pertinents. Il en va de même pour les fichiers individuels au sein d'un volume.
- Évitez les fichiers non pertinents : Incluez uniquement les fichiers pertinents pour le domaine de l’agent. Les fichiers non pertinents peuvent perturber l’agent.
- Utilisez des noms de fichiers clairs : Utilisez des noms de fichiers descriptifs afin que l’agent puisse distinguer les fichiers.
Posez des questions sur les fichiers
Pour poser des questions sur les fichiers dans un Genie Agent :
- Ouvrez un Genie Agent auquel des volumes sont attachés.
- Activez le mode Agent dans la boîte de discussion. Vous devez utiliser le mode Agent pour répondre aux questions concernant les fichiers.
- Saisissez une question et envoyez votre invite. Le mode Agent récupère le contexte à partir du volume pertinent, puis génère une réponse une fois l’analyse terminée.
Régions prises en charge pour la recherche de contenu
La recherche de contenu est disponible dans les régions répertoriées dans cette section.
Dans certaines régions, la recherche de contenu ne s’exécute que si un administrateur de compte active le traitement inter-Geo, ce qui permet à Databricks de traiter vos fichiers en dehors du Geo de votre workspace. Voir Activer le traitement inter-Geo.
Regions that don't require cross-Geo processing
La recherche de contenu s’exécute dans la région de votre Workspace pour les régions suivantes :
us-central1(Iowa)us-east4(Virginie)
Regions that require cross-Geo processing
For the following regions, an account admin must enable cross-Geo processing before content search runs:
europe-west3(Francfort)
Limitations
Les limitations suivantes s’appliquent :
-
Vous pouvez attacher un maximum de 10 volumes à un Genie Agent.
-
Pour utiliser du contenu provenant de sources externes comme Google Drive ou SharePoint, connectez plutôt des connecteurs MCP. Voir Connecter un agent Genie Agent à des outils et sources MCP.
-
Chaque utilisateur de l’agent doit disposer à la fois du droit Workspace access et du droit Databricks SQL access . Voir Droits d’accès.
-
Pendant la preview publique, les utilisateurs disposant uniquement d’un compte ne peuvent pas utiliser cette fonctionnalité. Voir Accès des utilisateurs disposant uniquement d’un compte à Genie One.
-
Seuls les volumes gérés par Unity Catalog prennent en charge la recherche de contenu. Les volumes externes et les volumes Mes fichiers ne sont pas pris en charge. Voir Stocker des fichiers dans Mes fichiers.
-
Chaque workspace peut comporter jusqu’à 250 volumes associés à des Genie Agents.
-
Chaque volume indexé peut contenir jusqu’à 10 000 fichiers. Pour utiliser un volume plus grand, activez les événements de fichier. Voir Utiliser des volumes avec plus de 10 000 fichiers.
-
La recherche de contenu ignore les fichiers de plus de 100 Mo et les fichiers comptant plus de 500 pages.
-
La recherche de contenu prend en charge les fichiers PDF, JPG, JPEG, PNG, TIFF, TIF, DOC, DOCX, PPT, PPTX, MD ou TXT. Tous les autres types de fichiers sont ignorés.
Utilisez des volumes avec plus de 10 000 fichiers
Sans événements de fichier, la recherche de contenu prend en charge les volumes gérés par Unity Catalog avec jusqu'à 10 000 fichiers. Pour utiliser un volume géré contenant plus de 10 000 fichiers, activez les événements de fichier sur l'emplacement externe qui contient le volume. Les événements de fichier permettent à la recherche de contenu de détecter les fichiers nouveaux, modifiés et supprimés via des notifications de stockage cloud, au lieu d'analyser le stockage de manière répétée. Pour en savoir plus sur les événements de fichier et leur fonctionnement, consultez la FAQ sur les événements de fichier.
La configuration comprend les étapes suivantes :
- Trouvez l'emplacement externe qui contient votre volume.
- Activez les événements de fichier pour cet emplacement externe et testez la connexion.
- Si le test échoue, configurez les autorisations cloud nécessaires aux événements de fichiers. Consultez Configuration des événements de fichiers pour un emplacement externe.
Vous pouvez ignorer cette configuration dans les cas suivants :
- Votre volume utilise le stockage par default. Pour vérifier, ouvrez le volume dans l’ Explorateur de catalogue et accédez à l’onglet Détails tab. Si l’ Emplacement de stockage est le Stockage default , vous pouvez ignorer cette configuration.
- Les événements de fichier sont déjà activés et fonctionnent sur l'emplacement externe qui contient votre volume. Pour trouver l'emplacement externe et vérifier son état, voir Étape 1 : Trouver l'emplacement externe qui contient votre volume.
Étape 1 : Trouvez l'emplacement externe qui contient votre volume
Autorisations requises :
USE CATALOGsur le catalogue qui contient le volume.USE SCHEMAsur le schéma qui contient le volume.READ METADATAsur le volume.READ VOLUME,MANAGEou la propriété du volume vous permettent également d'afficher ses métadonnées.READ METADATAsur chaque emplacement externe que vous devez inspecter.MANAGE, la propriété de l’emplacement externe ou l’accès administrateur au métastore sont également qualifiés.
- Catalog Explorer
- Python SDK
-
Dans la barre latérale, cliquez sur
Catalogue .
-
Ouvrez le volume que votre agent Genie Agent utilise. Dans le Détails tab, recherchez Emplacement de stockage et copiez le chemin cloud. Vous l’utilisez pour trouver l’emplacement externe correspondant. Par exemple :
gs://bucket-1/6c55cf12…/volumes/de8e8205… -
Cliquez sur Connecter > Emplacements externes .
-
Trouvez l’emplacement externe dont l’URL est le début du chemin de stockage du volume.
Par exemple, un emplacement externe sur
gs://bucket-1/6c55cf12…couvre un volume géré stocké surgs://bucket-1/6c55cf12…/volumes/de8e8205…. -
Ouvrez le tab Présentation de l'emplacement externe correspondant et cochez Activer les événements de fichier . S'il affiche Activé , cliquez sur Tester la connexion pour confirmer que les événements de fichier fonctionnent. Si le test réussit, vous n'avez pas besoin des étapes 2 et 3. En cas d'échec, passez à l'étape 3.
Exécutez le code suivant dans un notebook. Remplacez <catalog>.<schema>.<volume> par le nom complet de votre volume. Ces extraits nécessitent une version récente du SDK Databricks pour Python. Si vous obtenez un ImportError ou AttributeError, exécutez %pip install --upgrade databricks-sdk, puis exécutez dbutils.library.restartPython().
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
# Storage location of the volume
print(w.volumes.read("<catalog>.<schema>.<volume>").storage_location)
# External locations that you can access
for location in w.external_locations.list():
print(location.name, location.url)
Recherchez l'emplacement externe dont l'URL est le début de l'emplacement de stockage du volume.
Si l’emplacement externe correspondant est __databricks_managed_storage_location, le volume utilise le stockage default et vous n’avez pas besoin de cette configuration.
Si vous avez trouvé un emplacement externe correspondant, vérifiez si les événements de fichier sont activés :
print(w.external_locations.get("<external-location-name>").effective_enable_file_events)
Si la commande affiche True, cliquez sur Tester la connexion sur l’emplacement externe dans l’Explorateur de catalogue pour confirmer que les événements de fichier fonctionnent. Si le test est réussi, vous n’avez pas besoin des étapes 2 et 3. En cas d’échec, passez à l’ étape 3. Si la commande affiche False ou None, passez à l’étape 2.
Si aucun emplacement externe ne correspond, il est possible que vous n’y ayez pas accès. La liste n’affiche que les emplacements externes auxquels vous avez accès. Demandez à votre administrateur de métastore ou au propriétaire de l’emplacement externe de vérifier. Si le volume utilise le stockage racine du métastore sans emplacement externe, vous ne pouvez pas activer les événements de fichier tant qu’il n’existe pas. La suppression du stockage au niveau du métastore en crée un, mais après cela, chaque nouveau catalogue doit avoir son propre emplacement de stockage. Voir Supprimer le stockage au niveau du métastore.
Sur le tab Présentation de l'emplacement externe dans Catalog Explorer , notez le nom des informations d'identification de stockage dans la ligne Informations d'identification . Vous avez besoin de ce nom pour les autorisations de l'étape 2 et la configuration cloud de l'étape 3.
Étape 2 : Activer les événements de fichier et tester la connexion
Utilisez l’emplacement externe et les informations d’identification de stockage que vous avez trouvés à l’étape 1.
Autorisations requises : les administrateurs de Metastore peuvent effectuer cette étape. Dans le cas contraire, vous avez besoin des deux éléments suivants :
MANAGEsur l'emplacement externe, ou la propriété de l'emplacement externe.MANAGEsur les informations d'identification de stockage, la propriété des informations d'identification ouCREATE EXTERNAL LOCATIONsur les informations d'identification et sur le metastore qui contient l'emplacement externe.
- Catalog Explorer
- Python SDK
- Accédez à l'emplacement externe dans l'Explorateur de catalogue . Cliquez sur le menu kebab
à côté de Tester la connexion et sélectionnez Modifier .
- Développez Options avancées . Activez Activer les événements de fichier et définissez Type d'événement de fichier sur Automatique .
- Cliquez sur Mettre à jour . Si la validation échoue et que l'on vous demande de forcer la mise à jour, annulez et continuez avec l'étape 3. Une mise à jour forcée laisse les événements de fichier activés, mais ils ne fonctionneront pas.
- Attendez quelques secondes, puis cliquez sur Tester la connexion pour confirmer que les événements de fichier fonctionnent. Si le test échoue et que les événements de fichier étaient désactivés avant cette étape, désactivez à nouveau Activer les événements de fichier afin que les Trigger d’arrivée de fichier sur cet emplacement continuent de fonctionner. Passez ensuite à l’ étape 3.
Exécutez le code suivant dans un notebook. Remplacez <external-location-name> par l'emplacement externe de l'étape 1.
Pour un emplacement externe sur GCS :
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import GcpPubsub, FileEventQueue
w = WorkspaceClient()
w.external_locations.update(
name="<external-location-name>",
enable_file_events=True,
file_event_queue=FileEventQueue(managed_pubsub=GcpPubsub()),
)
Cliquez ensuite sur Tester la connexion dans l’Explorateur de catalogues pour confirmer que les événements de fichier fonctionnent. Si update déclenche une erreur de validation, continuez avec l’ étape 3. Si le test échoue et que les événements de fichier étaient désactivés avant cette étape, désactivez-les à nouveau afin que les Trigger d’arrivée de fichier sur cet emplacement continuent de fonctionner, puis continuez avec l’étape 3 :
w.external_locations.update(name="<external-location-name>", enable_file_events=False)
Étape 3 : Configurer les autorisations cloud
Effectuez cette étape si le test de connexion a échoué à l’étape 1 ou à l’étape 2, ou si la validation des événements de fichier a échoué lorsque vous avez cliqué sur Mettre à jour à l’étape 2.
Suivez les instructions Configurer les événements de fichier pour un emplacement externe pour obtenir les instructions complètes de configuration cloud. Les remarques et exemples suivants vous aideront à identifier les autorisations et les ressources cloud nécessaires pour votre emplacement externe.
Autorisations requises : Autorisation d’accéder à l’identité cloud utilisée par vos informations d’identification de stockage et de modifier les paramètres de stockage requis par le guide. Si vous n’avez pas cet accès, demandez à votre administrateur cloud.
Pour trouver cette identité cloud, ouvrez l’ tab Présentation de l’emplacement externe dans l’Explorateur de catalogue et cliquez sur le nom dans la ligne Informations d’identification pour afficher les détails des informations d’identification de stockage.
Si un administrateur cloud effectue la modification, fournissez-lui l’URL de l’emplacement externe et les détails de ses informations d’identification de stockage afin qu’il puisse identifier les ressources et l’identité cloud appropriées.
Par exemple, pour un emplacement externe sur GCS avec l'URL gs://bucket-1/6c55cf12…, le nom du bucket est bucket-1.
Attribuez au compte de service de la SGC des informations d'identification de stockage un rôle personnalisé avec les autorisations suivantes :
pubsub.subscriptions.consume
pubsub.subscriptions.create
pubsub.subscriptions.delete
pubsub.subscriptions.get
pubsub.subscriptions.list
pubsub.subscriptions.update
pubsub.topics.attachSubscription
pubsub.topics.detachSubscription
pubsub.topics.create
pubsub.topics.delete
pubsub.topics.get
pubsub.topics.list
pubsub.topics.update
storage.buckets.update
Accordez ensuite au service agent Cloud Storage le rôle Éditeur Pub/Sub . Pour trouver le service agent, consultez Obtenir le service agent Cloud Storage.
Après avoir terminé la configuration cloud du guide pour l'installation automatique, revenez à l'étape 2 pour activer les événements de fichier et tester la connexion.
Questions fréquemment posées
Les questions suivantes couvrent les sujets courants pour l'analyse des fichiers dans les volumes.
Comment cette fonctionnalité est-elle facturée ?
Databricks charges for the following:
- Preparing files : When Databricks enables content search or syncs a volume, it parses your files with the
ai_parse_documentAI function, which is billed under AI Functions Tarifs. - Answering questions : The agent's reasoning over your files is billed as part of standard Genie usage. See Genie Tarifs.
Puis-je analyser des fichiers dans des volumes via l'API ?
Oui. Vous pouvez analyser des fichiers dans des volumes via les APIs du mode Agent. Consultez la référence de l’API du mode Agent.
Comment puis-je utiliser des volumes avec plus de 10 000 fichiers ?
Pour utiliser un volume géré par le Unity Catalog contenant plus de 10 000 fichiers, activez les événements de fichier sur l’emplacement externe qui contient le volume. Voir Utiliser des volumes avec plus de 10 000 fichiers.
Ressources supplémentaires
Voir les ressources suivantes pour des informations connexes :