Eseguire la migrazione da dbx a bundle

Articolo
02/05/2025

Importante

Databricks consiglia di usare i bundle di asset di Databricks invece di dbx di Databricks Labs. Gli articoli correlati su dbx sono stati ritirati e potrebbero non essere aggiornati.

Questo articolo descrive come eseguire la migrazione di progetti per dbx da Databricks Labs a Aggregazioni di asset di Databricks. Vedi Introduzione a dbx di Databricks Labs e Cosa sono i bundle di asset di Databricks?.

Prima di eseguire la migrazione, prendere nota delle limitazioni e dei confronti delle funzionalità seguenti tra dbx da Databricks Labs e i bundle di asset di Databricks.

Confronto delle funzionalità

Prima di eseguire la migrazione, tenere presente come vengono implementate le funzionalità seguenti per dbx di Databricks Labs nei bundle di asset di Databricks.

Modelli e progetti

dbx fornisce supporto per la creazione di modelli Jinja. È possibile includere i modelli Jinja nella configurazione della distribuzione e passare variabili di ambiente inline o tramite un file di variabili. Anche se non consigliato, dbx fornisce anche il supporto sperimentale per le funzioni utente personalizzate.

I bundle forniscono supporto per i modelli Go per il riutilizzo della configurazione. Gli utenti possono creare bundle basati su modelli predefiniti. C'è quasi una parità completa per la creazione di modelli, ad eccezione delle funzioni utente personalizzate.

Gestione della costruzione

dbx fornisce supporto per la compilazione tramite pip wheel, Poetry e Flit. Gli utenti possono specificare l'opzione di compilazione nella sezione build del file deployment.yml un progetto.

I Bundle consentono agli utenti di creare, distribuire ed eseguire file wheel di Python. Gli utenti possono sfruttare la voce predefinita whl nel file databricks.yml di un bundle.

Sincronizzare, distribuire ed eseguire codice

dbx permette di caricare il codice separatamente dalla generazione di risorse dell'area di lavoro, ad esempio i processi di Azure Databricks.

I bundle caricano sempre il codice e creano o aggiornano le risorse dell'area di lavoro contemporaneamente. Ciò semplifica le distribuzioni ed evita condizioni di blocco per i processi già in corso.

Eseguire la migrazione di un progetto dbx a un bundle

Dopo aver annotato le limitazioni e i confronti delle funzionalità precedenti tra dbx di Databricks Labs e i bundle di asset di Databricks, è possibile eseguire la migrazione da dbx ai bundle.

Databricks consiglia, per iniziare una migrazione del progetto dbx, di mantenere il progetto dbx nella cartella originale e di avere una cartella vuota separata in cui copiare il contenuto del progetto originale dbx. Questa cartella separata sarà il tuo nuovo bundle. È possibile riscontrare problemi imprevisti se si inizia a convertire il progetto dbx nella cartella originale in un bundle e quindi si commettono alcuni errori o si vuole ricominciare dall'inizio,

Passaggio 1: Installare e configurare l'interfaccia della riga di comando di Databricks

I bundle di asset di Databricks sono disponibili a livello generale nell'interfaccia della riga di comando di Databricks versione 0.218.0 e successive. Se è già stata installata e configurata l'interfaccia della riga di comando di Databricks versione 0.218.0 o successiva, passare al passaggio 2.

Nota

I bundle non sono compatibili con l'interfaccia della riga di comando di Databricks versione 0.18 e precedenti.

Installare o aggiornare a Databricks CLI versione 0.218.0 o superiore. Consulta Installare o aggiornare la CLI di Databricks.
Configurare l'interfaccia della riga di comando di Databricks per l'autenticazione con le aree di lavoro di Azure Databricks di destinazione, ad esempio usando l'autenticazione del token di accesso personale di Azure Databricks. Per altri tipi di autenticazione di Azure Databricks, vedere Autenticazione per l'interfaccia della riga di comando di Databricks.

