疑難排解線上端點部署和評分

  • 發行項

適用於：Azure CLI ml 延伸模組 v2 (現行)Python SDK azure-ai-ml v2 (現行)

了解如何解決 Azure Machine Learning 線上端點常見的部署和評分問題。

本文件以您進行疑難排解的方式結構化：

  1. 在雲端中部署之前，請使用本機部署在本機測試您的模型並執行偵錯。
  2. 請使用容器記錄來協助執行問題偵錯。
  3. 瞭解可能發生的常見部署錯誤，以及如何修正這些錯誤。

HTTP 狀態碼一節說明使用 REST 要求評分端點時，引動和預測錯誤如何對應至 HTTP 狀態碼。

必要條件

本機部署

本機部署會將模型部署到本機 Docker 環境。 本機部署適用於在部署至雲端之前的測試和偵錯。

提示

您也可以使用 Azure Machine Learning 推斷 HTTP 伺服器 Python 套件 ，在本機對評分腳本進行偵錯。 使用推斷伺服器進行偵錯可協助您在部署至本機端點之前偵錯評分腳本，如此您就能偵錯，而不會受到部署容器組態的影響。

本機部署支援建立、更新和刪除本機端點。 也可讓您叫用並從端點取得記錄。

如要使用本機部署，請新增 --local 至適當的 CLI 命令：

az ml online-deployment create --endpoint-name <endpoint-name> -n <deployment-name> -f <spec_file.yaml> --local

在本機部署過程中，會執行下列步驟：

  • Docker 可以建置新的容器映像，或從本機 Docker 快取提取現有的映像。 若現有的映像符合規格檔案的環境部分，則會使用現有的映像。
  • Docker 會使用已裝載的本機成品 (例如模型和程式碼檔案)，啟動新的容器。

如需詳細資訊，請參閱在本機部署並評分機器學習模型。

提示

使用 Visual Studio Code 在本機測試和偵錯端點。 如需詳細資訊，請參閱在 Visual Studio Code 中從本機偵錯線上端點。

Conda 安裝

一般而言，MLflow 部署的問題源自檔案中所 conda.yaml 指定使用者環境安裝的問題。

若要對 conda 安裝問題進行偵錯，請嘗試下列步驟：

  1. 檢查 Conda 安裝的記錄。 如果容器損毀或啟動時間太長，則 Conda 環境更新可能無法正確解決。

  2. 使用 conda env create -n userenv -f <CONDA_ENV_FILENAME> 命令在本機安裝 mlflow conda 檔案。

  3. 如果本機發生錯誤，請嘗試解決 Conda 環境，並在重新部署之前建立功能環境。

  4. 如果容器在本機解析時損毀，可能是用於部署的 SKU 大小太小。

    1. Conda 套件安裝會在執行時間發生，因此如果 SKU 大小太小而無法容納 conda.yaml 環境檔案中詳述的所有套件，則容器可能會損毀。
    2. Standard_F4s_v2 VM 是不錯的起始 SKU 大小，但視 Conda 檔案中指定的相依性而定，可能需要較大的 SKU 大小。
    3. 針對 Kubernetes 線上端點，Kubernetes 叢集至少必須有 4 個 vCPU 核心和 8 GB 記憶體。

取得容器記錄

您無法直接存取部署模型的 VM。 不過，您可以從 VM 上執行的某些容器中取得記錄。 您取得的資訊量取決於部署的布建狀態。 如果指定的容器已啟動並執行，您會看到其主控台輸出;否則，您會收到一則訊息，稍後再試一次。

有兩種類型的容器可供您從下列專案取得記錄：

  • 推斷伺服器：記錄包含推斷 伺服器 (主控台記錄) ，其中包含評分腳本的列印/記錄函式輸出 (score.py 程式碼) 。
  • 儲存體初始化運算式：記錄包含程式碼和模型資料是否已成功下載至容器的資訊。 容器會在推斷伺服器容器開始執行之前執行。

若要查看容器的記錄輸出，請使用下列 CLI 命令：

az ml online-deployment get-logs -e <endpoint-name> -n <deployment-name> -l 100

或

az ml online-deployment get-logs --endpoint-name <endpoint-name> --name <deployment-name> --lines 100

如果您尚未透過 az configure 設定這些參數，請將 和 --workspace-name 新增 --resource-group 至這些命令。

若要查看如何設定這些參數的相關資訊，以及如果您已經設定目前的值，請執行：

az ml online-deployment get-logs -h

根據預設，系統會從推斷伺服器提取記錄。

注意

若您使用 Python 記錄，請確定您使用正確的記錄層級順序，將訊息發佈至記錄。 例如：INFO。

您也可以藉由傳遞 –-container storage-initializer 來取得儲存體初始化容器中的記錄。

將 --help 和/或 --debug 新增至命令，以查看詳細資訊。

針對 Kubernetes 線上端點，系統管理員能夠直接存取您部署模型的叢集，更有彈性，讓他們能夠檢查 Kubernetes 中的記錄。 例如：

kubectl -n <compute-namespace> logs <container-name>

要求追蹤

有兩個支援的追蹤標頭：

  • x-request-id 保留給伺服器追蹤。 我們會覆寫此標頭，以確保它是有效的 GUID。

    注意

    當您為失敗的要求建立支援票證時，請附加失敗的要求識別碼以加速調查。

  • x-ms-client-request-id 適用於用戶端追蹤案例。 此標頭會清理成隻接受英數位元、連字號和底線，並截斷為最多 40 個字元。

一般部署錯誤

這是一份常見的部署錯誤清單，這些錯誤會回報為部署作業狀態的一部分。

如果您要建立或更新 Kubernetes 線上部署，您可以看到 Kubernetes 部署特有的常見錯誤。

錯誤：ImageBuildFailure

