共用方式為

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

  • 發行項

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

本文說明如何針對常見的 Azure Machine Learning 線上端點部署和評分問題進行疑難排解和解決。

文件結構反映出進行疑難排解的正確方式：

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

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

必要條件

要求追蹤

有兩個支援的追蹤標頭：

  • x-request-id 保留給伺服器追蹤。 Azure Machine Learning 會覆寫此標頭，以確保其為有效的 GUID。 為失敗的要求建立支援票證時，請附加失敗的要求識別碼以加速調查。 或者，提供區域的名稱和端點名稱。

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

在本機部署

本機部署表示將模型部署至本機 Docker 環境。 本機部署支援建立、更新和刪除本機端點，並可讓您從端點叫用並取得記錄。 本機部署適用於在部署至雲端之前的測試和偵錯。

提示

您可以使用 Azure Machine Learning 推斷 HTTP 伺服器 Python 套件，於本機對評分指令碼進行偵錯。 使用推斷伺服器進行偵錯可協助您先偵錯評分指令碼再部署至本機端點，以在不受部署容器設定影響的情況下進行偵錯。

您可以使用 Azure CLI 或 Python SDK 在本機部署。 Azure Machine Learning 工作室不支援本機部署或本機端點。

若要使用本機部署，請將 --local 新增至適當的命令。

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

下列步驟會在本機部署期間發生：

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

如需詳細資訊，請參閱使用本機端點在本機進行部署和偵錯 (英文)。

提示

您可以使用 Visual Studio Code 在本機對您的端點進行測試和偵錯。 如需詳細資訊，請參閱在 Visual Studio Code 中於本機對線上端點進行偵錯 (英文)。

取得容器記錄

您無法直接存取模型部署所在的虛擬機器 (VM)，但您可以從在 VM 上執行的一些容器取得記錄。 您獲得的資訊量取決於部署的佈建狀態。 如果指定的容器已啟動並執行中，您會看到其主控台輸出。 否則，您會收到要您稍後再試的訊息。

您可以從下列類型的容器取得記錄：

  • 推斷伺服器主控台記錄包含來自評分指令碼 score.py 程式碼的列印和記錄函式輸出。
  • 儲存體初始設定式記錄包含是否已成功將程式碼和模型資料下載至容器的資訊。 該容器會在推斷伺服器容器開始執行之前執行。

針對 Kubernetes 線上端點，系統管理員可以直接存取您部署模型所在的叢集，並檢查 Kubernetes 中的記錄。 例如：

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

注意

若您使用 Python 記錄，請務必使用正確的記錄層級 (例如 INFO)，以將訊息發佈至記錄。

查看容器的記錄輸出

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

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

Or

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

根據預設，系統會從推斷伺服器中提取記錄。 您可以藉由傳遞 –-container storage-initializer 來取得儲存體初始設定式容器中的記錄。

如果您尚未透過 az configure 設定這些參數，請將 --resource-group 和 --workspace-name 新增至命令。 若要查看如何設定這些參數的相關資訊，或如果您目前已設定值，請執行下列命令：

az ml online-deployment get-logs -h

若要查看詳細資訊，請將 --help 或 --debug 新增至命令。

一般部署錯誤

部署作業狀態可以回報下列常見的部署錯誤：

如果正在建立或更新 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]'"。

下列各節說明常見的映像建置失敗案例：

Azure Container Registry 授權失敗

如果錯誤訊息提及 "container registry authorization failure"，表示您無法使用目前的認證來存取容器登錄。 工作區資源金鑰不同步可能會導致此錯誤，且其需要一些時間來自動同步。 不過，您可以使用 az ml workspace sync-keys (部分機器翻譯) 手動呼叫金鑰同步處理，其可能解決授權失敗。

如果位於虛擬網路後方的容器登錄設定不正確，其也可能遭遇此錯誤。 請確認虛擬網路設定正確。

未在具有虛擬網路的私人工作區中設定映像建置計算

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

