通过

使用 Databricks 资产捆绑包开发 Python wheel 文件

  • 项目

本文介绍如何在 Databricks 资产捆绑包项目中生成、部署和运行 Python wheel 文件。 请参阅什么是 Databricks 资产捆绑包？

要求

  • Databricks CLI 版本 0.218.0 或更高版本。 若要检查安装的 Databricks CLI 版本，请运行命令 databricks -v。 要安装 Databricks CLI，请参阅《安装或更新 Databricks CLI》。
  • 远程工作区必须启用工作区文件。 请参阅什么是工作区文件？。

决策：手动或使用模板创建捆绑包

决定是要使用模板创建初学者捆绑包，还是手动创建捆绑包。 使用模板创建程序包更快速、更简单，但程序包可能会生成不需要的内容，并且程序包的默认设置必须针对实际应用程序进行进一步的自定义。 手动创建程序包可以完全控制程序包的设置，但必须熟悉程序包的工作方式，因为你需要从头开始执行所有工作。 选择以下一组步骤：

使用模板创建捆绑包

在这些步骤中，将使用适用于 Python 的 Azure Databricks 默认捆绑包模板创建捆绑包。 这些步骤将指导你创建一个包，其中包含要构建到 Python wheel 文件中的文件以及用于构建此 Python wheel 文件的 Azure Databricks 作业的定义。 然后，使用 Azure Databricks 工作区中的 Python Wheel 作业验证、部署部署的文件并将其构建到 Python Wheel 文件中。

适用于 Python 的 Azure Databricks 默认捆绑模板使用 setuptools 生成 Python wheel 文件。 若想使用 Poetry 来构建 Python wheel 文件，请按照本节后面的说明将 setuptools 实现替换为 Poetry 实现。

步骤 1：设置身份验证

若要详细了解如何设置身份验证，请参阅 Databricks 身份验证。

步骤 2：创建捆绑包

捆绑包中有要部署的工件以及要运行的工作流的设置。

  1. 使用终端或命令提示符切换到本地开发计算机上的目录，该目录中包含模板生成的捆绑。

  2. 使用 Databricks CLI 版本运行 bundle init 命令：

    databricks bundle init

  3. 对于 Template to use，请按 Enter 保留 default-python 的默认值。

  4. 对于 Unique name for this project，请保留 my_project 的默认值，或键入其他值，然后按 Enter。 这将确定此捆绑包的根目录的名称。 此根目录是在当前工作目录中创建的。

  5. 对于“Include a stub (sample) notebook”，选择“no”并按“Enter”。 这会指示 Databricks CLI 不要向捆绑包添加示例笔记本。

  6. 对于“Include a stub (sample) DLT pipeline”，选择“no”并按“Enter”。 这会指示 Databricks CLI 不要在捆绑包中定义示例 Delta Live Tables 管道。

  7. 对于 Include a stub (sample) Python package，请按 Enter 保留 yes 的默认值。 这会指示 Databricks CLI 向捆绑包添加示例 Python wheel 包文件和相关的生成说明。

步骤 3：浏览捆绑包

若要查看模板生成的文件，请切换到新创建的捆绑包的根目录，并使用首选 IDE（例如 Visual Studio Code）打开此目录。 特别感兴趣的文件包括：

  • databricks.yml：此文件指定捆绑包的编程名称，包括对 Python wheel 作业定义的引用，并指定有关目标工作区的设置。
  • resources/<project-name>_job.yml：此文件指定 Python wheel 作业的设置。
  • src/<project-name>：此目录包括 Python wheel 作业用于生成 Python wheel 文件的文件。

注意

如果要在安装了 Databricks Runtime 12.2 LTS 或更低版本的目标群集上安装 Python wheel 文件，则必须将以下顶级映射添加到 databricks.yml 文件：

# Applies to all tasks of type python_wheel_task.
experimental:
  python_wheel_wrapper: true