在建置環境 (Docker 映像) 時，會傳回此錯誤。 您可以檢查組建記錄檔，以取得失敗的詳細資訊。 組建記錄檔位於 Azure Machine Learning 工作區的預設儲存體中。 確切的位置會作為錯誤的一部分傳回。 例如： "The build log is available in the workspace blob store '[storage-account-name]' under the path '/azureml/ImageLogs/your-image-id/build.log'" 。 在此情況下，"azureml" 是儲存體帳戶中的 Blob 容器名稱。

這是常見的映射建置失敗案例清單：

如果 ImageBuild 逾時，我們也建議您檢閱預設 探查設定 。

容器登錄授權失敗

如果錯誤訊息提及 "container registry authorization failure" ，表示您無法使用目前的認證來存取容器登錄。 工作區資源金鑰的還原同步處理可能會導致此錯誤，而且需要一些時間才能自動同步處理。 不過，您可以 手動呼叫金鑰同步處理，這可能會解決授權失敗。

如果設定不正確，虛擬網路背景的容器登錄也可能遭遇此錯誤。 您必須確認您已正確設定的虛擬網路。

一般映像組建失敗

如上所述，您可以檢查組建記錄檔，取得失敗的詳細資訊。 如果在組建記錄檔中找不到明顯的錯誤，且最後一行是 Installing pip dependencies: ...working... ，則相依性可能會導致錯誤。 在 Conda 檔案中釘選版本相依性可修正此問題。

此外，建議您在部署至雲端前，先在本機部署以在本機測試並偵錯您的模型。

ERROR: OutOfQuota

這是使用 Azure 服務時可能會用盡配額的常見資源清單：

此外，這是可能只針對 Kubernetes 線上端點用盡配額的常見資源清單：

CPU 配額

部署模型之前，您需要有足夠的計算配額。 此配額會定義每個訂閱、每個工作區、每個 SKU 以及每個區域的可用虛擬核心數量。 每個部署都會從可用配額中減去，並根據 SKU 的類型在刪除之後將其新增回來。

可能的緩和措施是檢查是否有未使用的部署可供刪除。 或者，您可以提交配額增加的要求。

叢集配額

當您沒有足夠的 Azure ML 計算叢集配額時，就會發生此問題。 此配額會定義每個訂用帳戶一次可使用的叢集總數，以在 Azure 雲端中部署 CPU 或 GPU 節點。

可能的緩和措施是檢查是否有未使用的部署可供刪除。 或者，您可以提交配額增加的要求。 請務必選取 Machine Learning Service: Cluster Quota 作為此配額增加要求的配額類型。

磁碟配額

當模型的大小大於可用的磁碟空間，且無法下載模型時，就會發生此問題。 嘗試具有更多磁碟空間的 SKU ，或減少映射和模型大小。

記憶體配額

當模型的記憶體使用量大於可用的記憶體時，就會發生此問題。 嘗試具有更多記憶體的 SKU 。

角色指派配額

當您建立受控線上端點時，受控 識別 需要角色指派才能存取工作區資源。 如果您已達到 角色指派限制，請嘗試刪除此訂用帳戶中的一些未使用的角色指派。 您可以流覽至 [存取控制] 功能表，以檢查Azure 入口網站中的所有角色指派。

端點配額

嘗試刪除此訂閱中某些未使用的端點。 如果所有端點都在使用中，您可以嘗試 要求增加端點配額。

針對 Kubernetes 線上端點，叢集層級也有端點配額界限，您也可以查看 Kubernetes 線上端點配額 一節以取得詳細資料。

Kubernetes 配額

當要求 CPU 或記憶體無法滿足時，就會發生此問題，因為此部署的所有節點都無法排程，例如節點已連線或節點無法使用。

錯誤訊息通常表示叢集中的資源不足，例如 ， OutOfQuota: Kubernetes unschedulable. Details:0/1 nodes are available: 1 Too many pods... 這表示叢集中有太多 Pod，而且沒有足夠的資源根據您的要求來部署新的模型。

您可以嘗試下列緩和措施來解決此問題：

  • 對於維護 Kubernetes 叢集的 IT 作業，您可以嘗試新增更多節點，或清除叢集中某些未使用的 Pod 來釋放某些資源。
  • 針對部署模型的機器學習工程師，您可以嘗試減少部署的資源要求：
    • 如果您透過資源直接在部署組態中定義資源要求，您可以嘗試減少資源要求。
    • 如果您使用 instance type 來定義模型部署的資源，您可以連絡 IT 作業以調整實例類型資源設定，如需詳細資訊，請參閱 如何管理 Kubernetes 實例類型。

全區域 VM 容量

由於區域中缺少 Azure Machine Learning 容量，服務無法布建指定的 VM 大小。 請稍後重試，或嘗試部署至不同的區域。

其他配額

為了在部署過程中執行提供的 score.py，Azure 會建立一個容器，其中包含 score.py 所需的全部資源，並在該容器上執行評分指令碼。

若無法啟動容器，則表示無法進行評分。 其原因可能在於容器要求的資源比 instance_type 可支援的還多。 若發生此情況，請考慮更新線上部署的 instance_type。

如要取得錯誤的確切原因，請執行：

az ml online-deployment get-logs -e <endpoint-name> -n <deployment-name> -l 100

ERROR: BadArgument

這是使用受控線上端點或 Kubernetes 線上端點時，可能會遇到此錯誤的原因清單：

此外，這是只有在使用 Kubernetes 線上端點時，您才會遇到此錯誤的原因清單：

訂閱不存在

請務必輸入現有的 Azure 訂閱。 找不到參考的 Azure 訂閱時，便會發生此錯誤。 原因可能是訂閱識別碼輸入錯誤。 請仔細檢查是否正確輸入訂閱識別碼，並確認識別碼目前有效。

