Modelli di progetto del bundle di asset di Databricks

Questo articolo descrive la sintassi per i modelli del bundle di asset di Databricks. I bundle consentono di gestire i flussi di lavoro di Azure Databricks a livello di codice. Vedere Che cosa sono i bundle di asset di Databricks?

I modelli di aggregazione consentono agli utenti di creare bundle in modo coerente e ripetibile, stabilendo strutture di cartelle, passaggi di compilazione e attività, test e altri attributi dell'infrastruttura distribuita come codice (IaC) DevOps comuni in una pipeline di distribuzione dell'ambiente di sviluppo.

Ad esempio, se si eseguono regolarmente processi di Databricks che richiedono pacchetti personalizzati con un passaggio di compilazione dispendioso in termini di tempo durante l'installazione, è possibile velocizzare il ciclo di sviluppo creando un modello di bundle che supporta ambienti contenitore personalizzati.

I modelli di bundle definiscono la struttura di directory del bundle che verrà creato e includono un modello di file di configurazione databricks.yml.tmpl, nonché un file databricks_template_schema.json contenente variabili di richiesta utente.

Usare un modello di bundle predefinito

Per usare un modello di bundle predefinito di Azure Databricks per creare il bundle, usare il comando bundle init dell'interfaccia della riga di comando di Databricks, specificando il nome del modello predefinito da usare. Ad esempio, il comando seguente crea un bundle usando il modello di bundle Python predefinito:

databricks bundle init default-python

Se non si specifica un modello predefinito, il comando bundle init presenta il set di modelli disponibili da cui è possibile scegliere.

Azure Databricks offre i modelli di bundle predefiniti seguenti:

Usare un modello di bundle personalizzato

Per usare un modello di bundle diverso dai modelli di bundle predefiniti di Azure Databricks, passare il percorso locale o l'URL remoto del modello al comando bundle init dell'interfaccia della riga di comando di Databricks.

Ad esempio, il comando seguente usa il modello dab-container-template creato nell'Esercitazione sul modello di bundle personalizzato:

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Creare un modello di bundle personalizzato

I modelli di bundle usano la sintassi di creazione di modelli del pacchetto Go. Vedere la documentazione sul modello di pacchetto Go.

Come minimo, un progetto di modello di bundle deve avere:

• Un file databricks_template_schema.json nella radice del progetto che definisce una variabile di richiesta utente per il nome del progetto bundle.
• Un file databricks.yml.tmpl che si trova in una cartella template che definisce la configurazione per tutti i bundle creati con il modello. Se il file databricks.yml.tmpl fa riferimento a modelli di configurazione aggiuntivi *.yml.tmpl, specificare il percorso di questi nel mapping include.

Facoltativamente, è possibile aggiungere sottocartelle e file alla cartella di cui si vuole eseguire il mirroring template nei bundle creati dal modello.

Definire le variabili di richiesta utente

Il primo passaggio per la creazione di un modello di bundle di base consiste nel creare una cartella di progetto modello e un file denominato databricks_template_schema.json nella radice del progetto. Questo file contiene le variabili per cui gli utenti forniscono valori di input quando usano il modello per creare un bundle usando bundle init. Questo formato di file segue la specifica dello schema JSON.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Aggiungere il codice seguente al file databricks_template_schema.json e quindi salvare il file:

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

In questo file:

• project_name è l'unico nome della variabile di input.
• default è un valore predefinito facoltativo se un valore non viene fornito dall'utente con --config-file come parte del comando bundle init o disabilitato dall'utente al prompt dei comandi.
• description è il prompt dell'utente associato alla variabile di input, se un valore non viene fornito dall'utente con --config-file come parte del comando bundle init.
• order è un ordine facoltativo in cui ogni prompt dell'utente viene visualizzato se un valore non viene fornito dall'utente con --config-file come parte del comando bundle init. Se order non viene specificato, gli utenti visualizzano l'ordine in cui sono elencati nello schema.
• success_message è un messaggio facoltativo visualizzato al termine della creazione del progetto.

Compilare la struttura di cartelle

Creare quindi la cartella richiesta template e compilare la struttura di cartelle al suo interno. Questa struttura verrà con mirroring in base ai bundle creati con questo modello. Inserire anche tutti i file che si desidera includere in tali cartelle. Questo modello di bundle di base archivia i file in una cartella src e include un semplice notebook.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Aggiungere il testo seguente al file simple_notebook.ipynb:

print("Hello World!")

Popolare i file dei modelli di configurazione

Creare ora il file necessario databricks.yml.tmpl nella cartella template:

touch basic-bundle-template/template/databricks.yml.tmpl

Popolare questo file con il modello di configurazione di base YAML. Questo modello di configurazione stabilisce il nome del bundle, un processo usando il file del notebook specificato e due ambienti di destinazione per i bundle creati usando questo modello. Sfrutta anche le sostituzioni di bundle, che sono altamente consigliate. Vedere sostituzioni bundle.

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

Testare il modello di bundle

Infine, testare il modello. Creare una nuova cartella di progetto bundle, quindi usare l'interfaccia della riga di comando di Databricks per inizializzare un nuovo bundle usando il modello:

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

Per il prompt, What is your bundle project name?, digitare my_test_bundle.

Dopo aver creato il bundle di test, viene restituito il messaggio di esito positivo del file di schema. Se si esamina il contenuto della cartella my-test-bundle, verrà visualizzato quanto segue:

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

E il file databricks.yml è ora personalizzato:

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

Condividere il modello

Se si vuole condividere questo modello di bundle con altri utenti, è possibile archiviarlo nel controllo della versione con qualsiasi provider supportato da Git e a cui gli utenti hanno accesso. Per eseguire il comando bundle init con un URL Git, assicurarsi che il file databricks_template_schema.json si trovi nel percorso radice relativo a tale URL Git.

Passaggi successivi

• Esplorare modelli aggiuntivi creati e gestiti da Databricks. Vedere gli esempi di bundle nel repository GitHub.
• Per usare stack MLOps con i modelli di aggregazione di asset di Databricks, vedere Aggregazioni di asset di Databricks per stack MLOps.
• Altre informazioni sulla creazione di modelli dei pacchetti Go. Vedere la documentazione sul modello di pacchetto Go.