映像建置逾時

映像建置逾時通常是因為映像太大而無法在部署建立時間範圍內完成建置。 在錯誤指定的位置檢查您的映像建置記錄。 記錄會在映像建置逾時的時間點截斷。

若要解決此問題，請個別建置映像 (部分機器翻譯)，以便只需要在部署建立期間提取映像。 如果您遇到 ImageBuild 逾時，請檢閱預設探查設定 (部分機器翻譯)。

一般映像組建失敗

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

請嘗試在本機部署，以在部署至雲端之前先對模型進行測試和偵錯。

ERROR: OutOfQuota

使用 Azure 服務時，下列資源可能會用盡配額：

針對僅限 Kubernetes 線上端點，Kubernetes 資源也可能會用盡配額。

CPU 配額

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

您可以檢查是否有未使用的部署可以刪除，或提交增加配額的要求 (英文)。

叢集配額

如果沒有足夠的 Azure Machine Learning 計算叢集配額，就會發生 OutOfQuota 錯誤。 配額會定義每個訂用帳戶的叢集總數，可供您同時用來在 Azure 雲端中部署 CPU 或 GPU 節點。

磁碟配額

當模型的大小大於可用磁碟空間且無法下載模型時，就會發生 OutOfQuota 錯誤。 嘗試使用具有更多磁碟空間的 SKU (部分機器翻譯)，或減少映像和模型的大小。

記憶體配額

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

角色指派配額

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

端點配額

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

Kubernetes 配額

當因節點無法針對此部署進行排程，而無法提供所要求的 CPU 或記憶體時，就會發生 OutOfQuota 錯誤。 例如，節點可能受到封鎖或因其他原因而無法使用。

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

請嘗試下列風險降低來解決此問題：

  • 維護 Kubernetes 叢集的 IT 操作員可嘗試新增更多節點，或清除叢集中一些未使用的 Pod，以釋出一些資源。

  • 部署模型的機器學習工程師可嘗試減少部署的資源要求。

    • 如果透過資源區段直接在部署設定中定義資源要求，請嘗試減少資源要求。
    • 如果您使用 instance_type 來定義模型部署的資源，請連絡 IT 操作員以調整執行個體類型資源設定。 如需詳細資訊，請參閱建立和管理執行個體類型。

全區域 VM 容量

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

其他配額

為了在部署過程中執行您提供的 score.py 檔案，Azure 會建立包括 score.py 所需之所有資源的容器。 Azure Machine Learning 接著會在該容器上執行評分指令碼。 如果您的容器無法啟動，則無法進行評分。 容器可能會要求比 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 會使用受控識別來存取儲存體帳戶和容器登錄。

如果您使用使用者指派的身分識別來建立相關聯的端點，則使用者的受控識別必須具有工作區儲存體帳戶上的儲存體 Blob 資料讀者權限，以及工作區容器登錄上的 AcrPull 權限。 請確定您使用者指派的身分識別擁有適當權限。

若您使用系統指派的身分識別來建立相關聯的端點，則會自動授與 Azure 角色型存取控制 (RBAC) 權限，且不需要進一步的權限。 如需詳細資訊，請參閱容器登錄授權錯誤。

範本函式規格不正確

未正確指定範本函式時，便會發生此錯誤。 請修正原則，或移除原則指派以解除封鎖。 錯誤訊息可能包括原則指派名稱和原則定義，以協助您對此錯誤進行偵錯。 如需避免範本失敗的提示，請參閱 Azure 原則定義結構 (部分機器翻譯)。

無法下載使用者容器映像

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

確定工作區容器登錄中的容器映像是可用的。 例如，如果映像是 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，您可以使用下列命令來檢查 Blob 是否存在：

az storage blob exists --account-name <storage-account-name> --container-name <container-name> --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 模型，請嘗試使用工作區受控虛擬網路 (英文)。

資源要求超過限制

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

Azureml-fe 尚未就緒

