針對在線端點部署和評分進行疑難解答

  • 發行項

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

瞭解如何解決 Azure 機器學習 在線端點部署和評分的常見問題。

本檔是以您應該進行疑難解答的方式進行結構化：

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

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

必要條件

在本機部署

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

提示

您也可以使用 Azure 機器學習 推斷 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 檔案中指定的相依性而定，可能需要較大的 VM。
    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，從記憶體初始化表達式容器取得記錄。

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

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

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

要求追蹤

有兩個支持的追蹤標頭：

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

    注意

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

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

一般部署錯誤

下列清單列出回報為部署作業狀態一部分的常見部署錯誤：

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

錯誤：ImageBuildFailure

建立環境 （docker 映射） 時，會傳回此錯誤。 您可以檢查組建記錄檔，以取得失敗的詳細資訊。 組建記錄位於 Azure 機器學習 工作區的預設記憶體中。 確切的位置可能會作為錯誤的一部分傳回。 例如： "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 檔案中釘選版本相依性可以修正此問題。

我們也建議您 先在本機 部署，以在本機測試模型並進行偵錯，再部署到雲端。

錯誤：OutOfQuota

下列清單列出在使用 Azure 服務時可能會用盡配額的常見資源：

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

CPU 配額

部署模型之前，您需要有足夠的計算配額。 此配額會定義每個訂用帳戶、每個工作區、每個 SKU 和每個區域可用的虛擬核心數目。 每個部署都會從可用的配額減去，並根據 SKU 的類型，在刪除後再新增。

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

叢集配額

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

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

磁碟配額

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

記憶體配額

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

角色指派配額

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

端點配額

嘗試刪除此訂用帳戶中某些未使用的端點。 如果所有端點都主動使用中，您可以嘗試 要求增加端點限制。 若要深入瞭解端點限制，請參閱使用 Azure 機器學習 在線端點和批次端點的端點配額。

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 機器學習 容量，服務無法布建指定的 VM 大小。 請稍後重試，或嘗試部署到不同的區域。

其他配額

為了在部署中執行 score.py 提供的 ，Azure 會建立包含所有所需資源的 score.py 容器，並在該容器上執行評分腳本。

如果您的容器無法啟動，表示無法進行評分。 容器要求的資源可能比支持的資源 instance_type 還多。 如果是，請考慮更新 instance_type 線上部署的 。

若要取得錯誤的正確原因，請執行：

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

錯誤：BadArgument

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

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

訂閱不存在

輸入的 Azure 訂用帳戶必須是現有的訂用帳戶。 當我們找不到參考的 Azure 訂用帳戶時，就會發生此錯誤。 此錯誤可能是因為訂用帳戶標識碼中的錯字。 請仔細檢查訂用帳戶標識碼是否已正確輸入，且目前為使用中。

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

授權錯誤

布建計算資源之後（在建立部署時），Azure 會嘗試從工作區 Azure Container Registry （ACR） 提取使用者容器映像。 它會嘗試從工作區記憶體帳戶將使用者模型和程式代碼成品掛接至使用者容器。

若要執行這些動作，Azure 會使用 受控識別 來存取記憶體帳戶和容器登錄。

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

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

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

無效的範本函式規格

當範本函式未正確指定時，就會發生此錯誤。 修正原則或移除要解除封鎖的原則指派。 錯誤訊息可能包含原則指派名稱和原則定義，以協助您偵錯此錯誤，以及 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 機器學習 工作區時，我們會設定預設值。 您可以在 Azure 入口網站 或使用 az ml compute show 命令來檢查限制。

azureml-fe 尚未就緒

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

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

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

錯誤：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 伺服器的常見問題。

錯誤：ResourceNotFound

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

Resource Manager 找不到資源

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

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

容器登錄授權錯誤

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

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

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

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

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

錯誤：OperationCanceled

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

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

Azure 作業具有特定優先順序層級，且會從最高到最低執行。 當作業被優先順序較高的另一個作業覆寫時，就會發生此錯誤。

重試作業可能會允許它執行而不取消。

作業已取消，等待鎖定確認

Azure 作業在提交後有短暫的等候期間，其會擷取鎖定，以確保我們不會遇到競爭條件。 當您提交的作業與另一個作業相同時，就會發生此錯誤。 另一項作業目前正在等待確認它已收到鎖定以繼續。 它可能表示您在初始要求之後提交過類似的要求太快。

等候數秒後重試作業，最多一分鐘可能會允許在不取消的情況下執行作業。

錯誤：SecretsInjectionError

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

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

如需詳細資訊，請參閱 在線端點中的秘密插入 （預覽） 和 使用秘密插入 （預覽） 從在線部署存取秘密。

錯誤：InternalServerError

雖然我們盡最大努力提供穩定且可靠的服務，但有時候事情不會按照計劃進行。 如果您收到此錯誤，這表示我們這邊的內容不正確，我們需要加以修正。 提交具有所有相關信息的客戶支援票證，我們可以解決此問題。

Kubernetes 部署特有的常見錯誤

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

有關 crashloopbackoff 的錯誤：

評分文稿的相關錯誤：

其他：

錯誤：ACRSecretError

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

  • 角色指派尚未完成。 在此情況下，請等候幾秒鐘，稍後再試一次。
  • Azure ARC（適用於 Azure Arc Kubernetes 叢集）或 Azure 機器學習 擴充功能 （For AKS） 未正確安裝或設定。 嘗試檢查 Azure ARC 或 Azure 機器學習 擴充功能組態和狀態。
  • Kubernetes 叢集的網路設定不正確，請檢查 Proxy、網路原則或憑證。
    • 如果您使用私人 AKS 叢集，則必須為 AKS vnet 中的 ACR、記憶體帳戶、工作區設定私人端點。
  • 請確定您的 Azure 機器學習 擴充功能版本大於 v1.1.25。

錯誤：TokenRefreshFailed

此錯誤是因為擴充功能無法從 Azure 取得主體認證，因為 Kubernetes 叢集身分識別未正確設定。 重新安裝 Azure 機器學習 擴充功能，然後再試一次。

錯誤：GetAADTokenFailed

此錯誤是因為 Kubernetes 叢集要求 Azure AD 令牌失敗或逾時，請檢查您的網路輔助功能，然後再試一次。

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

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

錯誤：ACRAuthenticationChallengeFailed

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

您可以依照 GetAADTokenFailed 中的疑難解答步驟來檢查網路。

錯誤：ACRTokenExchangeFailed

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

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

錯誤：KubernetesUnaccessible

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

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

若要減輕此錯誤，您可以：

錯誤：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 機器學習 擴充功能。

錯誤：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 機器學習 推斷路由器是一個前端元件，可處理 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_timeout_msrequest_settings所提供的逾時時間。
424 模型錯誤 如果您的模型容器傳回非 200 回應，Azure 會傳回 424。 Model Status Code在端點的 Azure 監視器計量總管的計量底下Requests Per Minute檢查維度。 或檢查響應標頭 ms-azureml-model-error-statuscode 和 ms-azureml-model-error-reason 以取得詳細資訊。 如果 424 隨附即時或整備探查失敗，請考慮調整 探查設定 ，以允許較長的時間探查容器的活躍度或整備程度。
429 太多擱置的要求 您的模型目前收到的要求數目超過其所能處理的要求。 Azure 機器學習 已實作一個系統，允許在任何指定時間平行處理最多2 * max_concurrent_requests_per_instance * instance_count requests，以確保順暢的作業。 超過此最大值的其他要求會遭到拒絕。 您可以在request_settings和scale_settings區段底下檢閱模型部署設定，以確認並調整這些設定。 此外，如 Request 的 YAML 定義中所述 設定，請務必確保已正確傳遞環境變數WORKER_COUNT。

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

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 機器學習 布建的基礎結構失敗。

如何防止 503 狀態碼

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

有兩件事有助於防止 503 狀態代碼：

提示

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

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

    重要

    這項變更不會讓複本建立 得更快。 相反地，它們會以較低的使用率閾值建立。 當發生 30% 使用率時，將值變更為 30% 會建立複本，而不是等到使用服務 70% 為止。

    如果 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 機器學習 工作區，以停用 v2 API。 受控在線端點是 v2 API 平臺的功能，如果 v1_legacy_mode 已啟用工作區，將無法運作。

重要

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

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

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

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

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

此指令的回應類似下列 JSON 檔案：

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

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

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

注意

當您針對受控在線端點使用舊版網路隔離方法時，會套用此問題，其中 Azure 機器學習 會在端點下為每個部署建立受控虛擬網路。

  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 機器學習 工作區的虛擬網路。

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

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

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

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

在本節中，我們提供 Azure 機器學習 推斷 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 的相依性關聯釘選至相容的版本。 伺服器的最新版本已修正此問題。

下一步