Bibliotecas de Python com âmbito de bloco de notas

  • Artigo

As bibliotecas com escopo de bloco de anotações permitem criar, modificar, salvar, reutilizar e compartilhar ambientes Python personalizados específicos de um bloco de anotações. Quando você instala uma biblioteca com escopo de bloco de anotações, somente o bloco de anotações atual e todos os trabalhos associados a esse bloco de anotações têm acesso a essa biblioteca. Outros blocos de anotações conectados ao mesmo cluster não são afetados.

As bibliotecas com escopo de bloco de anotações não persistem entre sessões. Você deve reinstalar bibliotecas com escopo de bloco de anotações no início de cada sessão ou sempre que o bloco de anotações for desanexado de um cluster.

O Databricks recomenda o uso do %pip comando magic para instalar bibliotecas Python com escopo de notebook.

Você pode usar %pip em blocos de anotações agendados como trabalhos. Se você precisar gerenciar o ambiente Python em um notebook Scala, SQL ou R, use o comando magic em conjunto com %pipo %python .

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

Para instalar bibliotecas para todos os blocos de anotações conectados a um cluster, use bibliotecas de cluster. Veja Bibliotecas de cluster.

Nota

No Databricks Runtime 10.4 LTS e inferior, você pode usar o utilitário de biblioteca (legado) Azure Databricks. O utilitário de biblioteca é suportado apenas no Databricks Runtime, não no Databricks Runtime ML. Consulte Utilitário de biblioteca (dbutils.library) (legado).

Gerenciar bibliotecas com %pip comandos

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

Importante

  • A partir do Databricks, os comandos do Runtime 13.0 %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. Consulte Reiniciar o processo Python no Azure Databricks.
  • No Databricks Runtime 12.2 LTS e inferior, o Databricks recomenda colocar todos os %pip comandos no início do notebook. O estado do bloco de anotações é redefinido após qualquer %pip comando que modifique o ambiente. Se você criar métodos Python ou variáveis em um bloco de anotações e, em seguida, usar %pip comandos em uma célula posterior, os métodos ou variáveis serão perdidos.
  • Atualizar, modificar ou desinstalar pacotes Python principais (como IPython) com pode fazer com %pip que alguns recursos parem de funcionar conforme o esperado. Se você tiver esses problemas, redefina o ambiente desanexando e reconectando o bloco de anotações ou reiniciando o cluster.

Instale uma biblioteca com %pip

%pip install matplotlib

Instale um pacote de roda Python com %pip

%pip install /path/to/my_package.whl

Desinstalar uma biblioteca com %pip

Nota

Não é possível desinstalar uma biblioteca incluída nas versões e compatibilidade das notas de versão do Databricks Runtime ou uma biblioteca que tenha sido instalada como uma biblioteca de cluster. Se você tiver instalado uma versão de biblioteca diferente da incluída no Databricks Runtime ou da instalada no cluster, poderá reverter %pip uninstall 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 %pip comando para desinstalar a versão de uma biblioteca incluída no Databricks Runtime ou instalada no cluster.

%pip uninstall -y matplotlib

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

Instale uma biblioteca a partir 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 coisas como a versão ou o subdiretório git. Consulte o suporte VCS para obter mais informações e exemplos de utilização de outros sistemas de controlo de versão.

Instale um pacote privado com credenciais gerenciadas por segredos do Databricks com %pip

O Pip suporta a 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 Databricks Secrets, que permite armazenar tokens de autenticação e senhas. Use a API DBUtils para acessar segredos do seu bloco de anotações. Note que você pode usar $variables em comandos mágicos.

Para instalar um pacote a partir de um repositório privado, especifique o URL do repositório com a --index-url opção de adicioná-lo pip ao %pip install arquivo de configuração 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 secreto com comandos mágicos 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>

Instale um pacote do DBFS com %pip

Importante

Qualquer usuário do espaço de trabalho pode modificar arquivos armazenados no DBFS. O Azure Databricks recomenda armazenar arquivos em espaços de trabalho ou em volumes do Catálogo 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 hífenes por sublinhados. Para arquivos de roda Python, pip requer que o nome do arquivo use períodos na versão (por exemplo, 0.1.0) e hífenes em vez de espaços ou sublinhados, para que esses nomes de arquivos não sejam alterados.

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

Instale um pacote a partir de um volume com %pip

Importante

Esta funcionalidade está em Pré-visualização Pública.

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 renomeia automaticamente o arquivo, substituindo espaços, pontos e hífenes por sublinhados. Para arquivos de roda Python, pip requer que o nome do arquivo use períodos na versão (por exemplo, 0.1.0) e hífenes em vez de espaços ou sublinhados, para que esses nomes de arquivos não sejam alterados.

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

Instale um pacote armazenado como um arquivo de espaço de trabalho com %pip

Com o Databricks Runtime 11.3 LTS e superior, você pode usar %pip para instalar um pacote privado que foi salvo como um arquivo de espaço de trabalho.

%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.txto , 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 pipo . Um exemplo de uso de um arquivo de requisitos é:

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

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

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

O uso de bibliotecas com escopo de bloco de anotações pode resultar em mais tráfego para o nó do driver à medida que ele trabalha para manter o ambiente consistente entre os nós do executor.

Quando você usa um cluster com 10 ou mais nós, o Databricks recomenda estas 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?

%she ! executar um comando shell em um notebook, o primeiro é um comando mágico auxiliar Databricks enquanto o segundo é um recurso do IPython. pip é uma abreviação para %pip quando o automagic está habilitado, que é o padrão nos blocos de anotações Python do Azure Databricks.

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

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 o uso de bibliotecas de cluster ou do kernel IPython.