Crie um arquivo de roda Python usando Databricks Asset Bundles

Esta página descreve como criar, implantar e executar um arquivo de roda Python usando o Databricks Asset Bundles. Consulte O que são Databricks Asset Bundles?.

Para obter um exemplo de configuração que cria um JAR e o carrega no Unity Catalog, consulte Pacote que carrega um arquivo JAR no Unity Catalog.

Requirements

A CLI do Databricks versão 0.218.0 ou superior está instalada e a autenticação está configurada. Para verificar a versão instalada da CLI do Databricks, execute o comando databricks -v. Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks. Para configurar a autenticação, consulte Configurar o acesso ao seu espaço de trabalho.
uv é necessário para executar testes e instalar dependências para este projeto a partir de um IDE.
O espaço de trabalho remoto deve ter os arquivos de espaço de trabalho ativados. Consulte O que são arquivos de espaço de trabalho?.
Um catálogo existente. Para criar um catálogo, consulte Criar catálogos.

Criar o pacote usando um modelo

Crie o pacote usando o modelo de pacote padrão Databricks Asset Bundles para Python. Este pacote consiste em arquivos para criar em um arquivo de roda Python e a definição de um trabalho do Azure Databricks para criar esse arquivo de roda Python. Em seguida, você valida, implanta e cria os arquivos implantados em um arquivo de roda Python a partir do trabalho de roda Python em seu espaço de trabalho do Azure Databricks.

Se você quiser criar um pacote do zero, consulte Criar um pacote manualmente.

Etapa 1: Criar o pacote

Um pacote contém os ativos que você deseja implantar e as configurações para os fluxos de trabalho que deseja executar.

Utilize o terminal para aceder a um diretório na máquina de desenvolvimento local que irá conter o pacote gerado pelo modelo.
Use a versão da CLI do Databricks para executar o bundle init comando:
```
databricks bundle init
```
Para Template to use, deixe o valor padrão de default-python pressionando Enter.
Para Unique name for this project, deixe o valor padrão de my_project, ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz para este pacote. Este diretório raiz é criado dentro do seu diretório de trabalho atual.
Para Include a job that runs a notebook, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não adicionar um notebook de exemplo à sua coleção.
Para Include an ETL pipeline, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não definir um pipeline de exemplo em seu pacote.
Para Include a stub (sample) Python package, deixe o valor padrão de yes pressionando Enter. Isso instrui a CLI do Databricks a adicionar os arquivos de exemplo dos pacotes Python wheel e as instruções de compilação relacionadas ao seu pacote.
Para Use serverless, selecione yes e pressione Enter. Isso instrui a CLI do Databricks a configurar seu pacote para ser executado em computação sem servidor.
Para Default catalog for any tables created by this project [hive_metastore], insira o nome de um catálogo Unity Catalog existente.
Para Use a personal schema for each user working on this project., selecione yes.

Passo 2: Explore o pacote

Para visualizar os arquivos que o modelo gerou, alterne para o diretório raiz do seu pacote recém-criado e abra esse diretório com seu IDE preferido. Os ficheiros de particular interesse incluem o seguinte:

databricks.yml: Este arquivo especifica o nome do pacote, inclui referências aos arquivos do pacote, especifica whl configurações de compilação, define variáveis de catálogo e esquema e especifica configurações para espaços de trabalho de destino.
resources/sample_job.job.yml: Este arquivo especifica as configurações do trabalho de roda do Python. Para obter informações sobre configurações de trabalho, consulte trabalho.
src/: Esta pasta inclui os ficheiros que a tarefa de roda Python utiliza para criar o ficheiro de roda Python.
tests/: Esta pasta contém exemplos de testes de unidade.
README.md: Este arquivo contém informações adicionais sobre como começar e usar este modelo de pacote.

Note

Se desejar instalar o arquivo wheel do Python num cluster com o Databricks Runtime 12.2 LTS ou inferior, deve-se adicionar o seguinte mapeamento de nível superior ao ficheiro databricks.yml:

# Applies to all tasks of type python_wheel_task.
experimental:
  python_wheel_wrapper: true