Passaggio 2: Creare il file di configurazione del bundel

Se si usa un IDE come Visual Studio Code, PyCharm Professional o IntelliJ IDEA Ultimate che fornisce supporto per file YAML e file di schema JSON, è possibile usare l'IDE non solo per creare il file di configurazione del bundle, ma per controllare la sintassi e la formattazione del file e fornire hint di completamento del codice, come indicato di seguito.

Visual Studio Code

Aggiungere il supporto del server di linguaggio YAML a Visual Studio Code, ad esempio installando l'estensione YAML da Visual Studio Code Marketplace.
Generare il file di schema JSON di configurazione del bundle di asset di Databricks usando l'interfaccia della riga di comando di Databricks per eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, generare un file denominato bundle_config_schema.json all'interno della directory corrente, come indicato di seguito:
```
databricks bundle schema > bundle_config_schema.json
```
Usare Visual Studio Code per creare o aprire un file di configurazione bundle all'interno della directory corrente. Per convenzione, questo file è denominato databricks.yml.
Aggiungere il commento seguente all'inizio del file di configurazione del bundle:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Nota

Nel commento precedente, se il file di schema JSON di configurazione del bundle di asset di Databricks si trova in un percorso diverso, sostituire bundle_config_schema.json con il percorso completo del file di schema.
Usare le funzionalità del server di linguaggio YAML aggiunte in precedenza. Per altre informazioni, consultare la documentazione del server del linguaggio YAML.

PyCharm Professional

Generare il file di schema JSON di configurazione del bundle di asset di Databricks usando l'interfaccia della riga di comando di Databricks per eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, generare un file denominato bundle_config_schema.json all'interno della directory corrente, come indicato di seguito:
```
databricks bundle schema > bundle_config_schema.json
```
Configurare PyCharm per riconoscere il file di schema JSON di configurazione del bundle e quindi completare il mapping dello schema JSON seguendo le istruzioni riportate in Configurare uno schema JSON personalizzato.
Usare PyCharm per creare o aprire un file di configurazione del bundle. Per convenzione, questo file è denominato databricks.yml. Durante la digitazione, PyCharm verifica la sintassi e la formattazione dello schema JSON e fornisce hint di completamento del codice.

IntelliJ IDEA Ultimate

Generare il file di schema JSON di configurazione del bundle di asset di Databricks usando l'interfaccia della riga di comando di Databricks per eseguire il comando bundle schema e reindirizzare l'output a un file JSON. Ad esempio, generare un file denominato bundle_config_schema.json all'interno della directory corrente, come indicato di seguito:
```
databricks bundle schema > bundle_config_schema.json
```
Configurare IntelliJ IDEA per riconoscere il file di schema JSON di configurazione del bundle e quindi completare il mapping dello schema JSON seguendo le istruzioni riportate in Configurare uno schema JSON personalizzato.
Usare IntelliJ IDEA per creare o aprire un file di configurazione del bundle. Per convenzione, questo file è denominato databricks.yml. Durante la digitazione, IntelliJ IDEA controlla la sintassi e la formattazione dello schema JSON e fornisce hint di completamento del codice.

Passaggio 3: Convertire le impostazioni del progetto dbx in databricks.yml

Convertire le impostazioni nel file dbx del progetto .dbx/project.json nelle impostazioni equivalenti nel file databricks.yml del bundle. Per informazioni dettagliate, vedere Conversione delle impostazioni del progetto dbx in databricks.yml.

Passaggio 4: Convertire le impostazioni di distribuzione dbx in databricks.yml

Convertire le impostazioni nella cartella dbx del progetto conf nelle impostazioni equivalenti nel file databricks.yml del bundle. Per informazioni dettagliate, vedere Conversione delle impostazioni di distribuzione dbx in databricks.yml.

Passaggio 5: Convalidare il bundle

