共用方式為

Git 與 Databricks Git 資料夾整合的限制和常見問題

  • 發行項

Databricks Git 資料夾和 Git 整合具有下列各節中指定的限制。 如需一般資訊，請參閱 Databricks 限制。

跳至：

檔案和存放庫限制

Azure Databricks 不會對存放庫的大小強制執行限制。 但是：

  • 工作分支限制為 1 個十億位元組 (GB)。
  • 無法在 Azure Databricks UI 中檢視大於 10 MB 的檔案。
  • 個別工作區檔案受限於單獨的大小限制。 如需詳細資訊，請參閱限制。

Databricks 建議在存放庫中：

  • 所有工作區資產與檔案的總數不超過 20,000 個。

針對任何 Git 作業，記憶體使用量限製為 2 GB，而磁碟寫入限制為 4 GB。 由於限制針對每個作業，因此如果您嘗試複製目前大小為 5 GB 的 Git 存放庫，就會發生失敗。 不過，如果您先複製一項作業中大小為 3 GB 的 Git 存放庫，稍後再將 2 GB 新增至該存放庫，則下一個提取作業將會成功。

如果您的存放庫超過這些限制，可能會收到錯誤訊息。 當您複製存放庫時，也可能會收到逾時錯誤，但作業可能會在背景中完成。

若要使用大於大小限制的存放庫，請嘗試疏鬆簽出。

如果您必須寫入在關閉叢集之後不想保留的暫存檔案，請將暫存檔案寫入 $TEMPDIR，以避免超過分支大小限制，如果 CWD 位於工作區檔案系統中，則會產生比寫入目前工作目錄 (CWD) 更好的效能。 如需詳細資訊，請參閱在 Azure Databricks 上寫入暫存檔案的位置？。

每個工作區的 Git 資料夾數目上限

每個工作區最多可以有 2,000 個 Git 資料夾。 如果您需要更多，請連絡 Databricks 支援人員。

復原從工作區中的 Git 資料夾刪除的檔案

Git 資料夾上的工作區動作會因檔案復原性而異。 有些動作允許透過 垃圾桶 資料夾進行復原，而其他動作則不允許。 先前認可並推送至遠端分支的檔案可以使用遠端 Git 存放庫的 Git 認可歷程記錄來還原。 下表概述每個動作的行為和復原能力：

動作 檔案是否可復原？
使用工作區瀏覽器刪除檔案 是，從 [垃圾箱] 資料夾
使用 Git 資料夾對話框捨棄新檔案 是，從 [垃圾箱] 資料夾
使用 Git 資料夾對話框捨棄修改過的檔案 否，檔案已消失
reset （硬） 用於未認可的檔案修改 否，檔案修改已消失
reset （硬） 針對未認可的新建立檔案 否，檔案修改已消失
使用 [Git 資料夾] 對話框切換分支 是，來自遠端 Git 存放庫
[Git 資料夾] 對話框的其他 Git 作業 （Commit & Push 等等） 是，來自遠端 Git 存放庫
PATCH 從 Repos API 更新的 /repos/id 作業 是，來自遠端 Git 存放庫

如果先前已認可並推送至遠端存放庫，則可以使用 Git 命令行或其他 Git 工具，從工作區 UI 透過 Git 作業從 Git 資料夾刪除的檔案復原。 工作區動作會因檔案復原性而異。 有些動作允許透過垃圾箱進行復原，而另一些動作則不允許。 先前認可並推送至遠端分支的檔案可以透過 Git 認可歷程記錄還原。 下表概述每個動作的行為和復原能力：

Monorepo 支援

Databricks 建議您不要建立由 monorepos 支援的 Git 資料夾，其中 monorepo 是大型的單一組織 Git 存放庫，在許多專案中具有數千個檔案。

Git 資料夾中支援的資產類型

Git 資料夾僅支援特定 Azure Databricks 資產類型。 支援的資產類型可以串行化、版本控制，並推送至支援 Git 存放庫。

目前支援的資產類型如下：

