Vorlagen für Databricks-Projekt-Ressourcenpakete

Databricks Asset Bundles beschreiben Databricks-Ressourcen wie Aufträge, Pipelines und Notizbücher als Quelldateien, ermöglichen es Ihnen, Metadaten zusammen mit diesen Quelldateien zur Bereitstellung von Infrastruktur und anderen Ressourcen einzuschließen und eine End-to-End-Definition eines Projekts bereitzustellen, die alle als einzelnes bereitstellungsfähiges Projekt verpackt sind. Siehe Was sind Databricks Asset Bundles?.

Bündelvorlagen ermöglichen Es Benutzern, Bündel auf konsistente, wiederholbare Weise zu erstellen, indem Ordnerstrukturen, Buildschritte und Aufgaben, Tests und andere IaC-Attribute (DevOps Infrastructure-as-Code) erstellt werden, die in einer Bereitstellungspipeline gemeinsam sind.

Wenn Sie beispielsweise Routineaufträge ausführen, für die benutzerdefinierte Pakete mit einem zeitaufwendigen Kompilierungsschritt bei der Installation erforderlich sind, können Sie die Entwicklungsschleife beschleunigen, indem Sie eine Bündelvorlage erstellen, die eine benutzerdefinierte Containerumgebung angibt.

Databricks bietet eine Reihe von Standardbundlevorlagen, aber Sie können auch benutzerdefinierte Bündelvorlagen erstellen. Benutzer können dann Bündel mit dem Befehl "init" initialisieren und eine Standardvorlage oder Ihre benutzerdefinierte Vorlage angeben.

Erstellen eines Bündels mithilfe einer Vorlage

Um eine Azure Databricks-Bündelvorlage zum Erstellen Ihres Bündels zu verwenden, verwenden Sie den Befehl Databricks CLIbundle init , der den Namen der zu verwendenden Vorlage angibt. Mit dem folgenden Befehl wird beispielsweise ein Bündel mithilfe der standardmäßigen Python-Bündelvorlage erstellt:

databricks bundle init default-python

Um eine benutzerdefinierte Bündelvorlage zu verwenden, übergeben Sie den lokalen Pfad oder die Remote-URL der Vorlage an den Befehl Databricks CLIbundle init .

Der folgende Befehl verwendet beispielsweise die dab-container-template-Vorlage, die im Tutorial für benutzerdefinierte Bündelvorlagen erstellt wurde:

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

Wenn Sie keine Vorlage angeben, werden die bundle init Eingabeaufforderungen mit der Gruppe der verfügbaren Standardvorlagen angezeigt, aus denen Sie auswählen können.

Standardbundlevorlagen

Azure Databricks stellt die folgenden Standardbundlevorlagen bereit:

Benutzerdefinierte Bündelvorlagen

Bundle-Vorlagen verwenden die Go-Paketvorlagen-Syntax, die Flexibilität bei der Erstellung von benutzerdefinierten Bundle-Vorlagen bietet. Weitere Informationen finden Sie in der Dokumentation zu Go-Paketvorlagen.

Vorlagenprojektstruktur

Ein Bündelvorlagenprojekt muss mindestens folgendes aufweisen:

• A databricks_template_schema.json Datei im Projektstamm, die eine Benutzeraufforderungseigenschaft für den Bundle-Projektnamen definiert. Siehe Vorlagenschema.
• Eine databricks.yml.tmpl-Datei in einem template-Ordner, der die Konfiguration für alle Bündel definiert, die mit der Vorlage erstellt wurden. Wenn Ihre databricks.yml.tmpl-Datei auf weitere *.yml.tmpl-Konfigurationsvorlagen verweist, geben Sie den Speicherort dieser Vorlagen in der include-Zuordnung an. Siehe Konfigurationsvorlagen.

Darüber hinaus wird die Ordnerstruktur und die eingeschlossenen Dateien des Projektordners template der Bündelvorlage von Bündeln gespiegelt, die mit der Vorlage erstellt wurden. Wenn die Vorlage beispielsweise ein Bündel mit einem einfachen Notizbuch im src Ordner und einer Auftragsdefinition generieren soll, die das Notizbuch im resources Ordner ausführt, würden Sie Ihr Vorlagenprojekt wie folgt organisieren:

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

Vorlagenschema

Ein benutzerdefiniertes Bundle-Vorlagenprojekt muss eine databricks_template_schema.jsonJSON file at the project root. Diese Datei definiert Felder, die von der Databricks CLI verwendet werden, wenn der bundle init Befehl ausgeführt wird, z. B. Eingabeaufforderungstext.

Die folgende Standarddatei databricks_template_schema.json definiert eine Eingabevariable project_name für das Bündelprojekt, die die Eingabeaufforderungsmeldung und einen Standardwert enthält. Anschließend wird eine Erfolgsmeldung für die Initialisierung des Bündelprojekts definiert, die den Eingabevariablenwert innerhalb der Nachricht verwendet.

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

Vorlagenschemafelder