將傳入推斷要求路由傳送至已部署服務的前端 azureml-fe 元件會在 k8s-extension (部分機器翻譯) 安裝期間安裝，並視需要自動調整。 此元件在叢集上應該要至少有一個狀況良好的複本。

如果此元件在您觸發 Kubernetes 線上端點或部署建立或更新要求時無法使用，您就會收到此錯誤。 請檢查 Pod 狀態和記錄，以修正此問題。 您也可以嘗試更新叢集上安裝的 k8s-extension。

ERROR: ResourceNotReady

為了在部署過程中執行您提供的 score.py 檔案，Azure 會建立包括 score.py 所需之所有資源的容器，並在該容器上執行評分指令碼。 此案例中的錯誤是此容器會在執行時當機，因此無法進行評分。 這個錯誤可能是因為下列其中一個狀況而發生：

  • score.py 中發生錯誤。 使用 get-logs 來診斷常見問題，例如：

    • score.py 嘗試匯入未包括在 conda 環境中的套件
    • 語法錯誤
    • init() 方法中發生失敗

    如果 get-logs 不會產生任何記錄，通常表示容器無法啟動。 若要對此問題進行偵錯，請改為嘗試在本機部署。

  • 未正確設定整備度或活躍度探查。

  • 容器初始化花費的時間太長，導致整備度或活躍度探查超出失敗閾值。 在此情況下，請調整探查設定 (部分機器翻譯)，以允許較長的時間來將容器初始化。 或嘗試使用更大的支援的 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 找不到必要的資源時，就會發生此錯誤。 例如，如果在指定的路徑上找不到儲存體帳戶，您可能會收到此錯誤。 請仔細檢查路徑或名稱規格的正確性和拼字。 如需詳細資訊，請參閱解決找不到資源的錯誤。

容器登錄授權錯誤

當提供屬於私人或因其他原因而無法存取之容器登錄的映像進行部署時，就會發生此錯誤。 Azure Machine Learning API 無法接受私人登錄認證。

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

  1. 將私人登錄的 acrPull 角色授與線上端點的系統身分識別。
  2. 在環境定義中，指定私人映像的位址，並提供不修改或建置映像的指示。

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

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

錯誤：WorkspaceManagedNetworkNotReady

如果您嘗試建立可啟用工作區受控虛擬網路的線上部署，但尚未佈建受控虛擬網路，就會發生此錯誤。 在您建立線上部署之前，請先佈建工作區受控虛擬網路。

若要手動佈建工作區受控虛擬網路，請遵循手動佈建受控 VNet (英文) 中的指示。 然後，您就可以開始建立線上部署。 如需詳細資訊，請參閱受控線上端點的網路隔離和使用網路隔離保護受控線上端點。

ERROR: OperationCanceled

使用受控線上端點或 Kubernetes 線上端點時，可能會收到此錯誤，原因如下：

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

Azure 作業具有特定的優先權層級，且會從最高到最低層級執行。 如果您的作業被其他有較高優先權的作業覆寫，便會發生此錯誤。 重試作業可能會允許其在不取消的情況下執行。

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

Azure 作業在提交期後有短暫的等候期間，系統會在該期間擷取鎖定，以確保其不會遇到競爭狀況。 提交的作業同於另一個作業時，便會發生此錯誤。 另一個作業目前正在等待確認其已收到鎖定，之後才會繼續進行。

您可能在初始要求後太快提交類似的要求。 等候最多一分鐘之後重試作業，可能會允許其在不取消的情況下執行。

ERROR: SecretsInjectionError

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

  • 端點身分識別沒有 Azure RBAC 權限來讀取工作區連線或金鑰保存庫中的祕密，即使部署定義已將祕密指定為對應至環境變數的參考。 角色指派可能需要一些時間，變更才會生效。

  • 祕密參考的格式無效，或指定的祕密不存在於工作區連線或金鑰保存庫中。

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

ERROR: InternalServerError

