Utilidad de biblioteca (dbutils.library) (heredada)

  • Artículo

Nota:

Las API dbutils.library.install y dbutils.library.installPyPI se quitaron en Databricks Runtime 11.0. La mayoría de comandos de la utilidad de biblioteca están en desuso. La mayoría de utilidades de biblioteca no están disponibles en Databricks Runtime ML. Para obtener más información sobre dbutils.library.restartPython, consulte Reinicio del proceso de Python en Azure Databricks.

Esta documentación se ha retirado y es posible que no se actualice. Los productos, servicios o tecnologías mencionados en este contenido ya no se admiten.

Databricks recomienda encarecidamente usar comandos mágicos %pip para instalar bibliotecas con ámbito de cuaderno. Consulte Bibliotecas de Python cuyo ámbito es Notebook.

Para obtener documentación completa sobre la funcionalidad de utilidades de Databricks, vea Referencia de Utilidades de Databricks (dbutils).

Comandos: install, installPyPI, list, restartPython, updateCondaEnv

La utilidad de biblioteca permite instalar las bibliotecas de Python y crear un entorno que tenga como ámbito una sesión de cuaderno. Las bibliotecas están disponibles tanto en el controlador como en los ejecutores, por lo que puede hacer referencia a ellas en funciones definidas por el usuario. Esto permite:

  • Que las dependencias de biblioteca de un cuaderno se organicen dentro del propio cuaderno.
  • Que los usuarios de cuadernos con diferentes dependencias de biblioteca compartan un clúster sin interferencias.

Al desasociar un cuaderno, se destruye este entorno. Sin embargo, puede crearlo de nuevo si vuelve a ejecutar los comandos de la API install de biblioteca en el cuaderno. Consulte la API restartPython para saber cómo puede restablecer el estado del cuaderno sin perder el entorno.

Las utilidades de biblioteca están habilitadas de manera predeterminada. Por lo tanto, de manera predeterminada, el entorno de Python para cada cuaderno se aísla mediante un ejecutable de Python independiente que se crea cuando el cuaderno se asocia al entorno predeterminado de Python en el clúster y lo hereda. Las bibliotecas instaladas a través de un script de inicialización en el entorno de Python de Azure Databricks siguen estando disponibles. Puede establecer el valor de spark.databricks.libraryIsolation.enabled en false para deshabilitar esta característica.

Esta API es compatible con la instalación existente de la biblioteca en todo el clúster a través de la interfaz de usuario y la API de bibliotecas. Las bibliotecas instaladas a través de esta API tienen mayor prioridad que las bibliotecas de todo el clúster.

Para enumerar los comandos disponibles, ejecute 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

Comando install (dbutils.library.install)

Dada una ruta de acceso a una biblioteca, instala la biblioteca en la sesión del cuaderno actual. Las bibliotecas instaladas mediante una llamada a este comando solo están disponibles para el cuaderno actual.

A fin de mostrar la ayuda para este comando, ejecute dbutils.library.help("install").

En este ejemplo se instala una biblioteca .egg o .whl en un cuaderno.

Importante

dbutils.library.install se quitó en Databricks Runtime 11.0 y versiones posteriores.

Databricks recomienda colocar todos los comandos de instalación de la biblioteca en la primera celda del cuaderno y llamar a restartPython al final de esa celda. El estado del cuaderno de Python se restablece después de ejecutar restartPython; el cuaderno pierde todo el estado, incluidas, entre otras, las variables locales, las bibliotecas importadas y otros estados efímeros. Por lo tanto, se recomienda instalar las bibliotecas y restablecer el estado del cuaderno en la primera celda del cuaderno.

Los orígenes de biblioteca aceptados son dbfs, abfss, adl y 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.

Nota:

Puede instalar directamente archivos wheel personalizados mediante %pip. En el ejemplo siguiente se supone que ha cargado el archivo wheel de la biblioteca en DBFS:

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

Pip no admite archivos egg. Los archivos wheel se consideran el estándar de compilación y empaquetado binario para Python. Sin embargo, si quiere usar un archivo egg de una manera que sea compatible con %pip, puede usar la siguiente solución alternativa:

# 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")

Comando installPyPI (dbutils.library.installPyPI)

Dado un paquete del índice de paquetes de Python (PyPI), instala ese paquete en la sesión del cuaderno actual. Las bibliotecas instaladas mediante una llamada a este comando están aisladas entre cuadernos.

A fin de mostrar la ayuda para este comando, ejecute dbutils.library.help("installPyPI").

En este ejemplo se instala un paquete PyPI en un cuaderno. version, repo y extras son opcionales. Use el argumento extras para especificar la característica adicional (requisitos adicionales).

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.

Importante

dbutils.library.installPyPI se quitó en Databricks Runtime 11.0 y versiones posteriores.

Las claves version y extras no pueden formar parte de la cadena del paquete PyPI. Por ejemplo, dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") no es válido. Use los argumentos version y extras para especificar la versión y la información adicional como se muestra a continuación:

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.

Nota:

Al reemplazar los comandos dbutils.library.installPyPI por los comandos %pip, el intérprete de Python se reinicia automáticamente. Puede ejecutar el comando de instalación como se muestra a continuación:

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

En este ejemplo se especifican los requisitos de biblioteca en un cuaderno y se instalan mediante %run en el otro. Para ello, defina primero las bibliotecas que se instalarán en un cuaderno. En este ejemplo se usa un cuaderno denominado 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.

A continuación, instálelas en el cuaderno que necesita esas dependencias.

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

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

En este ejemplo se restablece el estado del cuaderno de Python al mismo tiempo que se mantiene el entorno. Esta técnica solo está disponible en cuadernos de Python. Por ejemplo, puede usar esta técnica para recargar las bibliotecas de Azure Databricks preinstaladas con una versión diferente:

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

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

También puede usar esta técnica para instalar bibliotecas como tensorflow que deben cargarse al iniciarse el proceso:

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

# Use the library in another cell.
import tensorflow

Comando list (dbutils.library.list)

Enumera las bibliotecas aisladas agregadas para la sesión del cuaderno actual a través de la utilidad de biblioteca. Esto no incluye las bibliotecas que están asociadas al clúster.

A fin de mostrar la ayuda para este comando, ejecute dbutils.library.help("list").

En este ejemplo se enumeran las bibliotecas instaladas en un cuaderno.

dbutils.library.list()

Nota:

El equivalente de este comando con %pip es el siguiente:

%pip freeze

Comando updateCondaEnv (dbutils.library.updateCondaEnv)

Actualiza el entorno de Conda del cuaderno actual en función del contenido de environment.yml. Este método solo es compatible con Databricks Runtime en Conda.

A fin de mostrar la ayuda para este comando, ejecute dbutils.library.help("updateCondaEnv").

En este ejemplo se actualiza el entorno de Conda del cuaderno actual en función del contenido de la especificación proporcionada.

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