Bibliotecas de Python cuyo ámbito es el cuaderno

Las bibliotecas con ámbito de cuaderno permiten crear, modificar, guardar, reutilizar y compartir entornos de Python personalizados específicos de un cuaderno. Al instalar una biblioteca de ámbito de cuaderno, solo el cuaderno actual y los trabajos asociados a ese cuaderno tienen acceso a esa biblioteca. Otros cuadernos conectados al mismo clúster no se ven afectados.

Las bibliotecas con ámbito de cuaderno no se conservan entre sesiones. Debe volver a instalar las bibliotecas con ámbito de cuaderno al principio de cada sesión o siempre que el cuaderno se desasocia de un clúster.

Hay dos métodos para instalar bibliotecas de ámbito de cuaderno:

  • Ejecute el %pip comando magic en un cuaderno. El comando se admite en Databricks Runtime 7.1 y versiones posteriores, y en Databricks Runtime %pip 6.4 ML y versiones posteriores. Databricks recomienda usar este enfoque para nuevas cargas de trabajo. En este artículo se describe cómo usar estos comandos mágicos.
  • Use la utilidad Azure Databricks biblioteca de archivos. La utilidad de biblioteca solo se admite en Databricks Runtime, no en Databricks Runtime ML o Databricks Runtime para Genomics. Consulte Utilidad de biblioteca (dbutils.library).

Para instalar bibliotecas para todos los cuadernos asociados a un clúster, use el área de trabajo o las bibliotecas instaladas en clúster.

Requisitos

Las bibliotecas cuyo ámbito es Notebook que usan comandos magic están habilitadas de forma predeterminada en Databricks Runtime 7.1, y las versiones posteriores; Databricks Runtime 7.1 ML, y las versiones posteriores; y Databricks Runtime 7.1 for Genomics, y las versiones posteriores.

También están disponibles mediante un valor de la configuración en Databricks Runtime 6.4 ML a 7.0 ML y Databricks Runtime 6.4 for Genomics a Databricks Runtime 7.0 for Genomics. Establezca la configuración de Spark en true .

En un clúster de alta simultaneidad que ejecuta Databricks Runtime 7.4 ML o Databricks Runtime 7.4 para Genomics o una versión inferior, las bibliotecas de ámbito de cuaderno no son compatibles con el control de acceso a tablas o el paso a través de credenciales . Una alternativa es usar la utilidad Library (dbutils.library) en un clúster de Databricks Runtime o actualizar el clúster a Databricks Runtime 7.5 ML o Databricks Runtime 7.5 para Genomics o versiones posteriores.

Para usar bibliotecas con ámbito de cuaderno con Databricks Conectar, debe usar la utilidad Library (dbutils.library).

Nodo de controlador

El uso de bibliotecas con ámbito de cuaderno podría dar lugar a más tráfico al nodo del controlador, ya que funciona para mantener el entorno coherente entre los nodos ejecutores.

Cuando se usa un clúster con 10 nodos o más, Databricks recomienda estas especificaciones como requisito mínimo para el nodo de controlador:

  • Para un clúster de CPU de 100 nodos, use Standard_DS5_v2.
  • Para un clúster de GPU de 10 nodos, use Standard_NC12.

Para clústeres más grandes, use un nodo de controlador mayor.

Instalación de bibliotecas con ámbito de cuaderno con %pip

Importante

  • Debe colocar todos %pip los comandos al principio del cuaderno. El estado del cuaderno se restablece después de %pip cualquier comando que modifique el entorno. Si crea métodos o variables de Python en un cuaderno y, a continuación, usa comandos en una celda posterior, se pierden %pip los métodos o variables.
  • La actualización, modificación o desinstalación de paquetes principales de Python (como IPython) con puede hacer que algunas características dejen de %pip funcionar según lo previsto. Por ejemplo, IPython 7.21 y versiones posteriores son incompatibles con Databricks Runtime 8.1 y versiones posteriores. Si experimenta estos problemas, restablezca el entorno desasociando y asociando de nuevo el cuaderno o reiniciando el clúster.

Administración de bibliotecas con %pip comandos

El %pip comando es equivalente al comando %pip y admite la misma API. En las secciones siguientes se muestran ejemplos de cómo puede usar %pip comandos para administrar el entorno. Para obtener más información sobre cómo instalar paquetes de Python con pip , consulte la documentación de instalación de pip pip las páginas relacionadas.

En esta sección:

Instalación de una biblioteca con %pip

%pip install matplotlib

Instalación de un paquete wheel con %pip

%pip install /path/to/my_package.whl

Desinstalación de una biblioteca con %pip

Nota

No se puede desinstalar una biblioteca incluida en Databricks Runtime o una biblioteca que se haya instalado como biblioteca de clúster. Si ha instalado una versión de biblioteca diferente de la incluida en Databricks Runtime o la instalada en el clúster, puede usar para revertir la biblioteca a la versión predeterminada de Databricks Runtime o la versión instalada en el clúster, pero no puede usar un comando para desinstalar la versión de una biblioteca incluida en Databricks Runtime o instalada en el %pip uninstall%pip clúster.