此錯誤表示 Azure Machine Learning 服務中有一些問題需要修正。 提交客戶支援票證並提供解決問題所需的所有資訊。

Kubernetes 部署特有的常見錯誤

身分識別和驗證錯誤：

Crashloopbackoff 錯誤：

評分指令碼錯誤：

其他錯誤：

ERROR: ACRSecretError

當您建立或更新 Kubernetes 線上部署時，可能會因為下列其中一個原因而收到此錯誤：

  • 角色指派尚未完成。 等待幾秒鐘，然後再試一次。

  • 未正確安裝或設定已啟用 Azure Arc 的 Kubernetes 叢集或 AKS Azure Machine Learning 延伸模組。 檢查已啟用 Azure ARC 的 Kubernetes 或 Azure Machine Learning 延伸模組的設定和狀態。

  • Kubernetes 叢集的網路設定不正確。 檢查 Proxy、網路原則或憑證。

  • 您的私人 AKS 叢集沒有適當的端點。 請務必為 Container Registry、儲存體帳戶和 AKS 虛擬網路中的工作區設定私人端點。

  • 您的 Azure Machine Learning 延伸模組版本是 v1.1.25 或更低版本。 請確定您的延伸模組版本大於 v1.1.25。

ERROR: TokenRefreshFailed

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

ERROR: GetAADTokenFailed

發生此錯誤的原因是因為 Kubernetes 叢集要求 Microsoft Entra ID 權杖失敗或逾時。請檢查您的網路存取權，然後再試一次。

  • 請遵循使用 Kubernetes 計算中的指示，以檢查輸出 Proxy 並確定叢集可以連線到工作區。 您可以在叢集中的線上端點自訂資源定義 (CRD) 中找到工作區端點 URL。

  • 檢查工作區是否允許公用存取。 不論 AKS 叢集本身是公用還是私人，如果私人工作區停用公用網路存取，Kubernetes 叢集便只能透過私人連結與該工作區通訊。 如需詳細資訊，請參閱什麼是安全的 AKS 推斷環境。

錯誤：ACRAuthenticationChallengeFailed

之所以發生此錯誤，是因為 Kubernetes 叢集無法連線到工作區 Container Registry 服務來執行驗證挑戰。 請檢查您的網路，特別是 Container Registry 公用網路存取，然後再試一次。 您可以遵循 GetAADTokenFailed 中的疑難排解步驟來檢查網路。

錯誤：ACRTokenExchangeFailed

發生此錯誤的原因是因為尚未授權 Microsoft Entra ID 權杖，因此 Kubernetes 叢集交換 Container Registry 權杖會失敗。 角色指派需要一些時間，所以請稍候一分鐘，然後再試一次。

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

ERROR: KubernetesUnaccessible

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

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

若要減輕此錯誤，您可以輪替叢集的 AKS 憑證。 新的憑證應該在 5 個小時後更新，因此您可以等待 5 個小時再進行重新部署。 如需詳細資訊，請參閱 Azure Kubernetes Service (AKS) 中的憑證輪替。

ERROR: ImagePullLoopBackOff

當您建立或更新 Kubernetes 線上部署時，可能會收到此錯誤，因為您無法從容器登錄下載映像，而導致映像提取失敗。 檢查叢集網路原則和工作區容器登錄，以查看叢集是否可以從容器登錄提取映像。

錯誤：DeploymentCrashLoopBackOff

當您建立或更新 Kubernetes 線上部署時，可能會收到此錯誤，因為使用者容器會在初始化時當機。 發生此錯誤的可能原因有兩個：

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

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

ERROR: KubernetesCrashLoopBackOff

當您建立或更新 Kubernetes 線上端點或部署時，可能會因為下列其中一個原因而收到此錯誤：

  • 一或多個 Pod 卡在 CrashLoopBackoff 狀態。 檢查部署記錄是否存在，以及記錄中是否有錯誤訊息。
  • score.py 中發生錯誤，且容器會在您的評分程式碼初始化時當機。 請遵循錯誤：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 排程到節點。
  • 沒有節點符合節點親和性選取器。