Etapa 3: Validar a configuração do pacote

Agora verifique se a configuração do pacote é válida.

No diretório raiz, use a CLI do Databricks para executar o bundle validate comando:
```
databricks bundle validate
```
Se um resumo da configuração do pacote for retornado, a validação será bem-sucedida. Se algum erro for retornado, corrija-os e repita esta etapa.

Etapa 4: Implantar o pacote no espaço de trabalho remoto

Em seguida, implante o pacote em seu espaço de trabalho remoto do Azure Databricks. Isso gera o ficheiro wheel do Python. Verifique se um trabalho do Azure Databricks foi criado em seu espaço de trabalho.

Na raiz do pacote, use a CLI do Databricks para executar o comando bundle deploy:
```
databricks bundle deploy --target dev
```
Confirme se o arquivo de roda Python criado localmente foi implantado:
1. Na barra lateral do seu espaço de trabalho do Azure Databricks, clique em Espaço de trabalho.
2. Clique na seguinte pasta: Workspace > Users ><your-username>> .bundle ><project-name>> dev > artifacts > .internal ><whl-file-name>.whl.
O arquivo de roda Python deve estar nesta pasta.
Verifique se o trabalho foi criado:
1. Na barra lateral do espaço de trabalho do Azure Databricks, clique em Trabalhos & Pipelines.
2. Opcionalmente, selecione os filtros Trabalhos e Propriedade de mim .
3. Clique em [dev <your-username>] sample_job.
4. Clique na guia Tarefas . Deve haver uma python_wheel_task.

Se você fizer alterações no pacote após esta etapa, repita as etapas 3 a 4 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplante o projeto.

Etapa 5: Executar o projeto implantado

Agora acione uma execução do trabalho do Azure Databricks em seu espaço de trabalho.

No diretório raiz, use a CLI do Databricks para executar o bundle run comando:
```
databricks bundle run --target dev sample_job
```
Copie o valor de Run URL que aparece no seu terminal e cole esse valor no seu navegador da web para abrir o seu espaço de trabalho do Azure Databricks.
No seu espaço de trabalho do Azure Databricks, depois que a tarefa for concluída com êxito e mostrar uma barra de título verde, clique na tarefa de trabalho para ver os resultados.

Construa o whl usando Poetry ou setuptools

Quando você usa databricks bundle init com o modelo default-python, um bundle é criado que mostra como configurar um bundle que cria uma roda Python usando uv e pyproject.toml. No entanto, você pode querer usar Poesia ou setuptools em vez disso para construir uma roda.

Instalar o Poetry ou Setuptools

Instale o 'Poetry' ou setuptools:

Poetry
- Instale o Poetry, versão 1.6 ou superior, se ainda não estiver instalado. Para verificar a versão instalada do Poetry, execute o comando poetry -V ou poetry --version.
- Certifique-se de ter o Python versão 3.10 ou superior instalado. Para verificar sua versão do Python, execute o comando python -V ou python --version.
Setuptools

Instale os wheel pacotes e setuptools se ainda não estiverem instalados, executando o seguinte comando:
```
pip3 install --upgrade wheel setuptools
```
Se você pretende armazenar esse pacote com um provedor Git, adicione um .gitignore arquivo na raiz do projeto e adicione as seguintes entradas a esse arquivo:

Poetry
```
.databricks
dist
```
Setuptools
```
.databricks
build
dist
src/my_package/my_package.egg-info
```

Adicionar arquivos de compilação

Na raiz do seu pacote, crie as seguintes pastas e arquivos, dependendo se você usa o Poetry ou setuptools para construir arquivos de roda Python:

Poetry

├── src
│     └── my_package
│           ├── __init__.py
│           ├── main.py
│           └── my_module.py
└── pyproject.toml

Setuptools

├── src
│     └── my_package
│           ├── __init__.py
│           ├── main.py
│           └── my_module.py
└── setup.py

Adicione o seguinte código ao pyproject.toml arquivo ou setup.py :

Pyproject.toml

