共用方式為

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

  • 發行項

適用於：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 指令碼) 的 print/logging 函式輸出。
  • 儲存體初始設定式：這些記錄包含是否已成功將程式碼和模型資料下載至容器的資訊。 該容器會在推斷伺服器容器開始執行之前執行。

若要查看容器的記錄輸出，請使用下列 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 設定這些參數，請將 --resource-group 和 --workspace-name 新增至這些命令。

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

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 under the storage account '[storage-account-name]' in the container '[container-name]' at the path '[path-to-the-log]'" 。

下列清單包含常見的映射建置失敗案例：

如果您發生 ImageBuild 逾時，也建議您檢閱預設的探查設定。

容器登錄授權失敗

如果錯誤訊息提及 "container registry authorization failure"，表示您無法使用目前的認證來存取容器登錄。 此錯誤可能是工作區資源索引不同步所致，需要一些時間來自動同步。 但您可以手動呼叫索引同步，這或許可以解決授權失敗的問題。

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

未在具有 VNet 的私人工作區中設定映像建置計算

如果錯誤訊息提及 "failed to communicate with the workspace's container registry"，而且您正在使用虛擬網路，且工作區的 Azure Container Registry 是私人的，並使用私人端點進行設定，則您必須啟用 Azure Container Registry，以允許在虛擬網路中建置映像。

一般映像組建失敗

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

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

ERROR: OutOfQuota

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

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

CPU 配額

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

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

叢集配額

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

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

磁碟配額

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

記憶體配額

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

角色指派配額

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

端點配額

嘗試刪除此訂閱中某些未使用的端點。 如果所有端點都在使用中，建議您嘗試要求增加端點限制。 若要深入了解端點限制，請參閱 Azure Machine Learning 線上端點和批次端點的端點配額。

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 權限。 請確定您的使用者指派身分識別擁有適當權限。

如需詳細資訊，請參閱容器登錄授權錯誤。

範本函式規格不正確

未正確指定範本函式時，便會發生此錯誤。 請修正原則，或移除原則指派以解除封鎖。 錯誤訊息可能包含原則指派名稱和原則定義，以協助您偵錯此錯誤，以及 Azure 原則定義結構一文，其中討論避免範本失敗的秘訣。

無法下載使用者容器映像

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

