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

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

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

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

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

HTTP 狀態碼一節說明當使用 REST 請求對端點進行操作時，呼叫和預測錯誤如何映射至 HTTP 狀態碼。

必要條件

• 具有免費或付費版 Azure Machine Learning 的有效 Azure 訂用帳戶。 取得免費試用 Azure 訂用帳戶。

要求追蹤

有兩個支援的追蹤標頭：

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

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

本機部署

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

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

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

ml_client.begin_create_or_update(online_deployment, local=True)

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

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

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

取得容器記錄

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

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

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

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

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

查看容器的日誌輸出

az ml online-deployment get-logs -g <resource-group> -w <workspace-name> -e <endpoint-name> -n <deployment-name> -l 100

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

az configure --defaults group=<resource-group> workspace=<workspace-name>

az configure --list-defaults

ml_client.online_deployments.get_logs(
    name="<deployment-name>", endpoint_name="<endpoint-name>", lines=100
)

ml_client.online_deployments.get_logs(
    name="<deployment-name>", endpoint_name="<endpoint-name>", lines=100, container_type="storage-initializer"
)

一般部署錯誤

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

• ImageBuildFailure

  • Azure Container Registry 授權失敗
  • 未在具有虛擬網路的私人工作區中設定映像建置計算
  • 映像建置逾時
  • 一般或未知的失敗

• OutOfQuota

  • 中央處理器
  • 叢集
  • 磁碟
  • 記憶體
  • 角色指派
  • 端點
  • 全區域 VM 容量
  • 其他

• BadArgument

  常見於受控線上端點和 Kubernetes 線上端點：

  • 訂用帳戶不存在
  • 啟動工作因授權錯誤而失敗
  • 啟動工作因資源上的角色指派不正確而失敗
  • 啟動工作失敗，因為啟用 mdc 時記憶體帳戶的角色指派不正確
  • 範本函式規格不正確
  • 無法下載使用者容器映像
  • 無法下載使用者模型

  僅限於 Kubernetes 線上端點：

  • 資源要求超過限制
  • Azureml-fe 用於 Kubernetes 的線上端點尚未就緒

• ResourceNotReady

• ResourceNotFound

  • Azure Resource Manager 找不到必要的資源
  • 容器登錄為私人或因其他原因而無法存取

• WorkspaceManagedNetworkNotReady

• OperationCanceled

  • 作業已由另一個優先順序較高的作業取消
  • 作業因為先前的作業正在等候鎖定確認而取消

• SecretsInjectionError

• InternalServerError

如果正在建立或更新 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 授權失敗
• 未在具有虛擬網路的私人工作區中設定映像建置計算
• 映像建置逾時
• 一般或未知的失敗

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 服務時，下列資源可能會用盡配額：

• 中央處理器
• 叢集
• 磁碟
• 記憶體
• 角色指派
• 端點
• 全區域 VM 容量
• 其他

僅適用於 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

ml_client.online_deployments.get_logs(
    name="<deployment-name>", endpoint_name="<endpoint-name>", lines=100
)

ERROR: BadArgument

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

• 訂用帳戶不存在
• 啟動工作因授權錯誤而失敗
• 啟動工作因資源上的角色指派不正確而失敗
• 範本函式規格不正確
• 無法下載使用者容器映像
• 無法下載使用者模型
• 不支援具有私人網路的 MLflow 模型格式

您也可能會在僅使用 Kubernetes 線上端點時收到此錯誤，原因如下：

• 資源要求超過限制
• Azureml-fe for Kubernetes 線上端點尚未就緒

訂用帳戶不存在

參考的 Azure 訂用帳戶必須是現有且有效。 當 Azure 找不到您輸入的訂用帳戶識別碼時，就會發生此錯誤。 此錯誤可能是因為訂用帳戶識別碼中的錯字所致。 再次檢查是否正確輸入訂用帳戶識別碼，並確認該識別碼目前有效。

授權錯誤

在建立部署時佈建計算資源之後，Azure 會從工作區容器登錄提取使用者容器映像，並從工作區儲存體帳戶將使用者模型和程式碼成品掛接至使用者容器。 Azure 會使用受控識別來存取儲存體帳戶和容器登錄。

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

啟用 MDC 時，使用者的受控識別必須具有工作區儲存體帳戶的儲存體 Blob 資料參與者權限。 如需詳細資訊，請參閱 啟用 MDC 時的記憶體 Blob 授權錯誤。

若您使用系統指派的身分識別來建立相關聯的端點，則會自動授與 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>

