Projectsjablonen voor Databricks Asset Bundle

Databricks Asset Bundles beschrijft Databricks-resources, zoals taken, pijplijnen en notebooks als bronbestanden, zodat u metagegevens naast deze bronbestanden kunt opnemen om infrastructuur en andere resources in te richten en een end-to-end definitie van een project te bieden, allemaal verpakt als één implementeerbaar project. Bekijk wat zijn Databricks Asset Bundles?.

Met bundelsjablonen kunnen gebruikers bundels op een consistente, herhaalbare manier maken door mapstructuren tot stand te brengen, stappen en taken, tests en andere IaC-kenmerken (Infrastructure-as-Code) van DevOps te maken die gebruikelijk zijn in een implementatiepijplijn.

Als u bijvoorbeeld regelmatig Databricks-taken uitvoert waarvoor aangepaste pakketten nodig zijn met een tijdrovende compilatiestap bij de installatie, kunt u uw ontwikkelingslus versnellen door een bundelsjabloon te maken waarmee een aangepaste containeromgeving wordt opgegeven.

Databricks biedt een set standaardbundelsjablonen, maar u kunt ook aangepaste bundelsjablonenmaken. Gebruikers kunnen vervolgens bundels initialiseren met behulp van de init-opdracht, waarbij een standaardsjabloon of uw aangepaste sjabloon wordt opgegeven.

Een bundel maken met behulp van een sjabloon

Als u een Azure Databricks-bundelsjabloon wilt gebruiken om uw bundel te maken, gebruikt u de opdracht Databricks CLIbundle init, waarbij u de naam van de sjabloon opgeeft die u wilt gebruiken. Met de volgende opdracht maakt u bijvoorbeeld een bundel met behulp van de standaard-Python-bundelsjabloon:

databricks bundle init default-python

Als u een aangepaste bundelsjabloon wilt gebruiken, geeft u het lokale pad of de externe URL van de sjabloon door aan de opdracht Databricks CLIbundle init.

Met het volgende commando wordt bijvoorbeeld de dab-container-template sjabloon gebruikt die is gemaakt in de Zelfstudie: Aangepaste Bundelsjabloon:

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

Als u geen sjabloon opgeeft, geeft het bundle init-commando een prompt met de beschikbare standaardsjablonen waaruit u kunt kiezen.

Standaardbundelsjablonen

Azure Databricks biedt de volgende standaardbundelsjablonen:

Aangepaste bundelsjablonen

Bundelsjablonen maken gebruik van go-pakket templatingssyntaxis, die flexibiliteit bieden voor de aangepaste bundelsjablonen die u kunt maken. Zie de Go-pakket sjabloondocumentatie.

sjabloonprojectstructuur

Een bundelsjabloonproject moet minimaal het volgende hebben:

• Een databricks_template_schema.json-bestand in de hoofdmap van het project dat één gebruikersprompt-eigenschap definieert voor de naam van de projectbundel. Zie sjabloonschema.
• Een databricks.yml.tmpl bestand in een template map die de configuratie definieert voor alle bundels die met de sjabloon zijn gemaakt. Als uw databricks.yml.tmpl bestand verwijst naar aanvullende *.yml.tmpl configuratiesjablonen, geeft u de locatie van deze sjablonen op in de include toewijzing. Zie Configuratiesjablonen.

Daarnaast worden de mapstructuur en opgenomen bestanden van het bundelsjabloonproject template map gespiegeld door bundels die met de sjabloon zijn gemaakt. Als u bijvoorbeeld wilt dat de sjabloon een bundel genereert met een eenvoudig notitieblok in de map src en een taakdefinitie waarmee het notebook wordt uitgevoerd in de map resources, zou u het sjabloonproject als volgt organiseren:

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

sjabloonschema

Een aangepast bundelsjabloonproject moet een databricks_template_schema.jsonJSON-bestand in de hoofdmap van het project bevatten. Dit bestand definieert velden die worden gebruikt door de Databricks CLI wanneer de opdracht bundle init wordt uitgevoerd, zoals prompttekst.

Het volgende basisbestand databricks_template_schema.json definieert een invoervariabele project_name voor het bundelproject, dat het promptbericht en een standaardwaarde bevat. Vervolgens wordt een succesbericht gedefinieerd voor de initialisatie van het bunde-project die gebruikmaakt van de waarde van de invoervariabele in het bericht.

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

Sjabloonschemavelden