若要減輕此錯誤，請依照下列步驟執行：

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

ERROR: PodOutOfMemory

當您建立或更新線上部署時，可能會收到此錯誤，因為您為部署指定的記憶體限制不足。 若要減輕此錯誤，您可以將記憶體限制設定為較大的值，或使用較大的執行個體類型。

錯誤：InferencingClientCallFailed

當您建立或更新 Kubernetes 線上端點或部署時，可能會收到此錯誤，因為 Kubernetes 叢集的 k8s-extension 無法連線。 在此情況下，請將計算中斷連結，然後重新連結計算。

若要透過重新連結來針對錯誤進行疑難排解，請務必使用與已中斷連結的計算相同的設定來重新連結 (例如計算名稱和命名空間)，以避免其他錯誤。 如果仍然無法運作，請要求可存取叢集的系統管理員使用 kubectl get po -n azureml 來檢查轉送伺服器 Pod 是否正在執行。

模型使用量問題

端點 invoke 作業狀態所產生的常見模型使用量錯誤包括頻寬限制問題、CORS 原則，以及各種 HTTP 狀態碼。

頻寬限制問題

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

若要監視頻寬延遲，請使用計量 [網路位元組] 來了解目前的頻寬使用量。 如需詳細資訊，請參閱監視受控的線上端點。

如果強制執行頻寬限制，則會傳回兩個回應結尾：

  • ms-azureml-bandwidth-request-delay-ms 是要求資料流傳輸所耗費的延遲時間 (以毫秒為單位)。
  • ms-azureml-bandwidth-response-delay-ms 是回應資料流傳輸所耗費的延遲時間 (以毫秒為單位)。

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 預檢要求。

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，請考慮調整 ProbeSettings (部分機器翻譯)，以允許更多時間來探查容器活躍度或整備度。
429 擱置的要求太多 模型目前獲得的要求超過其可處理的要求數。 為了保證順暢的作業，Azure Machine Learning 在任何時間允許最多 2 * max_concurrent_requests_per_instance * instance_count requests 以進行平行處理。 系統會拒絕超過此最大值的要求。

您可以在 request_settings 和 scale_settings 區段底下檢閱模型部署設定，以確認並調整這些設定。 也請確定已正確傳遞環境變數 WORKER_COUNT，如 RequestSettings (部分機器翻譯) 中所述。

如果您在使用自動調整時收到此錯誤，便代表您的模型收到要求的頻率已超過系統所能擴大的速度。 請考慮使用指數輪詢 (英文) 重新傳送要求，讓系統有時間進行調整。 您也可以使用程式碼來計算執行個體計數，以增加執行個體的數目。 結合這些步驟與設定自動調整，以協助確保您的模型已準備好處理湧入的要求。
429 速率限制 每秒的要求數目達到受控線上端點的限制 (英文)。
500 內部伺服器錯誤 Azure Machine Learning 佈建的基礎結構失敗。

Kubernetes 線上端點的常見錯誤碼

下表包含 REST 要求取用 Kubernetes 線上端點時的常見錯誤碼：

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

如何防止 503 狀態碼錯誤

Kubernetes 線上部署支援自動調整，其允許將複本新增至支援的額外負載。 如需詳細資訊，請參閱 Azure Machine Learning 推斷路由器。 擴大或縮小的決策是以目前容器複本的使用量為基礎。

兩個動作有助於防止 503 狀態碼錯誤：變更建立新複本的使用率層級，或變更複本的最小數目。 您可以個別或組合使用這些方法。

  • 將 autoscale_target_utilization 設定為較低的值來變更自動調整建立新複本的使用率目標。 此變更不會讓複本建立得更快，但能以較低的使用率閾值進行。 例如，將值變更為 30%，會導致系統在發生 30% 使用率時建立複本，而不是等待直到服務的使用率達到 70% 的時候。

  • 變更複本數目下限，以提供可處理傳入尖峰的較大集區。