Prima di distribuire gli artefatti o di eseguire un processo di Azure Databricks, una pipeline DLT o una pipeline MLOps, è necessario assicurarsi che il file di configurazione del bundle sia sintatticamente corretto. A tale scopo, eseguire il comando bundle validate dalla radice del bundle:

databricks bundle validate

Per informazioni su bundle validate, vedere Convalidare un bundle.

Passaggio 6: Distribuire il bundle

Per distribuire gli artefatti locali specificati nell'area di lavoro remota, eseguire il comando bundle deploy dalla radice del bundle. Se non vengono specificate opzioni di comando, viene usata la destinazione predefinita dichiarata nel file di configurazione del bundle:

databricks bundle deploy

Per distribuire gli artefatti all'interno del contesto di una destinazione specifica, specificare l'opzione -t (o --target) insieme al nome della destinazione come dichiarato all'interno del file di configurazione del bundle. Ad esempio, per una destinazione indicata con il nome development:

databricks bundle deploy -t development

Per altre informazioni su bundle deploy, vedere Distribuire un bundle.

Suggerimento

È possibile collegare processi e pipeline definiti dal bundle a processi e pipeline esistenti nell'area di lavoro di Azure Databricks per mantenerli sincronizzati. Vedere Associare le risorse del bundle.

Passaggio 7: Eseguire il pacchetto

Per eseguire un processo o una pipeline specifica, eseguire il comando bundle run dalla radice del bundle. È necessario specificare il processo o la pipeline dichiarata all'interno del file di configurazione del bundle. Se l'opzione -t non è specificata, viene usata la destinazione predefinita come dichiarata all'interno del file di configurazione del bundle. Ad esempio, per eseguire un processo denominato hello_job all'interno del contesto della destinazione predefinita:

databricks bundle run hello_job

Per eseguire un processo denominato hello_job all'interno del contesto di una destinazione dichiarata con il nome development:

databricks bundle run -t development hello_job

Per informazioni su bundle run, vedere Esecuzione di un processo o di una pipeline.

(Facoltativo) Passaggio 8: Configurare il bundle per CI/CD con GitHub

Se si usa GitHub per CI/CD, è possibile usare GitHub Actions per eseguire automaticamente i comandi databricks bundle deploy e databricks bundle run , in base a specifici eventi del flusso di lavoro GitHub e ad altri criteri. Consulta Esegui un flusso di lavoro CI/CD con un Databricks Asset Bundle e GitHub Actions.

Conversione delle impostazioni del progetto dbx in databricks.yml

Per dbx, le impostazioni del progetto sono per impostazione predefinita in un file denominato project.json nella cartella .dbx del progetto. Vedere Informazioni di riferimento sul file di progetto.

Per i bundle, le configurazioni del bundle sono per impostazione predefinita in un file denominato databricks.yml all'interno della cartella radice del bundle. Vedere Configurazione del bundle di asset di Databricks.

Per un file conf/project.json con il contenuto seguente:

{
  "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
}

Il file databricks.yml corrispondente è il seguente:

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.

Gli oggetti seguenti nel precedente file conf/project.json di questo esempio non sono supportati nei file databricks.yml e non presentano soluzioni alternative:

inplace_jinja_support
storage_type

I seguenti oggetti consentiti aggiuntivi nei file conf/project.json non sono supportati nei file databricks.yml e non dispongono di soluzioni alternative:

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

Conversione delle impostazioni di distribuzione dbx in databricks.yml

Per dbx, le impostazioni di distribuzione sono per impostazione predefinita in un file all'interno della cartella del progetto conf. Vedere Informazioni di riferimento sul file di distribuzione. Per impostazione predefinita, il file delle impostazioni di distribuzione ha uno dei nomi di file seguenti:

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

Per i bundle, le impostazioni di distribuzione sono per impostazione predefinita in un file denominato databricks.yml all'interno della cartella radice del bundle. Vedere Configurazione del bundle di asset di Databricks.

Per un file conf/deployment.yml con il contenuto seguente:

build:
  python: 'pip'

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