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

Nota

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

Esta documentação foi desativada e pode não ser atualizada. Os produtos, serviços ou tecnologias mencionados neste conteúdo não são mais suportados.

O Databricks recomenda vivamente a utilização %pip de comandos mágicos para instalar bibliotecas com âmbito de bloco de notas. Veja Bibliotecas em Python com âmbito de bloco de notas.

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

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

O utilitário de biblioteca permite que você instale bibliotecas Python e crie um ambiente com escopo para uma sessão de notebook. As bibliotecas estão disponíveis tanto no driver quanto nos executores, para que você possa consultá-las em funções definidas pelo usuário. Isto permite:

• Dependências de biblioteca de um bloco de anotações a serem organizadas dentro do próprio bloco de anotações.
• Usuários de bloco de anotações com diferentes dependências de biblioteca para compartilhar um cluster sem interferência.

Separar um notebook destrói esse ambiente. No entanto, você pode recriá-lo executando novamente os comandos da API da biblioteca install no bloco de anotações. Consulte a API para saber como você pode redefinir o estado do restartPython bloco de anotações sem perder o ambiente.

Os utilitários de biblioteca estão habilitados por padrão. Portanto, por padrão, o ambiente Python para cada bloco de anotações é isolado usando um executável Python separado que é criado quando o bloco de anotações é anexado e herda o ambiente Python padrão no cluster. As bibliotecas instaladas por meio de um script init no ambiente Python do Azure Databricks ainda estão disponíveis. Você pode desativar esse recurso definindo spark.databricks.libraryIsolation.enabled como false.

Essa API é compatível com a instalação de biblioteca existente em todo o cluster por meio da interface do usuário e da API de bibliotecas. As bibliotecas instaladas por meio dessa API têm prioridade maior 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, instala essa biblioteca na sessão de bloco de anotações atual. As bibliotecas instaladas chamando este comando estão disponíveis apenas para o bloco de anotações atual.

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

Este exemplo instala uma .egg biblioteca ou .whl em um bloco de anotações.

Importante

dbutils.library.install é removido no Databricks Runtime 11.0 e superior.

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

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.

Nota

Você pode instalar diretamente arquivos de roda personalizados usando %pipo . No exemplo a seguir, estamos supondo que você carregou seu arquivo de roda de biblioteca para DBFS:

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

Os arquivos Egg não são suportados pelo pip, e os arquivos wheel são considerados o padrão para build e empacotamento binário para Python. No entanto, se você quiser usar um arquivo egg de uma forma compatível com %pipo , você pode 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)

Dado um pacote Python Package Index (PyPI), instale esse pacote dentro da sessão atual do bloco de anotações. As bibliotecas instaladas chamando esse comando são isoladas entre os blocos de anotações.

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

Este exemplo instala um pacote PyPI em um notebook. version, repoe extras são opcionais. Use o extras argumento para especificar o recurso Extras (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 superior.

As version chaves 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 version argumentos e extras para especificar a versão e as informações extras da seguinte maneira:

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

Ao substituir dbutils.library.installPyPI comandos por %pip comandos, o interpretador Python é reiniciado automaticamente. Você pode executar o comando install da seguinte maneira:

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

Este exemplo especifica os requisitos de biblioteca em um bloco de anotações e os instala usando %run no outro. Para fazer isso, primeiro defina as bibliotecas a serem instaladas em um notebook. Este exemplo usa um bloco de anotações 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 bloco de anotações Python enquanto mantém o ambiente. Esta técnica está disponível apenas em blocos de notas 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 tensorflow que precisam ser carregadas na inicialização 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 para a sessão de bloco de anotações atual por meio do utilitário de biblioteca. Isso não inclui bibliotecas anexadas ao cluster.

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

Este exemplo lista as bibliotecas instaladas em um bloco de anotações.

dbutils.library.list()

Nota

O equivalente a este comando usando %pip é:

%pip freeze

comando updateCondaEnv (dbutils.library.updateCondaEnv)

Atualiza o ambiente Conda do notebook atual com base no conteúdo do environment.yml. Este método é suportado apenas para Databricks Runtime no Conda.

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

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

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