共用方式為

使用 Databricks 资产捆绑生成 Python 滚轮文件

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

有关生成 JAR 并将其上传到 Unity 目录的示例配置,请参阅将 JAR 文件上传到 Unity 目录 捆绑包。

要求

使用模板创建捆绑包

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

注意

适用于 Python 的 Azure Databricks 默认捆绑模板使用 uv 生成 Python wheel 文件。 若要安装 uv,请参阅 安装 uv

如果要从头开始创建 捆绑包,请参阅手动创建捆绑包

步骤 1:创建捆绑包

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

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

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

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

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

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

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

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

步骤 2:探索组件包

若要查看模板生成的文件,请切换到新创建的捆绑包的根目录,并使用首选 IDE 打开此目录。 特别感兴趣的文件包括:

  • databricks.yml:此文件指定捆绑包的名称,指定 whl 生成设置,包括对作业配置文件的引用,并定义目标工作区的设置。
  • 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

步骤 3:验证项目的捆绑配置文件

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

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

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

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

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

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

  1. 使用 Databricks CLI 运行以下命令 bundle deploy ,如下所示:

    databricks bundle deploy -t dev
    
  2. 检查本地生成的 Python wheel 文件是否已部署:

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

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

  3. 检查作业是否已创建:

    1. 在 Azure Databricks 工作区的边栏中,单击作业和管道
    2. (可选)选择作业归我所有筛选器。
    3. 单击 [dev <your-username>] <project-name>_job
    4. 单击“任务”选项卡。

    应该有一个任务:main_task

如果在此步骤后对捆绑包进行任何更改,请重复步骤 3-4,检查捆绑包配置是否仍然有效,然后重新部署项目。

步骤 5:运行已部署的项目

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

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

    databricks bundle run -t dev <project-name>_job
    
  2. 复制终端中显示的 Run URL 值,并将该值粘贴到 Web 浏览器中以打开 Azure Databricks 工作区。

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

使用诗歌或 setuptools 生成 whl

与默认 Python 模板一起使用 databricks bundle init 时,将创建一个捆绑包,演示如何配置使用 uvpyproject.toml生成 Python 滚轮的捆绑包。 但是,你可能想要使用诗歌,或者 setuptools 改用轮子。

安装诗歌或 setuptools

  1. 安装诗歌或 setuptools

    诗歌

    • 安装 Poetry 1.6 或更高版本(如果尚未安装)。 若要检查已安装的 Poetry 版本,请运行命令 poetry -Vpoetry --version
    • 确保已安装 Python 3.10 或更高版本。 若要检查 Python 版本,请运行命令 python -Vpython --version

    Setuptools

    wheel运行以下命令,安装这些和setuptools包(如果尚未安装):

    pip3 install --upgrade wheel setuptools
    
  2. 如果计划将此捆绑包与 Git 提供程序存储在一起,请在项目的根目录中添加 .gitignore 文件,并向此文件添加以下条目:

    诗歌

    .databricks
    dist
    

    Setuptools

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

添加生成文件

  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. 将以下代码添加到 pyproject.tomlsetup.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 文件的显示说明。

添加项目捆绑包配置

  1. artifacts映射配置添加到生成databricks.ymlwhl项目:

    诗歌

    此配置运行 poetry build 命令,并指示文件的路径 pyproject.toml 与该文件位于同一目录中 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

    此配置运行 setuptools 命令,并指示文件的路径 setup.py 与该文件位于同一目录中 databricks.yml

    bundle:
      name: my-wheel-bundle
    
    artifacts:
      default:
        type: whl
        build: python3 setup.py bdist wheel
        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>