%pip uninstall -y matplotlib

La -y opción es obligatoria.

Instalación de una biblioteca desde un sistema de control de versiones con %pip

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

Puede agregar parámetros a la dirección URL para especificar elementos como la versión o el subdirectorio de Git. Consulte compatibilidad con VCS para obtener más información y ejemplos de uso de otros sistemas de control de versiones.

Instalación de un paquete privado con credenciales administradas por secretos de Databricks con %pip

Pip admite la instalación de paquetes desde orígenes privados con autenticación básica,incluidos los sistemas de control de versiones privados y los repositorios de paquetes privados, como Nexusy Artifactory. La administración de secretos está disponible a través de la API de secretos de Databricks, que permite almacenar tokens de autenticación y contraseñas. Use la API DBUtils para acceder a los secretos desde el cuaderno. Tenga en cuenta que puede $variables usar en comandos mágicos.

Para instalar un paquete desde un repositorio privado, especifique la dirección URL del repositorio con la opción a o --index-url%pip install agrégrelo al archivo pip de configuración en ~/.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 forma similar, puede usar la administración de secretos con comandos mágicos para instalar paquetes privados desde sistemas de control de versiones.

token = dbutils.secrets.get(scope="scope", key="key")
%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Instalación de un paquete desde DBFS con %pip

Puede usar para %pip instalar un paquete privado que se haya guardado en DBFS.

Al cargar un archivo en DBFS, cambia automáticamente el nombre del archivo, reemplazando espacios, puntos y guiones por caracteres de subrayado. pip requiere que el nombre del archivo wheel use puntos en la versión (por ejemplo, 0.1.0) y guiones en lugar de espacios o caracteres de subrayado. Para instalar el paquete con un %pip comando, debe cambiar %pip para cumplir estos requisitos.

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

Guardar bibliotecas en un archivo de requisitos

%pip freeze > /dbfs/requirements.txt

Los subdirectorios de la ruta de acceso del archivo ya deben existir. Si ejecuta , se produce un error en el comando %pip freeze > /dbfs/<new-directory>/requirements.txt si el directorio aún no /dbfs/<new-directory> existe.

Uso de un archivo de requisitos para instalar bibliotecas

Un archivo de requisitos contiene una lista de paquetes que se instalarán mediante . Un ejemplo de uso de un archivo de requisitos es:

%pip install -r /dbfs/requirements.txt

Consulte Requirements File Format (Formato de archivo de requisitos) para obtener más información sobre los archivos.

Administración de bibliotecas con %conda comandos

Importante

%condaLos comandos han quedado en desuso y ya no se admiten después Databricks Runtime ML 8.4. Databricks recomienda usar para %pip administrar bibliotecas de ámbito de cuaderno. Si necesita bibliotecas de Python que solo se pueden instalar mediante conda, puede usar contenedores de Docker basados en Conda para instalar previamente las bibliotecas que necesita.

Anaconda Inc. actualizó sus términos de servicio para anaconda.org canales en septiembre de 2020. En función de los nuevos términos de servicio, puede requerir una licencia comercial si se basa en el empaquetado y distribución de Anaconda. Consulte Preguntas más frecuentes sobre Anaconda Commercial Edition para obtener más información. El uso de cualquier canal de Anaconda se rige por sus términos de servicio.

Como resultado de este cambio, Databricks ha quitado la configuración predeterminada del canal para el administrador de paquetes de Conda Databricks Runtime ML 8.0. Para instalar o actualizar paquetes mediante %conda el comando , debe especificar un canal.

Los canales predeterminados de Anaconda se quitarán de todas Databricks Runtime versiones anteriores o posteriores al 25 de mayo de 2021. Éste es un cambio importante. Debe actualizar todo el uso de %conda install y para especificar un %sh conda install canal.

El %conda comando es equivalente al comando %conda y admite la misma API con algunas restricciones que se indican a continuación. Las secciones siguientes contienen ejemplos de cómo usar %conda comandos para administrar el entorno. Para obtener más información sobre cómo instalar paquetes de Python conda con , consulte la documentación de instalación de conda.

Tenga en %conda cuenta que los comandos mágicos no están disponibles en Databricks Runtime. Solo están disponibles en Databricks Runtime ML hasta Databricks Runtime ML 8.4 y en Databricks Runtime para Genomics. Databricks recomienda usar pip para instalar bibliotecas. Para obtener más información, vea Descripción de conda y pip.

Si debe usar los comandos y en un cuaderno, consulte Interacciones entre los comandos %pip%conda pip y %pip.

Nota

Los siguientes conda comandos no se admiten cuando se usan con %conda :

  • activate
  • create
  • init
  • run
  • env create
  • env remove

