Utilitaire de bibliothèque (dbutils.library) (hérité)

  • Article

Remarque

Les API dbutils.library.install et dbutils.library.installPyPI ont été supprimées dans Databricks Runtime 11.0 et les versions ultérieures. La plupart des commandes des utilitaires de bibliothèque sont obsolètes. La plupart des utilitaires de bibliothèque ne sont pas disponibles sur Databricks Runtime ML. Si vous souhaitez obtenir plus d’informations sur dbutils.library.restartPython, consultez Redémarrer le processus Python sur Azure Databricks.

Cette documentation a été mise hors service et peut ne pas être mise à jour. Les produits, services ou technologies mentionnés dans ce contenu ne sont plus pris en charge.

Databricks recommande fortement d'utiliser des commandes magiques %pip pour installer des bibliothèques à l'échelle du bloc-notes. Consultez Bibliothèques Python délimitées à un notebook.

Pour obtenir une documentation complète sur les fonctionnalités des utilitaires Databricks, consultez la référence des utilitaires Databricks (dbutils).

Commandes : install, installPyPI, list, restartPython), updateCondaEnv

L'utilitaire de bibliothèque vous permet d'installer des bibliothèques Python et de créer un environnement adapté à une session de notebook. Les bibliothèques sont disponibles sur le pilote et sur les exécuteurs, ce qui vous permet de les référencer dans les fonctions définies par l’utilisateur. Vous pouvez ainsi :

  • Dépendances de bibliothèque d’un bloc-notes à organiser dans le bloc-notes.
  • Utilisateurs du Notebook avec différentes dépendances de bibliothèque pour partager un cluster sans interférence.

Le détachement d’un bloc-notes détruit cet environnement. Toutefois, vous pouvez le recréer en réexécutant les commandes de l’API de bibliothèque install dans le bloc-notes. Consultez l' API restartPython pour savoir comment réinitialiser l’état de votre Notebook sans perdre votre environnement.

Les utilitaires de bibliothèque sont activés par défaut. Par conséquent, par défaut, l'environnement Python de chaque notebook est isolé en utilisant un exécutable Python distinct qui est créé lorsque le notebook est rattaché au cluster et hérite de l'environnement Python par défaut. Les bibliothèques installées par un script init dans l'environnement Python d'Azure Databricks sont toujours disponibles. Vous pouvez désactiver cette fonctionnalité en affectant spark.databricks.libraryIsolation.enabled à false.

Cette API est compatible avec l’installation existante de la bibliothèque à l’ensemble du cluster par le biais de l’interface utilisateur et de l’API Bibliothèques. Les bibliothèques installées par le biais de cette API ont une priorité plus élevée que les bibliothèques à l’ensemble du cluster.

Pour répertorier les commandes disponibles, exécutez dbutils.library.help().

install(path: String): boolean -> Install the library within the current notebook session
installPyPI(pypiPackage: String, version: String = "", repo: String = "", extras: String = ""): boolean -> Install the PyPI library within the current notebook session
list: List -> List the isolated libraries added for the current notebook session via dbutils
restartPython: void -> Restart python process for the current notebook session
updateCondaEnv(envYmlContent: String): boolean -> Update the current notebook's Conda environment based on the specification (content of environment

Commande install (dbutils.library.install)

À partir d’un chemin d’accès à une bibliothèque, installe cette bibliothèque dans la session du bloc-notes active. Les bibliothèques installées en appelant cette commande sont uniquement disponibles pour le bloc-notes actuel.

Pour afficher l’aide de cette commande, exécutez dbutils.library.help("install").

Cet exemple installe une bibliothèque .egg ou .whl dans un bloc-notes.

Important

dbutils.library.install est supprimé dans Databricks Runtime 11.0 et versions ultérieures.

Databricks vous recommande de placer toutes les commandes d’installation de votre bibliothèque dans la première cellule de votre bloc-notes et d’appeler restartPython à la fin de cette cellule. L’état du Notebook Python est réinitialisé après l’exécution restartPython ; le bloc-notes perd tout l’état, y compris mais non limité aux variables locales, aux bibliothèques importées et aux autres États éphémères. Par conséquent, nous vous recommandons d’installer les bibliothèques et de réinitialiser l’état du Notebook dans la première cellule du bloc-notes.

Les sources de bibliothèque acceptées sont dbfs , abfss, adl , et wasbs.

dbutils.library.install("abfss:/path/to/your/library.egg")
dbutils.library.restartPython() # Removes Python state, but some libraries might not work without calling this command.

dbutils.library.install("abfss:/path/to/your/library.whl")
dbutils.library.restartPython() # Removes Python state, but some libraries might not work without calling this command.

Notes

