本頁說明如何為筆記本和工作任務配置無伺服器環境。 對於標準無伺服器筆記本,請使用 環境 側窗格選擇基礎環境、安裝筆記本範圍的相依關係、設定記憶體及套用使用政策。 對於工作任務,建立或編輯任務時要設定環境。
使用 Shared Serverless 時,筆記本與同一 Git 資料夾或套件中的檔案會使用由專案根目錄中的 pyproject.toml 檔案管理的環境,而非筆記本範圍的相依清單。 請參閱 管理共享無伺服器環境。
要展開 環境 側窗格,請點擊筆記本右側的
按鈕。
選擇基地環境
基礎環境決定了你的無伺服器筆記本預先安裝的函式庫和環境版本。 在環境側窗格的基礎環境選擇器是你選擇環境的地方。 若要查看每個環境版本的詳細數據,請參閱 無伺服器環境版本。 Databricks 建議使用最新版本,以獲得最新的筆記本功能。
基礎環境選擇器包含以下選項:
- 標準:預設無伺服器基礎環境,使用 Databricks 提供的函式庫。
- 機器學習:一個基礎環境,預裝了 Databricks Runtime for 機器學習 的 Python 與系統套件。 利用此環境將經典的 Databricks 執行環境(用於 機器學習 工作負載)遷移到無伺服器運算。 請參見 機器學習基礎環境。
- AI:一個由 AI 優化的基礎環境,內建機器學習(ML)函式庫。 此選項僅在選擇加速器(GPU)時出現。 參見 AI 環境。
-
更多:展開以顯示其他選項。
- 標準、機器學習與人工智慧環境的先前版本。
- 自訂:使用 YAML 檔案指定自訂環境。
- 工作空間環境:列出管理員為你的工作空間設定的所有相容基礎環境。
選擇基地環境:
- 在筆記本介面中,點選側邊窗格中的 環境
。 - 在 基礎環境下,從下拉選單選擇一個環境。
- 按一下 套用。
將相依性新增至筆記本
由於無伺服器不支援運算策略或初始化指令碼,因此你必須使用 環境 側邊窗格來安裝自訂相依性。 你可以個別安裝相依性,或使用可共用的基礎環境一次安裝多個相依性。
Azure Databricks 會快取你的筆記本虛擬環境,因此每次重新開啟筆記本或在閒置後繼續使用時,都不需要重新安裝相依性。 共用相同相依性集合的工作任務,在同一次執行期間也能受益於此快取。
若要個別安裝相依性:
在筆記本介面中,點選側邊窗格中的 環境
。在 相依性 區段中,於欄位中輸入相依性的路徑,然後按一下 +新增相依性。 您可以在任何格式中指定相依性,只要該格式在requirements.txt檔案中有效。 Python輪子檔案或Python專案(例如包含
pyproject.toml或setup.py的目錄)可以位於工作區檔案或 Unity 目錄卷中。- 如果使用工作區檔案,路徑應該是絕對路徑,並以
/Workspace/開頭。 - 如果在 Unity 目錄磁碟區中使用檔案,路徑的格式應如下:
/Volumes/<catalog>/<schema>/<volume>/<path>.whl。
- 如果使用工作區檔案,路徑應該是絕對路徑,並以
點擊 Apply 以安裝相依套件並重新啟動 Python 程序。
Important
請勿在無伺服器筆記本上安裝 PySpark 或任何將 PySpark 作為相依性安裝的函式庫。 這樣做會停止您的連線並產生錯誤訊息。 如果發生這種情況,請移除程式庫,並 重設您的環境。
要查看已安裝的相依性,請點擊環境側窗格中的「已安裝」標籤。 點擊窗格底部的 pip logs 來開啟筆記本環境的 pip 安裝日誌。
Note
無伺服器運算並不保證特定的 CPU 架構。 筆記本或工作可以在任一aarch64x86_64或 上執行,且架構可在執行間改變。 因為相依可能安裝在與原架構不同的架構上,你的相依必須支援運算可能使用的每一種架構。
如果某個相依項目是帶有原生(C)擴充功能的 Python wheel 套件,其預先建置的二進位檔會因架構而異。 為一種架構設計的輪子無法安裝到另一個架構,導致錯誤。 為避免此問題,盡量使用純 Python 輪子(標記 py3-none-any),或同時包含 aarch64 和 x86_64 輪子變體,並用platform_machine環境標記限制每個輪子的架構。
Note
Azure Databricks 會在你的筆記本或任務程式碼執行前解決並安裝相依關係。 筆記本儲存格中的程式碼無法改變相依關係的擷取方式。 無伺服器計算也不支援計算範圍的環境變數,因此執行時套用代理設定不會影響相依安裝。 若要從私有或認證套件儲存庫安裝,請在相依規範中指定 index-url 或 extra-index-url 安裝。 你也可以請工作區管理員將該儲存庫設定為預設的套件儲存庫。 請參見 「配置預設套件庫」。
設定預設套件倉庫
Workspace 管理員可以設定私有或認證套件庫作為無伺服器筆記本和作業的預設 PIP 來源。 這讓使用者可以從內部儲存庫安裝套件,而無需指定 index-url 或 extra-index-url。 請參見 「配置預設套件庫」。
建立自訂環境規格
您可以建立及重複使用自訂環境規格。
- 在無伺服器筆記本中,選擇基礎環境並安裝你想要的相依關係。
- 點選 Kebab 選單按鈕,在環境面板底部點擊
然後點 選「匯出環境」。
- 將規格儲存為工作區檔案或 Unity 目錄磁碟區中。 請確認你對目的地具有寫入權限,否則匯出會因
Forbidden錯誤而失敗。
要在筆記本中使用自訂環境規格,請從基礎環境下拉選單選擇自訂,然後使用資料夾你的 YAML 檔案。
建立共用工具,讓你在工作空間中共享
此範例將一個工具存放在工作區檔案中,並以無伺服器筆記本相依安裝:
使用下列結構建立資料夾。 請確保其他使用者已取得此路徑的閱讀權限:
helper_utils/ ├── helpers/ │ └── __init__.py # your common functions live here ├── pyproject.toml將
pyproject.toml填入如下:[project] name = "common_utils" version = "0.1.0"將函式新增至
init.py檔案。 例如:def greet(name: str) -> str: return f"Hello, {name}!"在筆記本介面中,按一下Environment側邊窗格
在 [ 相依性] 區段中,按兩下 [ 新增相依性 ],然後輸入 util 檔案的路徑。 例如:
/Workspace/helper_utils。按一下 套用。
您現已可以在筆記本中使用函數:
from helpers import greet
print(greet('world'))
這會輸出為:
Hello, world!
使用 AI 執行環境(無伺服器 GPU)
Important
這項功能目前處於 公開預覽版。
請依照以下步驟在你的 Azure Databricks 筆記本上配置由無伺服器 GPU 運算驅動的 AI 執行環境:
- 從筆記型電腦中點選頂部的計算下拉選單,選擇 無伺服器 GPU。
- 點擊
以開啟 環境 側窗格。
- 從 [加速器] 欄位選取 [A10]。
- 在 基礎環境中,選擇預設環境為 標準 ,或為預裝機器學習(ML)函式庫的 AI 優化環境選擇 AI 。
- 點 選「套用 」,然後 確認 你想將 AI 執行環境套用到你的筆記本環境。
更多細節請參見 AI 執行時。
使用高記憶體無伺服器計算
Important
這項功能目前處於 公開預覽版。
如果你的筆記本遇到記憶體不足錯誤,請設定筆記本使用較大的記憶體容量。 此記憶體大小設定會增加執行筆記本程式碼時所使用的 REPL 記憶體容量。 它不會影響 Spark 會話的記憶體大小。 具有高記憶體的無伺服器使用量具有比標準記憶體更高的 DBU 排放率。
可用的記憶體選項包括:
- 標準配置:總記憶體 16 GB。
- 最高:總記憶體 32 GB。
要設定筆記本的記憶體設定:
- 在筆記本介面中,點選側邊窗格中的 環境
。 - 在 [記憶體] 下,選取 [高記憶體]。
- 按一下 套用。
此記憶體設定同樣適用於使用筆記本記憶體偏好執行的筆記本工作任務。 更新筆記本中的記憶體喜好設定會影響下一個作業執行。
選擇無伺服器使用政策
Important
這項功能目前處於 公開預覽版。
無伺服器使用政策 允許您的組織在無伺服器使用時套用自訂標籤,以實現細緻的帳單歸屬。
如果你的工作空間使用無伺服器使用政策,請選擇你想套用在筆記本上的政策。 如果使用者只被指派一個無伺服器使用政策,該政策預設適用。
連接無伺服器運算後,請從 環境 側面板選擇一項政策:
- 在筆記本介面中,點選側邊窗格中的 環境
。 - 在 無伺服器使用政策 中,選擇你想套用到筆記本的無伺服器使用政策。
- 按一下 套用。
套用後,所有筆記本使用都會自動取得該政策的自訂標籤。
Note
如果你的筆記本來自 Git 倉庫,或沒有指定的 無伺服器使用政策,下一次連接到無伺服器運算時,它會預設使用你最後選擇的無伺服器使用政策。
在原始檔案匯出中包含環境
針對 Python 筆記本,你可以在環境設定中切換 在匯出原始檔時包含。 啟用後,基礎環境與相依性會以 PEP 723 格式儲存在原始檔案匯出中。 這有助於在筆記本儲存在 Git 資料夾 中或下載為 原始檔 時保留環境設定。
例如,使用 Standard v5 的筆記本會將其環境設定匯出為檔案頂端的內嵌元資料:
# Databricks notebook source
# /// script
# [tool.databricks.environment]
# environment_version = "5"
# ///
print("Hello World!")
重設環境相依性
如果您的筆記本連線到無伺服器計算,Databricks 會自動快取筆記本虛擬環境的內容。 這表示,當您開啟現有的筆記本時,通常不需要重新安裝Environment側邊窗格中指定的 Python 相依套件,即使筆記本已因閒置而中斷連線。
Python 虛擬環境快取也適用於工作。 當工作執行時,任何在同一執行中與已完成任務擁有相同相依性集合的任務會更快完成,因為快取已經包含所需的相依性。
Note
如果你更改了在無伺服器作業中使用的自訂 Python 套件實作,也必須更新其版本號,讓工作能取得最新的實作。
要清除環境快取並重新安裝連接到無伺服器運算的筆記本 環境側面板 中指定的相依關係,請點擊「 套用 」旁邊的箭頭,然後點 選「重置為預設」。
如果您安裝了中斷或變更核心筆記本或 Apache Spark 環境的套件,請移除有問題的套件,然後重新設置環境。 啟動新工作階段不會清除整個環境快取。
設定工作工作的環境
每個工作任務都運行在一個獨立的環境中,包含一個基礎環境以及你指定的額外函式庫。 基礎環境設定 Python 與 Scala 執行時版本及預裝函式庫。 任務繼承了環境版本預設的已安裝函式庫集合。 若要查看包含哪些內容,請參閱你所使用的 環境版本中的 已安裝的 Python 程式庫 或 已安裝的 Java 和 Scala 程式庫章節。
你可以用 工作空間檔案、Unity 目錄 卷或公開套件庫的函式庫來補充預裝的函式庫。 僅會在執行階段安裝任務所需的相依性。
若要配置筆記pyproject.toml本、Python 腳本或 Python wheel 任務,請參見「使用 pyproject.toml 配置專案環境」。
要將環境變數傳給你的任務中的應用程式程式碼,請參見 「為無伺服器工作配置環境變數」。
Important
選擇受管理基地環境仍處於測試階段。 在「配置環境」對話框中的基礎環境下拉選單,讓你可以從 Databricks 提供的環境(如標準和機器學習)或工作區配置的環境中選擇。 若未啟用此功能,對話框會改為顯示 Environment version 下拉式選單。 Workspace 管理員可從 預覽 頁面啟用此功能。
依任務類型配置環境
你在工作中如何設定環境取決於任務類型:
筆記本任務
筆記本任務預設為 筆記本環境,該環境使用筆記本自身設定的基礎環境與相依關係。 你可以用工作層級的環境來覆蓋這個問題。
若要設定作業層級的環境:
- 在任務設定中,點選環境 與函式庫 下拉選單。
- 在 工作環境中,點擊 預設旁邊的鉛筆圖示,或點選 + 新增工作環境。
- 在「配置環境」對話框中,於「環境來源」下,選擇「標準」或「專案」。 Project選項僅在您的工作區管理員從 Previews 頁面啟用 Project-Scoped 共享運算預覽時才可用。 請參閱 管理 Azure Databricks 預覽。 如果對話框中沒有顯示 環境來源,請依 照標準 步驟操作。
-
標準模式請從 基礎環境 下拉選單中選擇:
Databricks 環境 :Azure Databricks提供的選項如Standard 及 ML 。 - 工作區環境:由您的工作區管理員設定的自訂環境。 請參閱 管理工作空間基礎環境。
- 更多:舊版本與 自訂 (請指定 YAML 檔案)。
- 在 標準模式下,在 相依項下新增任何額外的函式庫。 請使用 requirements.txt 檔案中有效的任何格式。 你也可以使用絕對路徑指向工作區檔案或 Unity Catalog 磁碟區。
- 對於Project,在Project環境中,輸入工作區路徑至
pyproject.toml或選擇該檔案。 在pyproject.toml中設定環境版本與相依關係。 你無法同時設定 基礎環境 或 相依關係。 參見「使用pyproject.toml設定專案環境」。 - 按一下 [確認]。
Note
如果您的工作區沒有啟用工作區基礎環境預覽功能,配置 環境 對話框會顯示環境 版本 下拉選單,而非 基礎環境。
要設定環境,選擇版本,然後點擊 + 新增函式庫。 你可以指定工作區檔案路徑(以 /Workspace/ 開頭)、Unity Catalog 磁碟區路徑(以 /Volumes/ 開頭),或 requirements 檔案參照(例如 -r /Workspace/path/to/requirements.txt)。
Python 腳本與 Python 輪子任務
Python 指令碼和 Python wheel 工作都需要先設定環境。
- 在任務設定中,於 環境與函式庫中點選 + 新增相依性。
- 在「設定環境」對話方塊中,於「環境來源」下方,選取「標準」或「專案」。 Project選項僅在您的工作區管理員從Previews頁面啟用 Project-Scoped 共享運算預覽時才可用。 請參閱 管理 Azure Databricks 預覽。 如果對話框中沒有顯示 環境來源,請依 照標準 步驟操作。
- 對於 Standard,請從 基礎環境 下拉式選單中選擇:
Databricks 環境 :Azure Databricks提供的選項如Standard 及 ML 。 - 工作區環境:由您的工作區管理員設定的自訂環境。 請參閱 管理工作空間基礎環境。
- 更多:舊版本與 自訂 (請指定 YAML 檔案)。
- 在 標準模式下,在 相依項下新增任何額外的函式庫。
- 在Project中,在Project 環境中,輸入到
pyproject.toml的絕對工作區路徑(例如/Workspace/path/to/pyproject.toml),或選擇該檔案。 Python Wheel 任務不支援相對的專案-環境路徑。 在pyproject.toml中設定環境版本與相依關係。 你也無法設定 基礎環境 或 相依關係。 參見「使用pyproject.toml配置專案環境」。 - 按一下 [確認]。
Note
如果您的工作區沒有啟用工作區基礎環境預覽功能,配置 環境 對話框會顯示環境 版本 下拉選單,而非 基礎環境。
要設定環境,選擇版本,然後點擊 + 新增函式庫。 你可以指定工作區檔案路徑(以 /Workspace/ 開頭)、Unity Catalog 磁碟區路徑(以 /Volumes/ 開頭),或 requirements 檔案參照(例如 -r /Workspace/path/to/requirements.txt)。
DBT 任務
DBT 任務使用工作層級環境來進行函式庫設定。
若要設定作業層級的環境:
- 在任務設定中,點選環境 與函式庫 下拉選單。
- 在 工作環境中,點擊現有環境旁的鉛筆圖示,或點擊 + 新增工作環境。
- 在 「設定環境 」對話框中,從 基礎環境 下拉選單中選擇:
Databricks 環境 :Azure Databricks提供的選項如Standard 及 ML 。 - 工作區環境:由您的工作區管理員設定的自訂環境。 請參閱 管理工作空間基礎環境。
- 更多:舊版本與 自訂 (請指定 YAML 檔案)。
- 在 相依項中,新增任何額外的函式庫。 你可以使用 requirements.txt 檔案中任何有效的格式來指定函式庫,或使用工作區檔案或 Unity Catalog 磁碟區的絕對路徑。
- 按一下 [確認]。
Note
如果您的工作區沒有啟用工作區基礎環境預覽功能,配置 環境 對話框會顯示環境 版本 下拉選單,而非 基礎環境。
要設定環境,選擇版本,然後點擊 + 新增函式庫。 你可以指定工作區檔案路徑(以 /Workspace/ 開頭)、Unity Catalog 磁碟區路徑(以 /Volumes/ 開頭),或 requirements 檔案參照(例如 -r /Workspace/path/to/requirements.txt)。
JAR任務
工作區基層環境不支援 JAR 任務。 要設定 JAR 任務的環境:
- 在任務設定中,環境 與函式庫中點選 + 新增 JAR 相依。
- 在 「配置環境 」對話框中:
- 可選擇性地在 基礎環境 欄位輸入 YAML 檔案的路徑。
- 從環境版本下拉選單選擇環境版本。
- 在 JAR 相依關係中,將路徑加入你的 JAR 檔案。
- 按一下 [確認]。
若要建立基於 YAML 的自訂基礎環境,請參見 建立自訂環境規範。
環境與運算相容性
你選擇的基礎環境必須與任務的計算類型相容。 例如,為 GPU 運算打造的環境與 CPU 運算不相容。 在工作介面中,不相容的環境在基礎環境下拉式選單中無法使用。
當你設定筆記本任務時,計算類型(CPU 或 GPU)和基礎環境都可以來自工作設定或筆記本設定。
- 如果你在工作層級設定硬體加速器(GPU),你也必須在工作層級選擇一個基礎環境。 你無法將筆記本的環境與作業層級加速器一起使用。
- 如果你有工作任務會參考筆記本,且你更新了該筆記本的運算類型(例如從 CPU 到 GPU),現有任務可能會與其配置環境不相容。 更改筆記本的運算設定後,請檢查你的工作環境設定。
- 對於 API 使用者:如果您在作業層級設定基礎環境,但筆記本定義了運算類型,Azure Databricks 會在執行階段驗證相容性,而不是在建立作業時驗證。 若配置不相容,執行即以錯誤失敗。
使用 pyproject.toml 配置專案環境
Important
這項功能位於 測試版 (Beta) 中。 要使用此功能,工作空間管理員必須從 預覽 頁面開啟 Project-Scoped Shared Compute。 請參閱 管理 Azure Databricks 預覽。
專案環境會從 pyproject.toml 檔案設定無伺服器工作任務。 使用該檔案來宣告筆記本、Python 腳本和 Python wheel 任務的相依關係。 要選擇任務的專案環境,請參閱 「為工作任務配置環境」。
對於使用 Shared Serverless 的筆記本,請參閱 使用 pyproject.toml 管理環境。
Requirements
- 使用 無伺服器環境版本 5 及以上。
- 儲存
pyproject.toml在 工作區檔案中,例如/Workspace/path/to/pyproject.toml。 - 若要在
project_environment中使用,請使用 Databricks CLI 版本 1.21.0 及以上。 - 當你使用 Jobs API 或套件時,
project_environment必須是環境中spec唯一的環境來源欄位。 省略如environment_version、base_environment、dependencies等欄位。 請改在pyproject.toml中設定環境版本和相依性。
準備專案環境
要定義 pyproject.toml 檔案,請在 [project] 下宣告相依關係。 將無伺服器環境版本設為 [tool.databricks.environment]。 例如:
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
# Keep your other dependencies here.
"cowsay==6.1",
]
[tool.databricks.environment]
# Serverless environment version.
environment_version = "6"
對於僅安裝專案相依性的工作,若 uv.lock 缺失或已過時,執行時會退回到 uv pip install -r pyproject.toml。 此備援會從 pyproject.toml 解析相依性,且不強制執行鎖定版本,且不安裝專案套件本身。
若要將專案本身安裝為套件,請在 pyproject.toml 中加入建置後端。 例如,要使用 Hatchling,請加上以下內容:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
Hatchling 會從與專案名稱相符的來源目錄建立套件。 例如,對於 my-project,Hatchling 使用 src/my_project/__init__.py。 專案安裝需要在 pyproject.toml 旁放置最新的 uv.lock 檔案。 在專案目錄中產生該 uv lock 檔案。
若要確認 uv.lock 是否與 pyproject.toml 相符,請在專案目錄中的筆記本中執行以下指令:
%uv lock --check
在套件中配置專案環境
將 project_environment 設定為 pyproject.toml 的路徑。 在部署過程中,Databricks CLI 會將此路徑轉換成工作區路徑。
以下範例套件安裝了自己的套件 my-project。 它採用以下配置:
.
├── databricks.yml
├── pyproject.toml
├── uv.lock
├── resources/
│ └── my_project.job.yml
└── src/
├── main.py
└── my_project/
└── __init__.py
根 pyproject.toml 節點宣告了相依關係、Hatchling 建置後端以及環境版本:
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
"cowsay==6.1",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.databricks.environment]
environment_version = "6"
將以下配置儲存為 resources/my_project.job.yml。
project_environment和python_file路徑相對於此檔案而言:
resources:
jobs:
my_project_job:
name: my-project-job
environments:
- environment_key: project
spec:
project_environment: ../pyproject.toml
tasks:
- task_key: main
environment_key: project
spark_python_task:
python_file: ../src/main.py