Criar um arquivo de roda do Python usando Pacotes de ativos do Databricks

Esta página descreve como criar, implantar e executar um arquivo de roda do Python usando pacotes de ativos do Databricks. Veja que são pacotes de ativos do Databricks?.

Para obter uma configuração de exemplo que compila um JAR e o carrega no Catálogo do Unity, consulte Pacote que carrega um arquivo JAR para o Catálogo do Unity.

Requisitos

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 workspace.
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 arquivos de espaço de trabalho habilitados. Consulte O que são Arquivos de workspace?.
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 dos Pacotes de Ativos do Databricks para Python. Este pacote consiste em arquivos para construir um arquivo wheel do Python e na definição de um processo do Azure Databricks para criar este arquivo wheel do Python. Em seguida, você validará, implantará e compilará os arquivos implantados em um arquivo wheel do Python com base no trabalho wheel do Python no seu workspace 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 você deseja executar.

Use seu terminal ou prompt de comando para alternar para um diretório no seu computador de desenvolvimento local que conterá o pacote gerado do modelo.
Use a versão da CLI do Databricks para realizar a execução do comando bundle init:
```
databricks bundle init
```
Para Template to use, deixe o valor padrão 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 esse pacote. Esse diretório raiz é criado no diretório de trabalho atual.
Para Include a job that runs a notebook, selecionar no e pressionar Enter. Isso instrui a CLI do Databricks a não adicionar um notebook de exemplo ao seu pacote.
Para Include an ETL pipeline, selecionar no e pressionar 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 yes pressionando Enter. Isso instrui a CLI do Databricks a adicionar arquivos de pacote do wheel do Python de exemplo e instruções de compilação relacionadas ao seu pacote.
Para Use serverless, selecionar yes e pressionar Enter. Isso instrui a CLI do Databricks a configurar seu pacote para ser executado na computação sem servidor.
Para Default catalog for any tables created by this project [hive_metastore], insira o nome de um catálogo existente do Unity Catalog.
Para Use a personal schema for each user working on this project., selecione yes.

Etapa 2: Explorar o pacote

Para exibir os arquivos gerados pelo modelo, alterne para o diretório raiz do pacote recém-criado e abra esse diretório com seu IDE preferido. Os arquivos de interesse específico incluem o seguinte:

databricks.yml: esse arquivo especifica o nome do pacote, inclui referências aos arquivos do pacote, especifica whl as configurações de build, define variáveis de catálogo e esquema e especifica as configurações para workspaces de destino.
resources/sample_job.job.yml: esse arquivo especifica as configurações do trabalho wheel do Python. Para obter informações sobre configurações de trabalho, consulte o trabalho.
src/: essa pasta inclui os arquivos que o trabalho de roda do Python usa para criar o arquivo de roda do 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.

Observação

Se você quiser instalar o arquivo de roda do Python em um cluster com o Databricks Runtime 12.2 LTS ou inferior, deverá adicionar o seguinte mapeamento de nível superior ao databricks.yml arquivo:

# 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, então a validação foi bem-sucedida. Se algum erro for retornado, corrija-os e repita essa etapa.

Etapa 4: Implantar o pacote no workspace remoto

Em seguida, implante o pacote no workspace remoto do Azure Databricks. Isso cria o arquivo de roda do Python. Verifique se um trabalho do Azure Databricks foi criado em seu workspace.

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 do Python criado localmente foi implantado:
1. Na barra lateral do workspace do Azure Databricks, clique em Workspace.
2. Clique na seguinte pasta: Workspace > Usuários ><your-username>> .pacote ><project-name>> dev > artefatos > .internal ><whl-file-name>.whl.
O arquivo wheel do Python deve estar nesta pasta.
Verifique se o trabalho foi criado:
1. Na barra lateral do workspace do Azure Databricks, clique em Jobs & Pipelines.
2. Opcionalmente, selecione os filtros Trabalhos e Propriedade minha .
3. Clique em [dev <your-username>] sample_job.
4. Clique na guia Tarefas . Deve haver um 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 reimplantar o projeto.

Etapa 5: Executar o projeto implantado

Agora, inicie uma execução da tarefa do Azure Databricks em seu workspace.

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 em seu terminal e cole esse valor em seu navegador da Web para abrir seu workspace do Azure Databricks.
No workspace do Azure Databricks, depois que a tarefa for concluída com êxito e mostrar uma barra de título verde, clique na tarefa para ver os resultados.

Criar o whl usando Poetry ou setuptools

Quando você usa databricks bundle init com o modelo de python padrão, um pacote é criado que mostra como configurar um pacote que cria uma roda python usando uv e pyproject.toml. No entanto, talvez você queira usar Poetry ou setuptools para criar uma roda.

Instalar o Poetry ou setuptools

Instalar o Poetry ou setuptools:

Poesia
- Instale o Poetry, versão 1.6 ou superior, se ainda não estiver instalado. Para verificar sua versão instalada do Poetry, execute o comando poetry -V ou poetry --version.
- Verifique se você tem 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 o wheel pacote e setuptools se eles 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 este arquivo:

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

Adicionar arquivos de build

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

Poesia

├── 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 arquivo pyproject.toml 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 email principal da sua organização.
Substitua <my-package-description> por uma descrição de exibição para o arquivo wheel do 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 https://<my-url> pela 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 email principal da sua organização.
Substitua <my-package-description> por uma descrição de exibição para o arquivo wheel do Python.

Adicionar configuração do pacote de artefatos

Adicione a artifacts configuração de mapeamento ao seu databricks.yml para criar o artefato whl:

Poesia

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.

Observação

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

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>

Comentários

Esta página foi útil?

Last updated on 2025-11-15

Compartilhar via

Criar um arquivo de roda do Python usando Pacotes de ativos do Databricks

Requisitos

Criar o pacote usando um modelo

Etapa 1: Criar o pacote

Etapa 2: Explorar o pacote

Etapa 3: Validar a configuração do pacote

Etapa 4: Implantar o pacote no workspace remoto

Etapa 5: Executar o projeto implantado

Criar o whl usando Poetry ou setuptools

Instalar o Poetry ou setuptools

Poesia

Setuptools

Poesia

Setuptools

Adicionar arquivos de build

Poesia

Setuptools

Pyproject.toml

Setup.py

Adicionar configuração do pacote de artefatos

Poesia

Setuptools

Comentários

Recursos adicionais