从 dbx 迁移到捆绑包

项目
09/02/2024

重要

Databricks 建议使用 Databricks 资产捆绑包，而不是使用 Databricks Labs 的 dbx。有关dbx的相关文章已停用，可能不会更新。

本文介绍如何将 Databricks Labs dbx 的项目迁移到 Databricks 资产捆绑包。请参阅 Databricks Labs 的 dbx 简介和什么是 Databricks 资产捆绑包？。

在迁移之前，请注意 Databricks Labs 的 dbx 与 Databricks 资产捆绑包之间的以下限制和功能比较。

限制

Databricks Labs 的 dbx 中受支持的以下功能受到限制、不存在或者需要 Databricks 资产捆绑包中的解决方法。

捆绑包不支持生成 JAR 项目。
捆绑包不支持工作区路径的 FUSE 表示法（例如，/Workspace/<path>/<filename>）。但是，可以使用表示法（例如，/Workspace/${bundle.file_path}/<filename>）指示捆绑包在部署期间生成 FUSE 样式的工作区路径。

功能比较

在迁移之前，请注意 Databricks Labs dbx 的以下功能如何在 Databricks 资产捆绑包中实现。

模板和项目

dbx为Jinja 模板化提供支持。可以在部署配置中包含 Jinja 模板，并通过内联或变量文件传递环境变量。虽然不建议这样做，但dbx还提供对自定义用户函数的实验性支持。

捆绑包支持Go 模板进行配置重用。用户可以基于预生成的模板创建捆绑包。除了自定义用户函数之外，模板几乎完全相同。

生成管理

dbx通过pip wheel、Poetry 和 Flit 提供生成支持。用户可以在项目 deployment.yml 文件的 build 部分中指定生成选项。

捆绑包使用户能够生成、部署和运行 Python 滚轮文件。用户可以利用捆绑包 databricks.yml 文件中的内置 whl 条目。

同步、部署和运行代码

dbx使上传代码与生成 Azure Databricks 作业等工作区资源分开。

捆绑包始终上传代码并同时创建或更新工作区资源。这简化了部署，并避免了正在进行的作业的阻塞情况。

将 dbx 项目迁移到捆绑包

在注意到 Databricks Labs 的 dbx 与 Databricks 资产捆绑包之间的上述限制和功能比较之后，即可从 dbx 迁移到捆绑包。

Databricks 建议开始 dbx 项目迁移，请将项目 dbx 保留在其原始文件夹中，并确保提供一个单独的空白文件夹，以将原始 dbx 项目的内容复制到其中。此单独的文件夹将是新的捆绑包。如果在原始文件夹中开始将dbx项目转换为捆绑包，然后犯了一些错误或想要从头开始，可能会遇到意外问题。

步骤 1：安装和设置 Databricks CLI

Databricks 资产捆绑在 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 个人访问令牌身份验证。有关其他 Databricks 身份验证类型，请参阅Databricks CLI 身份验证。

步骤 2：创建捆绑包配置文件

如果使用支持 YAML 文件和 JSON 架构文件的 IDE（如 Visual Studio Code、PyCharm Professional 或 IntelliJ IDEA Ultimate），则使用 IDE 不仅可以创建程序包配置文件，还可以检查文件语法和格式，并提供代码补全提示，如下所示。

Visual Studio Code

将 YAML 语言服务器支持添加到 Visual Studio Code，例如，通过从 Visual Studio Code Marketplace 安装 YAML 扩展。
使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 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 资产捆绑包配置 JSON 架构文件位于不同的路径中，请将 bundle_config_schema.json 替换为架构文件的完整路径。
使用之前添加的 YAML 语言服务器功能。有关详细信息，请参阅 YAML 语言服务器的文档。

PyCharm 专业版

使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。例如，在当前目录中生成名为bundle_config_schema.json的文件，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
配置 PyCharm 以识别捆绑包配置 JSON 架构文件，然后按照“配置自定义 JSON 架构”中的说明完成 JSON 架构映射。
使用 PyCharm 创建或打开捆绑包配置文件。按照约定，此文件命名为 databricks.yml。键入时，PyCharm 会检查 JSON 架构语法和格式，并提供代码补全提示。

IntelliJ IDEA Ultimate

使用 Databricks CLI 运行 bundle schema 命令并将输出重定向到 JSON 文件，生成 Databricks 资产捆绑包配置 JSON 架构文件。例如，在当前目录中生成名为bundle_config_schema.json的文件，如下所示：
```
databricks bundle schema > bundle_config_schema.json
```
配置 IntelliJ IDEA 以识别捆绑包配置 JSON 架构文件，然后按照“配置自定义 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 作业、增量实时表管道或 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 资产捆绑包和 GitHub Actions 运行 CI/CD 工作流。

将 dbx 项目设置转换为 databricks.yml

对于 dbx，项目设置默认位于项目 .dbx 文件夹中名为 project.json 的文件中。请参阅项目文件参考。

对于捆绑包，捆绑配置默认位于捆绑包根文件夹中名为 databricks.yml 的文件中。请参阅 Databricks 资产捆绑包配置。

对于包含以下示例内容的conf/project.json文件：

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Shared/dbx/charming_aurora",
        "artifact_location": "/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

databricks.yml文件中不支持conf/project.json文件中的以下其他允许对象，这些对象没有解决方法：

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 资产捆绑包配置。

对于包含以下示例内容的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"