Die databricks_template_schema.json Datei unterstützt das Definieren von Eingabevariablen zum Sammeln von Informationen während der Bundleinitialisierung durch den Benutzer innerhalb des properties Felds sowie zusätzliche Felder zum Anpassen der Initialisierung.

Eingabevariablen werden im properties Feld des Vorlagenschemas definiert. Jede Eingabevariable definiert Metadaten, die zum Präsentieren einer Eingabeaufforderung für den Benutzer während der Bündelinitalisierung erforderlich sind. Auf den Wert der Variablen kann dann mithilfe der Template-Variablensyntax, wie z.B. {{.project_name}}, zugegriffen werden.

Sie können auch die Werte einiger Felder festlegen, um den Initialisierungsprozess des Bündels anzupassen.

Unterstützte Schemafelder sind in der folgenden Tabelle aufgeführt.

Konfigurationsvorlagen

Eine benutzerdefinierte Bündelvorlage sollte eine databricks.yml.tmpl Datei in einem template Ordner im Bundlevorlagenprojekt enthalten, das zum Erstellen der Bündelprojektkonfigurationsdatei databricks.yml verwendet wird. Vorlagen für Konfigurationsdateien für Ressourcen können im resources Ordner erstellt werden. Füllen Sie diese Vorlagendateien mit der Konfigurationsvorlage YAML auf.

Die folgenden einfachen Beispielkonfigurationsvorlagen für databricks.yml und die zugehörigen *_job.yml richten den Bundlenamen und zwei Zielumgebungen ein und definieren einen Auftrag, der das Notebook im Bundle ausführt, für Bündel, die mit dieser Vorlage erstellt wurden. Diese Konfigurationsvorlagen nutzen Bündelersetzungen und Bündelvorlagenhilfsprogramme.

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

Vorlagenhilfsfunktionen und Variablen

Vorlagenhilfsprogramme sind Funktionen von Databricks, die Sie in Ihren Vorlagendateien verwenden können, um benutzerspezifische Informationen zur Laufzeit abzurufen oder mit dem Vorlagenmodul zu interagieren. Sie können auch eigene Vorlagenvariablen definieren.

Die folgenden Vorlagenhilfsprogramme sind für Databricks-Bündelvorlagenprojekte verfügbar. Informationen zur Verwendung von Go-Vorlagen und -Variablen finden Sie unter Go-Vorlagen.

Benutzerdefinierte Vorlagenhilfsprogramme

Um Ihre eigenen Hilfsfunktionen zu definieren, erstellen Sie eine Vorlagendatei im library-Ordner des Vorlagenprojekts und verwenden Sie die Go-Templating-Syntax, um Hilfsfunktionen zu definieren. Beispielsweise definieren die folgenden Inhalte einer library/variables.tmpl Datei die Variablen cli_version und model_name. Wenn diese Vorlage zum Initialisieren eines Bündels verwendet wird, wird der Wert der model_name Variablen mithilfe des input_project_name Felds erstellt, das in der Vorlagenschemadatei definiert ist. Der Wert dieses Feldwerts ist die Benutzereingabe nach einer Eingabeaufforderung.

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

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

Ein vollständiges Beispiel finden Sie in der Vorlagenvariablendatei "mlops-stacks".

Testen der Bündelvorlage

Stellen Sie abschließend sicher, dass Sie Ihre Vorlage testen. Verwenden Sie beispielsweise die Databricks CLI, um ein neues Paket mithilfe der Vorlage zu initialisieren, die in den vorherigen Abschnitten definiert ist.

databricks bundle init basic-bundle-template

Geben Sie für die Eingabeaufforderung What is your bundle project name?my_test_bundle ein.

Sobald das Testbündel erstellt wurde, wird die Erfolgsmeldung aus der Schemadatei ausgegeben. Wenn Sie den Inhalt des my_test_bundle-Ordners untersuchen, sollte Folgendes angezeigt werden:

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

And the databricks.yml Datei und der Einzelvorgang angepasst:

# 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

Freigeben der Vorlage

Wenn Sie diese Paketvorlage für andere Personen freigeben möchten, können Sie sie in der Versionskontrolle bei jedem Anbieter speichern, den Git unterstützt und auf den Ihre Benutzer*innen Zugriff haben. Um den Befehl bundle init mit einer Git-URL auszuführen, stellen Sie sicher, dass sich die Datei databricks_template_schema.json in einem Stammspeicherort relativ zu dieser Git-URL befindet.

Nächste Schritte

• Durchsuchen Sie zusätzliche Vorlagen, die von Databricks erstellt und verwaltet werden. Sehen Sie sich das Paketbeispielerepository in GitHub an.
• Informationen zur Verwendung von MLOps Stacks mit Databricks-Ressourcenbundlevorlagen finden Sie unter Databricks-Ressourcenbundles für MLOps Stack.
• Erfahren Sie mehr über die Erstellung von Go-Paketvorlagen. Weitere Informationen finden Sie in der Dokumentation zu Go-Paketvorlagen.