適用於預建 Docker 映像的 Python 套件擴充性 (預覽)

適用於：適用於 Python 的 Azure Machine Learning SDK v1

重要事項

本文提供使用 Azure Machine Learning SDK v1 的相關信息。 自 2025 年 3 月 31 日起，SDK v1 已淘汰，其支援將於 2026 年 6 月 30 日結束。 您能夠安裝並使用 SDK v1，直到該日期為止。

建議您在 2026 年 6 月 30 日之前轉換至 SDK v2。 如需 SDK v2 的詳細資訊，請參閱 什麼是 Azure Machine Learning Python SDK v2 和 SDK v2 參考。

用於模型推斷的預建 Docker 映像所包含的套件適用於各種熱門的機器學習架構。 有兩種方法可供新增 Python 套件，而不需重建 Docker 映像：

• 動態安裝：該方法會使用需求檔案，在 Docker 容器開機時自動還原 Python 套件。

  請考慮採用這個方法來快速建立原型。 當映像啟動時，系統會使用 requirements.txt 檔案來還原套件。 這個方法會增加映像的啟動時間，您必須等候更久的時間，部署才能處理要求。

• 預先安裝的 Python 套件：您要提供預先安裝 Python 套件的所在目錄。 在部署期間，此目錄會掛接到容器中以供您的輸入指令碼 (score.py) 使用。

  請使用此方法來進行生產環境部署。 由於套件所在的目錄會掛接到映像中，所以即使您的部署無法存取公用網際網路，也可以使用該目錄。 例如，在部署到安全的 Azure 虛擬網路時。

重要事項

使用適用於預建 Docker 映像的 Python 套件擴充性來搭配 Azure Machine Learning 目前為預覽版。 預覽功能以「原樣」提供，不保證支援或服務等級協定。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

必要條件

• Azure Machine Learning 工作區。 如需關於建立工作區的教學課程，請參閱開始使用 Azure Machine Learning。
• 熟悉如何使用 Azure Machine Learning 環境。
• 熟悉 Azure Machine Learning 的部署模型的位置和方式。

動態安裝

該方法會使用需求檔案，在映像啟動時自動還原 Python 套件。

若要透過 requirements.txt 來擴充預建的 Docker 容器映像，請遵循下列步驟：

1. 連同 score.py 指令碼一起建立 requirements.txt 檔案。
2. 將所有必要套件新增至 requirements.txt 檔案。
3. 將 Azure Machine Learning 環境中的 AZUREML_EXTRA_REQUIREMENTS_TXT 環境變數設定為 requirements.txt 檔案的位置。

一經部署，系統就會自動為您的評分指令碼還原套件。

提示

即使在建立原型時，也建議您在 requirements.txt 中鎖定每個套件版本。 例如，使用 scipy == 1.2.3 而非只使用 scipy 或甚至使用 scipy > 1.2.3。 如果您未鎖定確切版本，而且 scipy 發行新的版本，這可能會破壞您的評分指令碼，並導致部署和縮放期間發生失敗。

下列範例會示範如何設定 AZUREML_EXTRA_REQUIRMENTS_TXT 環境變數：

from azureml.core import Environment
from azureml.core.conda_dependencies import CondaDependencies 

myenv = Environment(name="my_azureml_env")
myenv.docker.enabled = True
myenv.docker.base_image = <MCR-path>
myenv.python.user_managed_dependencies = True

myenv.environment_variables = {
    "AZUREML_EXTRA_REQUIREMENTS_TXT": "requirements.txt"
}

下圖以視覺化方式呈現動態安裝程序：

預先安裝 Python 套件

這種方法會將您提供的目錄掛接到映像中。 然後，此目錄中的 Python 套件便可供輸入指令碼 (score.py) 使用。

若要透過預先安裝 Python 套件來擴充預建的 Docker 容器映像，請遵循下列步驟：

重要事項

您必須根據您使用的映像，使用與 Python 3.8 或 3.8 相容的套件。

1. 使用 virtualenv 來建立虛擬環境。

2. 安裝您的相依性。 例如，如果您在 requirements.txt 中有相依性清單，便可使用該清單，以 pip install -r requirements.txt 進行安裝，或只針對個別相依性進行 pip install。

3. 在指定 AZUREML_EXTRA_PYTHON_LIB_PATH 環境變數時，請務必指向正確的網站套件目錄，此目錄會根據您的環境名稱和 Python 版本而有所不同。 下列程式代碼示範如何為名為 myenv 和 Python 3.8 的虛擬環境設定路徑：

   from azureml.core import Environment
   from azureml.core.conda_dependencies import CondaDependencies 
   
   myenv = Environment(name='my_azureml_env')
   myenv.docker.enabled = True
   myenv.docker.base_image = <MCR-path>
   myenv.python.user_managed_dependencies = True
   
   myenv.environment_variables = {
       "AZUREML_EXTRA_PYTHON_LIB_PATH": "myenv/lib/python3.8/site-packages"
   }
   

