Bibliothèques Python délimitées aux notebooks

  • Article

Les bibliothèques délimitées aux notebooks vous permettent de créer, modifier, enregistrer, réutiliser et partager des environnements Python personnalisés qui sont spécifiques à un notebook. Lorsque vous installez une bibliothèque Python délimitée à un notebook, seuls le notebook actuel et les travaux associés à ce notebook ont accès à cette bibliothèque. Les autres notebooks attachés au même cluster ne sont pas concernés.

Les bibliothèques délimitées aux notebooks ne sont pas conservées entre les sessions. Vous devez réinstaller les bibliothèques délimitées aux notebooks au début de chaque session ou chaque fois que le notebook est détaché d’un cluster.

Databricks recommande d’utiliser la commande magic %pip pour installer des bibliothèques Python délimitées aux notebooks.

Vous pouvez utiliser %pip dans les notebooks planifiés en tant que travaux. Si vous devez gérer l’environnement Python dans un notebook Scala, SQL ou R, utilisez la commande magic %python conjointement avec %pip.

Vous pouvez rencontrer davantage de trafic vers le nœud du pilote quand vous utilisez des installations de bibliothèques délimitées aux notebooks. Consultez Quelle doit être la taille du nœud du pilote lors de l’utilisation de bibliothèques délimitées aux notebooks ?.

Pour installer des bibliothèques pour tous les notebooks attachés à un cluster, utilisez des bibliothèques de cluster. Consultez Bibliothèques de clusters.

Remarque

Sur Databricks Runtime 10.5 et antérieur, vous pouvez utiliser l’utilitaire de bibliothèque (hérité) d’Azure Databricks. L’utilitaire de bibliothèque est pris en charge uniquement sur Databricks Runtime, et non sur Databricks Runtime ML. Consultez utilitaire bibliothèque (dbutils.library) (hérité).

Gérer les bibliothèques avec les commandes %pip

La commande %pip est équivalente à la commande pip et prend en charge la même API. Les sections suivantes présentent des exemples de la façon dont vous pouvez utiliser les commandes %pip pour gérer votre environnement. Pour plus d’informations sur l’installation de packages Python avec pip, consultez la documentation d’installation pip et les pages associées.

Important

  • À partir de Databricks Runtime 13.0 %pip , les commandes ne redémarrent pas automatiquement le processus Python. Si vous installez un nouveau package ou mettez à jour un package existant, vous aurez sûrement à utiliser dbutils.library.restartPython() pour voir les nouveaux packages. Consultez Redémarrer le processus Python sur Azure Databricks.
  • Sur Databricks Runtime 12.2 LTS et versions ultérieures, Databricks recommande de placer toutes les %pip commandes au début du notebook. L’état du notebook est réinitialisé après toute commande %pip modifiant l’environnement. Si vous créez des méthodes ou des variables Python dans un notebook, puis utilisez des commandes %pip dans une cellule ultérieure, les méthodes ou variables sont perdues.
  • La mise à niveau, la modification ou la désinstallation de packages Python principaux (tels que IPython) avec %pip peuvent entraîner l’arrêt du fonctionnement normal de certaines fonctionnalités. Si vous rencontrez de tels problèmes, réinitialisez l’environnement en détachant et en attachant à nouveau le notebook ou en redémarrant le cluster.

Installer une bibliothèque avec %pip

%pip install matplotlib

Installer un package wheel Python avec%pip

%pip install /path/to/my_package.whl

Désinstaller une bibliothèque avec %pip

Remarque

Vous ne pouvez pas désinstaller une bibliothèque qui est incluse dans les Notes de publication sur les versions et la compatibilité de Databricks Runtime ou une bibliothèque qui a été installée en tant que bibliothèque de clusters. Si vous avez installé une version de bibliothèque différente de celle qui est incluse dans Databricks Runtime ou celle qui est installée sur le cluster, vous pouvez utiliser %pip uninstall pour rétablir la version par défaut de la bibliothèque dans Databricks Runtime ou la version installée sur le cluster, mais vous ne pouvez pas utiliser une commande %pip pour désinstaller la version d’une bibliothèque incluse dans Databricks Runtime ou installée sur le cluster.

%pip uninstall -y matplotlib

L’option -y est obligatoire.

Installer une bibliothèque à partir d’un système de gestion de version avec %pip

%pip install git+https://github.com/databricks/databricks-cli

Vous pouvez ajouter des paramètres à l’URL pour spécifier des éléments tels que la version ou le sous-répertoire git. Pour plus d’informations et pour obtenir des exemples d’utilisation d’autres systèmes de gestion de version, consultez la Prise en charge VCS.

Installer un package privé avec des informations d’identification gérées par des secrets Databricks avec %pip

PIP prend en charge l’installation de packages à partir de sources privées avec l’authentification de base, y compris les systèmes de gestion de version privés et les référentiels de packages privés, tels que Nexus et Artifactory. La gestion des secrets est disponible via l’API Databricks Secrets, qui vous permet de stocker des jetons d’authentification et des mots de passe. Utilisez l'API DBUtils pour accéder aux secrets depuis votre notebook. Notez que vous pouvez utiliser $variables dans les commandes magiques.