[tool.poetry]
name = "my_package"
version = "0.0.1"
description = "<my-package-description>"
authors = ["my-author-name <my-author-name>@<my-organization>"]

[tool.poetry.dependencies]
python = "^3.10"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry.scripts]
main = "my_package.main:main"

Substitua my-author-name pelo nome de contato principal da sua organização.
Substitua my-author-name>@<my-organization pelo endereço de contato de e-mail principal da sua organização.
Substitua <my-package-description> por uma descrição de exibição para seu arquivo de roda Python.

Setup.py

from setuptools import setup, find_packages

import src

setup(
  name = "my_package",
  version = "0.0.1",
  author = "<my-author-name>",
  url = "https://<my-url>",
  author_email = "<my-author-name>@<my-organization>",
  description = "<my-package-description>",
  packages=find_packages(where='./src'),
  package_dir={'': 'src'},
  entry_points={
    "packages": [
      "main=my_package.main:main"
    ]
  },
  install_requires=[
    "setuptools"
  ]
)

Substitua pelo https://<my-url> URL da sua organização.
Substitua <my-author-name> pelo nome de contato principal da sua organização.
Substitua <my-author-name>@<my-organization> pelo endereço de contato de e-mail principal da sua organização.
Substitua <my-package-description> por uma descrição de exibição para seu arquivo de roda Python.

Adicionar configuração de pacote de artefatos

Adicione a configuração do mapeamento artifacts ao seu databricks.yml para construir o artefacto whl.

Poetry

Essa configuração executa o poetry build comando e indica que o caminho para o pyproject.toml arquivo está no mesmo diretório que o databricks.yml arquivo.

Note

Se você já construiu um arquivo de roda Python e deseja apenas implantá-lo, modifique o seguinte arquivo de configuração do pacote omitindo o artifacts mapeamento. A CLI do Databricks assumirá que o pacote wheel do Python já está compilado e implantará automaticamente os arquivos especificados nas entradas de libraries da matriz whl.

bundle:
  name: my-wheel-bundle

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

resources:
  jobs:
    wheel-job:
      name: wheel-job
      tasks:
        - task_key: wheel-task
          new_cluster:
            spark_version: 13.3.x-scala2.12
            node_type_id: Standard_DS3_v2
            data_security_mode: USER_ISOLATION
            num_workers: 1
          python_wheel_task:
            entry_point: main
            package_name: my_package
          libraries:
            - whl: ./dist/*.whl

targets:
  dev:
    workspace:
    host: <workspace-url>

Setuptools

Essa configuração executa o setuptools comando e indica que o caminho para o setup.py arquivo está no mesmo diretório que o databricks.yml arquivo.

bundle:
  name: my-wheel-bundle

artifacts:
  default:
    type: whl
    build: python3 setup.py bdist wheel
    path: .

resources:
  jobs:
    wheel-job:
      name: wheel-job
      tasks:
        - task_key: wheel-task
          new_cluster:
            spark_version: 13.3.x-scala2.12
            node_type_id: Standard_DS3_v2
            data_security_mode: USER_ISOLATION
            num_workers: 1
          python_wheel_task:
            entry_point: main
            package_name: my_package
          libraries:
            - whl: ./dist/*.whl

targets:
  dev:
    workspace:
    host: <workspace-url>

Feedback

Esta página foi útil?

Last updated on 2025-11-15

Partilhar via

Crie um arquivo de roda Python usando Databricks Asset Bundles

Requirements

Criar o pacote usando um modelo

Etapa 1: Criar o pacote

Passo 2: Explore o pacote

Etapa 3: Validar a configuração do pacote

Etapa 4: Implantar o pacote no espaço de trabalho remoto

Etapa 5: Executar o projeto implantado

Construa o whl usando Poetry ou setuptools

Instalar o Poetry ou Setuptools

Poetry

Setuptools

Poetry

Setuptools

Adicionar arquivos de compilação

Poetry

Setuptools

Pyproject.toml

Setup.py

Adicionar configuração de pacote de artefatos

Poetry

Setuptools

Feedback

Recursos adicionais