Databricks Asset Bundle 專案範本

Databricks 資產套件組合描述 Databricks 資源，例如作業、管線和筆記本作為來源檔案，可讓您將這些來源檔案包含元數據，以布建基礎結構和其他資源，並提供專案的端對端定義，全部封裝為單一可部署專案。 請參閱什麼是 Databricks Asset Bundles？。

套件組合範本可讓使用者以一致、可重複的方式建立套件組合，方法是建立跨部署管線通用的資料夾結構、建置步驟和工作、測試和其他 DevOps 基礎結構即程式代碼 （IaC） 屬性。

例如，如果您定期執行需要自定義套件的 Databricks 作業，並在安裝時執行耗時的編譯步驟，您可以建立指定自定義容器環境的套件組合範本來加速開發迴圈。

Databricks 提供一組 預設套件組合範本，但您也可以建立 自定義套件組合範本。 然後，使用者可以使用 套件組合 init 命令初始化套件組合，並指定預設範本或自定義範本。

使用範本建立套件組合

若要使用 Azure Databricks 套件組合範本來建立套件組合，請使用 Databricks CLIbundle init 命令，指定要使用的範本名稱。 例如，下列命令會使用預設 Python 套件組合範本來建立套件組合：

databricks bundle init default-python

若要使用自定義套件組合範本，請將範本的本機路徑或遠端 URL 傳遞至 Databricks CLIbundle init 命令。

例如，下列命令會使用在dab-container-template中建立的範本：

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

如果您未指定範本，bundle init 命令會提示一組可供您選擇的預設範本。

預設套件組合範本

Azure Databricks 提供下列預設套件組合範本：

自定義套件組合範本

套件組合範本會使用 Go 套件範本化語法，提供您可以建立之自定義套件組合範本的彈性。 請參閱 Go 套件範本文件。

範本項目結構

套件組合範本專案至少必須具備：

• 專案根目錄的 databricks_template_schema.json 檔案，定義套件組合項目名稱的一個使用者提示屬性。 請參閱 樣本架構。
• 位於 databricks.yml.tmpl 資料夾中的 template 檔案，定義使用範本建立的任何套件組合的組態。 如果您的 databricks.yml.tmpl 檔案參考任何其他 *.yml.tmpl 組態範本，請在 include 對應中指定這些範本的位置。 請參閱 組態範本。

此外，套件範本專案的資料夾結構及其內含檔案會由使用範本建立的套件在 template 資料夾中進行複製。 例如，如果您想要讓範本在 src 資料夾中產生包含一個簡單筆記本的套件，以及在 resources 資料夾中執行筆記本的作業定義，您可以這樣組織範本專案：

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

範本架構

自訂捆綁範本專案必須在專案根目錄包含一個 databricks_template_schema.jsonJSON 檔案。 當執行 bundle init 命令時，此檔案會定義 Databricks CLI 所使用的欄位，例如提示文字。

下列基本 databricks_template_schema.json 檔案會定義套件組合專案的輸入變數 project_name，其中包含提示訊息和預設值。 然後，它會定義一個統合專案初始化的成功訊息，該訊息會使用訊息中的輸入變數值。

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

範本架構欄位

databricks_template_schema.json 檔案支援定義輸入變數，以便從使用者於 properties 欄位中收集套件組合初始化期間的資訊，以及自定義初始化的其他欄位。

輸入變數定義於範本架構的 [properties] 欄位中。 每個輸入變數都會定義在套件組合初始化期間向用戶呈現提示所需的元數據。 然後使用樣本變數語法存取變數的值，例如 {{.project_name}}。

您也可以設定某些欄位的值，以自訂套件組合初始化程式。

下表列出支持的架構欄位。

組態範本

自定義套件組合範本應包含套件組合範本專案中 template 資料夾中的 databricks.yml.tmpl 檔案，該檔案是用來建立套件組合專案 databricks.yml 組態檔。 您可以在 resources 資料夾中建立資源的組態檔範本。 使用組態範本 YAML 填入這些範本檔案。

以下簡單的範例設定範本適用於 databricks.yml 和相關的 *_job.yml，以建立套件組合名稱和兩個目標環境，並定義一個作業，該作業在套件組合中執行筆記本，供使用此範本建立的套件組合使用。 這些配置模板利用 套件替代品 和 套件範本協助工具。

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

範本輔助工具和變數

範本協助程式是由 Databricks 提供的函式，您可以在範本檔案內使用，在運行時間取得使用者特定資訊，或與範本引擎互動。 您也可以定義自己的範本變數。

下列範本協助程式適用於 Databricks 套件組合範本專案。 如需使用 Go 範本和變數的相關信息，請參閱 Go 範本。

自訂範本輔助工具

若要定義您自己的範本協助程式，請在範本專案的 library 資料夾中建立範本檔案，並使用 Go 範本化語法來定義協助程式。 例如，library/variables.tmpl 檔案的下列內容會定義變數 cli_version 和 model_name。 當此範本用來初始化套件組合時，會使用範本架構檔案中定義的 model_name 欄位來建構 input_project_name 變數的值。 這個欄位的值是提示之後的使用者輸入。

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

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

若要查看完整的範例，請參閱 mlops-stacks 範本變數檔案。

測試套件組合範本

最後，請務必測試您的範本。 例如，使用 Databricks CLI，使用上一節中定義的範本來初始化新的套件組合：

databricks bundle init basic-bundle-template

請輸入my_test_bundle以回應What is your bundle project name?的提示。

建立測試套件組合之後，就會輸出結構描述檔案的成功訊息。 如果您檢查 my_test_bundle 資料夾的內容，應該會看到下列內容：

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

databricks.yml 檔案和作業現在已自訂：

# 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

共用範本

如果您想要與其他人共用此套件組合範本，可將其儲存於 Git 支援且您的使用者可存取的提供者版本控制中。 要使用 Git URL 執行 bundle init 命令，請確定 databricks_template_schema.json 檔案位於相對於該 Git URL 的根位置。

下一步

• 瀏覽 Databricks 所建立和維護的其他範本。 請參閱 GitHub 中的套件組件範例存放庫。
• 若要搭配 Databricks Asset Bundles 範本使用 MLOps Stacks，請參閱Databricks Asset Bundles for MLOps Stacks。
• 深入了解 Go 套件範本化。 請參閱 Go 套件範本文件。