如何計算執行個體計數

若要增加執行個體數目，您可以依照下列方式計算所需的複本：

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 狀態碼。 例如，隨著端點的流量增加，您可能需要增加最小複本數。

如果 Kubernetes 線上端點已使用目前最多的複本，但您仍收到 503 狀態碼，請增加 autoscale_max_replicas 值，以增加複本的數目上限。

網路隔離問題

本節提供常見網路隔離問題的相關資訊。

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

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

若要停用 v1_legacy_mode，請參閱使用 v2 的網路隔離。

重要

在停用 v1_legacy_mode 之前，請先檢查您的網路安全性小組，因為他們可能出於某種原因而加以啟用。

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

使用下列命令來列出工作區的 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 旗標針對部署是否為 disabled。 如果已啟用此旗標，且容器登錄的可見度為私人，則預期會發生此失敗。

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

    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 中。
    • 您可以在安全 Kubernetes 線上端點中找到更多方法來取得端點的 IP 位址。

  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 的解析是否正常運作。

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"

  3. 如果 curl HTTP 失敗或逾時，但 HTTP 可運作，請檢查憑證是否有效。

  4. 如果上述流程無法解析至 A 記錄，請確認解析是否可從 Azure DNS (168.63.129.16) 運作。

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

  5. 如果上述命令成功，請為自訂 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>

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

推斷伺服器問題

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

確認已安裝的套件

請遵循下列步驟來解決已安裝套件的問題。

  1. 收集 Python 環境已安裝套件和版本的相關資訊。

  2. 確認環境檔案中指定的 azureml-inference-server-http Python 套件版本是否符合啟動記錄中顯示的 Azure Machine Learning 推斷 HTTP 伺服器版本。

    在某些情況下，pip 相依性解析程式會安裝非預期的套件版本。 您可能需要執行 pip 來更正已安裝的套件和版本。

  3. 如果您在環境中指定 Flask 或其相依性，請移除這些項目。

    • 相依套件包括 flask、jinja2、itsdangerous、werkzeug、markupsafe 和 click。
    • flask 會列為伺服器套件中的相依性。 最佳方法是允許推斷伺服器安裝 flask 套件。
    • 當推斷伺服器設定為支援新版 Flask 時，伺服器會在套件更新可用時自動接收套件更新。

檢查伺服器版本

azureml-inference-server-http 伺服器套件會發行至 PyPI。 PyPI 頁面 (英文) 會列出變更記錄和所有舊版。

如果您使用舊版套件，請將您的設定更新為最新版本。 下表摘要說明穩定版本、常見問題和建議的調整：

套件版本 描述 問題 解決方案
0.4.x 包含在 20220601 或更早版本的訓練映像，以及從 .1.34 到 1.43 的 azureml-defaults 套件版本。 最新的穩定版本 0.4.13。 針對早於 0.4.11 的伺服器版本，您可能會遇到 Flask 相依性問題，例如 "can't import name Markup from jinja2"。 儘可能升級至 0.4.13 版或 0.8.x 版 (最新版本)。
0.6.x 預安裝於推斷 20220516 及更早版本的映像。 最新的穩定版本為 0.6.1。 N/A N/A
0.7.x 支援 Flask 2。 最新的穩定版本 0.7.7。 N/A N/A
0.8.x 記錄格式已變更。 Python 3.6 支援已結束。 N/A N/A

檢查套件相依性

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 需求。

伺服器啟動期間出現 TypeError

您可能在伺服器啟動期間遇到下列 TypeError：

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 時，就會發生此錯誤。 Flask 2 的支援適用於 azureml-inference-server-http 套件版本 0.7.0 和更新版本，以及azureml-defaults 套件版本 1.44 和更新版本。

  • 如果您未在 Azure Machine Learning Docker 映像中使用 Flask 2 套件，請使用最新版本的 azureml-inference-server-http 或 azureml-defaults 套件。

  • 如果您在 Azure Machine Learning Docker 映像中使用 Flask 2 套件，請確認映像組建版本為 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, Materialization Build:20220708.v2