請確定容器映像可在工作區 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`

不支援使用專用網的 MLFlow 模型格式

若您嘗試使用無程式碼部署方法來部署 MLflow 模型，同時搭配使用適用於受控線上端點的舊版網路隔離方法時，便會發生此錯誤。 如果您正在使用舊版網路隔離方法，則此專用網功能不能與 MLFlow 模型格式搭配使用。 如果您需要使用無程式碼部署方法來部署 MLflow 模型，請嘗試使用工作區受控 VNet。

資源要求超過限制

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

azureml-fe 尚未就緒

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

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

請檢查 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。

錯誤：WorkspaceManagedNetworkNotReady

當您嘗試在已啟用工作區受控 VNet 但尚未布建受控 VNet 的工作區下建立在線部署時，就會發生此錯誤。 建立在線部署之前，應該先布建工作區受控 VNet。 遵循手動布建 工作區受控 VNet 以手動布建工作區受控 VNet 的指示。 完成後，您可以開始建立在線部署。 如需詳細資訊，請參閱 使用受控在線端點 的網路隔離和 使用網路隔離保護受控在線端點。

ERROR: OperationCanceled

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

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

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

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

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

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

等待幾秒鐘 (最多一分鐘) 後再重試作業，便可能可以執行而不需取消。

ERROR: SecretsInjectionError

線上部署建立期間的祕密擷取和插入，會使用與線上端點相關聯的身分識別，擷取工作區連線和/或金鑰保存庫中的祕密。 此錯誤會在下列情況發生：

  • 端點身分識別沒有 Azure RBAC 權限，因此即使部署定義已將祕密指定為參考 (對應至環境變數)，仍無法讀取工作區連線和/或金鑰保存庫中的祕密。 請記住，角色指派可能需要時間，變更才會生效。
  • 祕密參考的格式無效，或指定的祕密不存在於工作區連線和/或金鑰保存庫中。

如需詳細資訊，請參閱線上端點中的祕密插入 (預覽) 和使用祕密插入從線上部署存取祕密 (預覽)。

ERROR: InternalServerError

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

Kubernetes 部署特有的常見錯誤

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

crashloopbackoff 的相關錯誤：

評分指令碼的相關錯誤：

其他：

ERROR: ACRSecretError

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

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

ERROR: TokenRefreshFailed

此錯誤的原因是延伸模組因為未正確設定 Kubernetes 叢集身分識別而無法從 Azure 取得主體認證。 重新安裝 Azure Machine Learning 延伸模組，然後再試一次。

ERROR: GetAADTokenFailed

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

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

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

錯誤：ACRAuthenticationChallengeFailed

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

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

錯誤：ACRTokenExchangeFailed

此錯誤的原因是 Kubernetes 叢集因為尚未獲得 Azure AD 權杖授權，而導致交換 ACR 權杖失敗。 由於角色指派需要一些時間，因此您可以稍候片刻，然後再試一次。

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

ERROR: KubernetesUnaccessible

在 Kubernetes 模型部署期間，您可能會收到下列錯誤：

{"code":"BadRequest","statusCode":400,"message":"The request is invalid.","details":[{"code":"KubernetesUnaccessible","message":"Kubernetes error: AuthenticationException. Reason: InvalidCertificate"}],...}

若要減輕這個錯誤，您可以：

ERROR: ImagePullLoopBackOff

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

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

錯誤：DeploymentCrashLoopBackOff

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

  • 使用者指令碼 score.py 發生語法錯誤或匯入錯誤，然後在初始化時引發例外狀況。
  • 或者，部署 Pod 所需的記憶體數量超過限制。

若要減輕此錯誤，首先您可以檢查部署記錄中的使用者指令碼是否有任何例外狀況。 如果錯誤持續發生，請嘗試擴充資源/執行個體類型記憶體限制。

ERROR: KubernetesCrashLoopBackOff

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

  • 如果一或多個 Pod 卡在 CrashLoopBackoff 狀態中，便可檢查部署記錄是否存在，並檢查記錄中是否有錯誤訊息。
  • score.py 發生錯誤，且容器在初始化分數碼時發生損毀，即可遵循 ERROR: ResourceNotReady 部分。
  • 您的評分流程需要更多記憶體，且部署設定上限不足，則可嘗試使用較大的記憶體限制來更新部署。

ERROR: NamespaceNotFound

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

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

ERROR: UserScriptInitFailed

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

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

錯誤：UserScriptImportError

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

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

錯誤：UserScriptFunctionNotFound

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

ERROR: EndpointNotFound

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

錯誤：EndpointAlreadyExists

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

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

ERROR: ScoringFeUnhealthy

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

若要疑難排解此問題，建議您在叢集中重新安裝或更新 Azure Machine Learning 延伸模組。

錯誤：ValidateScoringFailed

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

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

錯誤：InvalidDeploymentSpec

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

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

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

ERROR: PodUnschedulable

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

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

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

  • 檢查您所用 instance type 的 node selector 定義，以及您叢集節點的 node label 設定。
  • 檢查 AKS 叢集的 instance type 和節點 SKU 大小，或 Arc-Kubernetes 叢集的節點資源。
    • 如果叢集的資源不足，可減少執行個體類型資源需求，或使用另一個需要較少資源的執行個體類型。
  • 如果叢集沒有更多資源可以滿足部署需求，請刪除一些部署以釋出資源。

ERROR: PodOutOfMemory

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

錯誤：InferencingClientCallFailed

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

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

注意

若要透過重新附加來疑難排解錯誤，請保證重新附加時所使用的設定同於先前中斷連結的計算設定，例如相同的計算名稱和命名空間，否則，您可能會遇到其他錯誤。

如果仍然無法運作，您不妨請求可存取叢集的管理員，使用 kubectl get po -n azureml 來檢查中繼伺服器 Pod 是否正在執行。

自動調整問題

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

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

常見的模型取用錯誤

下列清單列出端點 invoke 作業狀態所產生的常見模型取用錯誤。

頻寬限制問題

受控線上端點針對每個端點具有頻寬限制。 您可以在線上端點的限制中找到限制設定。 若頻寬使用量超過限制，您的要求便會遭到延遲。 如要監視頻寬延遲：

  • 使用「網路位元組」計量來了解目前的頻寬使用量。 如需詳細資訊，請參閱監視受控的線上端點。
  • 若強制執行頻寬限制，則會傳回兩個回應尾端：
    • 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 衝突錯誤。 例如，若建立或更新線上端點作業正在進行，但您觸發新的刪除作業，則會擲回錯誤。
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。

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

注意

使用適用於受控線上端點的舊版網路隔離方法時，便會發生此問題，該方法中，Azure Machine Learning 會在端點下為每個部署建立一個受控虛擬網路。

  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 位址會包含在您可以直接在工作室 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 的相依性關聯釘選至相容的版本。 伺服器的最新版本已修正此問題。

下一步