Modelli di progetto del bundle di asset di Databricks

I bundle di asset di Databricks descrivono le risorse di Databricks, ad esempio processi, pipeline e notebook come file di origine, consentono di includere metadati insieme a questi file di origine per effettuare il provisioning dell'infrastruttura e di altre risorse e fornire una definizione end-to-end di un progetto, tutto incluso come singolo progetto distribuibile. Consultare Che cosa sono i Databricks Asset Bundle?.

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.

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 specifica un ambiente contenitore personalizzato.

Databricks fornisce un set di modelli di bundle predefiniti , ma è anche possibile creare modelli di bundle personalizzati. Gli utenti possono quindi inizializzare i bundle usando il comando init bundle, specificando un modello predefinito o il modello personalizzato.

Creare un bundle usando un modello

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

databricks bundle init default-python

Per usare un modello di bundle personalizzato, passare il percorso locale o l'URL remoto del modello al comando della CLI di Databricksbundle init.

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

Se non si specifica un template, il comando bundle init visualizza il set di template predefiniti disponibili da cui scegliere.

modelli di pacchetti predefiniti

Azure Databricks offre i modelli di bundle predefiniti seguenti:

Modelli di bundle personalizzati

I modelli di bundle usano la sintassi di creazione di modelli di pacchetto Go, che offrono flessibilità nei modelli di bundle personalizzati che è possibile creare. Vedere la documentazione sul modello di pacchetto Go.

struttura del progetto modello

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

• Un file databricks_template_schema.json alla radice del progetto che definisce una proprietà di richiesta utente per il nome del progetto del pacchetto. Consultare il Template schema.
• 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. Consultare Modelli di configurazione.

Inoltre, la struttura delle cartelle e i file inclusi del progetto modello di bundle nella cartella template vengono riflessi dai bundle creati con il modello. Ad esempio, se si vuole che il modello generi un bundle con un notebook semplice nella cartella src e una definizione di processo che esegue il notebook nella cartella resources, è necessario organizzare il progetto modello come segue:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb

Schema del modello

Un progetto modello di bundle personalizzato deve contenere un file JSON databricks_template_schema.json nella radice del progetto. Questo file definisce i campi usati dall'interfaccia della riga di comando di Databricks quando viene eseguito il comando bundle init, ad esempio il testo del prompt.

Il file di base databricks_template_schema.json seguente definisce una variabile di input project_name per il progetto bundle, che include il messaggio di richiesta e un valore predefinito. Definisce quindi un messaggio di esito positivo per l'inizializzazione del progetto bunde che usa il valore della variabile di input all'interno del messaggio.

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

Campi dello schema del modello

Il file databricks_template_schema.json supporta la definizione di variabili di input per la raccolta di informazioni durante l'inizializzazione del bundle dall'utente all'interno del campo properties, nonché campi aggiuntivi per personalizzare l'inizializzazione.

Le variabili di input vengono definite nel campo properties dello schema del modello. Ogni variabile di input definisce i metadati necessari per presentare un prompt all'utente durante l'initalizzazione del bundle. Il valore della variabile è quindi accessibile usando la sintassi delle variabili di modello, ad esempio {{.project_name}}.

È anche possibile impostare i valori di alcuni campi per personalizzare il processo di inizializzazione del bundle.

I campi dello schema supportati sono elencati nella tabella seguente.

modelli di configurazione

Un modello di bundle personalizzato deve contenere un file databricks.yml.tmpl in una cartella template nel progetto modello di bundle usato per creare il progetto bundle databricks.yml file di configurazione. I modelli per i file di configurazione per le risorse possono essere creati nella cartella resources. Popolare questi file modello con il modello di configurazione YAML.

I modelli di configurazione di esempio seguenti per databricks.yml e *_job.yml associati stabiliscono il nome del bundle e due ambienti di destinazione e definiscono un processo che esegue il notebook nel bundle, per i bundle creati usando questo modello. Questi modelli di configurazione sfruttano le sostituzioni di bundle e gli assistenti dei modelli di bundle .

template/{{.project_name}}/databricks.yml.tmpl:

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

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

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

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.project_name}}_job.yml
# 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

Aiuti e variabili del modello

Gli helper modello sono funzioni fornite da Databricks che è possibile usare all'interno dei file modello per ottenere informazioni specifiche dell'utente in fase di esecuzione o interagire con il motore di modelli. È anche possibile definire variabili di modello personalizzate.

Per i progetti modello di bundle di Databricks sono disponibili gli helper modello seguenti. Per informazioni sull'uso di modelli e variabili Go, vedere Modelli Go.

Helper di modelli personalizzati

Per definire gli helper di template personalizzati, creare un file template nella cartella library del progetto template e usare la sintassi di templating Go per definire gli helper. Ad esempio, il contenuto seguente di un file di library/variables.tmpl definisce le variabili cli_version e model_name. Quando questo modello viene usato per inizializzare un bundle, il valore della variabile model_name viene costruito usando il campo input_project_name definito nel file dello schema del modello. Il valore di questo campo è l'input dell'utente dopo una richiesta.

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

Per un esempio completo, vedere il file delle variabili del modello mlops-stacks .

Testare il modello di bundle

Infine, assicurarsi di testare il modello. Ad esempio, usare l'interfaccia della riga di comando di Databricks per inizializzare un nuovo bundle usando il modello definito nelle sezioni precedenti:

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
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

E il file e il processo databricks.yml sono ora personalizzati:

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

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

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

# my_test_bundle_job.yml
# 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

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. Vedi gli esempi di bundle nel repository di GitHub.
• Per usare stack MLOps con i modelli di aggregazione di asset di Databricks, vedere Aggregazioni di asset di Databricks per stack MLOps.
• Scopri di più sulla gestione dei template dei pacchetti Go. Vedere la documentazione sul modello di pacchetto Go.