Partager via

Bibliothèques

  • Article

Pour mettre du code de tiers ou du code personnalisé à la disposition de notebooks et de travaux en cours d’exécution sur vos clusters, vous pouvez installer une bibliothèque. Les bibliothèques peuvent être écrites en Python, Java, Scala et R. Vous pouvez charger des bibliothèques Java, Scala et Python, et pointer vers des packages externes dans des référentiels PyPI, Maven et CRAN.

Azure Databricks comprend de nombreuses bibliothèques courantes dans Databricks Runtime. Pour voir quelles bibliothèques sont comprises dans Databricks Runtime, consultez la sous-section Environnement système des notes de publication de Databricks Runtime pour votre version de Databricks Runtime.

Remarque

Le support Microsoft aide à isoler et résoudre les problèmes liés aux bibliothèques installées et gérées par Azure Databricks. Pour les composants tiers, dont les bibliothèques, Microsoft offre un support raisonnable du point de vue commercial pour vous aider à mieux résoudre les problèmes. Le support Microsoft met tout en œuvre pour vous aider à résoudre le problème. Pour les connecteurs open source et les projets hébergés sur GitHub, nous vous recommandons de consigner les problèmes sur GitHub et de les suivre. Les efforts de développement, tels que la trame de fichiers jar ou la création de bibliothèques Python, ne sont pas pris en charge par le biais du processus d’envoi de cas de support standard : ils demandent une implication consultative pour une résolution plus rapide. Le support peut vous inviter à faire appel à d’autres canaux qui offrent une expertise reconnue dans ces technologies open source. Il existe plusieurs sites communautaires ; la page Microsoft Q&A pour Azure Databricks et Stack Overflow en sont deux exemples.

Bibliothèques à l’échelle d’un cluster

Vous pouvez installer des bibliothèques sur des clusters afin qu’elles puissent être utilisées par tous les notebooks et travaux s’exécutant sur le cluster. Databricks prend en charge les bibliothèques Python, JAR et R. Consultez Bibliothèques de clusters.

Vous pouvez installer une bibliothèque de cluster directement à partir des sources suivantes :

Tous les emplacements ne sont pas pris en charge pour tous les types de bibliothèques ou toutes les configurations de calcul. Consultez Recommandations pour charger des bibliothèques pour obtenir des recommandations en matière de configuration.

Important

Vous pouvez également installer les bibliothèques à partir de DBFS lors de l’utilisation de Databricks Runtime 14.3 LTS et versions antérieures. Toutefois, tout utilisateur de l’espace de travail peut modifier les bibliothèques de codes stockées dans DBFS. Pour améliorer la sécurité des bibliothèques dans un espace de travail Azure Databricks, le stockage des bibliothèques de codes dans la racine DBFS est déconseillé et désactivé par défaut dans Databricks Runtime 15.1 et versions ultérieures. Consultez Le stockage des bibliothèques dans la racine DBFS est déconseillé et désactivé par défaut.

Au lieu de cela, Databricks recommande de charger toutes les bibliothèques, notamment les bibliothèques Python, les fichiers JAR et les connecteurs Spark, dans des fichiers d’espace de travail ou des volumes du catalogue Unity, ou d’utiliser des référentiels de packages de bibliothèques. Si votre charge de travail ne prend pas en charge ces modèles, vous pouvez également utiliser des bibliothèques stockées dans le stockage d’objets cloud.

Pour obtenir des informations complètes sur la prise en charge des bibliothèques, consultez Prise en charge des bibliothèques Python, Prise en charge des bibliothèques Java et Scala et Prise en charge des bibliothèques R.

Recommandations relatives au chargement de bibliothèques

