Compartilhar via

Bibliotecas Python no escopo do notebook

  • Artigo

As bibliotecas no escopo do notebook permitem criar, modificar, salvar, reutilizar e compartilhar ambientes personalizados do Python específicos de um notebook. Quando você instala uma biblioteca no escopo do notebook, somente o notebook atual e os trabalhos a ele associados têm acesso a essa biblioteca. Outros notebooks anexados ao mesmo cluster não são afetados.

As bibliotecas no escopo do notebook não persistem entre sessões. Você deve reinstalar bibliotecas no escopo do notebook no início de cada sessão, ou sempre que o notebook for desvinculado de um cluster.

Em vez disso, o Databricks recomenda usar o comando magic %pip para instalar bibliotecas no escopo do notebook.

Você pode usar %pip em notebooks agendados como trabalhos. Se você precisar gerenciar o ambiente do Python em um notebook Scala, SQL ou R, use o comando magic %python em combinação com %pip.

Você pode experimentar mais tráfego para o nó do driver ao trabalhar com instalações de biblioteca no escopo do notebook. Consulte Qual deve ser o tamanho do nó do driver ao trabalhar com bibliotecas no escopo do notebook?.

Para instalar bibliotecas para todos os notebooks anexados a um cluster, use as bibliotecas do cluster. Consulte as Bibliotecas de cluster.

Para obter uma visão geral abrangente das opções disponíveis para instalar bibliotecas do Python no Databricks, consulte Gerenciamento de ambiente do Python.

Observação

No Databricks Runtime 10.4 LTS e abaixo, você pode usar o utilitário de biblioteca (herdado) do Azure Databricks. O utilitário de biblioteca tem suporte apenas no Databricks Runtime, não no Databricks Runtime ML. Veja Utilitário de biblioteca (dbutils.library) (herdado).

Gerenciar bibliotecas com comandos%pip

O comando %pip é equivalente ao comando pip e dá suporte à mesma API. As seções a seguir mostram exemplos de como você pode usar comandos %pip para gerenciar seu ambiente. Para obter mais informações sobre como instalar pacotes do Python com pip, consulte a Documentação de instalação do pip e as páginas relacionadas.

Importante

  • A partir do Databricks Runtime 13.0, os comandos %pip não reiniciam automaticamente o processo do Python. Se você instalar um novo pacote ou atualizar um pacote existente, talvez seja necessário usar dbutils.library.restartPython() para ver os novos pacotes. Confira Reiniciar o processo do Python no Azure Databricks.
  • No Databricks Runtime 12.2 LTS e abaixo, o Databricks recomenda colocar todos os comandos %pip no início do notebook. O estado do notebook é redefinido após qualquer comando %pip que modifique o ambiente. Se você criar métodos ou variáveis do Python em um notebook e, em seguida, usar comandos %pip em uma célula posterior, os métodos ou variáveis serão perdidos.
  • Atualizar, modificar ou desinstalar pacotes principais do Python (como o IPython) com %pip pode fazer com que algumas funcionalidades parem de funcionar conforme o esperado. Se você tiver esses problemas, redefina o ambiente desconectando e anexando novamente o notebook ou reiniciando o cluster.

Instalar uma biblioteca com %pip

%pip install matplotlib

Instalar um pacote wheel do Python com %pip

%pip install /path/to/my_package.whl

Desinstalar uma biblioteca com %pip

Observação

Não é possível desinstalar uma biblioteca incluída nas versões de notas sobre a versão do Databricks Runtime e compatibilidade ou uma biblioteca que foi instalada como uma biblioteca de cluster. Se você tiver instalado uma versão de biblioteca diferente da versão incluída no Databricks Runtime ou da instalada no cluster, poderá usar %pip uninstall para reverter a biblioteca para a versão padrão no Databricks Runtime ou para a versão instalada no cluster, mas não poderá usar um comando %pip para desinstalar a versão de uma biblioteca incluída no Databricks Runtime ou instalada no cluster.

%pip uninstall -y matplotlib

A opção -y é obrigatória.

Instalar uma biblioteca de um sistema de controle de versão com %pip

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

Você pode adicionar parâmetros à URL para especificar parâmetros como a versão ou o subdiretório git. Consulte o Suporte do VCS para obter mais informações e exemplos que usem outros sistemas de controle de versão.

Instalar um pacote privado com credenciais gerenciadas pelos segredos do Databricks com %pip

