使用 Databricks 資產套件組合建置 Python 轉輪檔案

本頁說明如何使用 Databricks 資產套件組合建置、部署及執行 Python 輪盤檔案。 請參閱 什麼是 Databricks 資產套件組合？。

如需建置 JAR 並將其上傳至 Unity 目錄的範例組態，請參閱 將 JAR 檔案上傳至 Unity 目錄的配套。

Requirements

• 已安裝 Databricks CLI 0.218.0 版或更新版本，並設定驗證。 若要檢查您已安裝的 Databricks CLI 版本，請執行命令 databricks -v。 若要安裝 Databricks CLI，請參閱 安裝或更新 Databricks CLI。 若要設定驗證，請參閱 設定工作區的存取權。
• uv 是從 IDE 執行測試和安裝此專案依賴項所需的。
• 遠端工作區必須啟用工作區文件功能。 請參閱 什麼是工作區檔案？。
• 現有的目錄。 若要建立目錄，請參閱 建立目錄。

使用範本建立套件組合

使用 Python 的 Databricks 資產套件組合預設 套件組合範本來建立套件組合。 此套件組合包含要建置至 Python 轉輪檔案的檔案，以及用來建置此 Python 轉輪檔案的 Azure Databricks 作業定義。 然後，您在 Azure Databricks 工作區中，從 Python 輪子作業驗證、部署並將已部署的檔案建置為 Python 輪子檔案。

如果您想要從頭開始建立套件組合，請參閱手動建立套件組合。

步驟 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 job that runs a notebook，選取 no 並按 Enter。 這會指示 Databricks CLI 不要將範例筆記本新增至您的套件組合。

6. 針對 Include an ETL pipeline，選取 no 並按 Enter。 這會指示 Databricks CLI 不要在套件組合中定義範例管線。

7. 按下 Include a stub (sample) Python package，在 yes 中保留 Enter 的預設值。 這會指示 Databricks CLI 將範例 Python 轉輪套件檔案和相關組建指示新增至套件組合。

8. 針對 Use serverless，選取 yes 並按 Enter。 這會指示 Databricks CLI 將套件組合設定為在無伺服器計算上執行。

9. 針對 Default catalog for any tables created by this project [hive_metastore]，輸入現有 Unity 目錄目錄的名稱。

10. 針對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 滾輪工作用來建置 Python 滾輪檔案的檔案。
• tests/：此資料夾包含範例單元測試。
• README.md：此檔案包含有關開始使用和使用此套件範本的其他資訊。

# 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：將套件組合部署至遠端工作區

接下來，將套件組合部署至遠端 Azure Databricks 工作區。 這會建置 Python 輪檔。 確認已在您的工作區內建立 Azure Databricks 作業。

1. 從套件組合根目錄中，使用 Databricks CLI 來執行命令 bundle deploy ：

   databricks bundle deploy --target dev
   

2. 確認已部署本機建置的 Python 輪檔：

   1. 在 Azure Databricks 工作區的側邊欄中，按一下 [工作區]。
   2. 點選下列資料夾： 工作區 > 使用者 ><your-username>> .bundle ><project-name>> 開發檔案 > 物件 > .internal ><whl-file-name>.whl。

   Python 轉輪檔案應該在此資料夾中。

3. 檢查任務是否已成功建立：

   1. 在 Azure Databricks 工作區的側邊欄中，點擊 作業和管線。
   2. 或者，選取 [作業] 和 [我所擁有的] 篩選器。
   3. 點選 [dev <your-username>] sample_job。
   4. 按一下 任務 標籤。應該有一個 python_wheel_task。

如果您在此步驟之後對套件組合進行任何變更，請重複步驟 3-4 來檢查您的套件組合組態是否仍然有效，然後重新部署專案。

步驟 5：執行已部署的專案

現在，在您的工作區中觸發 Azure Databricks 作業的執行。

1. 從根目錄，使用 Databricks CLI 來執行命令 bundle run ：

   databricks bundle run --target dev sample_job
   

2. 複製終端機中顯示的 Run URL 的值，並將此值貼到您的網頁瀏覽器中，以開啟您的 Azure Databricks 工作區。

3. 在 Azure Databricks 工作區中，工作成功完成並顯示綠色標題列之後，按一下作業工作以查看結果。

使用 Poetry 或 setuptools 生成 whl

當您使用 default-python 範本與 databricks bundle init 時，會建立一個套件組合，示範如何使用 uv 和 pyproject.toml 來設定並建置一個 Python 套件輪子的組合。 不過，您可能想要使用詩歌，或 setuptools 改為建置方向盤。

安裝詩歌或安裝工具

1. 安裝 Poetry 或 setuptools：

   Poetry

   • 安裝 Poetry 1.6 版或更高版本（如果尚未安裝）。 若要檢查已安裝的 Poetry 版本，請執行 命令 poetry -V 或 poetry --version。
   • 請確定您已安裝 Python 3.10 版或更新版本。 若要檢查 Python 的版本，請執行 命令 python -V 或 python --version。

   Setuptools

   如果尚未安裝 wheel 和 setuptools 套件，請執行下列命令來安裝它們：

   pip3 install --upgrade wheel setuptools
   

2. 如果您想要將此套件包儲存到 Git 提供者，請在專案的根目錄建立一個 .gitignore 檔案，並將下列條目新增至此檔案：

   Poetry

   .databricks
   dist
   

   Setuptools

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

新增組建檔案

1. 在套件組合的根目錄中，根據您是否使用 Poetry 或 setuptools 建置 Python 轉輪檔案，建立下列資料夾和檔案：

   Poetry

   ├── 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.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 檔案的顯示描述。

新增工件包組態

1. 將 artifacts 對應配置新增到 databricks.yml 中，以建置 whl 工件：

   Poetry

   此組態會執行 poetry build 命令，並指出 pyproject.toml 檔案的路徑與 databricks.yml 檔案位於同一個目錄中。

   Note

   如果您已經建置 Python 輪檔並只想要部署它，請修改下列套件組合組態檔，省略 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>