Het databricks_template_schema.json-bestand ondersteunt het definiëren van invoervariabelen voor het verzamelen van informatie tijdens de bundelinitialisatie van uw gebruiker in het properties veld, evenals aanvullende velden om de initialisatie aan te passen.

Invoervariabelen worden gedefinieerd in het properties veld van het sjabloonschema. Elke invoervariabele definieert metagegevens die nodig zijn voor het presenteren van een prompt aan de gebruiker tijdens bundelinitalisatie. De waarde van de variabele is vervolgens toegankelijk met behulp van de syntaxis van de sjabloonvariabele, zoals {{.project_name}}.

U kunt ook de waarden van sommige velden instellen om het initialisatieproces van de bundel aan te passen.

Ondersteunde schemavelden worden vermeld in de volgende tabel.

configuratiesjablonen voor

Een aangepaste bundelsjabloon moet een databricks.yml.tmpl-bestand bevatten in een template map in het bundelsjabloonproject dat wordt gebruikt voor het maken van het bundelproject databricks.yml configuratiebestand. Sjablonen voor configuratiebestanden voor resources kunnen worden gemaakt in de map resources. Vul deze sjabloonbestanden in met YAML voor configuratiesjablonen.

De volgende eenvoudige voorbeeldconfiguratiesjablonen voor databricks.yml en de bijbehorende *_job.yml de naam van de bundel en twee doelomgevingen vaststellen en een taak definiëren waarmee het notebook in de bundel wordt uitgevoerd, voor bundels die met deze sjabloon zijn gemaakt. Deze configuratiesjablonen maken gebruik van bundelvervangingen en bundeltemplatehelpers.

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

Sjabloonhelpers en -variabelen

Sjabloonhelpers zijn functies van Databricks die u in uw sjabloonbestanden kunt gebruiken om tijdens runtime gebruikersspecifieke informatie op te halen of om te communiceren met de sjabloonengine. U kunt ook uw eigen sjabloonvariabelen definiëren.

De volgende sjabloonhelpers zijn beschikbaar voor Databricks-bundelsjabloonprojecten. Zie Go-sjablonenvoor meer informatie over het gebruik van Go-sjablonen en -variabelen.

Helpers voor aangepaste sjablonen

Als u uw eigen sjabloonhulpfuncties wilt definiëren, maakt u een sjabloonbestand in de map library van het sjabloonproject en gebruikt u de sjabloonsyntaxis go om helpers te definiëren. De volgende inhoud van een library/variables.tmpl-bestand definieert bijvoorbeeld de variabelen cli_version en model_name. Wanneer deze sjabloon wordt gebruikt om een bundel te initialiseren, wordt de waarde van de model_name-variabele samengesteld met behulp van het input_project_name veld dat is gedefinieerd in het sjabloonschemabestand. De waarde van deze veldwaarde is de gebruikersinvoer na een prompt.

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

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

Zie het bestand mlops-stacks-sjabloonvariabelenvoor een volledig voorbeeld.

De bundelsjabloon testen

Ten slotte moet u de sjabloon testen. Gebruik bijvoorbeeld de Databricks CLI om een nieuwe bundel te initialiseren met behulp van de sjabloon die in de vorige secties is gedefinieerd:

databricks bundle init basic-bundle-template

Voor de prompt What is your bundle project name? typt u my_test_bundle.

Zodra de testbundel is gemaakt, wordt het succesbericht van het schemabestand uitgevoerd. Als u de inhoud van de my_test_bundle map bekijkt, ziet u het volgende:

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

En het databricks.yml-bestand en de taak is nu aangepast:

# 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

De sjabloon delen

Als u deze bundelsjabloon met anderen wilt delen, kunt u deze opslaan in versiebeheer met elke provider die door Git wordt ondersteund en waartoe uw gebruikers toegang hebben. Als u de bundle init opdracht wilt uitvoeren met een Git-URL, moet u ervoor zorgen dat het databricks_template_schema.json bestand zich op de hoofdlocatie bevindt ten opzichte van die Git-URL.

Volgende stappen

• Blader door extra sjablonen die door Databricks worden gemaakt en onderhouden. Bekijk de opslagplaats met bundelvoorbeelden in GitHub.
• Als u MLOps Stacks wilt gebruiken met Databricks Asset Bundle-sjablonen, raadpleegt u Databricks Asset Bundles voor MLOps Stacks.
• Meer informatie over het gebruik van templates in Go-pakketten. Zie de documentatie van het Go-pakketsjabloon.