Azure Databricks Git 資料夾限制與參考

本頁涵蓋 Databricks Git 資料夾的大小限制、支援功能、安全考量及 CI/CD 行為。 關於一般 Databricks 資源限制，請參見 資源限制。 欲了解 Git 資料夾中支援的資產類型，請參閱 Git 資料夾中支援的資產類型。

檔案和存放庫限制

Azure Databricks 不會強制執行儲存庫大小限制。 然而，以下限制適用：

  • 工作分支的容量限制為 1 GB。
  • 你無法在 Azure Databricks 介面中查看超過 10 MB 的檔案。
  • 每個 Git 操作最多支援 2 GB 記憶體和 4 GB 磁碟寫入。
  • 每個工作區檔案都有獨立的大小限制。 請參閱限制。

Databricks 建議將工作空間資產與檔案總數控制在 20,000 個以下。

因為每次操作都有限制，克隆 5 GB 儲存庫會失敗，但克隆 3 GB 儲存庫並後續增加 2 GB 則成功。 若儲存庫超過這些限制，複製過程中可能會收到錯誤或逾時，但操作仍可能在背景完成。

要處理較大的倉庫，可以試試 sparse checkout 或 Git CLI 指令。 要寫入叢集關閉後不會持續存在的暫存檔案，請使用 $TEMPDIR。 此方法避免超過分支大小限制，且比寫入工作目錄（CWD）在工作區檔案系統中提供更好的效能。 請參見 我應該在哪裡寫入 Azure Databricks 的暫存檔？。

本地分支在遠端分支刪除後，仍可在相關的 Git 資料夾中保留長達 30 天。 若要完全移除本地分支，請刪除儲存庫。

縮減儲存庫大小

如果你的儲存庫因檔案大小超過限制，加入 .gitignore 檔案並不會減少儲存庫大小。 已提交到 Git 的檔案即使加入 .gitignore，仍會留在倉庫歷史中。

為了減少儲存庫大小：

  • 使用 Git 工具如 git filter-repo BFG Repo-Cleaner 來移除提交歷史中的大型檔案。 這會重寫歷史，並需要強制推送到遠端儲存庫。
  • 只複製特定的目錄。 請參見「設定稀疏簽出模式」。
  • 將無關程式碼移到不同的倉庫。

更多資訊請參閱GitHub文件中的從儲存庫移除敏感資料。

Monorepo 支持

Databricks 建議不要建立由 monorepo 支援的 Git 資料夾——大型、單一組織的 Git 倉庫，涵蓋多個專案中數千個檔案。 複製 monorepo 可能會超過 Git 資料夾的記憶體和磁碟限制，並導致 Git 操作變慢。 如果你的倉庫包含多個專案，可以考慮拆分或使用 sparse checkout，限制哪些目錄被複製。 請參見「設定稀疏簽出模式」。

配置

並非所有標準 Git 功能都能在 Git 資料夾中運作，且內容的儲存方式與本地克隆不同。 以下主題將說明儲存空間的運作機制、哪些伺服器受支援，以及像 .gitignore 和子模組這類特性的行為。

儲存庫內容儲存

Azure Databricks 會暫時將儲存庫內容複製到控制平面的磁碟。 控制層面資料庫會儲存類似主工作區裡的筆記本檔案。 非筆記本檔案最多會儲存在磁碟上 30 天。

本地部署與自架 Git 伺服器

Databricks Git 資料夾支援 GitHub Enterprise、Bitbucket Server、Azure DevOps Server，以及在伺服器可以被網際網路存取的情況下支援 GitLab Self-managed。 請參閱 供 Git 資料夾使用的 Git 代理伺服器 以進行本地整合。

若要與無法透過網路存取的 Bitbucket Server、GitHub Enterprise Server 或 GitLab 自管理實例整合，請聯絡您的 Azure Databricks 帳號團隊。

支援的資產類型

有關支援資產類型的詳細資訊，請參閱 Git 資料夾中的支援資產類型。

.gitignore 檔案支援

Git 資料夾支援 .gitignore 檔案。 為了防止 Git 追蹤檔案，請在檔案中加入檔名（包括副檔名）。.gitignore 你可以建立一個，或是使用從遠端儲存庫複製的現有檔案。

.gitignore 只適用於未追蹤的檔案。 新增已提交的檔案 .gitignore 不會從 Git 歷史紀錄中移除或減少儲存庫大小。 若要移除已提交的檔案，請參見 「縮減儲存庫大小」。

Git 子模組支援

標準 Git 資料夾不支援 Git 子模組，但有 Git CLI 存取權限的 Git 資料夾可以使用它們。 請參見 使用 Git CLI 指令。

Azure Data Factory 支援

Azure Data Factory （ADF） 支援 Git 資料夾。

來源管理

有些操作在 Git 資料夾中與標準 Git 工作流程不同，特別是關於筆記本和分支刪除。

筆記本儀表板與分支變更

Azure Databricks 原始格式的筆記本不會保存儀表板資訊。

為了保留儀表板，請將筆記本格式改為 .ipynb （Jupyter 格式），預設支援儀表板與視覺化定義。 為了保留視覺化資料，請將筆記本與輸出一起提交。

請參見管理 IPYNB 記事本輸出提交。

分支合併支援

Git 資料夾支援分支合併。 您也可以建立拉取請求，並透過您的 Git 提供者進行合併。

刪除分支

若要刪除分支，則必須在 Git 提供者中工作。

Python 依賴優先順序

