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

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

この記事では、Azure Machine Learning でのバッチ スコアリングにバッチ エンドポイントを使用するときの一般的なエラーのトラブルシューティングに関するガイダンスを提供します。 次のセクションでは、バッチ スコアリング ログを分析して、考えられる問題とサポートされていないシナリオを特定する方法について説明します。 推奨される解決策を確認して、一般的なエラーを解決することもできます。

バッチ スコアリング ジョブのログを取得する

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

• オプション 1: ジョブ ログをローカル コンソールにストリーミングします。 azureml-logs フォルダー内のログのみがストリーミングされます。

  次のコマンドを実行すると、システム生成のログをコンソールにストリーミングできます。 <job_name> パラメーターをバッチ スコアリング ジョブの名前に置き換えます。

  az ml job stream --name <job_name>
  

• オプション 2: Azure Machine Learning スタジオでジョブ ログを表示します。

  次のコマンドを実行して、スタジオで使用するジョブのリンクを取得します。 <job_name> パラメーターをバッチ スコアリング ジョブの名前に置き換えます。

  az ml job show --name <job_name> --query services.Studio.endpoint -o tsv
  

  1. スタジオでジョブのリンクを開きます。

  2. ジョブのグラフで、[batchscoring] ステップを選択します。

  3. [出力 + ログ] タブで、確認するログを 1 つ以上選択します。

ログ ファイルを確認する

Azure Machine Learning では、バッチ スコアリング ジョブのトラブルシューティングに役立つさまざまな種類のログ ファイルとその他のデータ ファイルを取得できます。

バッチ スコアリング ログ用の 2 つの最上位フォルダーは、azureml-logs と logsです。 スコアリング スクリプトを起動するコントローラーからの情報は、~/azureml-logs/70_driver_log.txt ファイルに格納されています。

情報の概要を調査する

バッチ スコアリング ジョブはその性質上分散しているので、ログは複数のソースに由来していますが、2 つの結合されたファイルから情報の概要を得られます。

エラーのスタック トレース データを調査する

その他のファイルでは、スクリプトに含まれている可能性のあるエラーに関する情報が得られます。

ノードごとのプロセス ログを調査する

各ノードがどのようにスコア スクリプトを実行しているかを完全に理解するには、各ノードの個々のプロセス ログを調べます。 プロセス ログは、~/logs/sys/node フォルダーに格納され、ワーカー ノードごとにグループ化されます。

このフォルダーには、<ip_address>/ サブフォルダーがあり、各ミニ バッチに関する詳細情報を含む <process_name>.txt ファイルが格納されます。 ワーカーがミニ バッチを選択または完了すると、フォルダーの内容が更新されます。 ミニ バッチごとに、ログ ファイルには次のものが含まれます。

• ワーカー プロセスの IP アドレスとプロセス ID (PID)。
• 項目の総数、正常に処理された項目の数、および失敗した項目の数。
• 開始時刻、期間、処理時間、および実行メソッドの時間。

ノードごとの定期的なチェックを調査する

また、各ノードのリソース使用率の定期的チェックの結果を確認することもできます。 ログ ファイルとセットアップ ファイルは、~/logs/perf フォルダーに格納されます。

チェック間隔を秒単位で変更するには、--resource_monitor_interval パラメーターを使用します。

• 既定値を使用: 既定の間隔は 600 秒 (約 10 分) です。
• チェックの停止: ノードのチェック実行を停止するには、値を 0 に設定します。

このフォルダーには、各ミニ バッチに関する <ip_address>/ サブフォルダーが含まれています。 ワーカーがミニ バッチを選択または完了すると、フォルダーの内容が更新されます。 ミニ バッチごとに、フォルダーには次の項目が含まれます。

スコアリング スクリプトにログ記録を追加する

スコアリング スクリプトで Python ログを使用できます。 これらのログは、logs/user/stdout/<node_id>/process<number>.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 というモジュールがない

Azure Machine Learning のバッチ デプロイでは、インストールに azureml-core パッケージが必要です。

ログに記録されたメッセージ: "azuremlという名前のモジュールがありません。"

理由: azureml-core パッケージがインストールに見つからないようです。

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

予測ファイルに出力がない

バッチ デプロイでは、predictions.csv ファイルを格納する空のフォルダーが必要です。 デプロイにおいて、指定したフォルダー内に既存のファイルがある場合、プロセスによってファイルの内容が新しい出力に置き換えられたり、結果を含む新しいファイルが作成されたりすることはありません。

ログに記録されたメッセージ: ログ記録されたメッセージがありません。

理由: バッチ デプロイにより、既存の predictions.csv ファイルを上書きすることはありません。