Vous pouvez installer directement des fichiers de roulette personnalisés à l’aide de %pip. Dans l’exemple suivant, nous supposons que vous avez chargé votre fichier de roulette de bibliothèque sur DBFS :

%pip install /dbfs/path/to/your/library.whl

Les fichiers Egg ne sont pas pris en charge par PIP et les fichiers wheel sont considérés comme la norme pour la génération et l’empaquetage binaire pour Python. Toutefois, si vous souhaitez utiliser un fichier Egg d’une manière compatible avec %pip, vous pouvez utiliser la solution de contournement suivante :

# This step is only needed if no %pip commands have been run yet.
# It will trigger setting up the isolated notebook environment
%pip install <any-lib>  # This doesn't need to be a real library; for example "%pip install any-lib" would work

import sys
# Assuming the preceding step was completed, the following command
# adds the egg file to the current notebook environment
sys.path.append("/local/path/to/library.egg")

Commande installPyPI (dbutils.library.installPyPI)

À partir d’un package d’index de package Python (PyPI), installez ce package dans la session du bloc-notes active. Les bibliothèques installées en appelant cette commande sont isolées parmi les blocs-notes.

Pour afficher l’aide de cette commande, exécutez dbutils.library.help("installPyPI").

Cet exemple installe un package PyPI dans un bloc-notes. version, repo et extras sont facultatifs. Utilisez l'argument extras pour spécifier la Fonctionnalité Extras (exigences supplémentaires).

dbutils.library.installPyPI("pypipackage", version="version", repo="repo", extras="extras")
dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this command.

Important

dbutils.library.installPyPI est supprimé dans Databricks Runtime 11.0 et versions ultérieures.

Les clés version et extras ne peuvent pas faire partie de la chaîne de package PyPI. Par exemple, dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") est incorrect. Utilisez les arguments version et extras pour spécifier la version et les informations supplémentaires comme suit :

dbutils.library.installPyPI("azureml-sdk", version="1.19.0", extras="databricks")
dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this command.

Notes

Lors du remplacement de commandes dbutils.library.installPyPI par des commandes %pip, l’interpréteur Python est redémarré automatiquement. Vous pouvez exécuter la commande d’installation comme suit :

%pip install azureml-sdk[databricks]==1.19.0

Cet exemple spécifie les spécifications de bibliothèque dans un bloc-notes et les installe à l’aide de %run dans l’autre. Pour ce faire, commencez par définir les bibliothèques à installer dans un Notebook. Cet exemple utilise un bloc-notes nommé InstallDependencies.

dbutils.library.installPyPI("torch")
dbutils.library.installPyPI("scikit-learn", version="1.19.1")
dbutils.library.installPyPI("azureml-sdk", extras="databricks")
dbutils.library.restartPython() # Removes Python state, but some libraries might not work without calling this command.

Ensuite, installez-les dans le bloc-notes qui a besoin de ces dépendances.

%run /path/to/InstallDependencies # Install the dependencies in the first cell.

import torch
from sklearn.linear_model import LinearRegression
import azureml
...

Cet exemple réinitialise l’état du Notebook python tout en conservant l’environnement. Cette technique est disponible uniquement dans les blocs-notes Python. Par exemple, vous pouvez utiliser cette technique pour recharger des bibliothèques Azure Databricks préinstallé avec une version différente :

dbutils.library.installPyPI("numpy", version="1.15.4")
dbutils.library.restartPython()

# Make sure you start using the library in another cell.
import numpy

Vous pouvez également utiliser cette technique pour installer des bibliothèques, telles que tensorflow, qui doivent être chargées au démarrage du processus :

dbutils.library.installPyPI("tensorflow")
dbutils.library.restartPython()

# Use the library in another cell.
import tensorflow

Commande list (dbutils.library.list)

Répertorie les bibliothèques isolées ajoutées pour la session actuelle du bloc-notes par le biais de l’utilitaire de bibliothèque. Cela n’inclut pas les bibliothèques attachées au cluster.

Pour afficher l’aide de cette commande, exécutez dbutils.library.help("list").

Cet exemple répertorie les bibliothèques installées dans un bloc-notes.

dbutils.library.list()

Notes

L’équivalent de cette commande à l’aide de %pip est :

%pip freeze

Commande updateCondaEnv (dbutils.library.updateCondaEnv)

Met à jour l’environnement Conda du bloc-notes actuel en fonction du contenu de environment.yml. Cette méthode est prise en charge uniquement pour les Databricks Runtime sur Conda.

Pour afficher l’aide de cette commande, exécutez dbutils.library.help("updateCondaEnv").

Cet exemple met à jour l’environnement Conda du bloc-notes actuel en fonction du contenu de la spécification fournie.

dbutils.library.updateCondaEnv(
"""
channels:
  - anaconda
dependencies:
  - gensim=3.4
  - nltk=3.4
""")