2022-08-22T17:05:02,188930082+00:00 | gunicorn/run | 
2022-08-22T17:05:02,190557998+00:00 | gunicorn/run |

    映像的建置日期會出現在 Materialization Build 標記法之後。 在上述範例中，映像版本為 20220708 或 2022 年 7 月 8 日。 此範例中的映像與 Flask 2 相容。

    如果您在容器記錄檔中看不到類似的訊息，您的映像已過期且應該更新。 如果您使用計算統一裝置架構 (CUDA) 映像，而且找不到較新的映像，請檢查您的映像是否已在 AzureML-Containers 中淘汰。 您可以找到已取代映像的指定取代項目。

    如果您使用伺服器搭配線上端點，您也可以在 Azure Machine Learning 工作室的 [端點] 頁面上的 [記錄] 中找到記錄。

如果您使用 SDK v1 進行部署，且未在部署組態中明確指定映像，伺服器會套用 openmpi4.1.0-ubuntu20.04 套件與本機 SDK 工具組相符的版本。 不過，安裝的版本可能不是映像的最新可用版本。

針對 SDK 1.43 版，伺服器預設會安裝 openmpi4.1.0-ubuntu20.04:20220616 套件版本，但此套件版本與 SDK 1.43 不相容。 請確定您為部署使用最新的 SDK。

如果您無法更新映像，您可以在環境檔案中釘選 azureml-defaults==1.43 或 azureml-inference-server-http~=0.4.13 項目，以暫時避免問題。 這些項目會指示伺服器使用 flask 1.0.x 安裝舊版。

在伺服器啟動期間出現 ImportError 或 ModuleNotFoundError

在伺服器啟動時，您可能會在特定模組上遇到 ImportError 或 ModuleNotFoundError，例如 opencensus、jinja2、markupsafe 或 click。 下列範例顯示錯誤訊息：

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

當您使用不會將 Flask 相依性釘選到相容版本的伺服器 0.4.10 版或更早版本時，就會發生匯入和模組錯誤。 若要避免此問題，請安裝較新版本的伺服器。

其他常見問題

其他常見的線上端點問題與 conda 安裝和自動調整有關。

Conda 安裝問題

與 MLflow 部署相關的問題一般源自 conda.yml 檔案中所指定與使用者環境安裝相關的問題。

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

  1. 檢查 conda 安裝記錄。 如果容器當機或啟動時間過長，conda 環境更新可能無法正確解析。
  2. 使用 conda env create -n userenv -f <CONDA_ENV_FILENAME> 命令在本機安裝 mlflow conda 檔案。
  3. 如果本機發生錯誤，請嘗試解決 Conda 環境，並在重新部署之前建立功能環境。
  4. 如果容器在本機解析後仍然損毀，則可能是用於部署的 SKU 大小太小。
    • Conda 套件安裝會在執行階段發生，因此如果 SKU 大小太小而無法容納 conda.yml 環境檔案中的所有套件，則容器可能會損毀。
    • Standard_F4s_v2 VM 是不錯的起始 SKU 大小，但視 conda 檔案指定的相依性而定，您可能需要較大的 VM。
    • 針對 Kubernetes 線上端點，Kubernetes 叢集必須有至少四個 vCPU 核心和 8 GB 的記憶體。

自動調整問題

如果您在自動調整時遇到問題，請參閱針對 Azure 監視器自動調整進行疑難排解 (英文)。

針對 Kubernetes 線上端點，Azure Machine Learning 推斷路由器是前端元件，可處理 Kubernetes 叢集上所有模型部署的自動調整。 如需詳細資訊，請參閱自動調整 Kubernetes 推斷路由。

相關內容