Databricks prend en charge la plupart des installations de configuration de bibliothèques Python, JAR et R, mais il existe certains scénarios non pris en charge. Nous vous recommandons de charger les bibliothèques vers des emplacements sources qui prennent en charge l’installation sur le calcul avec le mode d’accès partagé, car il s’agit du mode recommandé pour toutes les charges de travail. Voir Modes d’accès aux fichiers. Lorsque vous planifiez des travaux avec le mode d’accès partagé, exécutez le travail avec un principal de service.

Important

Utilisez uniquement le calcul avec mode d’accès utilisateur unique si la fonctionnalité requise n’est pas prise en charge par le mode d’accès partagé. Le mode d’accès partagé sans isolation est une configuration héritée sur Databricks qui n’est pas recommandée.

Le tableau suivant fournit des recommandations organisées en fonction de la version Databricks Runtime et de l’activation de Unity Catalog.

Configuration Recommandation
Databricks Runtime 13.3 LTS et version ultérieures avec Unity Catalog Installez les bibliothèques sur le calcul avec mode d’accès partagé à partir de volumes Unity Catalog avec GRANT READ pour tous les utilisateurs de compte.

Le cas échéant, les coordonnées Maven et les chemins de bibliothèque JAR doivent être ajoutés à la liste verte.
Databricks Runtime 11.3 LTS et versions ultérieures sans Unity Catalog Installez les bibliothèques à partir de fichiers d’espace de travail. (La taille maximale de fichier est de 500 Mo.)
Databricks Runtime 10.4 LTS et versions antérieures Installez les bibliothèques à partir de stockage d’objets cloud.

Prise en charge des bibliothèques Python

Le tableau suivant indique la compatibilité de la version de Databricks Runtime pour les fichiers wheel Python pour différents modes d’accès au cluster en fonction de l’emplacement source de la bibliothèque. Consultez Notes de publication sur les versions et la compatibilité de Databricks Runtime et Modes d’accès.

Dans Databricks Runtime 15.0 et versions ultérieures, vous pouvez utiliser des fichiers requirements.txt pour manager vos dépendances Python. Vous pouvez charger ces fichiers sur n’importe quel emplacement source pris en charge.

Remarque

L’installation des fichiers egg Python n’est prise en charge que sur Databricks Runtime 13.3 LTS ou sous, et uniquement pour un seul utilisateur ou pour des modes d'accès partagés sans isolation. En outre, vous ne pouvez pas installer les fichiers Python egg sur des volumes ou des fichiers d’espace de travail. Utilisez des fichiers wheel Python ou installez des packages à partir de PyPI à la place.

Mode d’accès partagé Mode d’accès utilisateur unique Mode d’accès partagé sans isolation (hérité)
PyPI 13.3 LTS et versions ultérieures Toutes les versions de Databricks Runtime prises en charge Toutes les versions de Databricks Runtime prises en charge
Fichiers d’espace de travail 13.3 LTS et versions ultérieures 13.3 LTS et versions ultérieures 14.1 et versions ultérieures
Volumes 13.3 LTS et versions ultérieures 13.3 LTS et versions ultérieures Non pris en charge
Stockage dans le cloud 13.3 LTS et versions ultérieures Toutes les versions de Databricks Runtime prises en charge Toutes les versions de Databricks Runtime prises en charge
DBFS (Non recommandé) Non pris en charge 14.3 et versions antérieures 14.3 et versions antérieures

Prise en charge des bibliothèques Java et Scala

Le tableau suivant indique la compatibilité de la version de Databricks Runtime pour les fichiers JAR pour différents modes d’accès au cluster en fonction de l’emplacement source de la bibliothèque. Consultez Notes de publication sur les versions et la compatibilité de Databricks Runtime et Modes d’accès.

Remarque

Le mode d’accès partagé nécessite qu’un administrateur ajoute des coordonnées Maven et des chemins pour les bibliothèques JAR à un allowlist. Consultez Bibliothèques de listes d’autorisation et scripts d’initialisation sur le calcul partagé.