下圖以視覺化方式呈現預先安裝的套件程序：

常見問題

只有當 myenv 網站套件目錄包含您所有的相依性時，掛接解決方案才能運作。 如果本機環境所使用的相依性安裝於不同位置，就無法在映像中取得這些相依性。

以下是一些可能會造成此問題的事項：

• virtualenv 預設會建立隔離的環境。 啟動虛擬環境之後，便無法使用全域相依性。
• 如果您讓 PYTHONPATH 環境變數指向全域相依性，此環境變數可能會干擾虛擬環境。 請在啟動環境後執行 pip list 和 pip freeze，以確保環境中沒有不必要的相依性。
• Conda 和 virtualenv 環境可能會產生干擾。 請務必不要同時使用 Conda 環境和 virtualenv。

限制

Model.package()

• Model.package() 方法可讓您以 Docker 映像或 Dockerfile 建置內容的形式建立模型套件。 使用 Model.package() 搭配預建的推斷 Docker 映像會觸發中繼映像建置，而將非根使用者變更為根使用者。

• 我們建議您使用 Python 套件擴充性解決方案。 如果需要其他相依性 (例如 apt 套件)，請建立您自己的 Dockerfile (從推斷映像擴充而來)。

常見問題集

• 在 requirements.txt 擴充性方法中，檔案名稱是否一定要命名為 requirements.txt？

  myenv.environment_variables = {
      "AZUREML_EXTRA_REQUIREMENTS_TXT": "name of your pip requirements file goes here"
  }
  

• 您是否可以摘要說明 requirements.txt 方法與掛接方法？

  一開始請使用 requirements.txt 方法來建立原型。 在反覆運算數次後，當您確信已得到成功部署模型所需的套件 (和版本) 時，請切換為掛接解決方案。

  詳細的比較如下。

  比較項目	Requirements.txt (動態安裝)	套件掛接
  解決方法	建立 requirements.txt，以在容器啟動時安裝指定的套件。	建立具有所有相依性的本機 Python 環境。 在執行階段將此目錄掛接至容器。
  安裝套件	沒有額外的安裝 (假設已安裝 pip)	虛擬環境或 Conda 環境安裝。
  設定虛擬環境	不需要額外設定虛擬環境，因為使用者可以視需要使用 pip freeze 來提取目前的本機使用者環境，以建立 requirements.txt。	需要設定乾淨的虛擬環境，視目前的使用者本機環境而定，可能要採取額外的步驟。
  偵錯	易於設定和偵錯伺服器，因為相依性已清楚列出。	不乾淨的虛擬環境會在偵錯伺服器時造成問題。 例如，可能會不清楚錯誤是來自環境還是使用者程式碼。
  擴增期間的一致性	不一致，因為相依於外部 PyPi 套件，而且使用者鎖定其相依性。 這些外部下載可能會不穩定。	僅依賴使用者環境，因此沒有一致性問題。

• 為何在容器中找不到我的 requirements.txt 和掛接的相依性目錄？

  請確認您已在本機正確設定環境變數。 接下來，確認所指定的路徑拼寫正確且存在。 檢查您是否已在推斷設定建構函式中正確地設定您的來源目錄。

• 是否可以覆寫預建推斷 Docker 映像中的 Python 套件相依性？

  是。 如果您想要使用已安裝在推斷映像中的其他 Python 套件版本，我們的擴充性解決方案會以您的版本為準。 請確定這兩個版本沒有任何衝突。

最佳做法

• 請參閱載入已註冊的模型文件。當您註冊模型目錄時，請勿在該目錄中納入評分指令碼、掛接的相依性目錄或 requirements.txt。

• 如需有關如何載入已註冊的模型或本機模型的詳細資訊，請參閱部署的位置和方式。

錯誤修正

2021-07-26

• AZUREML_EXTRA_REQUIREMENTS_TXT 和 AZUREML_EXTRA_PYTHON_LIB_PATH 現在一律相對於評分指令碼的目錄。 例如，如果 requirements.txt 和評分指令碼都位於 my_folder，則必須將 AZUREML_EXTRA_REQUIREMENTS_TXT 設定為 requirements.txt。 AZUREML_EXTRA_REQUIREMENTS_TXT 不會再設定為 my_folder/requirements.txt。

後續步驟

若要深入了解如何部署模型，請參閱如何部署模型。

若要了解如何針對預建的 Docker 映像部署進行疑難排解，請參閱如何針對預建的 Docker 映像部署進行疑難排解。