ml_client.models.get(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`

ml_client.online_deployments.get_logs(
  name="<deployment-name>", endpoint_name="<endpoint-name>", lines=100, container_type="storage-initializer"
)

不支援具有私人網路的 MLflow 模型格式

如果您針對受控線上端點使用舊版網路隔離方法 (英文)，則無法使用具有 MLflow 模型格式的私人網路功能。 如果您需要使用無程式碼部署方法來部署 MLflow 模型，請嘗試使用工作區受控虛擬網路 (英文)。

資源要求超過限制

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

Azureml-fe 尚未就緒

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

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

錯誤：資源未準備好

為了在部署過程中執行您提供的 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: 資源未找到

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

• Azure Resource Manager 找不到必要的資源
• 容器登錄為私人或因其他原因而無法存取

Resource Manager 找不到資源

當 Azure Resource Manager 找不到必要的資源時，就會發生此錯誤。 例如，如果在指定的路徑上找不到儲存體帳戶，您可能會收到此錯誤。 請仔細檢查路徑或名稱規格的正確性和拼字。 如需詳細資訊，請參閱解決找不到資源的錯誤。

容器登錄授權錯誤

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

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

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

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

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

錯誤：工作區管理網路尚未準備好 (WorkspaceManagedNetworkNotReady)

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

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

錯誤: 操作已取消

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

• 作業已由另一個優先順序較高的作業取消
• 作業因為先前的作業正在等候鎖定確認而取消

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

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

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

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

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

ERROR: SecretsInjectionError

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

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

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

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

錯誤：伺服器內部錯誤

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

Kubernetes 部署特有的常見錯誤

身分識別和驗證錯誤：

• ACRSecretError
• TokenRefreshFailed
• GetAADTokenFailed
• ACRAuthenticationChallengeFailed
• ACRTokenExchangeFailed
• Kubernetes 無法存取

Crashloopbackoff 錯誤：

• ImagePullLoopBackOff
• DeploymentCrashLoopBackOff
• KubernetesCrashLoopBackOff

評分指令碼錯誤：

• UserScriptInitFailed
• UserScriptImportError
• UserScriptFunctionNotFound

其他錯誤：

• NamespaceNotFound
• EndpointAlreadyExists
• ScoringFeUnhealthy
• 驗證計分失敗
• 無效部署規格
• PodUnschedulable
• PodOutOfMemory
• InferencingClientCallFailed

錯誤：ACRSecretError

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

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

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

• Kubernetes 叢集的網路設定不正確。 檢查代理伺服器、網路原則或憑證。

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

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

錯誤: TokenRefreshFailed

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

ERROR: 取得 AAD Token 失敗

發生此錯誤的原因是因為 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 服務的同時要求太多。 此錯誤應該是暫時性的，您可以稍後再試一次。

錯誤：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 底下的指示。
• 您的評分處理序需要比部署設定限制更多的記憶體。 您可以嘗試使用較大的記憶體限制來更新部署。

錯誤：NamespaceNotFound

當您建立或更新 Kubernetes 線上端點時，可能會收到此錯誤，因為您 Kubernetes 計算使用的命名空間無法在叢集中使用。 在工作區入口網站中檢查 Kubernetes 計算，並檢查 Kubernetes 叢集中的命名空間。 如果命名空間無法使用，請先將舊版計算中斷連結再重新連結以建立新的計算，並指定已存在於叢集中的命名空間。

錯誤：UserScript 初始化失敗

當您建立或更新 Kubernetes 線上部署時，可能會收到此錯誤，因為您已上傳的 init 檔案中的 函式引發例外狀況。 檢查部署記錄，以詳細查看例外狀況訊息並修正例外狀況。

錯誤：UserScriptImportError

當您建立或更新 Kubernetes 線上部署時，可能會收到此錯誤，因為您上傳的 score.py 檔案匯入無法使用的套件。 檢查部署記錄，以詳細查看例外狀況訊息並修正例外狀況。

錯誤：UserScriptFunctionNotFound

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

錯誤: 找不到端點

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

錯誤：EndpointAlreadyExists

當您建立 Kubernetes 線上端點時，可能會收到此錯誤，因為端點已存在於您的叢集中。 端點名稱應該針對每個工作區和每個叢集都是唯一的，因此請使用另一個名稱來建立端點。

ERROR: ScoringFeUnhealthy

當您建立或更新 Kubernetes 線上端點或部署時，可能會收到此錯誤，因為找不到在叢集中執行的 azureml-fe 系統服務或是其狀況不良。 若要減輕此問題，請重新安裝或更新叢集中的 Azure Machine Learning 延伸模組。

錯誤：驗證評分失敗

當您建立或更新 Kubernetes 線上部署時，可能會收到此錯誤，因為處理模型時評分要求 URL 驗證失敗。 檢查端點 URL，然後嘗試重新部署。

錯誤：無效的部署規格

當您建立或更新 Kubernetes 線上部署時，可能會收到此錯誤，因為部署規格無效。 請檢查錯誤訊息，以確定 instance count 有效。 如果您已啟用自動調整，請確定 minimum instance count 和 maximum instance count 都有效。

ERROR: PodUnschedulable

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

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

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

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

錯誤：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 要求取用受控線上端點時的常見錯誤碼：

Kubernetes 線上端點的常見錯誤碼

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

如何防止 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)

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

網路隔離問題

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

在線端點建立失敗，並出現關於 v1 舊版模式的訊息

受控在線端點是 Azure Machine Learning v2 API 平臺的功能。 如果您的 Azure Machine Learning 工作區已設定為 v1 舊版模式，受控在線端點將無法運作。 具體而言，如果 v1_legacy_mode 工作區設定為 true，則會開啟 v1 舊版模式，且不支援 v2 API。

若要查看如何關閉 v1 舊版模式，請參閱 Azure Resource Manager 上的新 API 平臺的網路隔離變更。

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

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

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

此命令的回應類似於下列 JSON 程式碼:

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

如果的值 bypass 不是 AzureServices，請使用設定 Azure Key Vault 網路設定 中的指引將其設定為 AzureServices。

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

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

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

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

   在回應碼中，確認 status 欄位已設定為 Approved。 如果值不是 Approved，請使用下列命令來核准連線。 用前述命令傳回的識別碼取代 <private-endpoint-connection-ID>。

   az network private-endpoint-connection approve --id <private-endpoint-connection-ID> --description "Approved"
   

無法解析評分端點

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

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

   nslookup <endpoint-name>.<endpoint-region>.inference.ml.azure.com
   

   例如，您的命令看起來可能類似下列命令：

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

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

   附註

   • 針對 Kubernetes 在線端點，端點主機名應該是您 Kubernetes 叢集中指定的 CName （域名）。
   • 如果端點使用 HTTP，IP 位址會包含在端點 URI 中，您可以從 Studio UI 取得。
   • 如需取得端點 IP 位址的詳細資訊，請參閱 使用 FQDN 更新 DNS。

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 <endpoint-name>.<endpoint-region>.inference.ml.azure.com
   

Kubernetes 線上服務端點

1. 檢查 Kubernetes 叢集中的 DNS 設定。

2. 檢查 Azure Machine Learning 推斷路由器 azureml-fe是否如預期般運作。 若要執行這項檢查，請執行下列步驟：

   1. 在 azureml-fe Pod 中執行下列命令：

      kubectl exec -it deploy/azureml-fe -- /bin/bash
      

   2. 執行下列其中一個命令：

      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 HTTPS 命令失敗或逾時，但 HTTP 命令可運作，請檢查憑證是否有效。

4. 如果上述程式無法解析為 A 記錄，請使用下列命令來驗證解析是否可從 Azure DNS 虛擬公用 IP 位址 168.63.129.16 運作：

   dig @168.63.129.16 <endpoint-name>.<endpoint-region>.inference.ml.azure.com
   

5. 如果上述命令成功，請在自訂 DNS 上針對具條件的轉寄站進行 Azure Private Link 的故障排除。

無法對線上部署進行評分

1. 執行下列命令以檢視無法評分的部署狀態：

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

   Succeeded 欄位的值 state 表示部署成功。

2. 若要成功部署，請使用下列命令來檢查是否已將流量指派給部署：

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

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

   秘訣

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

3. 如果流量指派或部署標頭已正確設定，請使用下列命令來取得端點的記錄：

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

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

推斷伺服器問題

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

確認已安裝的套件

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

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

2. 在您的環境檔案中，檢查指定的 Python 套件版本 azureml-inference-server-http 。 在 Azure Machine Learning 推斷 HTTP 伺服器 啟動記錄中，檢查顯示的推斷伺服器版本。 確認這兩個版本相符。

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

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

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

檢查推斷伺服器版本

azureml-inference-server-http 伺服器套件會發行至 PyPI。 PyPI 頁面會列出變更記錄檔和套件的所有版本。

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

檢查套件相依性

azureml-inference-server-http 伺服器套件最相關的相依套件包括：

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

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

推斷伺服器啟動時的 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 套件，請確認映像組建版本為 July 2022 或更新版本。

  您可以在容器記錄中找到映像版本。 例如，請參閱下列記錄語句：

  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 Studio 中找到記錄。 在端點的頁面上，選取 [記錄] 標籤。

如果您使用 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'

當您使用 0.4.10 版或更早版本的推斷伺服器，且未將 Flask 相依套件固定到相容版本時，就會發生匯入和模組錯誤。 若要避免此問題，請安裝更新版本的推斷伺服器。

其他常見問題

其他常見的線上端點問題與 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 推斷路由。

相關內容

• 使用線上端點部署和評分機器學習模型
• 線上端點的安全部署
• 線上端點 YAML 參考
• 針對 Kubernetes 計算進行疑難排解