解決策: プロセスで予測の出力フォルダーの場所が指定されている場合は、そのフォルダーに既存の predictions.csv ファイルが含まれていないことを確認します。

バッチ 処理がタイムアウトする

バッチ デプロイでは、timeout 値を使用して、各バッチ プロセスが完了するまでのデプロイの待機時間を決定します。 あるバッチの実行が指定されたタイムアウトを超えると、バッチ デプロイはそのプロセスを中止します。

中止されたプロセスは、max_retries 値で指定された最大試行回数まで再試行されます。 再試行のたびにタイムアウト エラーが発生した場合、そのデプロイ ジョブは失敗します。

retry_settings パラメーターを使用すると、各デプロイの timeout プロパティと max_retries プロパティを構成できます。

ログに記録されたメッセージ: "[数値] 秒で進行状況が更新されませんでした。 このチェックの進行状況は更新されません。 最後の更新から [数値] 秒間待ちます。"

理由: バッチ実行が、指定されたタイムアウトと再試行の最大数を超えています。 このアクションは、エントリ スクリプトの run() 関数の失敗に対応します。

解決策: デプロイの timeout 値を増やします。 既定では、timeout 値は 30、max_retries 値は 3 です。 デプロイに適した timeout 値を決定するには、各バッチで処理するファイルの数とファイル サイズを考慮します。 処理するファイルの数を減らすか、小さいサイズのミニ バッチを生成して対応できます。 こうすることで、実行時間を短縮できます。

ScriptExecution.StreamAccess.Authentication で例外発生

バッチ デプロイを成功させるには、コンピューティング クラスターのマネージド ID にデータ アセット ストレージをマウントするアクセス許可が必要です。 マネージド ID に十分なアクセス許可が付与されていない場合、スクリプトによって例外が発生します。 このエラーが原因で、データ アセット ストレージのマウントが失敗する場合もあります。

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

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

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

データセットの初期化に失敗し、データセットをマウントできない

バッチ デプロイ プロセスでは、データ アセットにマウントされたストレージが必要です。 ストレージがマウントされない場合、データセットを初期化できません。

ログに記録されたメッセージ: "データセットの初期化に失敗: UserErrorException: メッセージ: データセットをマウントできません (ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None)。 データセットのソースにアクセスできないか、データが含まれていません。"

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

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

dataset_param に指定された値または既定値がありません。

バッチのデプロイ中に、データ セットのノードは dataset_param パラメーターを参照します。 デプロイを続行するには、パラメーターに値を割り当てるか、既定値を指定する必要があります。

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

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

解決策: デプロイ スクリプトで、バッチ エンドポイントでサポートされているデータ入力が行われることを確認します。

ユーザー プログラムでエラーが発生したり、実行に失敗したりする

バッチ デプロイのスクリプト実行中に、init() または run() 関数でエラーが発生した場合、ユーザー プログラムまたは実行が失敗する可能性があります。 生成されたログ ファイルでエラーの詳細を確認できます。

ログに記録されたメッセージ: "ユーザー プログラムが例外で失敗しました: 実行に失敗しました。 詳細については、ログを確認してください。 ログのレイアウトについては、logs/readme.txt で確認できます。"

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

解決策: 次の手順に従って、関数のエラーに関する詳細を見つけます。

1. Azure Machine Learning スタジオで、失敗したバッチ デプロイ ジョブの実行に移動し、[出力とログ] タブを選択します。

2. ファイル logs>user>error><node_identifier>>process<number>.txt を開きます。

3. init() または run() 関数によって生成されたエラー メッセージを見つけます。

ValueError: 連結するオブジェクトがない

バッチ デプロイを成功させるには、ミニバッチ内の各ファイルが有効であり、サポートされているファイルの種類で実装されている必要があります。 MLflow モデルでは、ファイルの種類のサブセットのみがサポートされることに注意してください。 詳細については、「バッチ推論にデプロイするときの考慮事項」を参照してください。

ログに記録されたメッセージ: ValueError: 連結するオブジェクトがありません。"

理由: 生成されたミニ バッチ内のすべてのファイルが破損しているか、ファイルの種類がサポートされていません。

解決策: 次の手順に従って、問題が起こったファイルの詳細を見つけます。

1. Azure Machine Learning スタジオで、失敗したバッチ デプロイ ジョブの実行に移動し、[出力とログ] タブを選択します。

2. ファイル logs>user>stdout><node_identifier>>process<number>.txt を開きます。

3. "ERROR:azureml:Error processing input file" など、ファイル入力エラーが記述されたエントリを探します。