Mode d’accès partagé Mode d’accès utilisateur unique Mode d’accès partagé sans isolation (hérité)
Maven 13.3 LTS et versions ultérieures Toutes les versions de Databricks Runtime prises en charge Toutes les versions de Databricks Runtime prises en charge
Fichiers d’espace de travail Non pris en charge Non pris en charge 14.1 et versions ultérieures
Volumes 13.3 LTS et versions ultérieures 13.3 LTS et versions ultérieures Non pris en charge
Stockage dans le cloud 13.3 LTS et versions ultérieures Toutes les versions de Databricks Runtime prises en charge Toutes les versions de Databricks Runtime prises en charge
DBFS (Non recommandé) Non pris en charge 14.3 et versions antérieures 14.3 et versions antérieures

Prise en charge des bibliothèques R

Le tableau suivant indique la compatibilité de la version de Databricks Runtime pour les packages CRAN pour différents modes d’accès au cluster. Consultez Notes de publication sur les versions et la compatibilité de Databricks Runtime et Modes d’accès.

Mode d’accès partagé Mode d’accès utilisateur unique Mode d’accès partagé sans isolation (hérité)
CRAN Non pris en charge Toutes les versions de Databricks Runtime prises en charge Toutes les versions de Databricks Runtime prises en charge

Bibliothèques délimitées aux notebooks

Les bibliothèques délimitées au notebook, disponibles pour Python et R, vous permettent d’installer des bibliothèques et de créer un environnement délimité à une session de notebook. Ces bibliothèques n’affectent pas les autres notebooks s’exécutant sur le même cluster. Les bibliothèques délimitées au notebook ne sont pas persistantes et doivent être réinstallées pour chaque session. Utilisez des bibliothèques délimitées au notebook quand vous avez besoin d’un environnement personnalisé pour un notebook spécifique.

Remarque

Les fichiers JAR ne peuvent pas être installés au niveau du notebook.

Important

Les bibliothèques d’espace de travail ont été déconseillées et ne doivent pas être utilisées. Consultez Bibliothèques d’espace de travail (hérité). Toutefois, le stockage des bibliothèques en tant que fichiers d’espace de travail est distinct des bibliothèques d’espace de travail, et est toujours entièrement pris en charge. Vous pouvez installer des bibliothèques stockées en tant que fichiers d’espace de travail directement sur des tâches de travail ou de calcul.

Gestion de l’environnement Python

Le tableau suivant fournit une vue d’ensemble des options que vous pouvez utiliser pour installer des bibliothèques Python dans Azure Databricks.

Remarque

  • Les conteneurs personnalisés qui utilisent un environnement basé sur Conda ne sont pas compatibles avec les bibliothèques à l’échelle des notebooks et avec les bibliothèques de cluster dans Databricks Runtime 10.4 LTS et versions ultérieures. Au lieu de cela, Azure Databricks recommande d’installer des bibliothèques directement dans l’image, ou d’utiliser des scripts init. Pour continuer à utiliser des bibliothèques de cluster dans ces scénarios, vous pouvez définir la configuration Sparkspark.databricks.driverNfs.clusterWidePythonLibsEnabled sur false. La prise en charge de la configuration Spark sera supprimée le 31 décembre 2021 ou ultérieurement.
