Bibliotecas
Para disponibilizar códigos de terceiros ou personalizados para notebooks e trabalhos em execução em seus clusters, você pode instalar uma biblioteca. As bibliotecas podem ser escritas em Python, Java, Scala e R. É possível carregar bibliotecas em Python, Java e Scala, além de referenciar pacotes externos nos repositórios PyPI, Maven e CRAN.
O Azure Databricks inclui muitas bibliotecas comuns no Databricks Runtime. Para ver quais bibliotecas são incluídas no Databricks Runtime, examine a subseção Ambiente do Sistema das notas sobre a versão do Databricks Runtime da sua versão do Databricks Runtime.
Observação
O Suporte da Microsoft ajuda a isolar e resolver problemas relacionados a bibliotecas instaladas e mantidas pelo Azure Databricks. Para componentes de terceiros, incluindo bibliotecas, a Microsoft fornece suporte comercial razoável a fim de ajudar você ainda mais a solucionar problemas. O Suporte da Microsoft auxilia sempre da melhor maneira possível e pode ser capaz de resolver o problema. Para conectores de software livre e projetos hospedados no GitHub, recomendamos registrar problemas no GitHub e acompanhá-los. Os esforços de desenvolvimento, como os jars de sombreamento ou a criação de bibliotecas Python, não são compatíveis com um processo de envio de caso de suporte standard: eles exigem a participação de uma consultoria para obter uma resolução mais rápida. O suporte poderá solicitar que você envolva outros canais para obter tecnologias de software livre em que será possível encontrar uma experiência avançada para essa tecnologia. Há vários sites dessa comunidade. Dois exemplos são a Página do Microsoft Q&A para Azure Databricks e o Stack Overflow.
Bibliotecas com escopo de cluster
Instale bibliotecas em clusters para que elas estejam disponíveis para todos os notebooks e trabalhos em execução no cluster. O Databricks oferece suporte para bibliotecas Python, JAR e R. Consulte as Bibliotecas de cluster.
Você pode instalar uma biblioteca de clusters diretamente das seguintes fontes:
- Um repositório de pacotes como PyPI, Maven ou CRAN
- Arquivos de workspace
- Volumes do Catálogo do Unity
- Um local de armazenamento de objetos na nuvem
- Um caminho em seu computador local
Nem todos os locais têm suporte para todos os tipos de bibliotecas ou todas as configurações de computação. Confira recomendações de configurações em Recomendações para carregar bibliotecas.
Importante
As bibliotecas podem ser instaladas a partir do DBFS ao usar o Databricks Runtime 14.3 LTS e inferior. Porém, qualquer usuário do espaço de trabalho pode modificar os arquivos de biblioteca armazenados no DBFS. Para melhorar a segurança das bibliotecas em um workspace do Azure Databricks, o armazenamento de arquivos de biblioteca na raiz do DBFS foi preterido e desabilitado por padrão no Databricks Runtime 15.1 e em versões posteriores. Consulte O armazenamento de bibliotecas na raiz do DBFS é preterido e desabilitado por padrão.
Em vez disso, o Databricks recomenda carregar todas as bibliotecas, incluindo bibliotecas python, arquivos JAR e conectores Spark, para arquivos de workspace ou volumes do Catálogo do Unity ou usando repositórios de pacotes de biblioteca. Se sua carga de trabalho não der suporte a esses padrões, você também poderá usar bibliotecas armazenadas no armazenamento de objetos de nuvem.
Para informações completas sobre suporte às bibliotecas, confira Suporte às bibliotecas Python, Suporte às bibliotecas Java e Scala e Suporte às bibliotecas R.
Recomendações para carregar bibliotecas
O Databricks oferece suporte à maioria das configurações de instalação de bibliotecas Python, JAR e R, mas existem alguns cenários sem suporte. Recomenda-se carregar as bibliotecas em locais de origem que permitam a instalação em computação com modo de acesso compartilhado, que é o modo recomendado para todas as cargas de trabalho. Consulte Modos de acesso. Ao agendar trabalhos com o modo de acesso compartilhado, execute o trabalho com uma entidade de serviço.
Importante
Só use a computação com modo de acesso de usuário único se a funcionalidade necessária não tiver suporte no modo de acesso compartilhado. O modo de acesso compartilhado sem isolamento é uma configuração antiga no Databricks e não é recomendada.
A tabela a seguir fornece recomendações organizadas de acordo com a versão do Databricks Runtime e habilitação do Unity Catalog.
| Configuração | Recomendação |
|---|---|
| Databricks Runtime 13.3 LTS e superior com o Unity Catalog | Instale bibliotecas na computação com modo de acesso compartilhado a partir de volumes do Unity Catalog com permissão de leitura (GRANT READ) para todos os usuários da conta. Se aplicável, adicione as coordenadas Maven e os caminhos das bibliotecas JAR à lista de permissões. |
| Databricks Runtime 11.3 LTS e superior sem o Unity Catalog | Instale bibliotecas a partir de arquivos do workspace. (O limite de tamanho do arquivo é de 500 MB.) |
| Databricks Runtime 10.4 LTS e abaixo | Instalar bibliotecas do armazenamento de objetos na nuvem. |
Suporte da biblioteca Python
A tabela a seguir indica a compatibilidade da versão do Databricks Runtime para arquivos wheel do Python para diferentes modos de acesso ao cluster com base no local de origem da biblioteca. Veja Compatibilidade e notas sobre a versão do Databricks Runtime e Modos de acesso.
Com o Databricks Runtime 15.0 e superior, você pode usar arquivos requirements.txt para gerenciar suas dependências do Python. Esses arquivos podem ser carregados em qualquer local de origem com suporte.
Observação
Não há suporte para a instalação de arquivos egg do Python com o Databricks Runtime 14.0 e superior. Em vez disso, use arquivos wheel do Python ou instale pacotes PyPI.
| Modo de acesso compartilhado | Modo de acesso de usuário único | Modo de acesso compartilhado sem isolamento (herdado) | |
|---|---|---|---|
| PyPI | 13.3 LTS e superior | Todas as versões com suporte do Databricks Runtime | Todas as versões com suporte do Databricks Runtime |
| Arquivos do workspace | 13.3 LTS e superior | 13.3 LTS e superior | 14.1 e superior |
| Volumes | 13.3 LTS e superior | 13.3 LTS e superior | Sem suporte |
| Armazenamento em nuvem | 13.3 LTS e superior | Todas as versões com suporte do Databricks Runtime | Todas as versões com suporte do Databricks Runtime |
| DBFS(não recomendado) | Sem suporte | 14.3 e inferior | 14.3 e inferior |
Suporte à biblioteca Java e Scala
A tabela a seguir mostra a compatibilidade de versões do Databricks Runtime para arquivos JAR em diferentes modos de acesso ao cluster, baseando-se no local de origem da biblioteca. Veja Compatibilidade e notas sobre a versão do Databricks Runtime e Modos de acesso.
Observação
O modo de acesso compartilhado requer um administrador para adicionar coordenadas do Maven e caminhos para bibliotecas JAR a uma allowlist. Consulte Bibliotecas de lista de permitidos e scripts de inicialização na computação compartilhada.
| Modo de acesso compartilhado | Modo de acesso de usuário único | Modo de acesso compartilhado sem isolamento (herdado) | |
|---|---|---|---|
| Maven | 13.3 LTS e superior | Todas as versões com suporte do Databricks Runtime | Todas as versões com suporte do Databricks Runtime |
| Arquivos do workspace | Sem suporte | Sem suporte | 14.1 e superior |
| Volumes | 13.3 LTS e superior | 13.3 LTS e superior | Sem suporte |
| Armazenamento em nuvem | 13.3 LTS e superior | Todas as versões com suporte do Databricks Runtime | Todas as versões com suporte do Databricks Runtime |
| DBFS(não recomendado) | Sem suporte | 14.3 e inferior | 14.3 e inferior |
Suporte à biblioteca R
A tabela a seguir mostra a compatibilidade de versões do Databricks Runtime para pacotes CRAN em diferentes modos de acesso ao cluster. Veja Compatibilidade e notas sobre a versão do Databricks Runtime e Modos de acesso.
| Modo de acesso compartilhado | Modo de acesso de usuário único | Modo de acesso compartilhado sem isolamento (herdado) | |
|---|---|---|---|
| CRAN | Sem suporte | Todas as versões com suporte do Databricks Runtime | Todas as versões com suporte do Databricks Runtime |
Bibliotecas no escopo do notebook
As bibliotecas no escopo do notebook, disponíveis para Python e R, permitem que você instale bibliotecas e crie um ambiente com escopo para uma sessão de notebook. Essas bibliotecas não afetam outros notebooks em execução no mesmo cluster. As bibliotecas no escopo do notebook não são mantidas e precisam ser reinstaladas para cada sessão. Use bibliotecas no escopo do notebook quando precisar de um ambiente personalizado para um notebook específico.
Observação
Os JARs não podem ser instalados no nível do notebook.
Importante
As bibliotecas de workspace foram preteridas e não devem ser usadas. Veja Bibliotecas de workspace (herdadas). No entanto, o armazenamento de bibliotecas como arquivos de workspace é diferente das bibliotecas de workspace e ainda é totalmente compatível. Você pode instalar bibliotecas armazenadas como arquivos de espaço de trabalho diretamente em tarefas de computação ou de trabalho.
Gerenciamento de ambiente do Python
A tabela a seguir fornece uma visão geral das opções que você pode usar para instalar as bibliotecas do Python no Azure Databricks.
Observação
- Contêineres personalizados que usam um ambiente baseado no Conda não são compatíveis com bibliotecas com escopo de notebook e com bibliotecas de cluster no Databricks Runtime 10.4 LTS e versões superiores. Em vez Azure Databricks recomenda a instalação de bibliotecas diretamente na imagem ou o uso de scripts de init. Para continuar usando bibliotecas de cluster nesses cenários, você pode definir a configuração do Spark
spark.databricks.driverNfs.clusterWidePythonLibsEnabledcomofalse. O suporte para a configuração do Spark será removido em ou após 31 de dezembro de 2021.
| Origem do pacote do Python | Bibliotecas no escopo do notebook com %pip | Bibliotecas no escopo do notebook com arquivo YAML do ambiente base | Bibliotecas de cluster | Bibliotecas de trabalhos com a API de trabalhos |
|---|---|---|---|---|
| PyPI | Use %pip install. Confira o exemplo. |
Adicione um nome de pacote PyPI a um arquivo YAML do ambiente base. Confira o exemplo. | Selecione PyPI como a origem. | Adicione um novo objeto pypi às bibliotecas de trabalho e especifique o campo package. |
| Espelho PyPI privado, como Nexus ou Artifactory | Use %pip install com a opção --index-url . O gerenciamento de segredos está disponível. Confira o exemplo. |
Adicione o -–index-url a um arquivo YAML do ambiente base. O gerenciamento de segredos está disponível. Confira o exemplo. |
Sem suporte. | Sem suporte. |
| VCS, como o GitHub, com a origem bruta | Use o %pip install e especifique a URL do repositório como o nome do pacote. Confira o exemplo. |
Adicione uma URL de repositório como um nome de pacote a um arquivo YAML do ambiente base. Confira o exemplo. | Selecione PyPI como a origem e especifique a URL do repositório como o nome do pacote. | Adicione um novo objeto pypi às bibliotecas de trabalho e especifique a URL de repositório como o campo package. |
| VCS privado com origem bruta | Use o %pip install e especifique a URL do repositório com autenticação básica como o nome do pacote. O gerenciamento de segredos está disponível. Confira o exemplo. |
Adicione um repositório com autenticação básica como o nome do pacote a um arquivo YAML do ambiente base. Confira o exemplo. | Sem suporte. | Não há suporte. |
| Caminho do arquivo | Use %pip install. Confira o exemplo. |
Adicione um caminho de arquivo como um nome de pacote a um arquivo YAML do ambiente base. Confira o exemplo. | Selecione Caminho do arquivo/ADLS como a origem. | Adicione um novo objeto egg ou whl às bibliotecas de trabalho e especifique o caminho do arquivo como o campo package. |
| Azure Data Lake Storage Gen2 | Use %pip install junto com uma URL pré-assinada. Os caminhos com o protocolo Azure Data Lake Storage Gen2 abfss:// não têm suporte. |
Adicione uma URL pré-assinada como um nome de pacote a um arquivo YAML do ambiente base. Os caminhos com o protocolo Azure Data Lake Storage Gen2 abfss:// não têm suporte. |
Selecione Caminho do arquivo/ADLS como a origem. | Adicione um novo objeto egg ou whl às bibliotecas de trabalho e especifique o caminho do Azure Data Lake Storage Gen2 como o campo package. |
Precedência da biblioteca Python
Você pode encontrar uma situação em que precisa substituir a versão de uma biblioteca interna ou ter uma biblioteca personalizada que entre em conflito no nome com outra biblioteca instalada no cluster. Quando você executa import <library>, a biblioteca com a precedência alta é importada.
Importante
As bibliotecas armazenadas em arquivos de workspace têm precedência diferente dependendo de como elas são adicionadas ao Python sys.path. Uma pasta Git do Databricks adiciona o diretório de trabalho atual ao caminho antes de todas as outras bibliotecas, enquanto os notebooks fora das pastas Git adicionam o diretório de trabalho atual após a instalação de outras bibliotecas. Se você acrescentar manualmente diretórios de workspace ao seu caminho, eles sempre terão a precedência mais baixa.
A lista a seguir ordena a precedência do mais alto para o mais baixo. Nesta lista, um número menor significa precedência maior.
- Bibliotecas no diretório de trabalho atual (somente pastas Git).
- Bibliotecas no diretório raiz da pasta Git (somente pastas Git).
- Bibliotecas no escopo do notebook (
%pip installem notebooks). - Bibliotecas de cluster (usando a interface do usuário, a CLI ou a API).
- Bibliotecas incluídas no Databricks Runtime.
- As bibliotecas instaladas com scripts de inicialização podem resolver antes ou depois das bibliotecas internas, dependendo de como elas são instaladas. O Databricks não recomenda instalar bibliotecas com scripts de inicialização.
- Bibliotecas no diretório de trabalho atual (não em pastas Git).
- Arquivos de workspace acrescentados ao
sys.path.