Databricks Asset Bundle 專案範本

文章
09/25/2024

本文說明 Databricks Asset Bundle 範本的語法。套件組合可讓您以程式設計方式管理 Azure Databricks 工作流程。請參閱什麼是 Databricks Asset Bundles？

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

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

套件組合範本會定義將建立之套件組合的目錄結構，並包含 databricks.yml.tmpl 設定檔範本，以及包含使用者提示變數的 databricks_template_schema.json 檔案。

使用預設套件組合範本

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

databricks bundle init default-python

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

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

範本	描述
`default-python`	搭配 Databricks 使用 Python 的範本。此範本會建立工作和 Delta Live Tables 管線的套件組合。請參閱 default-python。
`default-sql`	搭配 Databricks 使用 SQL 的範本。此範本包含設定檔，定義在 SQL 倉儲上執行 SQL 查詢的工作。請參閱 default-sql。
`dbt-sql`	利用 dbt 核心進行本機開發，並利用套件組合進行部署的範本。此範本包含定義具有 dbt 任務的工作的設定，以及定義已部署 dbt 工作的 dbt 設定檔的設定檔。請參閱 dbt-sql。
`mlops-stacks`	用於啟動新的 MLOps Stacks 專案的進階完整堆疊範本。請參閱 mlops-stacks 和適用於 MLOps Stack 的 Databricks Asset Bundles。

使用自訂套件組合範本

若要使用 Azure Databricks 預設套件組合範本以外的套件組合範本，請將模板的本機路徑或遠端 URL 傳送至 Databricks CLI bundle init 指令。

例如，下列命令會使用自訂套件組合範本教學課程中建立的 dab-container-template 範本：

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

建立自訂套件組件範本

套件組合範本會使用 Go 套件範本化語法。請參閱 Go 套件範本文件。

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

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

您可以選擇性地將子資料夾和檔案新增至您想要在範本所建立套件組合中進行鏡像的 template 資料夾。

定義使用者提示變數

建置基本套件組合範本的第一個步驟是在專案根目錄中建立範本專案資料夾，以及名為 databricks_template_schema.json 的檔案。此檔案包含使用者在使用範本透過 bundle init 建立套件組合時，所提供的輸入值變數。此檔案的格式遵循 JSON 結構描述規格。

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

將下列程式碼加入 databricks_template_schema.json 檔案，然後儲存該檔案：

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

在這個檔案中：

project_name 是唯一的輸入變數名稱。
如果使用者未在 bundle init 命令中透過 --config-file 提供值，或使用者在命令提示字元中覆寫該值，則 default 是可選預設值。
如果使用者未在 --config-file 命令中透過 bundle init 提供值，則 description 是與輸入變數關聯的使用者提示。
如果使用者未在 bundle init 命令中透過 order 提供值，則 --config-file 是每個使用者提示顯示的可選順序。如果未提供 order，則使用者提示會依結構描述中所列的順序顯示。
success_message 是選擇性訊息，會在成功建立專案時顯示。

建置資料夾結構

接下來，建立所需的 template 資料夾，並在其中建置資料夾結構。此結構將會由使用此範本建立的套件組合進行鏡像。此外，請將想要包含的任何檔案放入這些資料夾中。這個基本套件組合範本會將檔案儲存在 src 資料夾中，並且包含一個簡單的筆記本。

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

將下列內容新增至 simple_notebook.ipynb 檔案中：

print("Hello World!")

填入設定範本檔案

現在，在 template 資料夾中建立必要的 databricks.yml.tmpl 檔案：

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

使用基本組態範本 YAML 來填入此檔案。此組態範本會建立套件組合名稱、使用指定筆記本檔案的一個工作，以及使用此範本建立的套件組合的兩個目標環境。它還利用了套件組合替代項目，這是強烈建議的。請參閱套件組合替代項目。

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

測試套件組合範本

最後，測試您的範本。建立新的套件組合專案資料夾，然後使用 Databricks CLI 藉助範本初始化新的套件組合：

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

對於提示 What is your bundle project name?，輸入 my_test_bundle。

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

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

而 databricks.yml 檔案現已自訂：

# 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

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

提示

您可以將 databricks_template_schema.json 檔案放在相對於套件組合根目錄的不同資料夾中。然後，您可以使用 bundle init 命令的 --template-dir 選項來參考包含 databricks_template_schema.json 檔案的該資料夾。

下一步

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

分享方式：

Databricks Asset Bundle 專案範本

使用預設套件組合範本

使用自訂套件組合範本

建立自訂套件組件範本

定義使用者提示變數

建置資料夾結構

填入設定範本檔案

測試套件組合範本

下一步

意見反映

更多資源

分享方式：

Databricks Asset Bundle 專案範本

使用預設套件組合範本

使用自訂套件組合範本

建立自訂套件組件範本

定義使用者提示變數

建置資料夾結構

填入設定範本檔案

測試套件組合範本

共用範本

下一步

意見反映

更多資源