Cree un archivo wheel de Python usando conjuntos de recursos de Databricks

En esta página se describe cómo compilar, implementar y ejecutar un archivo de rueda de Python mediante Conjuntos de recursos de Databricks. Consulte ¿Qué son las conjuntos de recursos de Databricks?.

Para un ejemplo de configuración que construye un JAR y lo carga en Unity Catalog, consulte Paquete que carga un JAR en Unity Catalog.

Requirements

La VERSIÓN 0.218.0 o posterior de la CLI de Databricks está instalada y se configura la autenticación. Para comprobar la versión de la CLI de Databricks instalada, ejecute el comando databricks -v. Para instalar la CLI de Databricks, consulte Instalación o actualización de la CLI de Databricks. Para configurar la autenticación, consulte Configuración del acceso al área de trabajo.
se requiere uv para ejecutar pruebas e instalar dependencias para este proyecto desde un IDE.
El área de trabajo remota debe tener habilitados los archivos del área de trabajo. Consulte ¿Qué son los archivos del área de trabajo?
Un catálogo existente. Para crear un catálogo, consulte Creación de catálogos.

Creación de la agrupación mediante una plantilla

Cree la agrupación mediante la plantilla de agrupación predeterminada de conjuntos de recursos de Databricks para Python. Esta agrupación consta de archivos para compilar en un archivo de rueda de Python y la definición de un trabajo de Azure Databricks para compilar este archivo de rueda de Python. A continuación, valide, implemente y compile los archivos implementados en un archivo wheel de Python desde el trabajo wheel de Python dentro de su área de trabajo de Azure Databricks.

Si desea crear una agrupación desde cero, consulte Creación de una agrupación manualmente.

Paso 1: Crear la agrupación

Una agrupación contiene los recursos que desea implementar y la configuración de los flujos de trabajo que desea ejecutar.

Use el terminal o el símbolo del sistema para cambiar a un directorio de la máquina de desarrollo local que contendrá la agrupación generada por la plantilla.
Utilice la versión CLI de Databricks para ejecutar el comando bundle init:
```
databricks bundle init
```
En Template to use, deje el valor predeterminado de default-python presionando Enter.
En Unique name for this project, deje el valor predeterminado de my_project o escriba un valor diferente y, a continuación, presione Enter. Con ello se determina el nombre del directorio raíz de esta agrupación. Este directorio raíz se crea en el directorio de trabajo actual.
En Include a job that runs a notebook, seleccione no y presione Enter. Esto indica al CLI de Databricks que no agregue un bloc de notas de ejemplo a su agrupación.
En Include an ETL pipeline, seleccione no y presione Enter. Esto indica a la CLI de Databricks que no defina una canalización de ejemplo en el paquete.
En Include a stub (sample) Python package, deje el valor predeterminado de yes presionando Enter. Esto indica a la CLI de Databricks que agregue archivos de paquete de rueda de Python de muestra e instrucciones de compilación relacionadas a su agrupación.
En Use serverless, seleccione yes y presione Enter. Esto instruye a la CLI de Databricks que configure el paquete para que se ejecute en cómputo sin servidor.
En Default catalog for any tables created by this project [hive_metastore], escriba el nombre de un catálogo existente de Unity Catalog.
En Use a personal schema for each user working on this project., seleccione yes.

Paso 2: Explorar el paquete

Para ver los archivos que generó la plantilla, cambie al directorio raíz de la agrupación recién creada y abra este directorio con su IDE preferido. Entre los tipos de especial interés se incluyen los siguientes:

databricks.yml: este archivo especifica el nombre del lote, incluye referencias a los archivos del lote, especifica whl la configuración de compilación, define las variables de catálogo y esquema y especifica la configuración de las áreas de trabajo de destino.
resources/sample_job.job.yml: Este archivo especifica la configuración del trabajo de la rueda Python. Para obtener información sobre la configuración del trabajo, consulte trabajo.
src/: Esta carpeta incluye los archivos que el trabajo de wheel de Python utiliza para construir el archivo wheel de Python.
tests/: esta carpeta contiene pruebas unitarias de ejemplo.
README.md: Este archivo contiene información adicional sobre cómo comenzar y usar esta plantilla de paquete.

Note

Si desea instalar el archivo de rueda de Python en un clúster con Databricks Runtime 12.2 LTS o inferior, debe añadir la siguiente asignación de nivel superior al archivo databricks.yml:

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

Paso 3: Validación de la configuración de agrupación

Ahora compruebe si la configuración del lote es válida.

En el directorio raíz, use la CLI de Databricks para ejecutar el bundle validate comando :
```
databricks bundle validate
```
Si se devuelve un resumen de la configuración de la agrupación, indica que la validación se ha realizado correctamente. Si se devuelven errores, corrija los errores y repita este paso.

Paso 4: Implementar la agrupación en el área de trabajo remota

A continuación, implemente la agrupación en el área de trabajo remota de Azure Databricks. Esto genera el archivo wheel de Python. Compruebe que se crea un trabajo de Azure Databricks en el área de trabajo.

