針對批次端點進行疑難排解

  • 發行項

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

瞭解如何針對使用 批次端點 進行批次評分時可能會遇到的常見錯誤進行疑難解答並加以解決。 在本文中，您將了解：

了解批次評分作業的記錄

取得記錄

使用 Azure CLI 或 REST 叫用批次端點後，批次評分作業將以非同步方式執行。 有兩個選項可取得批次評分作業的記錄。

選項 1：將記錄串流至本機主控台

您可以執行下列命令，將系統產生的記錄串流至主控台。 只會串流資料夾中的 azureml-logs 記錄。

az ml job stream --name <job_name>

選項 2：在工作室中檢視記錄

若要在工作室中取得執行的連結，請執行：

az ml job show --name <job_name> --query services.Studio.endpoint -o tsv
  1. 使用上述命令傳回的值，在工作室中開啟作業。
  2. 選擇 [batchscoring]
  3. 開啟 [輸出 + 記錄] 索引標籤
  4. 選擇您想要檢閱的一或多個記錄

了解記錄結構

有兩個最上層記錄資料夾：azureml-logs 和 logs。

檔案 ~/azureml-logs/70_driver_log.txt 包含啟動評分指令碼的控制器所提供的資訊。

由於批次評分作業的分散式本質，記錄來自幾個不同來源。 不過，已建立兩個合併檔案來提供高階資訊：

  • ~/logs/job_progress_overview.txt：此檔案提供的高階資訊是關於目前為止建立的迷你批次 (也稱為工作) 數目，以及目前為止處理的迷你批次數目。 當迷你批次結束時，記錄會記錄作業的結果。 如果作業失敗，則會顯示錯誤訊息，以及應從何處開始進行疑難排解。

  • ~/logs/sys/master_role.txt：此檔案提供執行中作業的主體節點 (也稱為協調器) 檢視。 此記錄提供有關建立工作、進度監視、作業結果的資訊。

若要概略了解指令碼中的錯誤，可以參考：

  • ~/logs/user/error.txt：此檔案會嘗試彙總指令碼中的錯誤。

如需指令碼中所含錯誤的詳細資訊，可以參考：

  • ~/logs/user/error/：此檔案包含載入和執行輸入腳本時所擲回例外狀況的完整堆疊追蹤。

如果您需要完整了解每個節點執行分數指令碼的方式，請查看每個節點的個別程序記錄。 程序記錄會位於 sys/node 資料夾中，依背景工作節點分組：

  • ~/logs/sys/node/<ip_address>/<process_name>.txt：此檔案提供背景工作角色挑選或完成的每個迷你批次的詳細資訊。 針對每個迷你批次，此檔案會包含：

    • 背景工作程序的 IP 位址和 PID。
    • 項目總數、成功處理的項目數，以及失敗項目數。
    • 開始時間、持續時間、處理時間和執行方法時間。

針對每個節點，您也可以檢視定期檢查資源使用量的結果。 記錄檔和安裝檔案位於此資料夾中：

  • ~/logs/perf：設定 --resource_monitor_interval 來變更檢查間隔 (秒)。 預設間隔為 600，大約 10 分鐘。 若要停止監視，請將值設定為 0。 每個 <ip_address> 資料夾包含：

    • os/：節點中所有執行中程序的相關資訊。 一項檢查會執行作業系統命令，並將結果儲存至檔案。 在 Linux 上，命令為 ps。
      • %Y%m%d%H：子資料夾名稱是精確至小時的時間。
        • processes_%M：檔案的結尾是檢查時間的分鐘。
    • node_disk_usage.csv：節點的詳細磁碟使用量。
    • node_resource_usage.csv：節點的資源使用量概觀。
    • processes_resource_usage.csv：每個程序的資源使用量概觀。

如何在評分指令碼中記錄

您可以在評分指令碼中使用 Python 記錄。 記錄儲存在 logs/user/stdout/<node_id>/processNNN.stdout.txt 中。

import argparse
import logging

# Get logging_level
arg_parser = argparse.ArgumentParser(description="Argument parser.")
arg_parser.add_argument("--logging_level", type=str, help="logging level")
args, unknown_args = arg_parser.parse_known_args()
print(args.logging_level)

# Initialize Python logger
logger = logging.getLogger(__name__)
logger.setLevel(args.logging_level.upper())
logger.info("Info log statement")
logger.debug("Debug log statement")

常見問題

下列區段包含在開發和取用批次端點期間可能會看到的常見問題和解決方案。

沒有名為 'azureml' 的模組

記錄的訊息：No module named 'azureml'。

原因：Azure Machine Learning 批次部署需要安裝 azureml-core 套件。

解決方案：將 azureml-core 新增至 conda 相依性檔案。

輸出已經存在

原因：Azure Machine Learning 批次部署無法覆寫輸出所產生的 predictions.csv 檔案。

解決方案：如果您指出預測的輸出位置，請確定路徑會導向不存在的檔案。

輸入腳本中的 run() 函式已逾時 [數字] 次

記錄的訊息：No progress update in [number] seconds. No progress update in this check. Wait [number] seconds since last update.

原因：批次部署可以設定 timeout 值，指出處理單一批次之前部署應該等候的時間。 如果批次的執行時間超過此值，工作就會中止。 中止的工作可以重試至設定的次數上限。 如果在每次重試時都發生 timeout，則部署作業會失敗。 您可以為每個部署設定這些屬性。

解決方案：藉由更新部署來增加部署的 timemout 值。 這些屬性會在 retry_settings 參數中設定。 預設會設定 timeout=30 和 retries=3。 決定 timeout 的值時，請將每個批次上正在處理的檔案數目和每個檔案的大小納入考慮。 您也可以減少這些數目，以考慮較小的迷你批次，進而更快速地執行。

ScriptExecution.StreamAccess.Authentication

記錄的訊息：ScriptExecutionException 是由 StreamAccessException 所造成。 StreamAccessException 是由 AuthenticationException 所造成。

原因：部署執行所在的計算叢集無法掛接資料資產所在的儲存體。 計算的受控識別沒有執行掛接的權限。

解決方案：請確定與部署執行所在的計算叢集相關聯的身分識別，至少具有儲存體帳戶的儲存體 Blob 資料讀者存取權。 只有儲存體帳戶擁有者可以透過 Azure 入口網站變更您的存取層級。

資料集初始化失敗

記錄的訊息：資料集初始化失敗：UserErrorException：訊息：無法掛接資料集 (識別碼='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'、名稱='None'、版本=None)。 資料集的來源無法存取或未包含任何資料。

原因：部署執行所在的計算叢集無法掛接資料資產所在的儲存體。 計算的受控識別沒有執行掛接的權限。

解決方案：請確定與部署執行所在的計算叢集相關聯的身分識別，至少具有儲存體帳戶的儲存體 Blob 資料讀者存取權。 只有儲存體帳戶擁有者可以透過 Azure 入口網站變更您的存取層級。

數據集節點 [程序代碼] 會參考 dataset_param 沒有指定值或預設值的參數

訊息記錄：數據集節點 [程序代碼] 會參考 dataset_param 沒有指定值或預設值的參數。

原因：不支援提供給批次端點的輸入資料資產。

解決方案：務必提供批次端點支援的資料輸入。

使用者程式失敗，發生例外狀況：執行失敗，請檢查記錄以取得詳細資料

記錄的訊息：使用者程式失敗，發生例外狀況：執行失敗，請檢查記錄以取得詳細資料。 您可以檢查 logs/readme.txt 的記錄配置。

原因：執行評分指令碼的 init() 或 run() 函式時發生錯誤。

解決方案：移至 [輸出 + 記錄]，然後在 logs > user > error > 10.0.0.X > process000.txt 開啟檔案。 您會看到 init() 或 run() 方法所產生的錯誤訊息。

ValueError：沒有要串連的物件

記錄的訊息：ValueError：沒有要串連的物件。

原因：產生的迷你批次中的所有檔案都會損毀，或為不支援的檔案類型。 請記住，MLflow 模型支援檔案類型的子集，如部署至批次推斷時的考量所記載。

解決方案：移至 logs/usr/stdout/<process-number>/process000.stdout.txt 檔案並尋找 ERROR:azureml:Error processing input file 之類的項目。 如果不支援檔類型，請檢閱支援的檔案清單。 您可能需要變更輸入數據的檔類型，或藉由提供評分腳本來提供評分腳本，如搭配評分腳本使用 MLflow 模型中所述來自定義部署。

run() 未傳回成功的迷你批次項目

記錄的訊息：run() 未傳回成功的迷你批次項目。 請檢查 https://aka.ms/batch-inference-documentation 中的 'response: run()'。

原因：批次端點無法提供預期格式的資料給 run() 方法。 這可能是因為讀取損毀的檔案，或與模型簽章的輸入數據不相容（MLflow）。

解決方案：若要了解可能發生的情況，請移至 [輸出 + 記錄]，然後在 logs > user > stdout > 10.0.0.X > process000.stdout.txt 開啟檔案。 尋找類似 Error processing input file 的錯誤項目。 您應該會發現為何無法正確讀取輸入檔的詳細資料。

不允許 JWT 中的對象

內容：使用批次端點的 REST API 叫用批次端點。

原因：用來叫用端點/部署 REST API 的存取權杖指示一個為不同物件/服務發出的權杖。 系統會針對特定動作發出 Microsoft Entra 權杖。

解決方案：產生要與批次端點 REST API 搭配使用的驗證權杖時，請確定 resource 參數已設定為 https://ml.azure.com。 請注意，此資源與使用 REST API 管理端點所需的資源不同。 所有 Azure 資源 (包括批次端點) 都會使用 https://management.azure.com 資源來進行管理。 務必在每個案例上使用正確的資源 URI。 請注意，如果您想要同時使用管理 API 和作業叫用 API，您將需要兩個權杖。 如需詳細資訊，請參閱：批次端點上的驗證 (REST)。

沒有要路由傳送至的有效部署。 請檢查端點至少有一個部署具有正加權值，或使用部署特定標頭來路由傳送。

原因：未正確設定預設批次部署。

解決方案：確定已正確設定預設批次部署。 您可能需要更新預設批次部署。 如需詳細資訊，請參閱：更新預設批次部署

限制和不支援的案例

設計依賴批次端點的機器學習解決方案時，可能不支援某些設定和案例。

不支援下列工作區設定：

  • 已啟用隔離功能的 Azure 容器登錄所設定的工作區。
  • 具有客戶自控金鑰 (CMK) 的工作區。

不支援下列計算設定：

  • Azure ARC Kubernetes 叢集。
  • Azure Kubernetes 叢集的細微資源要求 (記憶體、vCPU、GPU)。 只能要求執行個體計數。

不支援下列輸入類型：

  • 表格式資料集 (V1)。
  • 資料夾和檔案資料集 (V1)。
  • MLtable (V2)。

下一步