Instalar bibliotecas para computação

Quando executas notebooks e jobs em computação Azure Databricks, muitas vezes precisas de pacotes de terceiros ou código personalizado que não está incluído no runtime padrão. Instalar bibliotecas ao nível do cluster garante que todos os notebooks e trabalhos que utilizam esse computador têm acesso às mesmas dependências, criando um ambiente de execução consistente.

Compreender como instalar bibliotecas de forma eficaz torna-se fundamental à medida que os seus fluxos de trabalho de engenharia de dados se tornam mais complexos. Precisas de saber qual o método de instalação a usar, onde guardar os ficheiros da biblioteca e como os modos de acesso afetam as tuas opções.

Compreender bibliotecas de âmbito computacional

Bibliotecas compute-scoped instalam-se num cluster e tornam-se disponíveis para todos os notebooks e jobs que correm nesse cluster. Ao contrário das bibliotecas com âmbito de notebook que se instalam apenas para uma sessão específica do notebook, as bibliotecas compute-scoped persistem através dos reinícios do cluster e fornecem um ambiente partilhado para todos os utilizadores.

Quando instalas uma biblioteca ao nível do cluster, o Azure Databricks reinstala-a automaticamente sempre que o cluster inicia. Este comportamento garante consistência — não precisa de reinstalar manualmente as dependências depois de parar e reiniciar um cluster. Todos os notebooks ligados ao cluster podem importar e usar os pacotes instalados imediatamente.

As bibliotecas compute-scoped suportam rodas Python, ficheiros Java JAR e pacotes R. Pode instalá-los a partir de repositórios de pacotes como PyPI e Maven, ou a partir de ficheiros armazenados em ficheiros de workspace, volumes do Unity Catalog ou armazenamento de objetos na cloud. O método de instalação que escolher depende do tipo de biblioteca, do modo de acesso ao cluster e dos requisitos de segurança organizacional.

No entanto, as bibliotecas compute-scoped têm uma limitação importante: qualquer biblioteca que instale afeta todos os notebooks do cluster. Se diferentes equipas precisarem de versões conflitantes da mesma biblioteca, vais precisar de clusters separados ou instalações com âmbito de caderno para evitar conflitos.

Instalar bibliotecas a partir de repositórios de pacotes

Os repositórios de pacotes fornecem a forma mais comum de instalar bibliotecas. O PyPI aloja pacotes Python, o Maven hospeda bibliotecas Java e Scala, e o CRAN aloja pacotes R. Estes repositórios tratam automaticamente da resolução de dependências e da gestão de versões.

Para instalar uma biblioteca a partir do PyPI, selecione PyPI como fonte da biblioteca e introduza o nome do pacote. Para cargas de trabalho de produção, especifique uma versão exata para garantir a reprodutibilidade: pymssql==2.3.9. Sem um número de versão, o Azure Databricks instala a versão mais recente disponível, que pode mudar entre instalações e potencialmente quebrar o seu código.

As bibliotecas Maven requerem coordenadas no formato groupId:artifactId:version. Por exemplo, para instalar o Microsoft JDBC Driver para a biblioteca SQL Server, deveria usar com.microsoft.sqlserver:mssql-jdbc:13.2.1.jre11. Podes procurar pacotes diretamente no diálogo de instalação se não souberes as coordenadas exatas. O Maven também suporta a exclusão de dependências transitivas específicas que possam 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 retiram sempre a versão mais recente do espelho configurado. Para fixar versões específicas de pacotes R, precisa de guardar os ficheiros em ficheiros de espaço de trabalho ou volumes em vez de instalar a partir do CRAN.

Com clusters configurados em modo de acesso padrão, as coordenadas Maven e os caminhos dos ficheiros JAR requerem allowlist aprovação antes da instalação. Esta medida de segurança garante que os administradores revejam e aprovam bibliotecas que correm em recursos de computação partilhados.

Instalar bibliotecas a partir de ficheiros

Armazenar ficheiros de biblioteca em ficheiros de workspace ou volumes do Unity Catalog dá-te controlo preciso sobre quais as versões das bibliotecas que os teus clusters usam. Esta abordagem funciona bem quando precisa de bibliotecas não disponíveis em repositórios públicos, pacotes personalizados que construiu internamente ou versões específicas que já não estão disponíveis nos repositórios de pacotes.

A utilização de ficheiros de espaço de trabalho e volumes do Catálogo Unity para a instalação de bibliotecas mantém a gestão centralizada, em vez de contornar os controlos de segurança com instalações ad-hoc, como comandos pip3 diretos ou scripts personalizados não geridos executados a partir de notebooks. Os volumes do Catálogo Unity proporcionam uma governação melhorada através do modelo de controlo de acesso do Catálogo Unity, garantindo que todas as instalações da biblioteca são monitorizadas com registos de auditoria e protegidas por permissões detalhadas.

Os ficheiros de espaço de trabalho fornecem um local conveniente para armazenamento de bibliotecas com um limite de 500 MB de tamanho de ficheiro. Para instalar uma biblioteca a partir de ficheiros da área de trabalho, carregue o seu ficheiro wheel, JAR ou ficheiro requirements.txt através do diálogo de Importação da área de trabalho, e depois faça referência a este durante a instalação da biblioteca usando um caminho como por exemplo /Workspace/Users/you@example.com/libraries/mypackage-1.0.0-py3-none-any.whl.

