Pular para o conteúdo principal
Última atualização em

Gerenciar dependências para um aplicativo Databricks

Um aplicativo Databricks pode incluir dependências do Python, dependências do Node.js ou ambos. As dependências são declaradas em arquivos específicos da linguagem que a Databricks instala quando o aplicativo é implantado:

Defina as dependências do Python com pip​

Os aplicativos que usam pip vêm com um conjunto de bibliotecas Python pré-instaladas. Para definir bibliotecas Python adicionais, use um arquivo requirements.txt . Se algum pacote listado corresponder a pacotes pré-instalados, as versões no seu arquivo substituirão as versões padrão.

Aplicativos com dimensionamento horizontal (Beta) convertidos de aplicativos padrão podem dispensar as bibliotecas pré-instaladas e executar em uma imagem base de SO limpa, em vez disso. Consulte Recusar bibliotecas Python pré-instaladas para aplicativos Databricks.

Por exemplo:

# Override default version of dash
dash==2.10.0

# Add additional libraries not pre-installed
requests==2.31.0
numpy==1.24.3

# Specify a compatible version range
scikit-learn>=1.2.0,<1.3.0

Pré-instalado Python biblioteca​

pipaplicativos baseados em incluem as seguintes bibliotecas Python pré-instaladas. Não é necessário adicioná-los ao seu requirements.txt, a menos que uma versão diferente seja exigida.

Biblioteca

Versão

conector sql databricks-sql

3.4.0

databricks-sdk

0,33,0

malflow-skinny

2.16.2

rádio

4,44,0

simplificado

1.38,0

brilhante

1.1.0

traço

2.18.1

frasco

3.0.3

API rápida

0.115,0

uvicorn [padrão]

0,30,6

unicórnio

23,0,0

hub de rostos abraçados

0.35.3

dash-ag-grid

31,2,0

componentes do dash-mantine

0,14.4

componentes do dash-bootstrap

1.6.0

Plotly

5.24.1

reamostrador de plotagem

0.10.0

Biblioteca

Versão

conector sql databricks-sql

3.4.0

databricks-sdk

0,33,0

malflow-skinny

2.16.2

rádio

4,44,0

simplificado

1.38,0

brilhante

1.1.0

traço

2.18.1

frasco

3.0.3

API rápida

0.115,0

uvicorn [padrão]

0,30,6

unicórnio

23,0,0

hub de rostos abraçados

0.35.3

dash-ag-grid

31,2,0

componentes do dash-mantine

0,14.4

componentes do dash-bootstrap

1.6.0

Plotly

5.24.1

reamostrador de plotagem

0.10.0

Defina as dependências do Python com uv​

Se seu aplicativo usa uv para gerenciamento de dependência, defina as dependências do Python em um arquivo pyproject.toml em vez de requirements.txt. Aplicativos baseados em uvnão incluem bibliotecas pré-instaladas, portanto você deve declarar todas as dependências em seu pyproject.toml. Você também pode especificar qualquer versão do Python usando o campo requires-python, diferentemente dos aplicativos baseados em pip, que usam o Python 3.11.

O mesmo se aplica a aplicativos com escalabilidade horizontal que optaram por não usar bibliotecas pré-instaladas. Consulte Desativar bibliotecas Python pré-instaladas para aplicativos Databricks.

Durante a implantação, o Databricks Apps seleciona uma estratégia de instalação com base nos arquivos presentes:

  • Se requirements.txt existir, o aplicativo usa pip para instalar dependências, independentemente de pyproject.toml também estar presente. requirements.txt sempre tem precedência.
  • Se requirements.txt não existir e ambos pyproject.toml e uv.lock existirem, o aplicativo usa uv para instalar dependências do arquivo de bloqueio.

O instalador uv cria e gerencia seu próprio ambiente virtual, então você não precisa criar um diretório .venv .

O exemplo a seguir mostra um valor mínimo de pyproject.toml para um aplicativo Databricks:

Toml
[project]
name = "my-app"
requires-python = ">=3.11"
dependencies = [
    "dash==2.10.0",
    "requests==2.31.0",
]

Para usar uv, você deve incluir um arquivo uv.lock junto com seu pyproject.toml. Gere-o executando uv lock localmente e inclua-o no diretório do seu aplicativo.

Definir dependências do Node.js​

Para definir bibliotecas Node.js, inclua um arquivo package.json na raiz do seu aplicativo. A Databricks oferece suporte tanto a npm quanto a pnpm, e seleciona o gerenciador de pacotes com base no arquivo de bloqueio que você incluir:

  • Caso pnpm-lock.yaml esteja presente, o aplicativo utiliza pnpm. Consulte Usar pnpm.
  • Caso contrário, o aplicativo usa npm.
  • Se ambos pnpm-lock.yaml e package-lock.json estiverem presentes, pnpm tem precedência.

Por exemplo, um arquivo package.json para um aplicativo React usando o Vite pode ter a seguinte aparência:

JSON
{
  "name": "react-fastapi-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "npm run build:frontend",
    "build:frontend": "vite build frontend"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.2.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0"
  }
}
nota

Liste todos os pacotes necessários para a etapa de construção sob dependencies, não devDependencies. Se você definir NODE_ENV=production em suas variáveis de ambiente, o processo de implantação ignora a instalação de devDependencies.

Uso pnpm​

Para criar com pnpm, inclua um arquivo pnpm-lock.yaml junto com seu package.json. Gere-o executando pnpm install localmente e inclua-o no diretório da sua aplicação. Databricks fornece pnpm por meio de Corepack.

