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

本页介绍如何使用 Databricks 资产捆绑包生成、部署和运行 Python 滚轮文件。请参阅什么是 Databricks 资产捆绑包？。

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

要求

已安装 Databricks CLI 版本 0.218.0 或更高版本，并配置身份验证。若要检查安装的 Databricks CLI 版本，请运行命令 databricks -v。要安装 Databricks CLI，请参阅《安装或更新 Databricks CLI》。若要配置身份验证，请参阅 “配置对工作区的访问权限”。
需要 uv 才能运行测试和从 IDE 安装此项目的依赖项。
远程工作区必须启用工作区文件。请参阅什么是工作区文件？。
现有目录。若要创建目录，请参阅 “创建目录”。

使用模板创建捆绑包

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

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

步骤 1：创建捆绑包

捆绑包包含要部署的资产和要运行的工作流的设置。

使用终端或命令提示符切换到本地开发计算机上的目录，该目录中包含模板生成的捆绑。
使用 Databricks CLI 版本运行 bundle init 命令：
```
databricks bundle init
```
对于 Template to use，请按 default-python 保留 Enter 的默认值。
对于 Unique name for this project，请保留 my_project 的默认值，或键入其他值，然后按 Enter。这将确定此捆绑包的根目录的名称。此根目录是在当前工作目录中创建的。
对于“Include a job that runs a notebook”，选择“no”并按“Enter”。这会指示 Databricks CLI 不要向捆绑包添加示例笔记本。
对于“Include an ETL pipeline”，选择“no”并按“Enter”。这指示 Databricks CLI 在捆绑包中不定义示例管道。
对于 Include a stub (sample) Python package，请按 yes 保留 Enter 的默认值。这会指示 Databricks CLI 向捆绑包添加示例 Python wheel 包文件和相关的生成说明。
对于“Use serverless”，选择“yes”并按“Enter”。这会指示 Databricks CLI 将捆绑包配置为在无服务器计算上运行。
对于 Default catalog for any tables created by this project [hive_metastore]，请输入现有 Unity 目录目录的名称。
对于 Use a personal schema for each user working on this project.，请选择 yes。

步骤 2：探索组件包

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

databricks.yml：此文件指定捆绑包的名称，包括对捆绑包文件的引用、指定 whl 生成设置、定义目录和架构变量，以及指定目标工作区的设置。
resources/sample_job.job.yml：此文件指定 Python 滚轮作业的设置。有关作业设置的信息，请参阅作业。
src/：此文件夹包括 Python wheel 作业用于生成 Python wheel 文件的文件。
tests/：此文件夹包含示例单元测试。
README.md：此文件包含有关入门和使用此捆绑模板的其他信息。

注意

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

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

步骤 3：验证捆绑包配置

现在检查捆绑配置是否有效。

在根目录中，使用 Databricks CLI 运行以下命令 bundle validate ：
```
databricks bundle validate
```
如果返回了捆绑包配置的摘要，则表示验证成功。如果返回了任何错误，请修复错误，然后重复此步骤。

步骤 4：将捆绑包部署到远程工作区

接下来，将捆绑包部署到远程 Azure Databricks 工作区。这会生成 Python 滚轮文件。验证是否在您的工作区中创建了 Azure Databricks 作业。

在捆绑根目录下，使用 Databricks CLI 运行以下命令 bundle deploy ：
```
databricks bundle deploy --target dev
```
确认已部署本地生成的 Python wheel 文件：
1. 在 Azure Databricks 工作区的边栏中，单击“ 工作区”。
2. 单击进入以下文件夹：“工作区”>“用户”><your-username>>“.bundle”><project-name>>“开发”>“项目”>“.internal”><whl-file-name>.whl。
Python wheel 文件应位于此文件夹中。
检查是否已创建作业：
1. 在 Azure Databricks 工作区的边栏中，单击作业和管道。
2. （可选）选择作业和归我所有筛选器。
3. 单击 [dev <your-username>] sample_job。
4. 单击“ 任务 ”选项卡。应该有一个 python_wheel_task。

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

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

现在，在工作区中触发 Azure Databricks 作业的运行。

在根目录中，使用 Databricks CLI 运行以下命令 bundle run ：
```
databricks bundle run --target dev sample_job
```
复制终端中显示的 Run URL 值，并将该值粘贴到 Web 浏览器中以打开 Azure Databricks 工作区。
在 Azure Databricks 工作区中，任务成功完成并显示绿色标题栏后，单击作业任务以查看结果。

使用诗歌或 setuptools 生成 whl

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

安装诗歌或 setuptools

安装诗歌或 setuptools：

诗歌
- 安装 Poetry 1.6 或更高版本（如果尚未安装）。若要检查已安装的 Poetry 版本，请运行命令 poetry -V 或 poetry --version。
- 确保已安装 Python 3.10 或更高版本。若要检查 Python 版本，请运行命令 python -V 或 python --version。
Setuptools

wheel运行以下命令，安装这些和setuptools包（如果尚未安装）：
```
pip3 install --upgrade wheel setuptools
```
如果打算将此捆绑包与 Git 提供程序一起存储，请在项目的根目录中添加一个 .gitignore 文件，并将以下条目添加到此文件中：

诗歌
```
.databricks
dist
```
Setuptools
```
.databricks
build
dist
src/my_package/my_package.egg-info
```

添加生成文件

在程序包的根目录中，创建以下文件夹和文件，具体取决于是使用 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

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

添加项目捆绑包配置

将artifacts映射配置添加到生成databricks.ymlwhl项目：

诗歌

此配置运行 poetry build 命令，并指示文件的路径 pyproject.toml 与该文件位于同一目录中 databricks.yml 。

注意

如果已生成 Python wheel 文件并只想部署该文件，请通过省略 artifacts 映射来修改以下捆绑配置文件。然后，Databricks CLI 将假定已生成 Python 滚轮文件，并自动部署数组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>

反馈

此页面是否有帮助？

Last updated on 2025-11-15

通过

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

要求

使用模板创建捆绑包

步骤 1：创建捆绑包

步骤 2：探索组件包

步骤 3：验证捆绑包配置

步骤 4：将捆绑包部署到远程工作区

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

使用诗歌或 setuptools 生成 whl

安装诗歌或 setuptools

诗歌

Setuptools

诗歌

Setuptools

添加生成文件

诗歌

Setuptools

Pyproject.toml

Setup.py

添加项目捆绑包配置

诗歌

Setuptools

反馈

其他资源