如何通过VS Code与databricks.yml生成部署版本化Wheel包至Databricks集群

核心思路 #

利用Databricks Bundles的资源部署能力，仅通过databricks.yml定义要上传的Wheel包资源，结合本地Python打包工具生成带版本号的Wheel，最后通过Bundles命令完成上传，全程无需创建任何工作流或任务。

步骤1：整理项目结构 #

确保你的Python项目具备以下基础结构：

your-project/
├── src/
│   └── your_package/       # 你的代码包
│       ├── __init__.py
│       └── ...
├── pyproject.toml          # 打包配置（推荐）或 setup.py
└── databricks.yml          # Databricks Bundles配置

步骤2：配置打包文件（生成带版本号的Wheel） #

用pyproject.toml定义包信息和版本号，支持两种版本管理方式：

方式1：固定版本

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "your-package"
version = "1.0.0"  # 手动指定版本号
authors = [{"name" = "Your Name", "email" = "your@email.com"}]
description = "Your package description"

方式2：自动生成版本（基于Git标签）

如果想通过Git标签自动同步版本，添加setuptools-scm依赖实现动态版本：

[build-system]
requires = ["setuptools>=61.0", "setuptools-scm>=7.0"]
build-backend = "setuptools.build_meta"

[project]
name = "your-package"
dynamic = ["version"]
authors = [{"name" = "Your Name", "email" = "your@email.com"}]
description = "Your package description"

[tool.setuptools_scm]
root = "."
relative_to = __file__

步骤3：编写databricks.yml配置 #

只定义Library资源，不包含任何任务/工作流：

bundle:
  name: your-package-bundle

resources:
  libraries:
    your_package_wheel:
      wheel:
        # 用通配符匹配本地生成的带版本号的Wheel文件
        path: "./dist/your_package-*.whl"
        # 指定上传到Databricks工作区的固定路径（可选，默认存临时库）
        workspace_path: "/Shared/libraries/your_package"

注：path中的*会自动匹配dist/目录下生成的任意版本Wheel，无需手动修改版本号。

步骤4：本地生成Wheel并上传到Databricks #

在VS Code终端执行以下命令：

1. 生成Wheel文件：

python -m build --wheel

执行后dist/目录会生成类似your_package-1.0.0-py3-none-any.whl的带版本号文件。

2. 用Databricks Bundles上传Wheel：

databricks bundle deploy

该命令仅完成资源上传，不会创建任何工作流或任务。

步骤5：在Notebook中导入使用 #

上传完成后，在Databricks Notebook中按以下步骤使用：

1. 安装Wheel到集群（二选一）：
   • 通过集群UI的「库」页面，选择工作区路径下的Wheel文件添加
   • 在Notebook中运行代码安装：

     dbutils.library.install("/Shared/libraries/your_package/your_package-1.0.0-py3-none-any.whl")
     dbutils.library.restartPython()  # 重启Python环境生效
     

2. 导入并验证：

import your_package
print(your_package.__version__)  # 确认版本号正确

内容的提问来源于stack exchange，提问作者question.it