En esta sección:

Instalación de una biblioteca con %conda

%conda install matplotlib -c conda-forge

Desinstalación de una biblioteca con %conda

%conda uninstall matplotlib

Guardar y reutilizar o compartir un entorno

Al separar un cuaderno de un clúster, el entorno no se guarda. Para guardar un entorno para poder reutilizarlo más adelante o compartirlo con otra persona, siga estos pasos.

Databricks recomienda que los entornos solo se compartan entre clústeres que ejecutan la misma versión de Databricks Runtime ML o la misma versión de Databricks Runtime para Genomics.

  1. Guarde el entorno como una especificación de YAML de Conda.

    %conda env export -f /dbfs/myenv.yml
    
  2. Importe el archivo a otro cuaderno mediante conda env update .

    %conda env update -f /dbfs/myenv.yml
    

Enumeración del entorno de Python de un cuaderno

Para mostrar el entorno de Python asociado a un cuaderno, use %conda list :

%conda list

Interacciones entre los pipconda comandos y

Para evitar conflictos, siga estas instrucciones al usar pip o conda para instalar paquetes y bibliotecas de Python.

  • Las bibliotecas instaladas mediante la API o mediante la interfaz de usuario del clúster se instalan mediante . Si alguna biblioteca se ha instalado desde la API o la interfaz de usuario del clúster, solo debe usar comandos al instalar bibliotecas de %pip ámbito de cuaderno.
  • Si usa bibliotecas de ámbito de cuaderno en un clúster, los scripts de init que se ejecutan en ese clúster pueden usar los comandos conda o pip para instalar bibliotecas. Sin embargo, si el script init incluye pip comandos, use solo %pip comandos en cuadernos (no %conda ).
  • Es mejor usar comandos exclusivamente o pipconda comandos exclusivamente. Si debe instalar algunos paquetes mediante y otros mediante , ejecute primero los comandos y, a conda continuación, ejecute pip los condapip comandos. Para obtener más información, vea Uso de Pip en un entorno de Conda.

Preguntas más frecuentes

¿Cómo interactúan las bibliotecas instaladas desde la interfaz de usuario o API del clúster con las bibliotecas de ámbito de cuaderno?

Las bibliotecas instaladas desde la interfaz de usuario o api del clúster están disponibles para todos los cuadernos del clúster. Estas bibliotecas se instalan mediante ; por lo tanto, si las bibliotecas se instalan mediante la interfaz de usuario del clúster, use solo pip%pip comandos en cuadernos.

¿Cómo interactúan las bibliotecas instaladas mediante un script init con las bibliotecas de ámbito de cuaderno?

Las bibliotecas instaladas mediante un script init están disponibles para todos los cuadernos del clúster.

Si usa bibliotecas de ámbito de cuaderno en un clúster que ejecuta Databricks Runtime ML o Databricks Runtime para Genomics, los scripts de init que se ejecutan en el clúster pueden usar los comandos o para instalar condapip bibliotecas. Sin embargo, si el script init incluye pip comandos, use solo %pip comandos en cuadernos.

Por ejemplo, este fragmento de código de cuaderno genera un script que instala fast.ai paquetes en todos los nodos del clúster.

dbutils.fs.put("dbfs:/home/myScripts/fast.ai", "conda install -c pytorch -c fastai fastai -y", True)

¿Puedo usar %pip los comandos y en %conda cuadernos de trabajo?

Sí.

¿Puedo usar %pip los comandos y en %conda cuadernos de R o Scala?

Sí, en una celda mágica de Python.

¿Puedo usar %sh pip o %sh conda ?

Databricks no recomienda usar %sh pip porque no es compatible con el %pip uso.

¿Puedo actualizar paquetes de R mediante %conda comandos?

No.

Problemas conocidos

  • En Databricks Runtime 7.0 ML y las siguientes, así como Databricks Runtime 7.0 para Genomics y adicionales, si una UDF registrada depende de los paquetes de Python instalados mediante o , no funcionará en %pip%conda%sql celdas. Use spark.sql en su lugar en un shell de comandos de Python.
  • En Databricks Runtime 7.2 ML y siguientes, así como Databricks Runtime 7.2 para Genomics y las siguientes, al actualizar el entorno del cuaderno mediante , el nuevo entorno no se activa en los procesos de Python de %conda trabajo. Esto puede causar problemas si una función UDF de PySpark llama a una función de terceros que usa recursos instalados dentro del entorno de Conda.
  • Cuando se usa para actualizar un entorno de cuaderno, no se garantiza el orden de instalación %conda env update de los paquetes. Esto puede causar problemas para el horovod paquete, que requiere que y se instalen antes tensorflow para poder usar o torchhorovodhorovod.tensorflowhorovod.torch respectivamente. Si esto sucede, desinstale horovod el paquete y vuelva a instalarlo después de asegurarse de que las dependencias están instaladas.