資產類型 詳細資料
檔案 檔案會串行化數據，而且可以包含從連結庫到二進位檔到程式代碼到影像的任何專案。 如需詳細資訊，請參閱 什麼是工作區檔案？
筆記本 筆記本是 Databricks 支援的筆記本檔格式。 Notebook 會被視為與檔案不同的 Azure Databricks 資產類型，因為它們並未串行化。 Git 資料夾會依擴展名（例如 .ipynb）或檔案內容中特殊標記結合的擴展名來判斷筆記本（例如， # Databricks notebook source 來源檔案開頭的 .py 批註）。
資料夾 資料夾是 Azure Databricks 特定結構，代表 Git 中檔案邏輯群組的串行化資訊。 如預期般，在檢視 Azure Databricks Git 資料夾或使用 Azure Databricks CLI 存取它時，用戶體驗為「資料夾」。

Git 資料夾中目前不支援的 Azure Databricks 資產類型包括：

  • DBSQL 查詢
  • 警示
  • 儀錶板（包括舊版儀錶板）
  • 實驗
  • Genie spaces

在 Git 中使用資產時，請觀察檔案命名中的下列限制：

  • 資料夾不能包含與相同 Git 存放庫中另一個筆記本、檔案或資料夾同名的筆記本，即使擴展名不同也一樣。 （針對來源格式筆記本，擴充功能適用於 .py python、 .scala Scala、 .sql SQL 和 .r R。針對IPYNB格式的筆記本，擴展名為 .ipynb。）例如，您無法使用相同的 Git 資料夾中名為 test1.py 的來源格式筆記本和名為 test1 的IPYNB筆記本，因為來源格式 Python 筆記本檔案 （test1.py） 會串行化為 test1 ，而且會發生衝突。
  • 檔名中不支援字元 / 。 例如，您無法在 Git 資料夾中有名為 i/o.py 的檔案。

如果您嘗試對具有這些模式名稱的檔案執行 Git 作業，您會收到「擷取 Git 狀態時發生錯誤」訊息。 如果您意外收到此錯誤，請檢閱 Git 存放庫中資產的檔名。 如果您發現名稱具有這些衝突模式的檔案，請重新命名這些檔案，然後再操作一次。

注意

您可以將現有的不支援的資產移至 Git 資料夾，但無法將這些資產的變更認可回存放庫。 您無法在 Git 資料夾建立新的不支援的資產。

筆記本格式

Databricks 會考慮兩種高階 Databricks 特定筆記本格式：“source” 和 “ipynb”。 當使用者以「來源」格式認可筆記本時，Azure Databricks 平台會認可具有語言後綴的一般檔案，例如 .py、 .sql、 .scala或 .r。 「來源」格式筆記本只包含原始程式碼，且不包含輸出，例如數據表顯示，以及執行筆記本結果的視覺效果。

不過，「ipynb」 格式確實有與其相關聯的輸出，而且這些成品會在推送 .ipynb 產生的筆記本時，自動推送至 Git 存放庫，以備份 Git 資料夾。 如果您想要認可輸出以及程式碼，請使用 「ipynb」 筆記本格式，並設定組態以允許使用者認可任何產生的輸出。 因此，“ipynb” 也針對透過 Git 資料夾推送至遠端 Git 存放庫的筆記本，在 Databricks 中支援更好的檢視體驗。

筆記本來源格式 詳細資料
來源 可以是任何具有標準檔案後綴的程式代碼檔案，其會發出程式碼語言的訊號，例如.py、 .r .scala和 .sql。 「來源」筆記本會被視為文本檔，且在認可回 Git 存放庫時不會包含任何相關聯的輸出。
ipynb “ipynb” 檔案結尾為 .ipynb ，如果已設定，可以將輸出（例如視覺效果）從 Databricks Git 資料夾推送至支援 Git 存放庫。 .ipnynb筆記本可以包含 Databricks 筆記本所支援之任何語言的程式代碼（儘管py屬於 .ipynb）。

如果您想要在執行筆記本之後將輸出推送回存放庫，請使用 .ipynb （Jupyter） 筆記本。 如果您只想在 Git 中執行筆記本並加以管理，請使用類似 的 .py「來源」格式。

如需所支援筆記本格式的詳細資訊，請參閱 匯出和匯入 Databricks 筆記本。

注意

什麼是「輸出」？

輸出是在 Databricks 平臺上執行筆記本的結果，包括數據表顯示和視覺效果。

如何? 告知筆記本所使用的格式，而不是擴展名？

在 Databricks 所管理的筆記本頂端，通常會有一行批注指出格式。 例如，針對 .py 「來源」筆記本，您會看到如下所示的一行：

# Databricks notebook source