ファイルの種類がサポートされていない場合、サポートされているファイルの一覧を確認します。 入力データのファイルの種類を変更したり、スコアリング スクリプトによりデプロイをカスタマイズしたりする必要がある場合があります。 詳しくは、スコアリング スクリプトでの MLflow モデルの使用をご覧ください。

成功したミニ バッチなし

バッチ デプロイ プロセスでは、バッチ エンドポイントには run() 関数で想定される形式のデータが必要です。 入力ファイルが破損している場合、またはモデル シグネチャと互換性がない場合、run() 関数はミニ バッチを正常に返しません。

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

理由: バッチ エンドポイントは、run() メソッドに予期される形式のデータを渡しませんでした。 この問題は、破損したファイルが読み込まれたか、入力データがモデルのシグネチャ (MLflow) と互換性がない場合に発生することがあります。

解決策: 次の手順に従って、失敗したミニ バッチに関する詳細を見つけます。

1. Azure Machine Learning スタジオで、失敗したバッチ デプロイ ジョブの実行に移動し、[出力とログ] タブを選択します。

2. ファイル logs>user>stdout><node_identifier>>process<number>.txt を開きます。

3. ミニ バッチの入力ファイルエラーを説明するエントリを探します ("Error processing input file." など)。詳細には、入力ファイルを正しく読み取れなかった理由が記載されています。

対象ユーザーまたはサービスが許可されない

Microsoft Entra トークンは、許可されたユーザー (対象ユーザー)、サービス、リソースを識別する特定のアクションに対して発行されます。 バッチ エンドポイント REST API の認証トークンでは、resource パラメーターを https://ml.azure.comに設定する必要があります。

ログに記録されたメッセージ: ログ記録されたメッセージがありません。

理由: 別の対象ユーザーまたはサービスに対して発行されたトークンを使用して、バッチ エンドポイントとデプロイに対して REST API を呼び出そうとしています。

解決策: この認証の問題を解決するには、次の手順に従います。

1. バッチ エンドポイント REST API の認証トークンを生成する際、resource パラメーターを https://ml.azure.comに設定します。

   このリソースは、REST API のエンドポイントを管理するために使用するリソースとは異なることに注意してください。 すべての Azure リソース (バッチ エンドポイントを含む) は、管理にリソース https://management.azure.com を使用します。

2. バッチ エンドポイントとデプロイに対して REST API を呼び出す場合は、別の対象ユーザーまたはサービスに対して発行されたトークンではなく、バッチ エンドポイント REST API に対して発行されたトークンを使用するように注意してください。 いずれの場合も、正しいリソース URI を使用していることを確認します。

管理 API とジョブ呼び出し API を同時に使用する場合は、2 つのトークンが必要となります。 詳細については、「バッチ エンドポイントでの認証 (REST)」を参照してください。

ルーティング先の有効なデプロイがない

バッチ デプロイを成功させるには、バッチ エンドポイントに少なくとも 1 つの有効なデプロイ ルートが必要です。 標準の方法としては、defaults.deployment_name パラメーターを使用して既定のバッチデプロイを定義します。

ログに記録されたメッセージ: "ルーティング先の有効なデプロイがありません。 エンドポイントに正の重み値を持つデプロイが少なくとも 1 つ存在することを確認するか、デプロイ固有のヘッダーを使用してルーティングしてください。"

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

解決策: ルーティングの問題を解決するには、次のいずれかの方法を使用します。

• defaults.deployment_name パラメーターで正しい既定のバッチ デプロイが定義されていることを確認します。 詳細については、「既定のバッチデプロイを更新する」を参照してください。

• デプロイ固有のヘッダーを使用してルートを定義します。

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

バッチ エンドポイントに依存する機械学習デプロイ ソリューションを設計する場合は、一部の構成とシナリオがサポートされていないことに注意してください。 次のセクションでは、サポートされていないワークスペースとコンピューティング リソースおよび、無効な種類の入力ファイルを特定します。

サポートされていないワークスペースの構成

次のワークスペース構成は、バッチデプロイではサポートされていません。

• 検査機能が有効になっている Azure コンテナー レジストリで構成されたワークスペース。
• カスタマー マネージド キーのあるワークスペース。

サポートされていないコンピューティング構成

バッチデプロイでは、次のコンピューティング構成はサポートされていません。

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

サポートされていない入力ファイルの種類

バッチデプロイでは、次の入力ファイルの種類はサポートされていません。

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

関連するコンテンツ

• バッチ デプロイ用のスコアリング スクリプトを作成する
• バッチ エンドポイントでの認可
• バッチ エンドポイントでのネットワークの分離