Pour installer un package à partir d’un dépôt privé, spécifiez l’URL du référentiel avec l'option --index-url sur %pip install ou ajoutez-la au fichier de configuration pip à l’emplacement ~/.pip/pip.conf.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

De même, vous pouvez utiliser la gestion des secrets avec les commandes magiques pour installer des packages privés à partir de systèmes de contrôle de version.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Installer un package à partir de DBFS avec %pip

Important

Tout utilisateur(-trice) de l’espace de travail peut modifier les fichiers stockés dans DBFS. Azure Databricks recommande de stocker des fichiers dans des espaces de travail ou sur des volumes de Unity Catalog.

Vous pouvez utiliser %pip pour installer un package privé qui a été enregistré sur DBFS.

Lorsque vous chargez un fichier sur DBFS, il renomme automatiquement le fichier, en remplaçant les espaces, les points et les traits d’union par des traits de soulignement. Pour les fichiers wheel Python, pip nécessite que le nom du fichier utilise des points dans la version (par exemple 0.1.0), et des traits d’union au lieu d’espaces ou de traits de soulignement pour que ces noms de fichiers ne soient pas modifiés.

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

Installer un package à partir d’un volume avec %pip

Important

Cette fonctionnalité est disponible en préversion publique.

Avec Databricks Runtime version 13.2 et supérieures, vous pouvez utiliser %pip pour installer un package privé qui a été enregistré sur un volume.

Lorsque vous chargez un fichier sur un volume, il renomme automatiquement le fichier, en remplaçant les espaces, les points et les traits d’union par des traits de soulignement. Pour les fichiers wheel Python, pip nécessite que le nom du fichier utilise des points dans la version (par exemple 0.1.0), et des traits d’union au lieu d’espaces ou de traits de soulignement pour que ces noms de fichiers ne soient pas modifiés.

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

Installer un package stocké en tant que fichier d’espace de travail avec %pip

Avec Databricks Runtime 11.3 LTS et ultérieur, vous pouvez utiliser %pip pour installer un package privé qui a été enregistré en tant que fichier d’espace de travail.

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

Enregistrer des bibliothèques dans un fichier de spécifications

%pip freeze > /Workspace/shared/prod_requirements.txt

Tous les sous-répertoires du chemin d’accès au fichier doivent déjà exister. Si vous exécutez %pip freeze > /Workspace/<new-directory>/requirements.txt, la commande échoue si le répertoire /Workspace/<new-directory> n’existe pas déjà.

Utiliser un fichier de spécifications pour installer les bibliothèques

Un fichier de spécifications contient une liste de packages à installer à l’aide pip. Voici un exemple d’utilisation d’un fichier de spécifications :

%pip install -r /Workspace/shared/prod_requirements.txt

Consultez Format du fichier de spécifications pour plus d’informations sur les fichiers requirements.txt.

Quelle doit être la taille du nœud du pilote lors de l’utilisation de bibliothèques délimitées aux notebooks ?

L’utilisation de bibliothèques délimitées aux notebooks peut entraîner un plus grand trafic vers le nœud du pilote, car cela permet de préserver la cohérence de l’environnement entre les nœuds de l’exécuteur.

Lorsque vous utilisez un cluster de 10 nœuds ou plus, Databricks recommande ces spécifications en tant que configuration minimale requise pour le nœud de pilote :

  • Pour un cluster d’UC à 100 nœuds, utilisez Standard_DS5_v2.
  • Pour un cluster GPU à 10 nœuds, utilisez Standard_NC12.

Pour les clusters de plus grande taille, utilisez un nœud de pilote plus grand.

Puis-je utiliser %sh pip, !pip ou pip ? Quelle est la différence ?

%sh et ! exécutent une commande d’interpréteur de commandes dans un notebook. La première est une commande magique auxiliaire Databricks, alors que la seconde est une fonctionnalité d’IPython. pip est une abréviation de %pip quand automagic est activé, ce qui correspond à la valeur par défaut dans les notebooks Python Azure Databricks.

Sur Databricks Runtime 11.0 et les versions ultérieures, %pip, %sh pip et !pip installent toutes une bibliothèque en tant que bibliothèque Python délimitées aux notebooks. Dans Databricks Runtime 10.4 LTS et les versions antérieures, Databricks recommande d’utiliser uniquement %pip ou pip pour installer les bibliothèques spécifiques à un notebook. Le comportement de %sh pip et !pip n’est pas cohérent dans Databricks Runtime 10.4 LTS et les versions antérieures.

Problèmes connus

  • Sur Databricks Runtime 10.3 et versions antérieures, les bibliothèques d’étendue notebook sont incompatibles avec les travaux de diffusion en continu par lots. Databricks recommande d’utiliser des bibliothèques de cluster ou le noyau IPython à la place.