此映射指示 Databricks CLI 执行以下操作：

  • 在后台部署 Python wheel 文件的副本。 此部署路径通常为 ${workspace.artifact_path}/.internal/<random-id>/<wheel-filename>.whl。
  • 在后台创建一个笔记本，其中包含在目标群集上安装前面部署的 Python Wheel 文件的说明。 此笔记本的路径通常为 ${workspace.file_path}/.databricks/bundle/<target-name>/.internal/notebook_<job-name>_<task-key>。
  • 运行包含 Python Wheel 任务的作业，并且该任务引用前面的 Python Wheel 文件时，系统会在后台创建一个运行前面笔记本的作业。

无需为安装了 Databricks Runtime 13.1 或更高版本的目标群集指定此映射，因为 Azure Databricks 工作区文件系统中的 Python wheel 安装将自动安装在这些目标群集上。

步骤 4：更新项目的程序包以使用 Poetry

默认情况下，捆绑模板指定使用 setuptools 以及 setup.py 和 requirements-dev.txt 文件构建 Python wheel 文件。 如果想保持这些默认值，请跳到步骤 5：验证项目的程序包配置文件。

若要更新项目的程序包以使用 Poetry 而不是 setuptools，请确保本地开发计算机满足以下要求：

  • Poetry 1.6 或更高版本。 若要检查已安装的 Poetry 版本，请运行命令 poetry -V 或 poetry --version。 要安装或升级 Poetry，请参阅安装。
  • Python 3.10 或更高版本。 若要检查 Python 版本，请运行命令 python -V 或 python --version。
  • Databricks CLI 0.209.0 或更高版本。 若要检查 Databricks CLI 版本，请运行命令 databricks -v 或 databricks --version。 请参阅安装或更新 Databricks CLI。

对项目的程序包进行以下更改：

  1. 在程序包的根目录中，运行以下命令，指示 poetry 初始化 Poetry 的 Python wheel 生成：

    poetry init

  2. Poetry 显示多个需要完成的提示。 对于 Python wheel 生成，请回答以下提示，以匹配项目程序包中的相关默认设置：

    1. 对于 Package name，请在 /src 下键入子文件夹的名称，然后按 Enter。 这还应该是包的 name 值，该值在程序包的 setup.py 文件中定义。
    2. 对于 Version，请键入 0.0.1 并按 Enter。 这与程序包的 src/<project-name>/__init__.py 文件中定义的版本号匹配。
    3. 对于 Description，请键入 wheel file based on <project-name>/src（将 <project-name> 替换为项目的名称），然后按 Enter。 这与模板的 setup.py 文件中定义的 description 值匹配。
    4. 对于 Author，请按 Enter。 此默认值与模板的 setup.py 文件中定义的作者匹配。
    5. 对于 License，请按 Enter。 模板中没有定义许可证。
    6. 对于 Compatible Python versions，请输入与目标 Azure Databricks 群集上的版本匹配的 Python 版本（例如 ^3.10），然后按 Enter。
    7. 对于 Would you like to define your main dependencies interactively?，请键入 no 并按 Enter。 稍后将定义依赖项。
    8. 对于 Would you like to define your development dependencies interactively?，请键入 no 并按 Enter。 稍后将定义依赖项。
    9. 对于 Do you confirm generation?，请按 Enter。

  3. 完成提示后，Poetry 会将 pyproject.toml 文件添加到程序包的项目中。 有关 pyproject.toml 文件的信息，请参阅 pyproject.toml 文件。

  4. 从程序包的根目录中，指示 poetry 读取 pyproject.toml 文件、解析依赖项并安装它们、创建 poetry.lock 文件来锁定依赖项，最后创建虚拟环境。 为此，请运行以下命令：

    poetry install

  5. 在 pyproject.toml 文件末尾添加以下部分，将 <project-name> 替换为包含 src/<project-name>/main.py 文件的目录名称（例如 my_project）：

    [tool.poetry.scripts]
