本文介绍如何在 Databricks 资产捆绑包项目中生成、部署和运行 Python wheel 文件。 请参阅什么是 Databricks 资产捆绑包?。
有关生成 JAR 并将其上传到 Unity 目录的示例配置,请参阅将 JAR 文件上传到 Unity 目录 的捆绑包。
要求
- 已安装 Databricks CLI 版本 0.218.0 或更高版本,并配置身份验证。 若要检查安装的 Databricks CLI 版本,请运行命令
databricks -v
。 要安装 Databricks CLI,请参阅《安装或更新 Databricks CLI》。 若要配置身份验证,请参阅 “配置对工作区的访问权限”。 - 远程工作区必须启用工作区文件。 请参阅什么是工作区文件?。
使用模板创建捆绑包
在这些步骤中,将使用适用于 Python 的 Azure 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 stub (sample) notebook
”,选择“no
”并按“Enter
”。 这会指示 Databricks CLI 不要向捆绑包添加示例笔记本。对于“
Include a stub (sample) Delta Live Tables pipeline
”,选择“no
”并按“Enter
”。 这指示 Databricks CLI 在捆绑包中不定义示例管道。对于
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:验证项目的捆绑配置文件
在此步骤中,检查捆绑包配置是否有效。
在根目录中,使用 Databricks CLI 运行
bundle validate
命令,如下所示:databricks bundle validate
如果返回了捆绑包配置的摘要,则表示验证成功。 如果返回了任何错误,请修复错误,然后重复此步骤。
如果在此步骤之后对捆绑包进行任何更改,则应重复此步骤以检查捆绑包配置是否仍然有效。
步骤 4:生成 Python wheel 文件并将本地项目部署到远程工作区
在此步骤中,Python wheel 文件生成并部署到远程 Azure Databricks 工作区,并在工作区中创建 Azure Databricks 作业。
使用 Databricks CLI 运行以下命令
bundle deploy
,如下所示:databricks bundle deploy -t dev
检查本地生成的 Python wheel 文件是否已部署:
- 在 Azure Databricks 工作区的边栏中,单击“工作区”。
- 单击进入以下文件夹:“工作区 > 用户 >
<your-username>
> .bundle ><project-name>
> dev > artifacts > .internal ><random-guid>
”。
Python wheel 文件应位于此文件夹中。
检查作业是否已创建:
- 在 Azure Databricks 工作区的边栏中,单击作业和管道。
- (可选)选择作业和归我所有筛选器。
- 单击 [dev
<your-username>
]<project-name>
_job。 - 单击“任务”选项卡。
应该有一个任务:main_task。
如果在此步骤后对捆绑包进行任何更改,请重复步骤 3-4,检查捆绑包配置是否仍然有效,然后重新部署项目。
步骤 5:运行已部署的项目
此步骤在工作区中运行 Azure Databricks 作业。
在根目录中,使用 Databricks CLI 运行
bundle run
命令,如下所示,替换为<project-name>
步骤 1 中项目的名称:databricks bundle run -t dev <project-name>_job
复制终端中显示的
Run URL
值,并将该值粘贴到 Web 浏览器中以打开 Azure Databricks 工作区。在 Azure Databricks 工作区中,任务成功完成并显示绿色标题栏后,请单击 main_task 任务以查看结果。
使用诗歌或 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
-
安装 Poetry 1.6 或更高版本(如果尚未安装)。 若要检查已安装的 Poetry 版本,请运行命令
如果计划将此捆绑包与 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.yml
whl
项目:诗歌
此配置运行
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>