Os seguintes requisitos devem ser observados para aplicativos pnpm:

  • As dependências são instaladas com pnpm install --frozen-lockfile, portanto pnpm-lock.yaml devem permanecer sincronizadas com package.json. Se houver desvio, a compilação falha em vez de atualizar o arquivo de bloqueio. É necessário regenerar o arquivo de bloqueio com pnpm install após a alteração das dependências.
  • Você deve especificar o comando de começar em app.yaml. Ao contrário dos aplicativos npm, os aplicativos pnpm não recorrem a um script start default. Consulte Configurar a execução de aplicativos Databricks com app.yaml.

Para projetos de pnpm workspace (onde há um arquivo pnpm-workspace.yaml), alguns comandos app.yaml são executados pnpm recursivamente. Por exemplo, uma etapa de compilação ou de início pode executar pnpm -r run build. Estes comandos devem chamar corepack pnpm em vez de pnpm para que os comandos aninhados sejam resolvidos corretamente.

Evite conflitos de versão​

Siga estas diretrizes para evitar conflitos de versão:

  • Para aplicativos baseados em pip , a substituição do pacote pré-instalado pode causar problemas de compatibilidade se a versão especificada diferir significativamente da pré-instalada.
  • Sempre teste seu aplicativo para verificar se as alterações na versão do pacote não introduzem erros.
  • Fixar versões explícitas em requirements.txt ajuda a manter o comportamento consistente do aplicativo em todas as implantações.
  • Ao usar uv, inclua um arquivo uv.lock para instalações totalmente reproduzíveis em todas as implantações.

Instalação e gerenciamento de dependências​

O Databricks instala bibliotecas definidas em requirements.txt, pyproject.toml e package.json diretamente no contêiner em execução em seu compute dedicado. É responsável por gerenciar e aplicar patches nessas dependências.

Você pode especificar bibliotecas de várias fontes em seus arquivos de dependência:

  • downloads de bibliotecas de repositórios públicos como PyPI e npm
  • Repositórios privados que autenticam usando credenciais armazenadas em segredos Databricks
  • biblioteca armazenada em seu diretório /Volumes/ (por exemplo, /Volumes/<catalog>/<schema>/<volume>/<path>)

Instalar a partir de repositórios privados​

Para instalar pacote de um repositório privado, configure variável de ambiente para autenticação. Por exemplo, defina PIP_INDEX_URL para apontar para seu repositório privado:

YAML
env:
  - name: PIP_INDEX_URL
    valueFrom: my-pypi-secret

A configuração da rede do seu workspace deve permitir acesso ao repositório privado. Consulte Configurar rede para aplicativos Databricks.

Utilize os repository de pacotes default no nível do Workspace​

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do Workspace deve ativar Ativar Configuração de repo do Workspace para Databricks Apps na Página de Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Se um administrador de workspace configurar repositórios de pacotes default para o workspace, os aplicativos nesse workspace instalam pacotes Python e Node.js dos repositórios configurados no workspace em vez dos registros públicos PyPI e npm. Isso permite que os desenvolvedores de aplicativos herdem automaticamente as configurações corporativas de repository de pacotes sem duplicar a configuração em cada aplicativo, enquanto ainda permite substituições por aplicativo.

Para configurar essas definições no nível do Workspace, consulte Configure os repository de pacotes default.

pacotes Python​

Durante a fase de instalação do pacote da compilação, o Databricks Apps herda as configurações do workspace para as seguintes variáveis de ambiente:

  • PIP_INDEX_URL
  • PIP_EXTRA_INDEX_URL
  • PIP_CERT
  • UV_INDEX_URL
  • UV_EXTRA_INDEX_URL
  • SSL_CERT_FILE

A configuração específica do aplicativo tem precedência sobre os default do Workspace. Se você definir qualquer uma das variáveis de ambiente precedentes (exceto as configurações de certificado observadas abaixo) no arquivo app.yaml do seu aplicativo, os valores em app.yaml substituirão as configurações do workspace para esse aplicativo.

nota

As configurações de certificado de PIP_CERT e SSL_CERT_FILE sempre utilizam os valores configurados no Workspace e não podem ser substituídas em app.yaml.

atenção

Teste seus aplicativos depois que o administrador do workspace ativar a visualização e defina PIP_INDEX_URL em app.yaml, se for necessário continuar instalando de um índice diferente.

Pacotes Node.js​

Quando um administrador do workspace configura um registro npm default, o Databricks Apps escreve a configuração do registro do workspace no arquivo .npmrc do aplicativo durante a implantação. Isso permite que os aplicativos instalem pacotes Node.js, incluindo pacotes privados, a partir do registro configurado no workspace sem que cada aplicativo armazene sua própria URL de registro ou token de autenticação.

Para usar um registro diferente para um aplicativo específico, defina a variável de ambiente NPMRC no arquivo app.yaml do seu aplicativo para referenciar sua própria configuração npm. A configuração específica do aplicativo tem precedência sobre os default do Workspace.

Instalar arquivos wheel dos volumes do Unity Catalog​

Para instalar o pacote Python a partir de arquivos wheel armazenados em volumes Unity Catalog :

  1. Adicione o volume do Unity Catalog como um recurso ao seu aplicativo. Veja o volumeUnity Catalog.
  2. Referencie o caminho completo do arquivo wheel diretamente em seu requirements.txt:
/Volumes/<catalog>/<schema>/<volume>/my_package-1.0.0-py3-none-any.whl
nota

Referências de variáveis de ambiente não são compatíveis em requirements.txt. O caminho completo do arquivo wheel deve ser codificado.

Para aumentar a segurança ao acessar repositórios de pacotes externos, use controles de saída serverless para restringir o acesso a repositórios públicos e configurar redes privadas. Consulte Configurar rede para aplicativos Databricks.

Nesta página