main = "<project-name>.main:main"

    该部分指定 Python wheel 作业的 Python wheel 入口点。

  6. 在程序包的 databricks.yml 文件顶层添加以下映射：

    artifacts:
  default:
    type: whl
    build: poetry build
    path: .

    此映射指示 Databricks CLI 使用 Poetry 生成 Python wheel 文件。

  7. 从捆绑包中删除 setup.py 和 requirements-dev.txt 文件，因为 Poetry 不需要它们。

步骤 5：验证项目的程序包配置文件

在此步骤中，检查捆绑包配置是否有效。

  1. 在根目录中，使用 Databricks CLI 运行 bundle validate 命令，如下所示：

    databricks bundle validate

  2. 如果返回了捆绑包配置的摘要，则表示验证成功。 如果返回了任何错误，请修复错误，然后重复此步骤。

如果在此步骤之后对捆绑包进行任何更改，则应重复此步骤以检查捆绑包配置是否仍然有效。

步骤 6：生成 Python wheel 文件并将本地项目部署到远程工作区

在此步骤中，你将生成 Python wheel 文件，将生成的 Python wheel 文件部署到远程 Azure Databricks 工作区，并在工作区中创建 Azure Databricks 作业。

  1. 如果使用 setuptools，请运行以下命令来安装 wheel 和 setuptools 包（如果尚未安装）：

    pip3 install --upgrade wheel setuptools

  2. 在 Visual Studio Code 终端中，使用 Databricks CLI 运行 bundle deploy 命令，如下所示：

    databricks bundle deploy -t dev

  3. 若要检查是否已部署本地生成的 Python wheel 文件，请执行以下操作：

    1. 在 Azure Databricks 工作区的边栏中，单击“工作区”。
    2. 单击进入以下文件夹：“工作区 > 用户 ><your-username>> .bundle ><project-name>> dev > artifacts > .internal ><random-guid>”。

    Python wheel 文件应位于此文件夹中。

  4. 如果要检查作业是否已创建：

    1. 在 Azure Databricks 工作区的边栏中，单击“工作流”。
    2. 在“作业”选项卡上，单击“[dev <your-username>] <project-name>_job”。
    3. 单击“任务”选项卡。

    应该有一个任务：main_task。

如果在此步骤之后对捆绑包进行了任何更改，则应重复步骤 5-6 以检查捆绑包配置是否仍然有效，然后重新部署项目。

步骤 7：运行部署的项目

此步骤在工作区中运行 Azure Databricks 作业。

  1. 在根目录中，使用 Databricks CLI 运行 bundle run 命令，如下所示，将 <project-name> 替换为步骤 2 中项目的名称：

    databricks bundle run -t dev <project-name>_job

  2. 复制终端中显示的 Run URL 值，并将该值粘贴到 Web 浏览器中以打开 Azure Databricks 工作区。

  3. 在 Azure Databricks 工作区中，任务成功完成并显示绿色标题栏后，请单击 main_task 任务以查看结果。

如果在此步骤之后对捆绑包进行了任何更改，则应重复步骤 5-7 以检查捆绑包配置是否仍然有效，重新部署项目，然后运行重新部署的项目。

你已达到使用模板创建捆绑包的步骤的末尾。

手动创建捆绑包

在这些步骤中，从头开始手动创建捆绑包。 这些步骤会指导你创建一个包，其中包含要构建到 Python wheel 文件中的文件以及用于构建此 Python wheel 文件的 Databricks 作业的定义。 然后，使用 Databricks 工作区中的 Python Wheel 作业验证、部署部署的文件并将其构建到 Python Wheel 文件中。

这些步骤包括向 YAML 文件添加内容。 （可选）你可能想要使用一个集成开发环境 (IDE)，它可以在处理 YAML 文件时提供自动架构建议和操作。 以下步骤使用 Visual Studio Code 以及从 Visual Studio Code Marketplace 安装的 YAML 扩展。

以下步骤假定你已知道：

按照以下说明创建一个示例包，该包使用 Poetry 或 setuptools 构建 Python wheel 文件，部署 Python wheel 文件，然后运行部署的 Python wheel 文件。