如需 Azure 訂用帳戶的詳細資訊，請參閱 必要條件一節。

授權錯誤

在建立部署) 時布建計算資源 (之後，Azure 會嘗試從工作區Azure Container Registry (ACR) 提取使用者容器映射，並從工作區儲存體帳戶將使用者模型和程式碼成品掛接至使用者容器。

若要這樣做，Azure 會使用 受控識別 來存取儲存體帳戶和容器登錄。

  • 如果您使用系統指派的身分識別建立相關聯的端點，系統會自動授與 Azure 角色型存取控制 (RBAC) 許可權，而且不需要進一步的許可權。

  • 如果您使用使用者指派的身分識別建立相關聯的端點，則使用者的受控識別必須具有工作區儲存體帳戶的儲存體 Blob 資料讀取器許可權，以及工作區Azure Container Registry (ACR) 的 AcrPull 許可權。 請確定您的使用者指派的身分識別具有正確的許可權。

如需詳細資訊，請參閱 Container Registry 授權錯誤。

無法下載使用者容器映像

可能找不到使用者容器。 檢查容器記錄以取得更多詳細資料。

請確定容器映像可在工作區 ACR 中使用。

例如，若映像為 testacr.azurecr.io/azureml/azureml_92a029f831ce58d2ed011c3c42d35acb:latest，請使用 az acr repository show-tags -n testacr --repository azureml/azureml_92a029f831ce58d2ed011c3c42d35acb --orderby time_desc --output table 檢查存放庫。

無法下載使用者模型

找不到使用者的模型。 檢查容器記錄以取得更多詳細資料。

請確定您是否已將模型註冊到與部署相同的工作區。 若要在工作區中顯示模型的詳細資料：

az ml model show --name <model-name> --version <version>

警告

您必須指定版本或標籤，以取得模型的資訊。

您也可以檢查工作區儲存體帳戶中是否有 blob。

  • 例如，若 blob 是 https://foobar.blob.core.windows.net/210212154504-1517266419/WebUpload/210212154504-1517266419/GaussianNB.pkl，則可使用此命令來檢查其是否存在：

    az storage blob exists --account-name foobar --container-name 210212154504-1517266419 --name WebUpload/210212154504-1517266419/GaussianNB.pkl --subscription <sub-name>`

  • 如果 Blob 存在，您可以使用此命令從儲存體初始化運算式取得記錄：

    az ml online-deployment get-logs --endpoint-name <endpoint-name> --name <deployment-name> –-container storage-initializer`

資源要求超過限制

資源的要求必須小於或等於限制。 若您未設定限制，我們會在您將計算附加至 Azure Machine Learning 工作區時設定預設值。 您可以使用 az ml compute show 命令，或是在 Azure 入口網站中檢查限制。

azureml-fe 尚未就緒

將傳入推斷要求路由至部署的服務的前端元件 (azureml-fe) 會視需要自動調整。 其會在 k8s 擴充功能安裝期間安裝。

此元件在叢集上應狀況良好，至少應有一個狀況良好的複本。 如果您在觸發 Kubernetes Online 端點和部署建立/更新要求時，無法使用此元件，將會收到此錯誤訊息。

請檢查 Pod 狀態和記錄以修正此問題，您也可以嘗試更新叢集上安裝的 k8s 擴充功能。

ERROR: ResourceNotReady

為了在部署過程中執行提供的 score.py，Azure 會建立一個容器，其中包含 score.py 所需的全部資源，並在該容器上執行評分指令碼。 此案例中的錯誤，在於此容器在執行時損毀，這表示無法進行評分。 此錯誤會在下列情況發生：

  • score.py 發生錯誤。 用來 get-logs 診斷常見問題：
    • 嘗試匯入的套件 score.py 不包含在 conda 環境中。
    • 語法錯誤。
    • init() 方法發生失敗。
  • 若 get-logs 未產生任何記錄，通常表示容器無法啟動。 若要偵錯此問題，請改為嘗試在本機部署。
  • 未正確設定整備度或活躍度探查。
  • 容器初始化需要太長的時間，讓整備或即時探查失敗超過失敗臨界值。 在此情況下，請調整 探查設定 ，以允許較長的時間初始化容器，或嘗試 在支援的 VM SKU 之間嘗試較大的 VM SKU，以加速初始化。
  • 環境設定容器時發生錯誤，例如遺漏的相依性。
  • 當您遇到 TypeError: register() takes 3 positional arguments but 4 were given 錯誤時，該錯誤很可能是因為 flask v2 與 azureml-inference-server-http 之間的相依性所造成。 如需詳細資訊，請參閱推斷 HTTP 伺服器的常見問題。

ERROR: ResourceNotFound

這是只有在使用受控線上端點或 Kubernetes 線上端點時，您才會遇到此錯誤的原因清單：

Resource Manager 找不到資源

當 Azure Resource Manager 找不到必要的資源時，就會發生此錯誤。 例如，如果參考儲存體帳戶，但在指定儲存體帳戶的路徑上找不到，您可以收到此錯誤。 請務必再次檢查可能由確切路徑提供的資源或其名稱的拼字。

如需詳細資訊，請參閱解決找不到資源的錯誤。

容器登錄授權錯誤

當提供屬於私人或無法存取容器登錄的映像進行部署時，就會發生此錯誤。 目前，我們的 API 無法接受私人登錄認證。

若要減輕此錯誤，請確定容器登錄不是私人，或遵循下列步驟：

  1. 將私人登錄的 acrPull 角色授與線上端點的系統身分識別。
  2. 在您的環境定義中，指定私人映像的位址，以及不修改 (建置) 映像的額外指示。

如果風險降低成功，映像就不需要任何建置，且最終映像位址只會是指定的映像位址。 在部署階段，您的線上端點系統身分識別會從私人登錄提取映像。

如需詳細資訊，請參閱如何使用工作區診斷 API。

ERROR: OperationCanceled

這是使用受控線上端點或 Kubernetes 線上端點時，可能會遇到此錯誤的原因清單：

作業已由另一個優先順序較高的作業取消

Azure 作業具有特定的優先權層級，且會從最高到最低層級執行。 當您的作業被其他具有較高優先權的作業覆寫時，就會發生此錯誤。

重試作業可能會允許其在不取消的情況下執行。

作業已取消，正在等候鎖定確認

Azure 作業在提交期後有短暫的等候期間，系統會在該期間擷取鎖定，以確保我們不會遇到競爭狀況。 當您提交的作業，與目前仍在等候確認收到鎖定並可繼續的另一個作業相同時，就會發生此錯誤。 這可能表示您在初始要求之後太快提交非常類似的要求。

在等候數秒到一分鐘之後重試作業，可能會允許執行作業而不取消。

ERROR: InternalServerError

雖然我們盡力提供穩定且可靠的服務，但有時並非一切皆按計畫進行。 若您遇到此錯誤，這表示我們遇到一些需要修正的問題。 提交具有所有相關資訊的 客戶支援票證 ，我們可以解決問題。

Kubernetes 部署特有的常見錯誤

身分識別和驗證的相關錯誤：

與 crashloopbackoff 相關的錯誤：

評分腳本的相關錯誤：

其他：

錯誤：ACRSecretError

這是您在建立/更新 Kubernetes 線上部署時可能會遇到此錯誤的原因清單：

  • 尚未完成角色指派。 在此情況下，請稍候幾秒鐘，稍後再試一次。
  • Azure ARC (For Azure Arc Kubernetes 叢集) 或 Azure Machine Learning 擴充功能 (For AKS) 未正確安裝或設定。 請嘗試檢查 Azure ARC 或 Azure Machine Learning 擴充功能設定和狀態。
  • Kubernetes 叢集的網路設定不正確，請檢查 Proxy、網路原則或憑證。
    • 如果您使用私人 AKS 叢集，則必須在 AKS vnet 中設定 ACR、儲存體帳戶、工作區的私人端點。

錯誤：TokenRefreshFailed

這是因為擴充功能無法從 Azure 取得主體認證，因為 Kubernetes 叢集身分識別未正確設定，請重新安裝 Azure Machine Learning 擴充功能 ，然後再試一次。

錯誤：GetAADTokenFailed

這是因為 Kubernetes 叢集要求 AAD 權杖失敗或逾時，請檢查您的網路協助工具，然後再試一次。

  • 您可以遵循 設定必要的網路流量 來檢查輸出 Proxy，確定叢集可以連線到工作區。
  • 您可以在叢集中的線上端點 CRD 中找到工作區端點 URL。

如果您的工作區是停用公用網路存取的私人工作區，Kubernetes 叢集應該只透過私人連結與該私人工作區通訊。

錯誤：ACRAuthenticationChallengeFailed

這是因為 Kubernetes 叢集無法連線到工作區的 ACR 服務來執行驗證挑戰。 請檢查您的網路，特別是 ACR 公用網路存取，然後再試一次。

您可以遵循 GetAADTokenFailed 中的疑難排解步驟來檢查網路。

錯誤：ACRTokenExchangeFailed

這是因為 Kubernetes 叢集交換 ACR 權杖失敗，因為 AAD 權杖尚未獲授權，因為角色指派需要一些時間，因此您可以稍候一段時間再試一次。

此失敗也可能是因為當時對 ACR 服務的要求太多，因此應該是暫時性錯誤，您可以稍後再試一次。

錯誤：ImagePullLoopBackOff

建立/更新 Kubernetes 線上部署時，可能會發生此錯誤的原因是您無法從容器登錄下載映射，導致映射提取失敗。

在此情況下，如果叢集可以從容器登錄提取映射，您可以檢查叢集網路原則和工作區容器登錄。

錯誤：DeploymentCrashLoopBackOff

建立/更新 Kubernetes 線上部署時，您可能會遇到此錯誤的原因是使用者容器初始化損毀。 此錯誤有兩個可能的原因：

  • 使用者腳本 score.py 有語法錯誤或匯入錯誤，然後在初始化時引發例外狀況。
  • 或者，部署 Pod 需要比其限制更多的記憶體。

若要減輕此錯誤，請先檢查部署記錄中是否有使用者腳本中的任何例外狀況。 如果錯誤持續發生，請嘗試擴充資源/實例類型記憶體限制。

錯誤：KubernetesCrashLoopBackOff

這是您在建立/更新 Kubernetes 線上端點/部署時可能會遇到此錯誤的原因清單：

  • 一或多個 Pod () 卡在 CrashLoopBackoff 狀態中，您可以檢查部署記錄是否存在，並檢查記錄檔中是否有錯誤訊息。
  • 在 中 score.py 發生錯誤，且容器在 init 您的分數代碼時損毀，您可以遵循 ERROR：ResourceNotReady 元件。
  • 您的評分程式需要更多記憶體，您的部署設定限制不足，您可以嘗試使用較大的記憶體限制來更新部署。

錯誤：NamespaceNotFound

建立/更新 Kubernetes 線上端點時，您可能會遇到此錯誤的原因，是因為您的 Kubernetes 計算在叢集中無法使用的命名空間。

您可以在工作區入口網站中檢查 Kubernetes 計算，並檢查 Kubernetes 叢集中的命名空間。 如果命名空間無法使用，您可以中斷連結舊版計算並重新附加以建立新的計算，並指定已存在於叢集中的命名空間。

錯誤：UserScriptInitFailed

建立/更新 Kubernetes 線上部署時，您可能會遇到此錯誤的原因，是因為已上傳 score.py 檔案中的 init 函式引發例外狀況。

您可以檢查部署記錄，以詳細查看例外狀況訊息並修正例外狀況。

錯誤：UserScriptImportError

建立/更新 Kubernetes 線上部署時，您可能會遇到此錯誤的原因，是因為 score.py 您上傳的檔案已匯入無法使用的套件。

您可以檢查部署記錄，以詳細查看例外狀況訊息並修正例外狀況。

錯誤：UserScriptFunctionNotFound

您在建立/更新 Kubernetes 線上部署時可能會遇到此錯誤的原因，是因為 score.py 您上傳的檔案沒有名為 init() 或 run() 的函式。 您可以檢查程式碼並新增 函式。

錯誤：EndpointNotFound

建立/更新 Kubernetes 線上部署時，您可能會遇到此錯誤的原因，是因為系統找不到叢集中部署的端點資源。 您應該在現有的端點中建立部署，或先在您的叢集中建立此端點。

錯誤：EndpointAlreadyExists

建立 Kubernetes 線上端點時，您可能會遇到此錯誤的原因，是因為建立端點已存在於叢集中。

每個工作區和每個叢集的端點名稱應該是唯一的，因此在此情況下，您應該使用其他名稱來建立端點。

錯誤：ScoringFeUnhealthy

建立/更新 Kubernetes 線上端點/部署時，您可能會遇到此錯誤的原因，是因為找不到在叢集中執行的系統服務或狀況不良的 Azureml-fe 。

若要解決此問題，您可以在叢集中重新安裝或更新 Azure Machine Learning 擴充功能。

錯誤：ValidateScoringFailed

建立/更新 Kubernetes 線上部署時，您可能會遇到此錯誤的原因，是因為處理模型部署時評分要求 URL 驗證失敗。

在此情況下，您可以先檢查端點 URL，然後嘗試重新部署部署。

錯誤：InvalidDeploymentSpec

建立/更新 Kubernetes 線上部署時，您可能會遇到此錯誤的原因，是因為部署規格無效。

在此情況下，您可以檢查錯誤訊息。

  • 請確定 instance count 有效。
  • 如果您已啟用自動調整，請確定 minimum instance count 和 maximum instance count 都有效。

錯誤：PodUnschedulable

這是您在建立/更新 Kubernetes 線上端點/部署時可能會遇到此錯誤的原因清單：

  • 無法將 Pod 排程到節點，因為叢集中的資源不足。
  • 沒有節點符合節點親和性/選取器。

若要減輕此錯誤，您可以遵循下列步驟：

  • node selector檢查您使用的定義 instance type ，以及 node label 叢集節點的組態。
  • 檢查 instance type AKS 叢集的節點 SKU 大小，或Arc-Kubernetes叢集的節點資源。
    • 如果叢集的資源不足，您可以減少實例類型資源需求，或使用另一個需要較小資源的實例類型。
  • 如果叢集沒有更多資源符合部署需求，請刪除一些部署以釋放資源。

錯誤：PodOutOfMemory

當您建立/更新線上部署時，可能會遇到此錯誤的原因是您提供給部署的記憶體限制不足。 您可以將記憶體限制設定為較大的值，或使用較大的實例類型來減輕此錯誤。

錯誤：InferencingClientCallFailed

建立/更新 Kubernetes 線上端點/部署時可能會遇到此錯誤的原因是 Kubernetes 叢集的 k8s 擴充功能無法連線。

在此情況下，您可以中斷連結，然後 重新附加 計算。

注意

若要藉由重新附加來針對錯誤進行疑難排解，請保證使用與先前卸離計算完全相同的組態重新附加，例如相同的計算名稱和命名空間，否則您可能會遇到其他錯誤。

如果仍然無法運作，您可以要求可存取叢集的系統管理員，以用來 kubectl get po -n azureml 檢查 轉寄伺服器 Pod 是否正在執行。

自動調整問題

若您在自動調整時遇到問題，請參閱疑難排解 Azure 自動調整。

針對 Kubernetes 線上端點，有Azure Machine Learning 推斷路由器是一個前端元件，可處理 Kubernetes 叢集上所有模型部署的自動調整，您可以在自動調整 Kubernetes 推斷路由中找到詳細資訊

常見的模型耗用量錯誤

這是端點 invoke 作業狀態所產生的常見模型耗用量錯誤清單。

頻寬限制問題

受控線上端點針對每個端點具有頻寬限制。 您可以在 使用 Azure Machine Learning 管理及增加資源的配額中找到限制設定。 若您的頻寬使用量超過限制，您的要求將會遭到延遲。 如要監視頻寬延遲：

  • 使用「網路位元組」度量來瞭解目前的頻寬使用量。 如需詳細資訊，請參閱監視受控的線上端點。
  • 若強制執行頻寬限制，則會傳回兩個回應尾端：
    • ms-azureml-bandwidth-request-delay-ms：回應資料流傳輸所耗費的延遲時間 (以毫秒為單位)。
    • ms-azureml-bandwidth-response-delay-ms：回應資料流傳輸所耗費的延遲時間 (以毫秒為單位)。

HTTP 狀態碼

當您使用 REST 要求存取線上端點時，傳回的狀態碼會符合 HTTP 狀態碼的標準。 這些是端點調用和預測錯誤如何對應至 HTTP 狀態碼的詳細資料。

受控線上端點的常見錯誤碼

使用 REST 要求取用受控線上端點時，這些是常見的錯誤碼：

狀態碼 原因描述 為何會傳回此代碼
200 [確定] 您的模型在延遲界限內執行成功。
401 未經授權 您無權執行要求的動作 (例如分數)，或權杖已過期。
404 找不到 端點沒有任何包含正權數的有效部署。
408 要求逾時 模型執行耗費的時間比模型部署設定 request_settings 下 request_timeout_ms 中提供的逾時更長。
424 模型錯誤 若您的模型容器傳回非 200 回應，則 Azure 會傳回 424。 在端點的 Azure 監視器計量總管上，檢查 Requests Per Minute 計量底下的 Model Status Code 維度。 或是檢查回應標頭 ms-azureml-model-error-statuscode 和 ms-azureml-model-error-reason 以取得詳細資訊。 如果 424 隨附即時性或整備探查失敗，請考慮調整 探查設定 ，以允許較長的時間探查容器的存留時間或整備程度。
429 擱置的要求太多 您的模型目前收到的要求比它所能處理的要求還多。 Azure Machine Learning 已實作系統，允許在任何指定時間平行處理最多 2 * max_concurrent_requests_per_instance * instance_count requests ，以確保順暢的作業。 超過此上限的其他要求將會遭到拒絕。 您可以在request_settings和scale_settings區段底下檢閱模型部署組態，以確認並調整這些設定。 此外，如 RequestSettings 的 YAML 定義中所述，請務必確保已正確傳遞環境變數 WORKER_COUNT 。

如果您使用自動調整並取得此錯誤，這表示您的模型會比系統可相應增加更快取得要求。 在此情況下，請考慮使用 指數輪詢 重新傳送要求，讓系統有調整的時間。 您也可以使用程式 代碼來計算實例計數來增加實例數目。 這些步驟與設定自動調整結合，有助於確保您的模型已準備好處理要求流入。
429 速率限制 每秒的要求數目達到受控線上端點的限制。
500 內部伺服器錯誤 Azure Machine Learning 布建的基礎結構失敗。

Kubernetes 線上端點的常見錯誤碼

以下是使用 REST 要求取用 Kubernetes 線上端點時的常見錯誤碼：

狀態碼 原因描述 為何會傳回此代碼
409 衝突錯誤 當作業正在進行時，該相同線上端點上的任何新作業會回應 409 衝突錯誤。 例如，如果建立或更新線上端點作業正在進行中，而且如果您觸發新的 Delete 作業，則會擲回錯誤。
502 已在 score.py 檔案的 方法中 run() 擲回例外狀況或當機 當 中 score.py 發生錯誤時，例如，匯入的封裝不存在於 conda 環境中、語法錯誤或 方法中的 init() 失敗。 您可以 依照這裡 進行偵錯檔案。
503 每秒接收大量要求尖峰 自動調整程式的設計訴求是處理負載中細微的變更。 如果您每秒收到非常大量的要求數，用戶端可能會收到 HTTP 狀態碼 503。 即使自動調整程式可迅速反應，AKS 建立更多容器仍需要大量時間。 您可以 遵循這裡 來防止 503 狀態碼。
504 要求已逾時 504 狀態碼表示要求已逾時。預設逾時設定為 5 秒。 您可以修改 score.py 來移除不必要的呼叫，以增加逾時或嘗試加速端點。 如果這些動作未修正問題，您可以 遵循這裡 對 score.py 檔案進行偵錯。 程式碼可能處於無回應狀態或無限迴圈。
500 內部伺服器錯誤 Azure Machine Learning 布建的基礎結構失敗。

如何防止 503 狀態碼

Kubernetes 線上部署支援自動調整，可新增複本以支援額外負載，您可以在 Azure Machine Learning 推斷路由器中找到更多資訊。 擴大/縮減的決策是以目前容器複本的使用量為基礎。

有兩個方法可協助防止出現 503 狀態碼：

提示

這兩個方法可以個別使用或結合使用。

  • 變更自動調整建立新複本的使用率層級。 您可以將 autoscale_target_utilization 設定為較低的值，來調整使用率目標。

    重要

    此變更不會「加快」建立複本的速度。 相反地，其會以較低的使用率閾值建立複本。 若不等到服務使用率達 70% 就將值變更為 30%，會在使用率達 30% 時建立複本。

    如果 Kubernetes 線上端點已經使用目前的最大複本，而且您仍會看到 503 狀態碼，請增加 autoscale_max_replicas 值以增加複本的最大數目。

  • 變更最低複本數目。 增加最少複本數可提供較大的集區來處理傳入尖峰。

    若要增加實例數目，您可以計算下列程式碼之後的必要複本。

    from math import ceil
# target requests per second
target_rps = 20
# time to process the request (in seconds, choose appropriate percentile)
request_process_time = 10
# Maximum concurrent requests per instance
max_concurrent_requests_per_instance = 1
# The target CPU usage of the model container. 70% in this example
target_utilization = .7

concurrent_requests = target_rps * request_process_time / target_utilization

# Number of instance count
instance_count = ceil(concurrent_requests / max_concurrent_requests_per_instance)

    注意

    如果您收到大於新最小複本可處理的要求尖峰，可能會再次收到 503。 例如，隨著端點的流量增加，您可能需要增加最小複本。

如何計算執行個體計數

若要增加實例數目，您可以使用下列程式碼來計算所需的複本：

from math import ceil
# target requests per second
target_rps = 20
# time to process the request (in seconds, choose appropriate percentile)
request_process_time = 10
# Maximum concurrent requests per instance
max_concurrent_requests_per_instance = 1
# The target CPU usage of the model container. 70% in this example
target_utilization = .7

concurrent_requests = target_rps * request_process_time / target_utilization

# Number of instance count
instance_count = ceil(concurrent_requests / max_concurrent_requests_per_instance)

CORS 原則封鎖

線上端點 (v2) 目前不支援 原生的跨原始來源資源分享 (CORS) 。 如果您的 Web 應用程式嘗試叫用端點，而不需正確處理 CORS 預檢要求，您會看到下列錯誤訊息：

Access to fetch at 'https://{your-endpoint-name}.{your-region}.inference.ml.azure.com/score' from origin http://{your-url} has been blocked by CORS policy: Response to preflight request doesn't pass access control check. No 'Access-control-allow-origin' header is present on the request resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with the CORS disabled.

建議您使用Azure Functions、Azure 應用程式閘道或任何服務作為過渡層來處理 CORS 預檢要求。

常見的網路隔離問題

線上端點建立失敗，出現 V1LegacyMode == true 訊息

您可針對 v1_legacy_mode 設定 Azure Machine Learning 工作區，這會停用 v2 API。 受控線上端點是 v2 API 平台的功能，如果工作區已啟用 v1_legacy_mode，將無法運作。

重要

請先洽詢您的網路安全性小組，再停用 v1_legacy_mode。 網路安全性小組可能基於某個原因而加以啟用。

如需如何停用 v1_legacy_mode 的詳細資訊，請參閱 v2 的網路隔離。

使用金鑰型驗證建立線上端點失敗

使用下列命令來列出工作區的 Azure Key Vault 網路規則。 將 <keyvault-name> 取代為金鑰保存庫的名稱：

az keyvault network-rule list -n <keyvault-name>

此命令的回應類似於下列 JSON 文件：

{
    "bypass": "AzureServices",
    "defaultAction": "Deny",
    "ipRules": [],
    "virtualNetworkRules": []
}

如果 bypass 的值不是 AzureServices，請使用設定金鑰保存庫網路設定中的指引，將它設定為 AzureServices。

線上部署失敗，發生映像下載錯誤

  1. 檢查是否已停用部署的 egress-public-network-access 旗標。 如果已啟用此旗標，且容器登錄的可見度為私人，則預期會發生此失敗。

  2. 使用下列命令來檢查私人端點連線的狀態。 將 <registry-name> 取代為工作區的 Azure Container Registry 名稱：

    az acr private-endpoint-connection list -r <registry-name> --query "[?privateLinkServiceConnectionState.description=='Egress for Microsoft.MachineLearningServices/workspaces/onlineEndpoints'].{Name:name, status:privateLinkServiceConnectionState.status}"

    在回應文件中，驗證 status 欄位已設定為 Approved。 如果未核准，請使用下列命令來核准它。 以上一個命令傳回的名稱取代 <private-endpoint-name>：

    az network private-endpoint-connection approve -n <private-endpoint-name>

無法解析評分端點

  1. 驗證發出評分要求的用戶端是可存取 Azure Machine Learning 工作區的虛擬網路。

  2. 使用端點主機名稱上的 nslookup 命令來擷取 IP 位址資訊：

    nslookup endpointname.westcentralus.inference.ml.azure.com

    回應包括位址。 此位址應位於虛擬網路所提供的範圍內

    注意

    針對 Kubernetes 線上端點，端點主機名稱應該是已在 Kubernetes 叢集中指定的 CName (功能變數名稱) 。 如果是 HTTP 端點，IP 位址將會包含在您可以直接在 Studio UI 中取得的端點 URI 中。 如需取得端點 IP 位址的更多方式，請參閱 安全 Kubernetes 線上端點。

  3. 如果主機名稱不是由 nslookup 命令解析：

    針對受控線上端點，

    1. 檢查虛擬網路的私人 DNS 區域中是否有 A 記錄。

      若要檢查記錄，請使用下列命令：

      az network private-dns record-set list -z privatelink.api.azureml.ms -o tsv --query [].name

      結果應該包括類似 *.<GUID>.inference.<region> 的項目。

    2. 如果未傳回任何推斷值，請刪除並重新建立工作區的私人端點。 如需詳細資訊，請參閱如何設定私人端點。

    3. 如果使用自訂 DNS 設定包含私人端點的工作區 (如何搭配自訂 DNS 伺服器使用工作區)，請使用下列命令驗證自訂 DNS 的解析是否正常運作。

      dig endpointname.westcentralus.inference.ml.azure.com

    針對 Kubernetes 線上端點，

    1. 檢查 Kubernetes 叢集中的 DNS 組態。

    2. 此外，您也可以檢查 azureml-fe 是否如預期般運作，請使用下列命令：

      kubectl exec -it deploy/azureml-fe -- /bin/bash
(Run in azureml-fe pod)

curl -vi -k https://localhost:<port>/api/v1/endpoint/<endpoint-name>/swagger.json
"Swagger not found"

      針對 HTTP，請使用

      curl https://localhost:<port>/api/v1/endpoint/<endpoint-name>/swagger.json
"Swagger not found"

    如果 curl HTTP 失敗 (例如逾時) 但 HTTP 正常運作，請檢查憑證是否有效。

    如果無法解析為 A 記錄，請確認是否可從 Azure DNS (168.63.129.16) 進行解析。

    dig @168.63.129.16 endpointname.westcentralus.inference.ml.azure.com

    如果成功，您可以針對自訂 DNS 上的私人連結，針對條件式轉寄站進行疑難排解。

無法對線上部署進行評分

  1. 使用下列命令來查看部署是否已成功部署：

    az ml online-deployment show -e <endpointname> -n <deploymentname> --query '{name:name,state:provisioning_state}'

    如果部署順利完成，則 state 的值會是 Succeeded。

  2. 如果部署成功，請使用下列命令來檢查是否已將流量指派給部署。 將 <endpointname> 取代為您的端點名稱：

    az ml online-endpoint show -n <endpointname>  --query traffic

    提示

    如果您正在使用要求中的 azureml-model-deployment 標頭來鎖定此部署，則不需要此步驟。

    此命令的回應應該會列出指派給部署的流量百分比。

  3. 如果已正確設定流量指派 (或部署標頭)，請使用下列命令來取得端點的記錄。 將 <endpointname> 取代為端點的名稱，並將 <deploymentname> 取代為部署：

    az ml online-deployment get-logs  -e <endpointname> -n <deploymentname>

    瀏覽記錄，以查看當您提交要求至部署時，是否發生執行評分程式碼的問題。

針對推斷伺服器進行疑難排解

在本節中，我們會提供 Azure Machine Learning 推斷 HTTP 伺服器的基本疑難排解秘訣。

基本步驟

疑難排解的基本步驟如下：

  1. 收集 Python 環境的版本資訊。
  2. 請確定環境檔案中指定的 azureml-inference-server-HTTP python 套件版本符合 開機記錄中顯示的 AzureML 推斷 HTTP 伺服器版本。 有時候 pip 的相依性解析程式會導致安裝非預期的套件版本。
  3. 如果您在環境中指定 Flask (及其相依性) ，請移除它們。 相依性包括 Flask 、 Jinja2 、 itsdangerous 、 Werkzeug 、 MarkupSafe 和 click 。 Flask 會列為伺服器套件中的相依性，最好讓我們的伺服器安裝它。 如此一來，當伺服器支援新版本的 Flask 時，您將會自動取得它們。

伺服器版本

伺服器套件 azureml-inference-server-http 會發佈至 PyPI。 您可以在 PyPI 頁面上找到我們的變更記錄和所有舊版。 如果您使用舊版，請更新為最新版本。

  • 0.4.x：定型映射中配套的版本≤ 20220601 和 中 azureml-defaults>=1.34,<=1.43 。 0.4.13 是最後一個穩定版本。 如果您在版本 0.4.11 之前使用伺服器，您可能會看到 Flask 相依性問題，例如無法從 匯 jinja2 入名稱 Markup 。 建議您盡可能升級至 0.4.13 或 0.8.x (最新版本) 。
  • 0.6.x：預先安裝于推斷映射的版本≤ 20220516。 最新穩定版本是 0.6.1。
  • 0.7.x：支援 Flask 2 的第一個版本。 最新穩定版本是 0.7.7。
  • 0.8.x：記錄格式已變更，Python 3.6 支援已卸載。

套件相依性

伺服器最相關的套件 azureml-inference-server-http 如下：

  • flask
  • opencensus-ext-azure
  • inference-schema

如果您在 Python 環境中指定 azureml-defaults ，則 azureml-inference-server-http 套件會依存于 ，且會自動安裝。

提示

如果您使用 Python SDK v1 且未在 Python 環境中明確指定 azureml-defaults ，SDK 可能會為您新增套件。 不過，它會鎖定 SDK 所在的版本。 例如，如果 SDK 版本是 1.38.0 ，它會新增 azureml-defaults==1.38.0 至環境的 pip 需求。

常見問題集

1. 我在伺服器啟動期間遇到下列錯誤：


TypeError: register() takes 3 positional arguments but 4 were given

  File "/var/azureml-server/aml_blueprint.py", line 251, in register

    super(AMLBlueprint, self).register(app, options, first_registration)

TypeError: register() takes 3 positional arguments but 4 were given

您已在 Python 環境中安裝 Flask 2，但執行的 azureml-inference-server-http 版本不支援 Flask 2。 在 azureml-inference-server-http>=0.7.0 中以及 azureml-defaults>=1.44 中新增 Flask 2 的支援。

  • 如果您未在 AzureML Docker 圖片中使用此套件，請使用 azureml-inference-server-http 或 azureml-defaults 的最新版本。

  • 如果您使用此套件搭配 AzureML Docker 圖片，請確定您是使用 2022 年 7 月內建或該月份之後的圖片。容器記錄中可找到圖片版本。 您應該能夠找到類似下列的記錄：

    2022-08-22T17:05:02,147738763+00:00 | gunicorn/run | AzureML Container Runtime Information
2022-08-22T17:05:02,161963207+00:00 | gunicorn/run | ###############################################
2022-08-22T17:05:02,168970479+00:00 | gunicorn/run | 
2022-08-22T17:05:02,174364834+00:00 | gunicorn/run | 
2022-08-22T17:05:02,187280665+00:00 | gunicorn/run | AzureML image information: openmpi4.1.0-ubuntu20.04, Materializaton Build:20220708.v2
2022-08-22T17:05:02,188930082+00:00 | gunicorn/run | 
2022-08-22T17:05:02,190557998+00:00 | gunicorn/run |

    圖片的組建日期會出現在「具體化組建」之後，在上述範例中為 20220708，或 2022 年 7 月 8 日。 此圖片與 Flask 2 相容。 如果您在容器記錄檔中看不到類似這樣的橫幅，您的圖片已過期，而且應該更新。 如果您使用 CUDA 映射，而且找不到較新的映射，請檢查您的映射是否已在 AzureML-Containers中淘汰。 如果是，您應該能夠找到取代專案。

  • 如果您使用伺服器搭配線上端點，您也可以在線上端點頁面的 [部署記錄] 底下找到Azure Machine Learning 工作室。 如果您使用第 1 版 SDK 進行部署，但未在部署組態中明確指定圖片，則會預設使用符合本機 SDK 工具組的 openmpi4.1.0-ubuntu20.04 版本，這可能不是圖片的最新版本。 例如，SDK 1.43 預設會使用不相容的 openmpi4.1.0-ubuntu20.04:20220616。 請確定您為部署使用最新的 SDK。

  • 如果基於某些原因而無法更新圖片，您可以透過釘選 azureml-defaults==1.43 或 azureml-inference-server-http~=0.4.13 來暫時避免問題，此舉會使用 Flask 1.0.x 安裝較舊的版本伺服器。

2. 在啟動期間，我在模組 opencensus、jinja2、MarkupSafe 或 click 發生 ImportError 或 ModuleNotFoundError，如以下訊息所示：

ImportError: cannot import name 'Markup' from 'jinja2'

舊版伺服器 (<= 0.4.10) 未將 Flask 的相依性關聯釘選至相容的版本。 伺服器的最新版本已修正此問題。

下一步