對於 .ipynb 檔案，會使用檔案後綴來指出它是 「ipynb」 筆記本格式。

Databricks Git 資料夾中的IPYNB筆記本

Git 資料夾中有支援 Jupyter Notebook（.ipynb 檔案）。 您可以使用筆記本複製存放庫、在 Azure Databricks 中使用存放庫，然後將存放庫 .ipynb 認可並推送為 .ipynb 筆記本。 會保留元數據，例如筆記本儀錶板。 管理員可以控制是否可以提交輸出。

允許認可 .ipynb 筆記本輸出

根據預設，Git 資料夾的系統管理員設定不允許 .ipynb 認可筆記本輸出。 工作區管理員可以變更此設定：

  1. 移至 [ 系統管理員設定 > ] [工作區設定]。

  2. 在 [Git 資料夾>允許 Git 資料夾匯出 IPYNB 輸出] 下，選取 [允許：IPYNB 輸出可以開啟]。

    管理主控台：允許 Git 資料夾匯出 IPYNB 輸出。

重要

包含輸出時，視覺效果和儀錶板組態會保留為 .ipynb 檔案格式。

控制IPYNB筆記本輸出成品認可

當您認可檔案 .ipynb 時，Databricks 會建立組態檔，讓您控制認可輸出的方式： .databricks/commit_outputs。

  1. 如果您有 .ipynb 筆記本檔案，但沒有存放庫中的組態檔，請開啟 Git 狀態模式。

  2. 在通知對話框中，按兩下 [ 建立commit_outputs檔案]。

    筆記本認可 UI：建立commit_outputs檔案按鈕。

您也可以從 [檔案 ] 選單產生組態檔。 [ 檔案 ] 選單有一個控件，可讓您自動更新組態檔，以指定特定筆記本的輸出包含或排除。

  1. 在 [ 檔案] 功能表中，選取 [ 認可筆記本輸出]。

    筆記本編輯器：認可筆記本會輸出狀態和控制。

  2. 在對話框中，確認您選擇認可筆記本輸出。

    認可筆記本輸出對話框。

將來源筆記本轉換為IPYNB

