Instalar bibliotecas para computação
Ao executar notebooks e trabalhos na computação do Azure Databricks, você costuma precisar de pacotes de terceiros ou código personalizado não incluído no runtime padrão. A instalação de bibliotecas no nível do cluster garante que cada notebook e trabalho usando essa computação tenham acesso às mesmas dependências, criando um ambiente de execução consistente.
Entender como instalar bibliotecas efetivamente se torna crítico à medida que seus fluxos de trabalho de engenharia de dados crescem em complexidade. Você precisa saber qual método de instalação usar, onde armazenar arquivos de biblioteca e como os modos de acesso afetam suas opções.
Entender bibliotecas com escopo de computação
Bibliotecas com escopo de computação são instaladas em um cluster e são disponibilizadas para todos os notebooks e trabalhos executados nesse cluster. Diferente de bibliotecas com escopo de notebook, que são instaladas apenas para uma sessão específica de notebook, as bibliotecas de escopo de computação persistem durante reinicializações de cluster e oferecem um ambiente compartilhado para todos os usuários.
Quando você instala uma biblioteca no nível do cluster, o Azure Databricks reinstala-a automaticamente sempre que o cluster é iniciado. Esse comportamento garante consistência: você não precisa reinstalar manualmente as dependências depois de parar e reiniciar um cluster. Todos os notebooks anexados ao cluster podem importar e usar os pacotes instalados imediatamente.
Observação
Para instalar bibliotecas em um cluster, você deve ter permissão CAN MANAGE nesse cluster. Essa permissão permite que você modifique a configuração do cluster, incluindo a adição e remoção de bibliotecas. Sem essa permissão, você não poderá acessar a interface de instalação da biblioteca.
As bibliotecas com escopo de computação dão suporte a Python wheels, arquivos JAR Java e pacotes R. Você pode instalá-los a partir de repositórios de pacotes, como PyPI e Maven, ou de arquivos armazenados em arquivos de workspace, volumes do Catálogo do Unity ou armazenamento de objetos na nuvem. O método de instalação escolhido depende do tipo de biblioteca, do modo de acesso do cluster e dos requisitos de segurança organizacional.
Mas, as bibliotecas com escopo de computação têm uma limitação importante: cada biblioteca instalada afeta cada notebook no cluster. Se equipes distintas precisarem de versões conflitantes da mesma biblioteca, você precisará de clusters separados ou instalações com escopo de notebook para evitar conflitos.
Instalar bibliotecas de repositórios de pacotes
Os repositórios de pacotes fornecem a maneira mais comum de instalar bibliotecas. O PyPI hospeda pacotes python, o Maven hospeda bibliotecas Java e Scala e o CRAN hospeda pacotes R. Esses repositórios lidam automaticamente com a resolução de dependência e o gerenciamento de versão.
Para instalar uma biblioteca do PyPI, selecione PyPI como a origem da biblioteca e insira o nome do pacote. Para cargas de trabalho de produção, especifique uma versão exata para garantir a capacidade de reprodução: pymssql==2.3.9. Sem um número de versão, o Azure Databricks instala a versão mais recente disponível, o que pode mudar entre instalações e potencialmente interromper seu código.
As bibliotecas Maven exigem coordenadas no formato groupId:artifactId:version. Por exemplo, para instalar a biblioteca do Microsoft JDBC Driver for SQL Server, você usaria com.microsoft.sqlserver:mssql-jdbc:13.2.1.jre11. Você pode pesquisar pacotes diretamente na caixa de diálogo de instalação se não souber as coordenadas exatas. O Maven também dá suporte à exclusão de dependências transitivas específicas que podem entrar em conflito com outras bibliotecas instaladas.
Para pacotes R do CRAN, forneça o nome do pacote. Ao contrário das bibliotecas Python e Java, as instalações cran sempre extraem a versão mais recente do espelho configurado. Para fixar versões específicas do pacote R, armazene os arquivos de pacote em arquivos de workspace ou volumes, em vez de instalar do CRAN.
Com clusters configurados no modo de acesso padrão, as coordenadas do Maven e os caminhos de arquivo JAR exigem allowlist aprovação antes da instalação. Essa medida de segurança garante que os administradores revisem e aprovem bibliotecas executadas em recursos de computação compartilhados.
Observação
Para saber mais sobre como configurar e gerenciar allowlists bibliotecas, consulte a documentação.
Instalar bibliotecas de arquivos
Armazenar arquivos da biblioteca em arquivos de workspace ou em volumes do Unity Catalog permite um controle preciso das versões de biblioteca utilizadas pelos seus clusters. Essa abordagem funciona bem quando você precisa de bibliotecas não disponíveis em repositórios públicos, pacotes personalizados criados internamente ou versões específicas que não estão mais disponíveis em repositórios de pacotes.
Utilizar arquivos de espaço de trabalho e volumes do Catálogo Unity para a instalação de bibliotecas mantém o gerenciamento centralizado, em vez de contornar os controles de segurança com instalações ad hoc, como comandos pip3 diretos ou scripts personalizados não gerenciados executados a partir de notebooks. Os volumes do Unity Catalog fornecem governança aprimorada por meio do modelo de controle de acesso do Unity Catalog, garantindo que todas as instalações de bibliotecas sejam acompanhadas por logs de auditoria e protegidas por permissões detalhadas.
Os arquivos de workspace fornecem um local conveniente para o armazenamento de biblioteca com um limite de tamanho de arquivo de 500 MB. Para instalar uma biblioteca a partir dos arquivos do workspace, carregue seu arquivo wheel, JAR ou requirements.txt por meio da caixa de diálogo Importar do workspace e, depois, referencie-o durante a instalação da biblioteca usando um caminho como /Workspace/Users/you@example.com/libraries/mypackage-1.0.0-py3-none-any.whl.
Os volumes do Catálogo do Unity oferecem segurança e governança aprimoradas para o armazenamento de bibliotecas. Você controla o acesso por meio de permissões do Catálogo do Unity, garantindo que somente usuários autorizados possam ler ou modificar arquivos de biblioteca. Carregue arquivos em um volume por meio do Catalog Explorer e instale-os usando um caminho como /Volumes/main/engineering/libraries/mypackage-1.0.0-py3-none-any.whl. A identidade usada para instalação deve ter a permissão READ VOLUME no volume especificado.
Os arquivos requirements.txt do Python funcionam com arquivos de workspace e volumes no Databricks Runtime 15.0 e posteriores. Esses arquivos permitem que você defina várias dependências de pacote em um único arquivo, facilitando a manutenção de ambientes consistentes entre clusters. Carregue o arquivo requirements.txt e instale-o como qualquer outra biblioteca— o Azure Databricks instala automaticamente todos os pacotes listados.
Para clusters com modo de acesso padrão, você deve adicionar caminhos de arquivo de biblioteca ao allowlist antes da instalação. Isso se aplica a arquivos de workspace e volumes, garantindo que os administradores aprovem as bibliotecas usadas na computação compartilhada.
Usar scripts de inicialização para configuração avançada
Os scripts init executam comandos de shell durante a inicialização do cluster, antes do início do driver e dos executores do Spark. Embora o Databricks não recomende usar scripts de inicialização para a instalação da biblioteca — bibliotecas com escopo de cluster fornecem uma abordagem melhor— os scripts de inicialização são úteis para a configuração no nível do sistema que as bibliotecas não podem lidar.
Você pode usar scripts de inicialização para instalar pacotes do sistema com apt-get, configurar variáveis de ambiente ou configurar agentes de monitoramento. Por exemplo, um script de inicialização pode instalar um driver de banco de dados especializado que requer bibliotecas do sistema e, em seguida, configurar parâmetros de conexão por meio de variáveis de ambiente. O script é executado sempre que o cluster é iniciado, garantindo que sua configuração persista entre reinicializações.
Armazene scripts de inicialização em volumes do Catálogo do Unity para clusters que executam o Databricks Runtime 13.3 LTS e superior. Crie um arquivo de script de shell, carregue-o em um volume e configure o cluster para executar o script especificando seu caminho como /Volumes/main/engineering/scripts/setup.sh. Para o modo de acesso padrão, adicione o caminho de script de inicialização ao allowlist antes de configurar o cluster.
Os scripts de inicialização são executados sequencialmente na ordem especificada. Se qualquer script retornar um código de saída diferente de zero, o cluster não será iniciado. Essa proteção contra falhas impede que os clusters sejam executados com configuração incompleta ou incorreta. Para solucionar problemas de scripts de inicialização com falha, configure a entrega de log do cluster e examine os logs do script de inicialização.
Considere os scripts de inicialização como um último recurso para as necessidades de configuração que as bibliotecas com escopo de cluster e as políticas de cluster não podem resolver. O uso de políticas de cluster para definir variáveis de ambiente e configurações do Spark geralmente fornece uma solução mais simples e mais mantenedível do que scripts de inicialização.
Configurar bibliotecas para o modo de acesso padrão
Os clusters configurados com o modo de acesso padrão fornecem a segurança e o isolamento mais fortes no Azure Databricks. Esse modo requer aprovação explícita para bibliotecas e scripts de inicialização para impedir a execução de código não autorizado em recursos de computação compartilhados.
Antes de instalar bibliotecas Maven ou arquivos JAR em clusters de modo de acesso padrão, um administrador do metastore deve adicioná-los ao allowlist. As coordenadas do Maven são colocadas no allowlist usando o formato groupId:artifactId:version. Você pode allowlist todas as versões de uma biblioteca com groupId:artifactId, ou todos os artefatos em um grupo com apenas groupId. Para arquivos JAR armazenados em volumes ou armazenamento de objetos, allowlist o caminho do arquivo ou o caminho do diretório.
Os scripts de inicialização exigem entradas separadas allowlist mesmo se armazenados no mesmo local que os arquivos JAR. Ao permitir a listagem de um caminho, o Azure Databricks usa a correspondência de prefixo — adicionar /Volumes/prod-libraries/ ao allowlist permite todos os arquivos e subdiretórios dentro desse local. Inclua uma barra no final para evitar correspondências de prefixo não intencionais em nível de diretório.
O allowlist apenas concede permissão para usar um caminho para instalação de biblioteca ou de script de inicialização. Você ainda precisa de permissões de acesso a dados apropriadas. Para volumes, a identidade do instalador deve ter permissão READ VOLUME. Para o modo de acesso padrão, a identidade do proprietário do cluster valida essas permissões durante a instalação da biblioteca.
Para configurar o allowlist, os administradores do metastore usam o Catalog Explorer, selecionando as configurações do metastore e navegando até a seção JARs/Init Scripts permitidos. Esse controle centralizado garante que as equipes de segurança possam examinar e aprovar todas as bibliotecas usadas nos recursos de computação da organização, mantendo a governança sem bloquear a produtividade.
Escolha o método de instalação correto
Diferentes métodos de instalação de biblioteca se adaptam a cenários diferentes. O diagrama a seguir ilustra um fluxo de decisão para ajudá-lo a selecionar a abordagem de instalação apropriada:
