Migrar de dbx a agrupaciones

2025-04-23

Importante

Databricks recomienda usar las agrupaciones de recursos de Databricks en lugar de dbx de Databricks Labs. Los artículos relacionados sobre dbx se han retirado y es posible que no se actualicen.

En este artículo se describe cómo migrar proyectos de dbxDatabricks Labs a conjuntos de recursos de Databricks. Consulte Introducción a dbx mediante Databricks Labs y ¿Qué son los conjuntos de recursos de Databricks?.

Antes de migrar, tenga en cuenta las siguientes limitaciones y comparaciones de características entre dbx de Databricks Labs y los conjuntos de recursos de Databricks.

Comparaciones de características

Antes de migrar, tenga en cuenta cómo se implementan las siguientes características de dbx de Databricks Labs en conjuntos de recursos de Databricks.

Plantillas y proyectos

dbx proporciona compatibilidad con plantillasde Jinja. Puede incluir plantillas de Jinja en la configuración de implementación y pasar variables de entorno en línea o a través de un archivo de variables. Aunque no se recomienda, dbx también proporciona compatibilidad experimental con funciones de usuario personalizadas.

Los paquetes proporcionan compatibilidad con las plantillas de Go para reutilizar la configuración. Los usuarios pueden crear agrupaciones basadas en plantillas precompiladas. Hay una paridad casi completa para plantillas, excepto para las funciones de usuario personalizadas.

Administración de compilaciones

dbx proporciona compatibilidad con la compilación a través pip wheel, Poesía y Flit. Los usuarios pueden especificar la opción de compilación en la build sección del archivo de deployment.yml un proyecto.

Los paquetes permiten a los usuarios construir, implementar y ejecutar archivos wheel de Python. Los usuarios pueden aprovechar la entrada integrada whl en el archivo databricks.yml de un paquete.

Sincronización, implementación y ejecución de código

dbx permite cargar el código de forma independiente a la generación de recursos del área de trabajo, como los trabajos de Lakeflow.

Las agrupaciones siempre cargan código y crean o actualizan los recursos del área de trabajo al mismo tiempo. Esto simplifica las implementaciones y evita las condiciones de bloqueo de los trabajos que ya están en curso.

Migración de un proyecto dbx a una agrupación

Después de tener en cuenta las limitaciones anteriores y las comparaciones de características entre dbx de Databricks Labs y los conjuntos de recursos de Databricks, está listo para migrar de dbx a los conjuntos.

Databricks recomienda que, para comenzar una migración de proyecto dbx, mantenga dbx el proyecto en su carpeta original y que disponga de una carpeta vacía e independiente en la que copie el contenido de su proyecto original dbx. Esta carpeta independiente será la nueva agrupación. Puede encontrar problemas inesperados si comienza a convertir el proyecto dbx en su carpeta original a una agrupación y, a continuación, comete algunos errores o quiere empezar de nuevo desde el principio,

Paso 1: Instalación y configuración de la CLI de Databricks

Los conjuntos de recursos de Databricks están disponibles con carácter general en la CLI de Databricks, versión 0.218.0 y posteriores. Si ya ha instalado y configurado la versión 0.218.0 o posterior de la CLI de Databricks, vaya al paso 2.

Nota:

Las agrupaciones no son compatibles con las versiones 0.18 y posteriores de la CLI de Databricks.

Instale o actualice a la CLI de Databricks versión 0.218.0 o posterior. Consulte Instalación o actualización de la CLI de Databricks.
Configure la CLI de Databricks para la autenticación con las áreas de trabajo de Azure Databricks de destino, por ejemplo, mediante la autenticación de Tokens de acceso personal de Azure Databricks. Para ver otros tipos de autenticación de Azure Databricks, consulte Autenticación para la CLIde Databricks.

Paso 2: Crear el archivo de configuración de agrupación

Si usa un IDE como Visual Studio Code, PyCharm Professional o IntelliJ IDEA Ultimate que proporciona compatibilidad con archivos YAML y archivos de esquema JSON, puede usar el IDE no solo para crear el archivo de configuración de agrupación, sino para comprobar la sintaxis y el formato del archivo y proporcionar sugerencias de finalización de código, como se indica a continuación.

Código de Visual Studio

Agregue compatibilidad con el servidor de lenguaje YAML a Visual Studio Code, por ejemplo, instalando la extensión YAML desde Visual Studio Code Marketplace.
Genere el archivo de esquema JSON de configuración del conjunto de recursos de Databricks mediante la CLI de Databricks para ejecutar el comando bundle schema y redirigir la salida a un archivo JSON. Por ejemplo, genere un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:
```
databricks bundle schema > bundle_config_schema.json
```
Use Visual Studio Code para crear o abrir un archivo de configuración de agrupación en el directorio actual. Por convención, este archivo se denomina databricks.yml.
Agregue el siguiente comentario al principio del archivo de configuración de agrupación:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Nota:

En el comentario anterior, si el archivo de esquema JSON de configuración del conjunto de recursos de Databricks está en una ruta de acceso diferente, reemplace bundle_config_schema.json por la ruta de acceso completa al archivo de esquema.
Use las características del servidor de lenguaje YAML que agregó anteriormente. Para obtener más información, consulte la documentación del servidor de lenguaje YAML.

PyCharm Professional

Genere el archivo de esquema JSON de configuración del conjunto de recursos de Databricks mediante la CLI de Databricks para ejecutar el comando bundle schema y redirigir la salida a un archivo JSON. Por ejemplo, genere un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:
```
databricks bundle schema > bundle_config_schema.json
```
Configure PyCharm para reconocer el archivo de esquema JSON de configuración de agrupación y, a continuación, complete la asignación de esquema JSON siguiendo las instrucciones de Configuración de un esquema JSON personalizado.
Use PyCharm para crear o abrir un archivo de configuración de agrupación. Por convención, este archivo se denomina databricks.yml. A medida que escribe, PyCharm comprueba si hay sintaxis y formato de esquema JSON y proporciona sugerencias de finalización de código.

IntelliJ IDEA Ultimate

Genere el archivo de esquema JSON de configuración del conjunto de recursos de Databricks mediante la CLI de Databricks para ejecutar el comando bundle schema y redirigir la salida a un archivo JSON. Por ejemplo, genere un archivo denominado bundle_config_schema.json dentro del directorio actual, como se indica a continuación:
```
databricks bundle schema > bundle_config_schema.json
```
Configure IntelliJ IDEA para reconocer el archivo de esquema JSON de configuración del conjunto y, después, complete la asignación de esquemas JSON siguiendo las instrucciones de Configuración de un esquema JSON personalizado.
Use IntelliJ IDEA para crear o abrir un archivo de configuración de agrupación. Por convención, este archivo se denomina databricks.yml. A medida que escribe, IntelliJ IDEA comprueba si hay sintaxis y formato de esquema JSON y proporciona sugerencias de finalización de código.

Paso 3: Convertir la configuración del proyecto dbx en databricks.yml

Convierta la configuración en dbx el archivo del .dbx/project.json proyecto en la configuración equivalente del archivo del databricks.yml lote. Para obtener más información, consulte Conversión de la configuración del proyecto dbx en databricks.yml.

Paso 4: convertir la configuración de implementación de dbx en databricks.yml

Convierte la configuración de la carpeta dbx de tu proyecto conf a la configuración equivalente en el archivo databricks.yml de tu paquete. Para más información, consulte Conversión de la configuración de implementación de dbx a databricks.yml.

Paso 5: Validar el paquete

Antes de implementar artefactos o ejecutar un trabajo de Azure Databricks, una canalización :o una canalización de MLOps, debe asegurarse de que el archivo de configuración de agrupación sea sintácticamente correcto. Para ello, ejecute el comando bundle validate desde la raíz del lote:

databricks bundle validate

Para obtener información sobre bundle validate, consulte Validar un paquete.

Paso 6: desplegar el paquete

Para implementar los artefactos locales especificados en el área de trabajo remota, ejecute el comando bundle deploy desde la raíz del lote. Si no se especifica ninguna opción de comando, se usa el destino predeterminado declarado en el archivo de configuración de agrupación:

databricks bundle deploy

Para implementar los artefactos en el contexto de un destino específico, especifique la -t opción (o --target) junto con el nombre del destino tal como se declara en el archivo de configuración de agrupación. Por ejemplo, para un destino declarado con el nombre development:

databricks bundle deploy -t development

Para obtener información sobre bundle deploy, consulte Desplegar un paquete.

Sugerencia

Puede vincular trabajos y canalizaciones definidos por agrupación a trabajos y canalizaciones existentes en el área de trabajo de Azure Databricks para mantenerlos sincronizados. Consulte Enlace de un recurso de agrupación.

Paso 7: ejecutar el paquete

Para ejecutar un trabajo o una canalización específicos, ejecute el comando bundle run desde la raíz del conjunto. Debe especificar el trabajo o la canalización declarados en el archivo de configuración del conjunto. Si no se especifica la opción -t, se usa el destino predeterminado declarado en el archivo de configuración de agrupación. Por ejemplo, para ejecutar un trabajo denominado hello_job en el contexto del destino predeterminado:

databricks bundle run hello_job

Para ejecutar un trabajo denominado hello_job en el contexto de un destino declarado con el nombre development:

databricks bundle run -t development hello_job

Para obtener información sobre bundle run, consulte Ejecución de un trabajo o una canalización.

(Opcional) Paso 8: configuración del paquete para CI/CD con GitHub

Si usa GitHub para CI/CD, puede usar Acciones de GitHub para ejecutar los comandos databricks bundle deploy y databricks bundle run automáticamente, en base a los eventos específicos de flujo de trabajo de GitHub y otros criterios. Consulte CI/CD con paquetes de activos de Databricks.

Conversión de la configuración del proyecto dbx en databricks.yml

Para dbx, la configuración del proyecto está de forma predeterminada en un archivo denominado project.json en la carpeta del .dbx proyecto. Consulte Referencia del archivo de proyecto.

En el caso de las agrupaciones, las configuraciones de agrupación se encuentran de forma predeterminada en un archivo denominado databricks.yml dentro de la carpeta raíz del lote. Consulta Configuración de agrupaciones de recursos de Databricks.

Para un archivo conf/project.json con el siguiente contenido de ejemplo:

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

El archivo correspondiente databricks.yml es el siguiente:

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

Los objetos siguientes del archivo anterior conf/project.json de este ejemplo no se admiten en databricks.yml los archivos y no tienen ninguna solución alternativa:

inplace_jinja_support
storage_type

Los siguientes objetos permitidos adicionales en los archivos conf/project.json no se admiten en los archivos databricks.yml y no tienen ninguna solución alternativa:

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Conversión de la configuración de implementación de dbx en databricks.yml

Para dbx, la configuración de implementación se encuentra de forma predeterminada en un archivo dentro de la carpeta del conf proyecto. Consulte Referencia del archivo de implementación. El archivo de configuración de implementación tiene de forma predeterminada uno de los siguientes nombres de archivo:

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

En el caso de las agrupaciones, la configuración de implementación se encuentra de forma predeterminada en un archivo denominado databricks.yml dentro de la carpeta raíz del lote. Consulta Configuración de agrupaciones de recursos de Databricks.

Para un archivo conf/deployment.yml con el siguiente contenido de ejemplo:

build:
  python: 'pip'

environments:
  default:
    workflows:
      - name: 'workflow1'
        tasks:
          - task_key: 'task1'
            python_wheel_task:
              package_name: 'some-pkg'
              entry_point: 'some-ep'