如果已生成 Python wheel 文件且只想部署并运行该文件，请跳到步骤 3：创建程序包的配置文件，在程序包配置文件中指定 Python wheel 设置。

步骤 1：设置身份验证

若要详细了解如何设置身份验证，请参阅 Databricks 身份验证。

步骤 2：创建捆绑包

捆绑包中有要部署的工件以及要运行的工作流的设置。

  1. 在程序包的根目录中，创建以下文件夹和文件，具体取决于是使用 Poetry 还是 setuptools 来生成 Python wheel 文件：

    诗歌

    ├── src
│     └── my_package
│           ├── __init__.py
│           ├── main.py
│           └── my_module.py
└── pyproject.toml

    Setuptools

    ├── src
│     └── my_package
│           ├── __init__.py
│           ├── main.py
│           └── my_module.py
└── setup.py

  2. 将 __init__.py 文件留空。

  3. 在 main.py 文件中添加以下代码，然后保存文件：

    from my_package.my_module import *

def main():

  first = 200
  second = 400

  print(f"{first} + {second} = {add_two_numbers(first, second)}")
  print(f"{second} - {first} = {subtract_two_numbers(second, first)}")
  print(f"{first} * {second} = {multiply_two_numbers(first, second)}")
  print(f"{second} / {first} = {divide_two_numbers(second, first)}")

if __name__ == "__main__":
  main()

  4. 在 my_module.py 文件中添加以下代码，然后保存文件：

    def add_two_numbers(a, b):
  return a + b

def subtract_two_numbers(a, b):
  return a - b

def multiply_two_numbers(a, b):
  return a * b

def divide_two_numbers(a, b):
  return a / b

  5. 在 pyproject.toml 或 setup.py 文件中添加以下代码，然后保存文件：

    Pyproject.toml

    [tool.poetry]
name = "my_package"
version = "0.0.1"
description = "<my-package-description>"
authors = ["my-author-name <my-author-name>@<my-organization>"]

[tool.poetry.dependencies]
python = "^3.10"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry.scripts]
main = "my_package.main:main"
    • 将 my-author-name 替换为组织的主要联系人姓名。
    • 将 my-author-name>@<my-organization 替换为组织的主电子邮件地址。
    • 将 <my-package-description> 替换为 Python wheel 文件的显示说明。

    Setup.py

    from setuptools import setup, find_packages

import src

setup(
  name = "my_package",
  version = "0.0.1",
  author = "<my-author-name>",
  url = "https://<my-url>",
  author_email = "<my-author-name>@<my-organization>",
  description = "<my-package-description>",
  packages=find_packages(where='./src'),
  package_dir={'': 'src'},
  entry_points={
    "packages": [
      "main=my_package.main:main"
    ]
  },
  install_requires=[
    "setuptools"
  ]
)
    • 将 https://<my-url> 替换为组织的 URL。
    • 将 <my-author-name> 替换为组织的主要联系人姓名。
    • 将 <my-author-name>@<my-organization> 替换为组织的主电子邮件地址。
    • 将 <my-package-description> 替换为 Python wheel 文件的显示说明。

步骤 3：创建程序包的配置文件

捆绑包配置文件描述要部署的生成工件以及要运行的工作流。

  1. 在程序包的根目录中，添加名为 databricks.yml 的程序包配置文件。 将以下代码添加到此文件：

    诗歌

    注意

    如果已生成 Python wheel 文件并只想部署该文件，请通过省略 artifacts 映射来修改以下捆绑配置文件。 然后，Databricks CLI 将假定 Python Wheel 文件已构建就绪，并将自动部署在 libraries 数组的 whl 条目中指定的文件。

    bundle:
  name: my-wheel-bundle

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

