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

適用於:Azure CLI ml 延伸模組第 2 版 (目前)Python SDK azure-ai-ml 第 2 版 (預覽)

重要

SDK v2 目前處於公開預覽狀態。 此預覽版本會在沒有服務等級協定的情況下提供,不建議用於實際執行工作負載。 可能不支援特定功能,或可能已經限制功能。 如需詳細資訊,請參閱 Microsoft Azure 預覽版增補使用條款

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

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

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

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

必要條件

本機部署

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

提示

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

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

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

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

在本機部署過程中,會執行下列步驟:

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

如需詳細資訊,請參閱使用受控線上端點部署在本機的部署和評分機器學習模型

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 大小。

取得容器記錄

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

如要查看容器的記錄輸出,請使用下列 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

根據預設,系統會從推斷伺服器提取記錄。 記錄檔包含來自推斷伺服器的主控台記錄,其中包含來自 `score.py' 程式碼的 print/log 陳述式。

注意

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

您也可以藉由傳遞 –-container storage-initializer 來取得儲存體初始化容器中的記錄。 這些記錄包含是否已成功將程式碼和模型資料下載至容器的資訊。

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

要求追蹤

有三個支援的追蹤標頭:

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

    注意

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

  • x-ms-client-request-id 適用於用戶端追蹤案例。 我們會處理此標頭,以移除非英數位元符號。 此標頭會截斷為 72 個字元。

一般部署錯誤

以下是部署作業狀態中所報告的常見部署錯誤清單。

錯誤:ImageBuildFailure

在建置環境 (Docker 映像) 時,會傳回此錯誤。 您可以檢查組建記錄檔,以取得失敗的詳細資訊。 組建記錄檔位於 Azure Machine Learning 工作區的預設儲存體中。 確切的位置會當作錯誤的一部分傳回。 例如,「組建記錄檔位於 "/azureml/ImageLogs/your-image-id/build.log" 路徑下的 "storage-account-name" 工作區 Blob 存放區中。 在此情況下,"azureml" 是儲存體帳戶中的 Blob 容器名稱。

如果在組建記錄檔中找不到明顯的錯誤,而最後一行是 Installing pip dependencies: ...working...,則錯誤可能是因相依性所造成。 釘選 Conda 檔案中的版本相依性可修正此問題。

我們也建議在雲端中部署之前,請使用本機部署在本機測試您的模型並偵錯。

ERROR: OutOfQuota

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

CPU 配額

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

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

磁碟配額

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

記憶體配額

當模型的記憶體使用量大於可用的記憶體時,就會發生此問題。 嘗試具有更多記憶體的受控線上端點 SKU 清單

角色指派配額

嘗試刪除此訂閱中未使用的角色指派。 您可以在 [存取控制] 功能表中,檢查 Azure 入口網站中的所有角色指派。

端點配額

嘗試刪除此訂閱中某些未使用的端點。

Kubernetes 配額

無法滿足要求的 CPU 或記憶體。 請調整您的要求或叢集。

其他配額

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

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

如要取得錯誤的確切原因,請執行:

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

ERROR: OutOfCapacity

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

ERROR: BadArgument

以下是您可能會遇到此錯誤的原因清單:

資源要求超過限制

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

授權錯誤

當您佈建計算資源之後,Azure 會在部署建立期間嘗試從工作區私人 Azure Container Registry (ACR) 提取使用者容器映像,並將使用者模型和程式碼成品從工作區儲存體帳戶裝載至使用者容器中。

首先,請檢查存取 ACR 是否有權限問題。

為了提取 blob,Azure 會使用受控身分識別來存取儲存體帳戶。

  • 若您使用 SystemAssigned 建立相關聯的端點,則會自動授與 Azure 角色型存取控制 (RBAC) 權限,且不需要進一步的權限。

  • 若您使用 UserAssigned 建立相關聯的端點,使用者的受控身分識別必須具有工作區儲存體帳戶的儲存體 blob 資料讀取器權限。

無法下載使用者容器映像

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

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

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

無法下載使用者模型

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

確定已將模型註冊至與部署相同的工作區。 使用 show 命令或對等 Python 方法顯示工作區中的模型詳細資料。

  • 例如:

    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`
    

