從 dbx 移轉至套件組合

發行項
10/09/2024

重要

Databricks 建議您使用 Databricks Asset Bundles，而不是 Databricks Labs 的 dbx。相關 dbx 文章已停用，可能不再更新。

本文說明如何將 Databricks Labs 的 dbx 專案移轉至 Databricks Asset Bundles。請參閱 Databricks Labs 的 dbx 簡介和什麼是 Databricks Asset Bundles？。

在移轉之前，請注意 Databricks Labs 的 dbx 與 Databricks Asset Bundles 之間的下列限制和功能比較。

限制

Databricks Labs 的 dbx 支援的下列功能受限、不存在或需要 Databricks Asset Bundles 中的因應措施。

套件組合中不支援建置 JAR 成品。
套件組合中不支援工作區路徑的 FUSE 標記法 (例如 /Workspace/<path>/<filename>)。不過，您可以使用 /Workspace/${bundle.file_path}/<filename> 等標記法，指示套件組合在部署期間產生 FUSE 樣式的工作區路徑。

功能比較

在移轉之前，請注意 Databricks Labs 在 Databricks Asset Bundles 中如何實作 dbx 的下列功能。

範本和專案

dbx提供 Jinja 範本化的支援。您可以在部署組態中包含 Jinja 範本，並透過內嵌或透過變數檔案，傳遞環境變數。雖然不建議，但 dbx 也提供自訂使用者函式的實驗性支援。

套件組合提供對 Go 範本的支援，以供設定重複使用。使用者可以根據預先建置的範本建立套件組合。範本化幾乎完全同位，但自訂使用者函式除外。

建置管理

dbx 透過 pip wheel、Poetry 和 Flit 提供組建支援。使用者可以在專案的 build 檔案的 deployment.yml 區段中指定建置選項。

套件組合可讓使用者建置、部署及執行 Python Wheel 檔案。使用者可以利用套件組合的 databricks.yml 檔案中的內建 whl 項目。

同步、部署和執行程式碼

dbx 可讓您單獨上傳程式碼，並產生工作區資源，如 Azure Databricks 工作。

套件組合一律同時上傳程式碼並建立或更新工作區資源。這可簡化部署，並避免進行中工作的封鎖條件。

將 dbx 專案移轉至套件組合

當您記下 Databricks Labs 的 dbx 與 Databricks Asset Bundles 之間的上述限制和功能比較之後，您就可以從 dbx 移轉至套件組合。

Databricks 建議您開始 dbx 專案移轉，請將 dbx 專案保留在其原始資料夾中，而且您有一個單獨、空白的資料夾，可讓您將原始的 dbx 專案內容複製到其中。這個單獨的資料夾將會是您新的套件組合。如果您在原始資料夾中開始將 dbx 專案轉換成套件組合，然後犯了一些錯誤或想要從頭開始，可能會遇到非預期的問題。

步驟 1：安裝並設定 Databricks CLI

Databricks Asset Bundles 一般可在 Databricks CLI 0.218.0 版和更新版本中取得。如果您已安裝並設定 Databricks CLI 0.218.0 版或更新版本，請直接跳至步驟 2。

注意

套件組合與 Databricks CLI 0.18 版及以下版本不相容。

安裝或更新至 Databricks CLI 0.218.0 版或更新版本。請參閱安裝或更新 Databricks CLI。
設定 Databricks CLI 以向目標 Azure Databricks 工作區進行驗證，例如使用 Azure Databricks 個人存取權杖驗證。若對於其他 Azure Databricks 驗證類型，請參閱 Databricks CLI 的驗證。

步驟 2：建立套件組合設定檔

如果您使用 Visual Studio Code、PyCharm Professional 或 IntelliJ IDEA Ultimate 等 IDE 來支援 YAML 檔案和 JSON 結構描述檔案，您不僅可以使用 IDE 來建立套件組合設定檔，還可以檢查檔案的語法和格式，並提供程式碼完成提示，如下所示。

Visual Studio Code

將 YAML 語言伺服器支援新增至 Visual Studio Code，例如從 Visual Studio Code 市集安裝 YAML 延伸項目。
使用 Databricks CLI 產生 Databricks Asset Bundle 組態 JSON 結構描述檔案，以執行 bundle schema 命令，並將輸出重新導向轉接至 JSON 檔案。例如，在目前的目錄中產生名為 bundle_config_schema.json 的檔案，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
使用 Visual Studio Code 在目前的目錄中建立或開啟套件組合設定檔。依照慣例，此檔案的名稱為 databricks.yml。
將下列註解新增至套件組合設定檔的開頭：
```
# yaml-language-server: $schema=bundle_config_schema.json
```
注意

在上述註解中，如果您的 Databricks Asset Bundle 組態 JSON 結構描述檔案位於不同的路徑，請將 bundle_config_schema.json 取代為結構描述檔案的完整路徑。
使用您之前新增的 YAML 語言伺服器功能。如需詳細資訊，請參閱您的 YAML 語言伺服器文件。

PyCharm Professional