resources:
  jobs:
    wheel-job:
      name: wheel-job
      tasks:
        - task_key: wheel-task
          new_cluster:
            spark_version: 13.3.x-scala2.12
            node_type_id: Standard_DS3_v2
            data_security_mode: USER_ISOLATION
            num_workers: 1
          python_wheel_task:
            entry_point: main
            package_name: my_package
          libraries:
            - whl: ./dist/*.whl

targets:
  dev:
    workspace:
    host: <workspace-url>

    Setuptools

    bundle:
  name: my-wheel-bundle

resources:
  jobs:
    wheel-job:
      name: wheel-job
      tasks:
        - task_key: wheel-task
          new_cluster:
            spark_version: 13.3.x-scala2.12
            node_type_id: Standard_DS3_v2
            data_security_mode: USER_ISOLATION
            num_workers: 1
          python_wheel_task:
            entry_point: main
            package_name: my_package
          libraries:
            - whl: ./dist/*.whl

targets:
  dev:
    workspace:
    host: <workspace-url>

    将 <workspace-url> 替换为每工作区 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn。

    使用 Poetry 构建 Python wheel 文件时，artifacts 映射为必要项；而使用 setuptools 构建 Python wheel 文件时，该映射为可选项。 artifacts 映射包含具有以下映射的一个或多个生成工件定义：

    • type 映射必须存在并设置为 whl 以指定要构建 Python wheel 文件。 对于 setuptools，如果未指定项目工件定义，则 whl 为默认值。
    • 对于 Poetry，path 映射指示 pyproject.toml 文件的路径；对于 setuptools，则指示 setup.py 文件的路径。 此路径是相对于 databricks.yml 文件的路径。 对于 setuptools，此路径默认为 .（与 databricks.yml 文件位于同一目录）。
    • build 映射会指示自定义构建命令，可通过运行这些命令以构建 Python wheel 文件。 对于 setuptools，此命令默认为 python3 setup.py bdist wheel。
    • files 映射由一个或多个 source 映射组成，这些映射指定要包含在 Python wheel 生成中的任何附加文件。 没有默认值。

    注意

    如果要在安装了 Databricks Runtime 12.2 LTS 或更低版本的目标群集上安装 Python wheel 文件，则必须将以下顶级映射添加到 databricks.yml 文件：

    # Applies to jobs with python_wheel_task and that use
# clusters with Databricks Runtime 13.0 or below installed.
experimental:
  python_wheel_wrapper: true

    此映射指示 Databricks CLI 执行以下操作：

    • 在后台部署 Python wheel 文件的副本。 此部署路径通常为 ${workspace.artifact_path}/.internal/<random-id>/<wheel-filename>.whl。
    • 在后台创建一个笔记本，其中包含在目标群集上安装前面部署的 Python Wheel 文件的说明。 此笔记本的路径通常为 ${workspace.file_path}/.databricks/bundle/<target-name>/.internal/notebook_<job-name>_<task-key>。
    • 运行包含 Python Wheel 任务的作业，并且该任务引用前面的 Python Wheel 文件时，系统会在后台创建一个运行前面笔记本的作业。

    无需为安装了 Databricks Runtime 13.1 或更高版本的目标群集指定此映射，因为 Azure Databricks 工作区文件系统中的 Python wheel 安装将自动安装在这些目标群集上。

  2. 如果使用 Poetry，请执行以下操作：

    • 安装 Poetry 1.6 或更高版本（如果尚未安装）。 若要检查已安装的 Poetry 版本，请运行命令 poetry -V 或 poetry --version。
    • 确保已安装 Python 3.10 或更高版本。 若要检查 Python 版本，请运行命令 python -V 或 python --version。
    • 安装 Databricks CLI 0.209.0 或更高版本。 若要检查 Databricks CLI 版本，请运行命令 databricks -v 或 databricks --version。 请参阅安装或更新 Databricks CLI。

  3. 如果使用 setuptools，请运行以下命令来安装 wheel 和 setuptools 包（如果尚未安装）：

    pip3 install --upgrade wheel setuptools

  4. 如果计划将此捆绑包与 Git 提供程序存储在一起，请在项目的根目录中添加 .gitignore 文件，并向此文件添加以下条目：

    诗歌

    .databricks
dist

    Setuptools

    .databricks
build
dist
src/my_package/my_package.egg-info

步骤 4：验证项目的程序包配置文件

在此步骤中，检查捆绑包配置是否有效。

  1. 在根目录中，验证捆绑包配置文件：

    databricks bundle validate

  2. 如果返回了捆绑包配置的摘要，则表示验证成功。 如果返回了任何错误，请修复错误，然后重复此步骤。

如果在此步骤之后对捆绑包进行任何更改，则应重复此步骤以检查捆绑包配置是否仍然有效。

步骤 5：生成 Python wheel 文件并将本地项目部署到远程工作区

在本地构建 Python wheel 文件，将构建的 Python wheel 文件部署到工作区，将笔记本部署到工作区，并在工作区中创建作业：

databricks bundle deploy -t dev

步骤 6：运行部署的项目

  1. 运行已部署的作业，该作业使用已部署的笔记本调用部署的 Python wheel 文件：

    databricks bundle run -t dev wheel-job

  2. 在输出中，复制 Run URL 并将其粘贴到 Web 浏览器的地址栏中。

  3. 在作业运行的“输出”页中，将显示以下结果：

    200 + 400 = 600
400 - 200 = 200
200 * 400 = 80000
400 / 200 = 2.0

如果在此步骤之后对捆绑包进行了任何更改，则应重复步骤 3-5 以检查捆绑包配置是否仍然有效，重新部署项目，然后运行重新部署的项目。

为作业生成并安装 Python wheel 文件

要使用 Poetry 或 setuptools 构建 Python wheel 文件，然后在作业中使用该 Python wheel 文件，必须向 databricks.yml 文件添加一或两个映射。

如果使用 Poetry，则必须在 databricks.yml 文件中包含以下 artifacts 映射。 此映射运行 poetry build 命令，并使用与 databricks.yml 文件位于同一目录的 pyproject.toml 文件：

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

注意

artifacts 映射对于 setuptools是可选的。 默认情况下，对于 setuptools，Databricks CLI 运行 python3 setup.py bdist_wheel 命令，并使用与 databricks.yml 文件位于同一目录中的 setup.py 文件。 Databricks CLI 假定你已经运行了一个命令（例如 pip3 install --upgrade wheel setuptools）来安装 wheel 和 setuptools 包（如果尚未安装）。

此外，作业任务的 libraries 映射必须包含一个 whl 值，该值指定相对于声明它的配置文件的生成 Python wheel 文件的路径。 以下示例在笔记本任务中展示此内容（省略号表示省略内容，以示简洁）：

resources:
  jobs:
    my-notebook-job:
      name: my-notebook-job
      tasks:
        - task_key: my-notebook-job-notebook-task
          notebook_task:
            notebook_path: ./my_notebook.py
          libraries:
            - whl: ./dist/*.whl
          new_cluster:
            # ...

为管道生成并安装 Python wheel 文件

若要使用 Poetry 或 setuptools 构建 Python wheel 文件，然后在 Delta Live Tables 管道中引用该 Python wheel 文件，则必须将映射添加到 databricks.yml 文件（前提是使用 Poetry），并且必须向管道笔记本添加 %pip install 命令，如下所示。

如果使用 Poetry，则必须在 databricks.yml 文件中包含以下 artifacts 映射。 此映射运行 poetry build 命令，并使用与 databricks.yml 文件位于同一目录的 pyproject.toml 文件：

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

注意

artifacts 映射对于 setuptools是可选的。 默认情况下，对于 setuptools，Databricks CLI 运行 python3 setup.py bdist_wheel 命令，并使用与 databricks.yml 文件位于同一目录中的 setup.py 文件。 Databricks CLI 假定你已经运行了一个命令（例如 pip3 install --upgrade wheel setuptools）来安装 wheel 和 setuptools 包（如果尚未安装）。

此外，相关的管道笔记本必须包含 %pip install 命令来安装构建的 Python Wheel 文件。 请参阅 Python 库。