您可以透過 Azure Databricks UI，將 Git 資料夾中的現有來源筆記本轉換成 IPYNB 筆記本。

  1. 在您的工作區中開啟來源筆記本。

  2. 從工作區功能表中選取 [ 檔案 ]，然後選取 [變更筆記本格式 [source]。 如果筆記本已經使用IPYNB格式，[source]將會是功能表元素中的 [ipynb]。

    展開的工作區檔案功能表，其中顯示 [變更筆記本格式] 選項。

  3. 在強制回應對話框中，選取 [Jupyter 筆記本格式 （.ipynb）]，然後按兩下 [ 變更]。

    您可以在其中選取 IPYNB 筆記本格式的強制回應對話方塊。

您也可以：

  • 建立新的 .ipynb 筆記本。
  • 將差異檢視為 Code diff （單元格中的程式碼變更）或 Raw diff （程式代碼變更會顯示為 JSON 語法，其中包含筆記本輸出作為元數據）。

如需 Azure Databricks 所支援筆記本類型的詳細資訊，請參閱 導出和匯入 Databricks 筆記本。

常見問題：Git 資料夾設定

Azure Databricks 存放庫內容儲存在哪裡？

存放庫的內容會暫時複製到控制平面中的磁碟上。 Azure Databricks 筆記本檔案會儲存在控制平面資料庫中，就像主要工作區中的筆記本一樣。 非筆記本檔案最多會儲存在磁碟上 30 天。

Git 資料夾是否支援內部部署或自我裝載的 Git 伺服器？

如果伺服器可存取網際網路，Databricks Git 資料夾支援 GitHub Enterprise、Bitbucket Server、Azure DevOps Server 和 GitLab 自我管理整合。 如需將 Git 資料夾與內部部署 Git 伺服器整合的詳細資訊，請參閱 Git 資料夾的 Git Proxy 伺服器。

若要與 Bitbucket Server、GitHub Enterprise Server 或無法存取網際網路的 GitLab 自我管理訂用帳戶執行個體整合，請與您的 Azure Databricks 帳戶小組聯絡。

Git 資料夾支援哪些 Databricks 資產類型？

如需所支持資產類型的詳細資訊，請參閱 Git 資料夾中支援的資產類型。

Git 資料夾是否支援 .gitignore 檔案？

是。 如果您將檔案新增至存放庫，且不希望 Git 追蹤檔案，請建立 .gitignore 檔案或使用從遠端存放庫複製的檔案，並新增檔案名，包括副檔名。

.gitignore 僅適用於 Git 尚未追蹤的檔案。 如果您將 Git 已追蹤的檔案新增至 .gitignore 檔案，則 Git 仍會追蹤該檔案。

我是否能建立並非使用者資料夾的最上層資料夾？

是的，系統管理員可以建立單一深度的最上層資料夾。 Git 資料夾不支援其他資料夾層級。

Git 資料夾是否支援 Git 子模組？

否。 您可複製包含 Git 子模組的存放庫，但不會複製子模組。

Azure Data Factory (ADF) 是否支援 Git 資料夾？

是。

來源管理

為什麼當我提取或簽出不同的分支時，筆記本儀表板會消失？

這是目前的限制，因為 Azure Databricks 筆記本來源檔案不會儲存筆記本儀表板資訊。

如果您想要保留 Git 存放庫中的儀表板，請將筆記本格式變更為 .ipynb (Jupyter Notebook 格式)。 根據預設，.ipynb 支援儀表板和視覺效果定義。 如果您想要保留圖形資料 (資料點)，必須認可具有輸出的筆記本。

若要了解如何提交 .ipynb 筆記本輸出，請參閱允許提交 .ipynb 筆記本輸出。

Git 資料夾是否支援分支合併？

是。 您也可建立提取要求，並透過 Git 提供者合併。

我能否從 Azure Databricks 存放庫刪除分支？

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

如果程式庫安裝在叢集上，且具有相同名稱的程式庫會包含在存放庫內的資料夾中，則會匯入哪個程式庫？

匯入存放庫中的程式庫。 如需 Python 中程式庫優先順序的詳細資訊，請參閱 Python 程式庫優先順序。

我能否先從 Git 提取最新版本的存放庫，再執行作業，而不需要依賴外部協調流程工具？

否。 一般而言，您可以將此整合為 Git 伺服器上的預先認可，讓每個推送至分支 (main/prod) 都會更新生產存放庫。

我能否匯出存放庫？

您可匯出筆記本、資料夾或整個存放庫。 您無法匯出非筆記本檔案。 如果您匯出整個存放庫，則不會包含非筆記本檔案。 若要匯出，請使用 Databricks CLI 中的 workspace export 命令或使用工作區 API。

安全性、驗證和權杖

Microsoft Entra ID 的條件式存取原則 (CAP) 問題

在您嘗試複製存放庫時，可能會在下列情況下收到「拒絕存取」錯誤訊息：

  • Azure Databricks 已設定為透過 Microsoft Entra ID 驗證使用 Azure DevOps。
  • 您已在 Azure DevOps 中啟用條件式存取原則，以及 Microsoft Entra ID 條件式存取原則。

若要解決此問題，請將排除項新增至 Azure Databricks IP 位址或使用者的條件式存取原則 (CAP)。

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

使用 Azure AD 權杖的允許清單

如果您使用 Azure Active Directory (AAD) 向 Azure DevOps 進行驗證，預設允許清單將 Git URL 限制為：

  • dev.azure.com
  • visualstudio.com

如需詳細資訊，請參閱允許清單限制遠端存放庫使用方式。

Azure Databricks Git 資料夾的內容是否加密？

Azure Databricks Git 資料夾的內容會由 Azure Databricks 使用預設金鑰加密。 除非加密您的 Git 認證，否則不支援使用客戶自控金鑰進行加密。

GitHub 權杖儲存在 Azure Databricks 中的方式和位置？ 有誰可以從 Azure Databricks 存取？

  • 驗證權杖會儲存在 Azure Databricks 控制平面中，而 Azure Databricks 員工只能透過稽核的暫時認證來取得存取權。
  • Azure Databricks 會記錄這些權杖的建立和刪除，但不會記錄其使用量。 Azure Databricks 有追蹤 Git 作業的記錄，可用於稽核 Azure Databricks 應用程式權杖的使用方式。
  • GitHub Enterprise 會稽核權杖使用量。 其他 Git 服務也可能會有 Git 伺服器稽核。

Git 資料夾是否支援 GPG 簽署提交？

否。

Git 資料夾是否支援 SSH？

否，只有 HTTPS。

將 Azure Databricks 連線至不同租用中的 Azure DevOps 存放庫時出現錯誤

嘗試在獨立租用中連線到 DevOps 時，您可能會收到訊息 Unable to parse credentials from Azure Active Directory account。 如果 Azure DevOps 專案位於與 Azure Databricks 不同的 Microsoft Entra ID 租用中，您需要從 Azure DevOps 使用存取權杖。 請參閱使用 DevOps 權杖連線到 Azure DevOps。

CI/CD 和 MLOps

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

改變筆記本原始程式碼的 Git 作業會導致筆記本狀態遺失，包括儲存格輸出、註解、版本歷程記錄和小工具。 例如，git pull 可以變更筆記本的原始程式碼。 在此情況下，Databricks Git 資料夾必須覆寫現有的筆記本，以匯入變更。 git commit 和 push 或建立新的分支不會影響筆記本原始程式碼，因此，筆記本狀態會保留在這些作業中。

重要

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

我能否在存放庫中建立 MLflow 實驗？

MLflow 實驗有兩種類型：[工作區] 和 [筆記本]。 如需這兩種 MLflow 實驗類型的詳細資訊，請參閱使用 MLflow 實驗組織訓練執行。

在 Git 資料夾中，您可以針對其中一種類型呼叫 MLflow 實驗的 mlflow.set_experiment("/path/to/experiment") 並記錄執行，但該實驗和相關聯的執行將不會簽入原始檔控制。

工作區 MLflow 實驗

您無法在 Databricks Git 資料夾 (Git 資料夾) 中建立工作區 MLflow 實驗。 如果多個使用者使用單獨的 Git 資料夾在相同的 ML 程式碼上共同作業，則記錄 MLflow 會執行至在一般工作區資料夾中建立的 MLflow 實驗。

Notebook MLflow 實驗

您可在 Databricks Git 資料夾中建立筆記本實驗。 如果您將筆記本以 .ipynb 檔案的形式簽入原始檔控制，可以將 MLflow 執行記錄至自動建立和相關聯的 MLflow 實驗。 如需詳細資訊，請參閱建立筆記本實驗。

防止 MLflow 實驗中的資料遺失

使用 Databricks Jobs 與遠端存放庫中原始程式碼所建立的 Notebook MLflow 實驗會儲存在暫時儲存位置。 這些實驗一開始會在工作流程執行之後持續儲存，但之後在排程移除暫存檔案期間，可能會面臨被刪除的風險。 Databricks 建議搭配作業和遠端 Git 來源使用工作區 MLflow 實驗。

警告

當您切換到不包含筆記本的分支時，有可能遺失相關聯的 MLflow 實驗資料。 如果在 30 天內未存取先前的分支，則此遺失會成為永久遺失。

若要在 30 天到期前復原遺漏的實驗資料，請將筆記本重新命名回原始名稱，開啟筆記本，按下右側窗格上的 [實驗] 圖示 (這也會有效地呼叫 mlflow.get_experiment_by_name() API)，您將可以看到已復原的實驗並執行。 30 天後將會清除任何孤立的 MLflow 實驗，以符合 GDPR 合規性政策。

若要防止這種情況，Databricks 建議您避免在存放庫中重新命名筆記本，或者如果您重新命名筆記本，請在重新命名筆記本之後，立即按下右側窗格中的 [實驗] 圖示。

當 Git 作業正在進行中時，筆記本作業在工作區中執行時會發生什麼？

在 Git 作業進行中時，存放庫中的某些筆記本可能已經更新，而其他筆記本則尚未更新。 這可能會導致未預期的行為。

例如，假設 notebook A 使用 %run 命令呼叫 notebook Z。 如果在 Git 作業期間執行的作業會啟動最新版本 notebook A，但 notebook Z 尚未更新，則筆記本 A 中的 %run 命令可能會啟動舊版的 notebook Z。 在 Git 作業期間，筆記本狀態無法預測，作業可能會失敗或從不同的認可執行 notebook A 和 notebook Z。

若要防止這種情況，請改用 Git 型作業 (其中來源是 Git 提供者，而不是工作區路徑)。 如需詳細資訊，請參閱搭配作業使用 Git。

資源

如需 Databricks 工作區檔案的詳細資訊，請參閱什麼是工作區檔案？。