Source de package Python Bibliothèques délimitées à un notebook avec %pip Bibliothèques délimitées au notebook avec un fichier YAML de l’environnement de base Bibliothèques de cluster Bibliothèques de travaux avec l’API Jobs
PyPI Utilisez %pip install. Consultez l’exemple. Ajoutez un nom de package PyPI à un fichier YAML de l’environnement de base. Consultez l’exemple. Sélectionnez PyPI comme source. Ajoutez un nouvel objet pypi aux bibliothèques de travaux et spécifiez le champ package.
Miroir PyPI privé, comme Nexus ou Artifactory Utilisez %pip install avec l’option --index-url. La gestion des secrets est disponible. Consultez l’exemple. Ajoutez le -–index-url fichier YAML d’un environnement de base. La gestion des secrets est disponible. Consultez l’exemple. Non pris en charge. Non pris en charge.
VCS, comme GitHub, avec source brute Utilisez %pip install et spécifiez l’URL du référentiel comme nom du package. Consultez l’exemple. Ajoutez une URL de référentiel en tant que nom de package à un fichier YAML de l’environnement de base. Consultez l’exemple. Sélectionnez PyPI comme source et spécifiez l’URL du référentiel comme nom du package. Ajoutez un nouvel objet pypi aux bibliothèques de travaux et spécifiez l’URL du référentiel comme champ package.
VCS privé avec source brute Utilisez %pip install et spécifiez l’URL du référentiel avec une authentification de base comme nom du package. La gestion des secrets est disponible. Consultez l’exemple. Ajoutez un référentiel avec l’authentification de base comme nom de package à un fichier YAML de l’environnement de base. Consultez l’exemple. Non pris en charge. Non pris en charge.
Chemins d'accès au fichier Utilisez %pip install. Consultez l’exemple. Ajoutez un chemin d’accès de fichier en tant que nom de package à un fichier YAML de l’environnement de base. Consultez l’exemple. Sélectionnez Chemin de fichier/ADLS comme source. Ajoutez un nouvel objet egg ou whl aux bibliothèques de travaux et spécifiez le chemin d'accès au fichier comme champ package.
Azure Data Lake Storage Gen2 Utilisez %pip install avec une URL pré-signée. Les chemins d’accès avec le protocole abfss:// Azure Data Lake Storage Gen2 ne sont pas pris en charge. Ajoutez une URL pré-signée en tant que nom de package à un fichier YAML de l’environnement de base. Les chemins d’accès avec le protocole abfss:// Azure Data Lake Storage Gen2 ne sont pas pris en charge. Sélectionnez Chemin de fichier/ADLS comme source. Ajoutez un nouvel objet egg ou whl aux bibliothèques de travaux et spécifiez le chemin d'accès à Azure Data Lake Storage Gen2 comme champ package.

Priorité de la bibliothèque Python

Vous pouvez rencontrer une situation où vous devez remplacer la version d’une bibliothèque intégrée ou avoir une bibliothèque personnalisée qui entre en conflit de nom avec une autre bibliothèque installée sur le cluster. Lorsque vous exécutez import <library>, la bibliothèque avec la priorité élevée est importée.

Important

Les bibliothèques stockées dans les fichiers d’espace de travail ont une précédence différente selon la façon dont elles sont ajoutées au sys.path Python. Un dossier Databricks Git ajoute le répertoire de travail actif au chemin d’accès avant toutes les autres bibliothèques, tandis que les notebooks en dehors des dossiers Git ajoutent le répertoire de travail actif après l’installation d’autres bibliothèques. Si vous ajoutez manuellement des répertoires d’espace de travail à votre chemin d’accès, ceux-ci ont toujours la priorité la plus faible.

La liste suivante classe la priorité de la plus élevée à la plus faible. Dans cette liste, un nombre inférieur signifie une priorité plus élevée.

  1. Bibliothèques dans le répertoire de travail actif (dossiers Git uniquement).
  2. Bibliothèques dans le répertoire racine du dossier Git (dossiers Git uniquement).
  3. Bibliothèques étendues au bloc-notes (%pip install dans les notebooks).
  4. Bibliothèques de cluster (à l’aide de l’interface utilisateur, de l’interface CLI ou de l’API).
  5. Bibliothèques incluses dans Databricks Runtime.
    • Les bibliothèques installées avec des scripts init peuvent être résolues avant ou après les bibliothèques intégrées, selon la façon dont elles sont installées. Databricks ne recommande pas d’installer des bibliothèques avec des scripts init.
  6. Bibliothèques dans le répertoire de travail actif (pas dans les dossiers Git).
  7. Fichiers d’espace de travail ajoutés à sys.path.