azureml-fe 尚未就緒

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

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

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

ERROR: ResourceNotReady

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

  • score.py 發生錯誤。 使用 get-logs 來協助診斷常見問題:
    • 已匯入但不在 conda 環境中的套件。
    • 語法錯誤。
    • init() 方法發生失敗。
  • get-logs 未產生任何記錄,通常表示容器無法啟動。 若要偵錯此問題,請改為嘗試在本機部署
  • 未正確設定整備度或活躍度探查。
  • 容器的環境設定發生錯誤,例如遺漏相依性。
  • 當您遇到 TypeError: register() takes 3 positional arguments but 4 were given 錯誤時,該錯誤很可能是因為 flask v2 與 azureml-inference-server-http 之間的相依性所造成。 如需詳細資訊,請參閱推斷 HTTP 伺服器的常見問題

ERROR: ResourceNotFound

以下是您可能會遇到此錯誤的原因清單:

Resource Manager 找不到資源

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

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

容器登錄授權錯誤

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

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

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

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

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

ERROR: OperationCanceled

以下是您可能會遇到此錯誤的原因清單:

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

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

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

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

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

若在等候幾秒鐘 (最多一分鐘) 後重試作業,系統可能會允許執行作業而不取消。

ERROR: InternalServerError

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

自動調整問題

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

頻寬限制問題

受控線上端點針對每個端點具有頻寬限制。 如需限制設定相關資訊,請參閱使用 Azure Machine Learning 針對資源進行管理和增加配額。 若您的頻寬使用量超過限制,您的要求將會遭到延遲。 如要監視頻寬延遲:

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

HTTP 狀態碼

當您使用 REST 要求存取線上端點時,傳回的狀態碼會符合 HTTP 狀態碼的標準。 以下是端點引動和預測錯誤如何對應至 HTTP 狀態碼的相關詳細資訊。

狀態碼 原因描述 為何會傳回此代碼
200 [確定] 您的模型在延遲界限內執行成功。
401 未經授權 您無權執行要求的動作 (例如分數),或權杖已過期。
404 找不到 您的 URL 不正確。
408 要求逾時 模型執行耗費的時間比模型部署設定 request_settingsrequest_timeout_ms 中提供的逾時更長。
424 模型錯誤 若您的模型容器傳回非 200 回應,則 Azure 會傳回 424。 在端點的 Azure 監視器計量總管上,檢查 Requests Per Minute 計量底下的 Model Status Code 維度。 或是檢查回應標頭 ms-azureml-model-error-statuscodems-azureml-model-error-reason 以取得詳細資訊。
429 速率限制 每秒的要求數目達到受控線上端點的限制
429 擱置的要求太多 模型獲得的要求超過其可處理的要求數。 我們可隨時允許 2 * max_concurrent_requests_per_instance * instance_count 個同時要求。 系統會拒絕其他要求。 您可以在 request_settingsscale_settings 下的模型部署設定中確認這些設定。 若您使用自動調整功能,則模型獲得要求的速度會比系統可擴大的速度還要快。 您可使用自動調整功能,嘗試以指數輪詢重新傳送要求。 這麼做讓系統有時間進行調整。
500 內部伺服器錯誤 Azure ML 佈建的基礎結構失敗。

常見的網路隔離問題

線上端點建立失敗,出現 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
    

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

  3. 如果 nslookup 命令未能解析主機名稱,請檢查虛擬網路的私人 DNS 區域中是否有 A 記錄存在。 若要檢查記錄,請使用下列命令:

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

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

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

無法對線上部署進行評分

  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> 
    

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

後續步驟