Compartilhar via

Utilitário de biblioteca (dbutils.library) (herdado)

  • Artigo

Observação

As APIs dbutils.library.install e dbutils.library.installPyPI são removidas no Databricks Runtime 11.0 e superior. A maioria dos comandos do utilitário de biblioteca foi preterida. A maioria dos utilitários de biblioteca não está disponível no Databricks Runtime ML. Para obter informações sobre dbutils.library.restartPython, confira Reiniciar o processo do Python no Azure Databricks.

Esta documentação foi desativada e pode não estar atualizada. Não há mais suporte para os produtos, serviços ou tecnologias mencionados neste conteúdo.

O Databricks recomenda usar comandos magic %pip para instalar bibliotecas com escopo de notebook. Confira as bibliotecas Python no escopo do notebook.

Para obter a documentação completa da funcionalidade de utilitários do Databricks, consulte Referência de Utilitários do Databricks (dbutils).

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

O utilitário de biblioteca permite instalar bibliotecas Python e criar um ambiente com escopo para uma sessão de notebook. As bibliotecas estão disponíveis no driver e nos executores, ou seja, você pode fazer referência a elas em funções definidas pelo usuário. Isso permite:

  • Que as dependências de biblioteca de um notebook sejam organizadas dentro do próprio notebook.
  • Que os usuários de notebook com dependências de biblioteca diferentes compartilhem um cluster sem interferência.

A desconexão de um notebook destrói esse ambiente. No entanto, você pode recriá-lo executando os comandos da API install de biblioteca no notebook. Confira a API restartPython para saber como você pode redefinir o estado do notebook sem perder seu ambiente.

Os utilitários de biblioteca são habilitados por padrão. Portanto, por padrão, o ambiente do Python para cada notebook é isolado com o uso de um executável do Python separado que é criado quando o notebook é anexado e herda o ambiente padrão do Python no cluster. Bibliotecas instaladas por meio de um script init no ambiente Python do Azure Databricks ainda estão disponíveis. Você pode desabilitar esse recurso definindo spark.databricks.libraryIsolation.enabled como false.

Essa API é compatível com a instalação da biblioteca em todo o cluster existente por meio da interface do usuário e da API de bibliotecas. As bibliotecas instaladas por meio dessa API têm prioridade mais alta do que as bibliotecas em todo o cluster.

Para listar os comandos disponíveis, execute 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)

Dado um caminho para uma biblioteca, a instalação dessa biblioteca é feita dentro da sessão atual do notebook. As bibliotecas instaladas com a chamada desse comando estão disponíveis somente para o notebook atual.

Para exibir a ajuda desse comando, execute dbutils.library.help("install").

Este exemplo instala uma biblioteca .egg ou .whl em um notebook.

Importante

dbutils.library.install é removido no Databricks Runtime 11.0 e versões posteriores.

O Databricks recomenda que você coloque todos os comandos de instalação da biblioteca na primeira célula do notebook e chame restartPython no final dessa célula. O estado do notebook Python é redefinido após a execução de restartPython; o notebook perde todo o estado, incluindo, por exemplo, variáveis locais, bibliotecas importadas e outros estados efêmeros. Portanto, recomendamos que você instale bibliotecas e redefina o estado do notebook na primeira célula do notebook.

As fontes de biblioteca aceitas são dbfs, abfss, adl e 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.

Observação

Você pode instalar diretamente arquivos .whl personalizados usando %pip. No exemplo abaixo, estamos supondo que você carregou o arquivo .whl de biblioteca no DBFS:

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

Não há suporte para arquivos egg no pip. Os arquivos wheel são considerados o padrão para build e empacotamento binário no Python. No entanto, se você quiser usar um arquivo .egg de maneira compatível com %pip, poderá usar a seguinte solução 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)

Ao receber um pacote PyPI (Índice de Pacotes Python), instale esse pacote na sessão atual do notebook. As bibliotecas instaladas com a chamada desse comando são isoladas entre notebooks.

Para exibir a ajuda desse comando, execute dbutils.library.help("installPyPI").

Este exemplo instala um pacote PyPI em um notebook. version, repo e extras são opcionais. Use o argumento extras para especificar o Recurso extra (requisitos extras).

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 é removido no Databricks Runtime 11.0 e versões posteriores.

As chaves version e extras não podem fazer parte da cadeia de caracteres do pacote PyPI. Por exemplo, dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") não é válido. Use os argumentos version e extras para especificar a versão e as informações extras da seguinte forma:

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.

Observação

Na substituição de comandos dbutils.library.installPyPI por comandos %pip, o interpretador do Python é reiniciado automaticamente. Você pode executar o comando install da seguinte forma:

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

Este exemplo especifica os requisitos de biblioteca em um notebook e os instala usando %run no outro. Para fazer isso, primeiro defina as bibliotecas a serem instaladas em um notebook. Este exemplo usa um notebook chamado 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.

Em seguida, instale-os no notebook que precisa dessas dependências.

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

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

Este exemplo redefine o estado do notebook Python, mas mantendo o ambiente. Essa técnica está disponível somente em notebooks Python. Por exemplo, você pode usar essa técnica para recarregar bibliotecas do Azure Databricks pré-instaladas com uma versão diferente:

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

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

Você também pode usar essa técnica para instalar bibliotecas como a tensorflow, que precisam ser carregadas no início do processo:

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

# Use the library in another cell.
import tensorflow

Comando list (dbutils.library.list)

Lista as bibliotecas isoladas adicionadas à sessão atual do notebook por meio do utilitário de biblioteca. Isso não inclui bibliotecas anexadas ao cluster.

Para exibir a ajuda desse comando, execute dbutils.library.help("list").

Este exemplo lista as bibliotecas instaladas em um notebook.

dbutils.library.list()

Observação

O equivalente desse comando usando %pip é:

%pip freeze

Comando updateCondaEnv (dbutils.library.updateCondaEnv)

Atualiza o ambiente Conda do notebook atual com base no conteúdo de environment.yml. Esse método tem suporte apenas no Databricks Runtime no Conda.

Para exibir a ajuda desse comando, execute dbutils.library.help("updateCondaEnv").

Este exemplo atualiza o ambiente Conda no notebook atual com base no conteúdo da especificação fornecida.

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