Desde la raíz del paquete, use la CLI de Databricks para ejecutar el comando bundle deploy
```
databricks bundle deploy --target dev
```
Confirme que se implementó el archivo de rueda de Python compilado localmente:
1. En la barra lateral del área de trabajo de Azure Databricks, haga clic en Área de trabajo.
2. Haga clic en la siguiente carpeta: Área de trabajo > Usuarios ><your-username>> .bundle ><project-name>> dev > artefactos > .internal ><whl-file-name>.whl.
El archivo wheel de Python debe estar en esta carpeta.
Compruebe si se creó el trabajo:
1. En la barra lateral del área de trabajo de Azure Databricks, haga clic en Trabajos y canalizaciones.
2. Opcionalmente, seleccione los filtros Trabajos y Propiedad de mí .
3. Haga clic en [dev <your-username>] sample_job.
4. Haga clic en la pestaña Tareas . Debe haber una python_wheel_task.

Si realiza algún cambio en la agrupación después de este paso, repita los pasos del 3 al 4 para comprobar si la configuración del lote sigue siendo válida y, a continuación, vuelva a implementar el proyecto.

Paso 5: Ejecución del proyecto implementado

Ahora, desencadene una ejecución del trabajo de Azure Databricks en el área de trabajo.

En el directorio raíz, use la CLI de Databricks para ejecutar el bundle run comando :
```
databricks bundle run --target dev sample_job
```
Copie el valor de Run URL que aparece en el terminal y pegue este valor en el explorador web para abrir el área de trabajo de Azure Databricks.
En el área de trabajo de Azure Databricks, después de que la tarea se complete correctamente y muestre una barra de título verde, haga clic en la tarea de trabajo para ver los resultados.

Generar el archivo whl usando Poetry o setuptools

Cuando se usa databricks bundle init con la plantilla de Python predeterminada, se crea un lote que muestra cómo configurar un lote que compila una rueda de Python mediante uv y pyproject.toml. Sin embargo, es posible que desee utilizar Poetry o setuptools en su lugar para construir una rueda.

Instalar Poetry o setuptools

Instalar Poetry o setuptools:

Poetry
- Instale Poetry, versión 1.6 o posterior, si aún no está instalado. Para comprobar la versión que tiene instalada de Poetry, ejecute el comando poetry -V o poetry --version.
- Asegúrese de que está instalada la versión 3.10. o posterior de Python. Para comprobar la versión de Python, ejecute el comando python -V o python --version.
Setuptools

Instale los wheel paquetes y setuptools si aún no están instalados; para ello, ejecute el siguiente comando:
```
pip3 install --upgrade wheel setuptools
```
Si piensa almacenar esta agrupación con un proveedor de Git, agregue un .gitignore archivo en la raíz del proyecto y agregue las siguientes entradas a este archivo:

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

Agregar archivos de compilación

En la raíz del conjunto, cree las siguientes carpetas y archivos, en función de si usa Poetry o setuptools para crear archivos wheel de 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

Agregue el código siguiente al pyproject.toml archivo o 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"

Reemplace por my-author-name el nombre de contacto principal de la organización.
Reemplace por my-author-name>@<my-organization la dirección de contacto de correo electrónico principal de su organización.
Reemplace <my-package-description> por una descripción para mostrar del archivo wheel de 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"
  ]
)

Remplace https://<my-url> por la dirección URL de la organización.
Reemplace por <my-author-name> el nombre de contacto principal de la organización.
Reemplace por <my-author-name>@<my-organization> la dirección de contacto de correo electrónico principal de su organización.
Reemplace <my-package-description> por una descripción para mostrar del archivo wheel de Python.

Agregar configuración de agrupación de artefactos

Agregue la configuración de mapeo artifacts a su databricks.yml para compilar el artefacto whl:

Poetry

Esta configuración ejecuta el poetry build comando e indica que la ruta de acceso al pyproject.toml archivo está en el mismo directorio que el databricks.yml archivo.

Note

Si ya ha creado un archivo wheel de Python y solo quiere implementarlo, modifique el siguiente archivo de configuración de la agrupación para omitir la asignación de artifacts. A continuación, la CLI de Databricks asumirá que el archivo wheel de Python ya está compilado e implementará automáticamente los archivos especificados en las entradas de la matriz librarieswhl.

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

Esta configuración ejecuta el setuptools comando e indica que la ruta de acceso al setup.py archivo está en el mismo directorio que el databricks.yml archivo.

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>

Retroalimentació

Ha estat útil aquesta pàgina?

Last updated on 2025-11-15

Comparteix via

Cree un archivo wheel de Python usando conjuntos de recursos de Databricks

Requirements

Creación de la agrupación mediante una plantilla

Paso 1: Crear la agrupación

Paso 2: Explorar el paquete

Paso 3: Validación de la configuración de agrupación

Paso 4: Implementar la agrupación en el área de trabajo remota

Paso 5: Ejecución del proyecto implementado

Generar el archivo whl usando Poetry o setuptools

Instalar Poetry o setuptools

Poetry

Setuptools

Poetry

Setuptools

Agregar archivos de compilación

Poetry

Setuptools

Pyproject.toml

Setup.py

Agregar configuración de agrupación de artefactos

Poetry

Setuptools

Retroalimentació

Recursos addicionals