使用 Databricks CLI 產生 Databricks Asset Bundle 組態 JSON 結構描述檔案，以執行 bundle schema 命令，並將輸出重新導向轉接至 JSON 檔案。例如，在目前的目錄中產生名為 bundle_config_schema.json 的檔案，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
依照設定自訂 JSON 結構描述中的指示，設定 PyCharm 以辨識套件組合設定 JSON 結構描述檔案，然後完成 JSON 結構描述對應。
使用 PyCharm 建立或開啟套件組合設定檔。依照慣例，此檔案的名稱為 databricks.yml。當您輸入時，PyCharm 會檢查 JSON 結構描述語法和格式，並提供程式碼完成提示。

IntelliJ IDEA Ultimate

使用 Databricks CLI 產生 Databricks Asset Bundle 組態 JSON 結構描述檔案，以執行 bundle schema 命令，並將輸出重新導向轉接至 JSON 檔案。例如，在目前的目錄中產生名為 bundle_config_schema.json 的檔案，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
依照設定自訂 JSON 結構描述中的指示，設定 IntelliJ IDEA 以辨識套件組合設定 JSON 結構描述檔案，然後完成 JSON 結構描述對應。
使用 IntelliJ IDEA 建立或開啟套件組合設定檔。依照慣例，此檔案的名稱為 databricks.yml。當您輸入時，IntelliJ IDEA 會檢查 JSON 結構描述語法和格式，並提供程式碼完成提示。

步驟 3：將 dbx 專案設定轉換為 databricks.yml

將 dbx 專案 .dbx/project.json 檔案中的設定轉換為套件組合 databricks.yml 檔案中的對等設定。如需詳細資訊，請參閱將 dbx 專案設定轉換成 databricks.yml。

步驟 4：將 dbx 部署設定轉換為 databricks.yml

將 dbx 專案 conf 資料夾中的設定轉換為套件組合 databricks.yml 檔案中的對等設定。如需詳細資訊，請參閱將 dbx 部署設定轉換成 databricks.yml。

步驟 5：驗證套件組合

部署成品或執行 Azure Databricks 工作、Delta Live Tables 管線或 MLOps 管線之前，應該確定套件組合設定檔語法正確無誤。為此，請從套件組合根目錄執行 bundle validate 命令：

databricks bundle validate

如需 bundle validate 的相關資訊，請參閱驗證套件組合。

步驟 6：部署套件組合

若要將任何指定的本機成品部署至遠端工作區，請從套件組合根目錄執行 bundle deploy 命令。如果未指定任何命令選項，則使用套件組合設定檔內宣告的預設目標：

databricks bundle deploy

若要在特定目標的內容中部署成品，請指定 -t (或 --target) 選項，並將目標的名稱指定為套件組合設定檔內宣告的名稱。例如，對於使用名稱 development 宣告的目標：

databricks bundle deploy -t development

如需 bundle deploy 的相關資訊，請參閱部署套件組合。

提示

您可以將套件組合定義的工作和管線連結至 Azure Databricks 工作區中的現有工作和管線，使其保持同步。請參閱繫結套件組合資源。

步驟 7：執行套件組合

若要執行特定工作或管線，請從套件組合根目錄執行 bundle run 命令。您必須指定套件組合設定檔內宣告的工作或管線。如果未指定 -t 選項，則會使用套件組合設定檔內宣告的預設目標。例如，若要在預設目標的內容內執行名為 hello_job 的工作：

databricks bundle run hello_job

若要在以名稱 development 宣告的目標內容中執行名為 hello_job 工作：

databricks bundle run -t development hello_job

如需的相關信息 bundle run，請參閱執行作業或管線。

(選擇性) 步驟 8：使用 GitHub 設定 CI/CD 的套件組合

如果您使用 GitHub 進行 CI/CD，可以使用 GitHub Actions 來根據特定的 GitHub 工作流程事件和其他準則自動執行 databricks bundle deploy 和 databricks bundle run 命令。請參閱使用 Databricks Asset Bundles 和 GitHub Actions 執行 CI/CD 工作流程。

將 dbx 專案設定轉換為 databricks.yml

針對 dbx，專案設定預設位於專案的 .dbx 資料夾中名為 project.json 的檔案中。請參閱專案檔參考。

對於套件組合，套件組合設定預設位於套件組合根資料夾內名為 databricks.yml 的檔案中。請參閱 Databricks Asset Bundle 組態。

對於含有下列範例內容的 conf/project.json 檔案：

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

對應的 databricks.yml 檔案如下所示：

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

此範例先前 conf/project.json 檔案中的下列物件在 databricks.yml 檔案中不受支援，而且沒有因應措施：

inplace_jinja_support
storage_type

conf/project.json 檔案中下列其他允許的物件在 databricks.yml 檔案中不受支援，而且沒有因應措施：

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

將 dbx 部署設定轉換為 databricks.yml

針對 dbx，部署設定預設位於專案的 conf 資料夾的檔案中。請參閱部署檔案參考。根據預設，部署設定檔案具有下列其中一個檔案名稱：

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

對於套件組合，部署設定預設位於套件組合根資料夾內名為 databricks.yml 的檔案中。請參閱 Databricks Asset Bundle 組態。

對於含有下列範例內容的 conf/deployment.yml 檔案：

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"