Git 資料夾中的 Python 函式庫會優先於存放在其他地方的函式庫。 例如，如果 Databricks 計算系統安裝了一個函式庫，且 Git 資料夾中有同名函式庫，該函式庫會被匯入。 參見Python圖書館優先次序。

安全性、認證與憑證

Azure Databricks 會將 Git 憑證儲存在控制平面，而不是在你的本地環境。 以下主題涵蓋 Git 資料夾內容如何加密、憑證如何儲存與稽核，以及遇到認證問題時該怎麼辦。

Microsoft Entra ID 的條件存取政策（CAP）問題

如果有以下情況，你可能會在複製儲存庫時出現「拒絕存取」錯誤：

  • 您的 Azure Databricks 工作區使用 Azure DevOps，並以 Microsoft Entra ID 進行驗證。
  • 你已經在 Azure DevOps 啟用了條件存取政策，以及 Microsoft Entra ID 的條件存取政策。

為了解決這個問題，可以在條件存取政策（CAP）中加入 Azure Databricks IP 位址或使用者的排除條款。

如需詳細資訊，請參閱條件式存取原則。

使用 Microsoft Entra ID 權杖設置允許清單

如果你使用 Microsoft Entra ID 來與 Azure DevOps 進行認證，預設允許清單會限制 Git URL 的範圍：

  • dev.azure.com
  • visualstudio.com

欲了解更多資訊，請參閱 Git URL 允許清單。

Git 資料夾加密

Azure Databricks 會用預設金鑰加密 Git 資料夾內容。 客戶管理金鑰僅支援用於加密 Git 憑證。

GitHub 令牌儲存與存取

  • Azure Databricks 控制平面會儲存認證權杖。 員工只能透過審核的臨時憑證存取這些資料。
  • Azure Databricks 記錄的是 token 的建立與刪除，但不會記錄使用情況。 Git 操作日誌讓你能稽核 Azure Databricks 應用程式的代幣使用情況。
  • GitHub Enterprise 會稽核代幣使用情況。 其他 Git 服務也可能提供伺服器稽核。

GPG 提交簽名

Git 資料夾不支援提交的 GPG 簽名。

SSH 支援

Git 資料夾只支援 HTTPS，不支援 SSH。

Azure DevOps 跨租戶錯誤

在另一個租戶中連接 DevOps 時，你可能會看到 Unable to parse credentials from Azure Active Directory account。 如果 Azure DevOps 專案屬於與 Azure Databricks 不同的 Microsoft Entra ID 租戶，請使用 Azure DevOps 存取令牌。 請參閱 個人存取令牌。

CI/CD 與 MLOps

如果你在 Git 資料夾中的檔案上執行任務，請注意 Git 操作可能會以不易察覺的方式影響 Notebook 狀態和 MLflow 實驗。

傳入的變更會清除筆記本狀態

修改筆記本原始碼的 git 操作會導致筆記本狀態遺失，包括儲存格輸出、註解、版本歷史和小工具。 例如，可以 git pull 更改筆記本原始碼，要求 Git 資料夾覆蓋現有筆記本。 像 git commit、 push、 或建立新分支這類操作不會影響原始碼，也不會保留筆記本狀態。

重要

MLflow 實驗無法在 Databricks Runtime 14.x 或更早版本的 Git 資料夾中運作。

Git 資料夾中的 MLflow 實驗

MLflow 實驗有兩種類型：[工作區] 和 [筆記本]。 請參閱 使用 MLflow 實驗組織訓練回合。

  • Workspace 實驗：你無法在 Git 資料夾中建立工作區 MLflow 實驗。 Log MLflow 會執行到一般工作區資料夾中建立的實驗。 多使用者協作時，請使用共用工作區資料夾。

  • 筆記本實驗：您可以在 Databricks Git 資料夾中建立筆記本實驗。 如果你將筆記本以.ipynb 檔案形式提交到 source control，MLflow 會自動將運行紀錄到一個自動建立的實驗中。 源控系統不會檢查實驗或執行過程。 請參閱建立筆記本實驗。

防止 MLflow 實驗中的資料遺失

使用 Lakeflow Jobs 建立並存檔於遠端儲存庫 的 Notebook MLflow 實驗，會儲存在暫存空間中。 這些實驗在工作流程執行後初期仍會持續，但在排程清理時有被刪除的風險。 Databricks 建議搭配 Jobs 和遠端 Git 來源使用工作區 MLflow 實驗。

警告

切換到不包含筆記本的分支可能會失去相關的 MLflow 實驗資料。 如果你在30天內未去前一個分行，這個損失將變成永久的。

若要在 30 天到期前恢復遺失的實驗資料，請還原原始筆記本名稱，打開筆記本，然後點擊右側窗格的 實驗圖示 。 這會觸發 mlflow.get_experiment_by_name() 並恢復實驗並執行。 30 天後，Azure Databricks 會清除孤立的 MLflow 實驗，以符合 GDPR 規範。

為防止資料遺失，避免在儲存庫中重新命名筆記本。 如果你重新命名筆記本，立刻點擊右側窗格的實驗圖示。

在 Git 作業中執行工作

在 Git 操作過程中，有些筆記本可能已經更新，而有些還沒更新，導致行為難以預測。

例如，若notebook A使用notebook Z來呼叫%run，並且工作在 Git 操作中啟動，該工作可能會執行最新的notebook A並搭配較舊的notebook Z。 工作可能會失敗，或是執行不同提交版本中的筆記本。

為了避免這種情況，請設定工作任務使用你的 Git 供應商作為來源，而非工作區路徑。 請參見「使用 Git 搭配 Lakeflow 工作」。

下一步

  • Last updated on