O pip dá suporte à instalação de pacotes de fontes privadas com autenticação básica, incluindo sistemas de controle de versão privados e repositórios de pacotes privados, como Nexus e Artifactory. O gerenciamento de segredos está disponível por meio da API de Segredos do Databricks, que permite armazenar tokens de autenticação e senhas. Use a API DBUtils para acessar segredos do notebook. Observe que você pode usar $variables em comandos magic.

Para instalar um pacote de um repositório privado, especifique a URL do repositório com a opção --index-url para %pip install ou adicione-a ao arquivo de configuração pip em ~/.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/

Da mesma forma, você pode usar o gerenciamento de segredos com comandos magic para instalar pacotes privados de sistemas de controle de versão.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Instalar um pacote do DBFS com %pip

Importante

Qualquer usuário do workspace pode modificar arquivos armazenados no DBFS. O Azure Databricks recomenda armazenar arquivos em workspaces ou em volumes do Catálogo do Unity.

Você pode usar %pip para instalar um pacote privado que foi salvo no DBFS.

Quando você carrega um arquivo no DBFS, ele renomeia automaticamente o arquivo, substituindo espaços, pontos e hifens por sublinhados. Para arquivos wheel do Python, pip exige que o nome do arquivo use pontos na versão (por exemplo, 0.1.0) e hifens em vez de espaços ou sublinhados, para esses nomes de arquivos não serem alterados.

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

Instalar um pacote de um volume com %pip

Importante

Esse recurso está em uma versão prévia.

Com o Databricks Runtime 13.3 LTS e superior, você pode usar %pip para instalar um pacote privado que foi salvo em um volume.

Quando você carrega um arquivo em um volume, ele automaticamente renomeia o arquivo, substituindo espaços, pontos e hifens por sublinhados. Para arquivos wheel do Python, pip exige que o nome do arquivo use pontos na versão (por exemplo, 0.1.0) e hifens em vez de espaços ou sublinhados, para esses nomes de arquivos não serem alterados.

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

Instalar um pacote armazenado como um arquivo de workspace com %pip

Com o Databricks Runtime 11.3 e superior, você pode usar %pip para instalar um pacote privado que tenha sido salvo em um volume.

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

Salvar bibliotecas em um arquivo de requisitos

%pip freeze > /Workspace/shared/prod_requirements.txt

Todos os subdiretórios no caminho do arquivo já devem existir. Se você executar %pip freeze > /Workspace/<new-directory>/requirements.txt, o comando falhará se o diretório /Workspace/<new-directory> ainda não existir.

Usar um arquivo de requisitos para instalar bibliotecas

Um arquivo de requisitos contém uma lista de pacotes a serem instalados usando pip. Um exemplo de como usar um arquivo de requisitos é:

%pip install -r /Workspace/shared/prod_requirements.txt

Consulte Formato de arquivo de requisitos para obter mais informações sobre arquivos requirements.txt.

Qual deve ser o tamanho do nó do driver ao trabalhar com bibliotecas no escopo do notebook?.

O uso de bibliotecas no escopo do notebook pode resultar em mais tráfego para o nó do driver, já que funciona para manter o ambiente consistente entre nós de executor.

Quando você usa um cluster com 10 ou mais nós, o Databricks recomenda essas especificações como um requisito mínimo para o nó do driver:

  • Para um cluster de CPU de 100 nós, use Standard_DS5_v2.
  • Para um cluster de GPU de 10 nós, use Standard_NC12.

Para clusters maiores, use um nó de driver maior.

Posso usar %sh pip, !pip ou pip? Qual é a diferença?

%sh e ! executam um comando do shell em um notebook; o primeiro é um comando magic auxiliar do Azure Databricks e o último é um recurso do IPython. pip é uma abreviação de %pip quando o automagic está habilitado, que é o padrão em notebooks Python do Azure Databricks.

No Databricks Runtime 11.3 LTS e superior, %pip, %sh pip, e !pip todos instalam uma biblioteca como uma biblioteca Python com escopo de notebook. No Databricks Runtime 10.4 LTS e versões inferiores, o Databricks recomenda usar apenas %pip ou pip para instalar bibliotecas com escopo de notebook. O comportamento de %sh pip e !pip não é consistente no Databricks Runtime 10.4 LTS e versões inferiores.

Problemas conhecidos

  • No Databricks Runtime 9.1 LTS, as bibliotecas com escopo de notebook são incompatíveis com trabalhos de streaming em lote. O Databricks recomenda usar bibliotecas de cluster ou o kernel do IPython.