Os volumes do Catálogo Unity oferecem segurança e governação reforçadas para o armazenamento de bibliotecas. Controla o acesso através das permissões do Catálogo Unity, garantindo que apenas utilizadores autorizados podem ler ou modificar ficheiros de biblioteca. Carrega ficheiros para um volume através do Explorador de Catálogo e instala-os usando um caminho como /Volumes/main/engineering/libraries/mypackage-1.0.0-py3-none-any.whl. A identidade usada para a instalação deve ter permissão de LER VOLUME no volume especificado.

Os ficheiros Pythonrequirements.txt funcionam tanto com ficheiros de workspace como com volumes no Databricks Runtime 15.0 e superiores. Estes ficheiros permitem-lhe definir múltiplas dependências de pacotes num único ficheiro, facilitando a manutenção de ambientes consistentes entre clusters. Carrega o ficheiro requirements.txt e instala-o como qualquer outra biblioteca — o Azure Databricks instala automaticamente todos os pacotes listados.

Para clusters com modo de acesso padrão, deverá adicionar os caminhos dos ficheiros da biblioteca ao allowlist antes da instalação. Isto aplica-se tanto a ficheiros de workspace como a volumes, garantindo que os administradores aprovam as bibliotecas usadas em computação partilhada.

Use scripts de init para configuração avançada

Os scripts de Init executam comandos shell durante o arranque do cluster, antes do início do driver Spark e dos executores. Embora o Databricks não recomende o uso de scripts de init para instalação de bibliotecas — as bibliotecas com âmbito de cluster oferecem uma abordagem melhor — os scripts de init revelam-se úteis para configurações a nível de sistema que as bibliotecas não conseguem gerir.

Podes usar scripts init para instalar pacotes de sistema com apt-get, configurar variáveis de ambiente ou configurar agentes de monitorização. Por exemplo, um script de init poderia instalar um driver de base de dados especializado que requer bibliotecas do sistema e depois configurar parâmetros de ligação através de variáveis de ambiente. O script é executado sempre que o cluster inicia, garantindo que a sua configuração persiste durante os reinícios.

Armazene scripts de init em volumes do Catálogo Unity para clusters que executem Databricks Runtime 13.3 LTS e superiores. Crie um ficheiro de script shell, carregue-o para um volume e depois configure o cluster para executar o script especificando o seu caminho como /Volumes/main/engineering/scripts/setup.sh. Para o modo de acesso padrão, adicione o caminho do script de iniciação ao allowlist antes de configurar o cluster.

Os scripts de init executam-se sequencialmente na ordem que especificar. Se algum script devolver um código de saída diferente de zero, o cluster falha ao iniciar. Esta proteção contra falhas impede que clusters corram com configurações incompletas ou incorretas. Pode diagnosticar scripts de inicialização com falha configurando a entrega de logs do cluster e examinando os logs dos scripts de inicialização.

Considere os scripts de inicialização como uma solução de último recurso para necessidades de configuração que bibliotecas e políticas de cluster com escopo do cluster não conseguem responder. Usar políticas de cluster para definir variáveis de ambiente e configurações do Spark proporciona frequentemente uma solução mais simples e fácil de manter do que scripts de init.

Configurar bibliotecas para o modo de acesso padrão

Clusters configurados com modo de acesso padrão proporcionam a maior segurança e isolamento no Azure Databricks. Este modo requer aprovação explícita para bibliotecas e scripts de entrada para evitar a execução não autorizada de código em recursos de computação partilhados.

Antes de instalar bibliotecas Maven ou ficheiros JAR em clusters de modo de acesso normal, um administrador do metastore deve adicioná-los ao allowlist. As coordenadas Maven são colocadas em allowlist utilizando o formato groupId:artifactId:version. Podes allowlist todas as versões de uma biblioteca com groupId:artifactId, ou todos os artefactos num grupo com apenas groupId. Para ficheiros JAR armazenados em volumes ou em armazenamento de objetos, allowlist o caminho do ficheiro ou o caminho do diretório.

Os scripts de init requerem entradas separadas allowlist mesmo que estejam armazenadas no mesmo local que ficheiros JAR. Ao permitir listar um caminho, o Azure Databricks utiliza correspondência de prefixos — adicionando /Volumes/prod-libraries/ ao allowlist permite todos os ficheiros e subdiretórios nessa localização. Inclua uma barra final para evitar correspondências não intencionais de prefixos ao nível do diretório.

Apenas allowlist concede permissão para usar um caminho para a instalação de bibliotecas ou scripts de inicialização. Ainda precisa de permissões de acesso aos dados adequadas. Para os volumes, a identidade do instalador deve ter a permissão READ VOLUME. No modo de acesso padrão, a identidade do proprietário do cluster valida estas permissões durante a instalação da biblioteca.

Para configurar o allowlist, os administradores do metastore usam o Explorador de Catálogo, selecionando as definições do metastore e navegando até à Secção de JARs/Scripts de Inicialização Permitidos. Este controlo centralizado garante que as equipas de segurança possam rever e aprovar todas as bibliotecas utilizadas nos recursos computacionais da organização, mantendo a governação sem bloquear a produtividade.

Escolha o método de instalação certo

Diferentes métodos de instalação de bibliotecas adaptam-se a diferentes cenários. O diagrama seguinte ilustra um fluxo de decisão para o ajudar a escolher a abordagem de instalação adequada: