バッチ エンドポイントのトラブルシューティング

  • [アーティクル]

適用対象:Azure CLI ml extension v2 (現行)Python SDK azure-ai-ml v2 (現行)

バッチ エンドポイントを使用したバッチ スコアリングでよく発生するエラーを解決する方法について説明します。 この記事では、次のことについて説明します。

バッチ スコアリング ジョブのログについて

ログを取得する

Azure CLI または REST を使用してバッチ エンドポイントを呼び出した後、バッチ スコアリング ジョブが非同期的に実行されます。 バッチ スコアリング ジョブのログは、2 とおりの方法で取得できます。

方法 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. 確認する 1 つ以上のログを選択する

ログの構造について

最上位のログ フォルダーには、azureml-logs と logs の 2 つのフォルダーがあります。

~/azureml-logs/70_driver_log.txt ファイルには、スコアリング スクリプトを起動するコントローラーからの情報が含まれています。

バッチ スコアリング ジョブには分散型の性質があるため、複数の異なるソースからのログが存在します。 ただし、概要情報を提供する、結合されたファイルが 2 つ作成されます。

  • ~/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/:ノードで実行されているすべてのプロセスに関する情報。 1 回のチェックでオペレーティング システムのコマンドが実行され、その結果がファイルに保存されます。 Linux では、コマンドは psです。
      • %Y%m%d%H:サブフォルダー名は、time to hour です。
        • 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")

一般的な問題

次のセクションには、バッチ エンドポイントを開発、利用する過程で遭遇する可能性のある一般的な問題と解決策が示されています。

No module named 'azureml' ('azureml' というモジュールはありません)

ログに記録されたメッセージ: No module named 'azureml'

理由: Azure Machine Learning Batch デプロイでは、パッケージ azureml-core をインストールする必要があります。

解決策: conda 依存関係ファイルに azureml-core を追加します。

出力が既に存在する

理由: Azure Machine Learning バッチ デプロイでは、出力によって生成された predictions.csv ファイルを上書きできません。

解決策: 予測の出力場所が示されている場合は、パスで指定されているファイルが存在しないことを確認します。

エントリ スクリプトの run() 関数に [number] 回のタイムアウトがあった

ログに記録されたメッセージ: No progress update in [number] seconds. No progress update in this check. Wait [number] seconds since last update.

理由: バッチ デプロイは、デプロイが 1 つのバッチの処理を待機する時間を示す timeout 値で構成できます。 バッチの実行にかかる時間がこの値を超えた場合、タスクは中止されます。 中止されたタスクは、これも構成可能な最大回数まで再試行できます。 timeout が再試行のたびに発生した場合、デプロイ ジョブは失敗します。 これらのプロパティは、デプロイごとに構成できます。

解決策: デプロイを更新して、デプロイの timemout 値を増やします。 これらのプロパティは、パラメーター retry_settings で構成されます。 既定では、timeout=30 と retries=3 が構成されています。 timeout の値を決定するときは、各バッチで処理されるファイルの数と、それらの各ファイルのサイズを考慮してください。 より小さいサイズのより多くのミニバッチを考慮して、実行を高速化するために、それらを減らすこともできます。

ScriptExecution.StreamAccess.Authentication

ログに記録されたメッセージ: ScriptExecutionException が StreamAccessException によって発生しました。 StreamAccessException が AuthenticationException によって発生しました。

理由: デプロイが実行されているコンピューティング クラスターでは、データ資産が配置されているストレージをマウントできません。 コンピューティングのマネージド ID には、マウントを実行するためのアクセス許可がありません。

解決策: デプロイが実行されているコンピューティング クラスターに関連付けられている ID に、少なくともストレージ アカウントへのストレージ BLOB データ閲覧者アクセス権があることを確認します。 Azure portal を使用してアクセス レベルを変更できるのは、ストレージ アカウントの所有者だけです。

データセットの初期化に失敗する

ログに記録されるメッセージ: Dataset initialization failed (データセットの初期化に失敗しました): UserErrorException: Message: Cannot mount Dataset(id='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None). データセットのソースは、アクセスできないか、データを含んでいません。

理由: デプロイが実行されているコンピューティング クラスターでは、データ資産が配置されているストレージをマウントできません。 コンピューティングのマネージド ID には、マウントを実行するためのアクセス許可がありません。

解決策: デプロイが実行されているコンピューティング クラスターに関連付けられている ID に、少なくともストレージ アカウントへのストレージ BLOB データ閲覧者アクセス権があることを確認します。 Azure portal を使用してアクセス レベルを変更できるのは、ストレージ アカウントの所有者だけです。

データ セット ノード [code] が、指定された値または既定値を持たないパラメーター dataset_param を参照する

ログに記録されるメッセージ: データ セット ノード [code] が、指定された値または既定値を持たないパラメーター dataset_param を参照しています。

理由: バッチ エンドポイントに提供される入力データ資産がサポートされていません。

解決策: バッチ エンドポイントでサポートされているデータ入力を指定していることを確認します。

User program failed with Exception: Run failed, please check logs for details (例外でユーザー プログラムが失敗しました: 実行に失敗しました。詳細についてはログを確認してください)

ログに記録されるメッセージ: User program failed with Exception: Run failed, please check logs for details (例外でユーザー プログラムが失敗しました: 実行に失敗しました。詳細についてはログを確認してください) logs/readme.txt でログのレイアウトを確認できます。

理由: スコアリング スクリプトの init() 関数または run() 関数の実行中にエラーが発生しました。

解決策: [Outputs + Logs](出力とログ) に移動し、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() から返される成功したミニ バッチ項目がない

ログに記録されるメッセージ:There is no succeeded mini batch item returned from run() (run() から返される成功したミニ バッチ項目がありません) https://aka.ms/batch-inference-documentation で 'response: run()' を確認してください。

理由: バッチ エンドポイントは、予期される形式のデータを run() メソッドに提供できませんでした。 これは、破損したファイルが読み取られているか、入力データとモデルのシグネチャ (MLflow) に互換性がないこと原因である可能性があります。

解決策: 何が起こっているかを理解するには、[Outputs + Logs](出力とログ) に移動し、logs > user > stdout > 10.0.0.X > process000.stdout.txt でファイルを開きます。 Error processing input file などのエラー エントリを探します。 入力ファイルを正しく読み取ることができない理由の詳細が表示されています。

JWT の対象ユーザーは許可されません

コンテキスト: REST API を使用してバッチ エンドポイントを呼び出す場合。

理由: エンドポイント/デプロイの REST API を呼び出すために使用されるアクセス トークンは、別の対象ユーザー/サービスに対して発行されるトークンを示しています。 Microsoft Entra トークンは、特定のアクションに対して発行されます。

解決策: Batch エンドポイント REST API で使用する認証トークンを生成する場合は、resource パラメーターが https://ml.azure.com に設定されていることを確認します。 このリソースは、REST API を使用してエンドポイントを管理するために指定する必要があるリソースとは異なることにご注意ください。 すべての Azure リソース (バッチ エンドポイントを含む) は、それらを管理するためにリソース https://management.azure.com を使用します。 各ケースで適切なリソース URI を使用していることを確認します。 管理 API とジョブ呼び出し API を同時に使用する場合は、2 つのトークンが必要であることに注意してください。 詳細については、「バッチ エンドポイントでの認証 (REST)」を参照してください。

No valid deployments to route to. (ルーティング先の有効なデプロイがありません。) Please check that the endpoint has at least one deployment with positive weight values or use a deployment specific header to route. (エンドポイントに正の重み値を持つデプロイが少なくとも 1 つ存在することを確認するか、デプロイ固有のヘッダーを使用してルーティングしてください。)

理由: 既定のバッチ デプロイが正しく設定されていません。

解決策: 既定のバッチ デプロイが正しく設定されていることを確認します。 既定のバッチ デプロイの更新が必要な場合があります。 詳しくは、「既定のバッチ デプロイを更新する」をご覧ください

制限事項およびサポートされていないシナリオ

バッチ エンドポイントに依存する機械学習ソリューションを設計する場合、一部の構成とシナリオはサポートされない場合があります。

次のワークスペースの構成はサポートされていません。

  • 検査機能が有効になっている Azure Container Registries で構成されたワークスペース。
  • カスタマー マネージド キー (CMK) を持つワークスペース。

次のコンピューティングの構成はサポートされていません。

  • Azure ARC Kubernetes クラスター。
  • Azure Kubernetes クラスターの詳細なリソース要求 (メモリ、vCPU、GPU)。 インスタンス数のみを要求できます。

次の入力タイプはサポートされていません。

  • 表形式データセット (V1)。
  • フォルダーとファイル データセット (V1)。
  • MLtable (V2)。

次の手順