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

[アーティクル]
09/03/2024

適用対象: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/job_progress_overview.txt	作成されたミニバッチ (tasksとも呼ばれます) の現在の数と、処理されたミニバッチの現在の数に関する概要情報が得られます。ミニバッチの処理が終了すると、ログにはジョブの結果が記録されます。ジョブが失敗した場合は、エラーメッセージと、トラブルシューティングを始めるべき場所が示されます。
~/logs/sys/master_role.txt	実行中のジョブのプリンシパルノード (オーケストレーターとも呼ばれます) を可視化できます。このログには、タスクの作成、進行状況の監視、ジョブの結果に関する情報が含まれます。

ファイル

説明

~/logs/job_progress_overview.txt

作成されたミニバッチ (tasksとも呼ばれます) の現在の数と、処理されたミニバッチの現在の数に関する概要情報が得られます。ミニバッチの処理が終了すると、ログにはジョブの結果が記録されます。ジョブが失敗した場合は、エラーメッセージと、トラブルシューティングを始めるべき場所が示されます。

~/logs/sys/master_role.txt

実行中のジョブのプリンシパルノード (オーケストレーターとも呼ばれます) を可視化できます。このログには、タスクの作成、進行状況の監視、ジョブの結果に関する情報が含まれます。

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

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

ファイル	説明
~/logs/user/error.txt	スクリプト内のエラーの要約が含まれています。
~/logs/user/error/*	エントリスクリプトの読み込み中および実行中にスローされた例外の詳細なスタックトレースが含まれています。

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

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

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

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

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

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

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

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

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

ファイルまたはフォルダー	説明
os/	ノードで実行されているすべてのプロセスに関する情報が格納されます。 1 回のチェックでオペレーティングシステムのコマンドが実行され、その結果がファイルに保存されます。 Linux では、コマンドは `ps`です。このフォルダーには次の項目が格納されています。 - %Y%m%d%H: 1 つ以上のプロセスチェックファイルを含むサブフォルダー。サブフォルダー名は、チェックの作成日時 (年、月、日、時) です。 processes_%M: サブフォルダー内のファイル。このファイルは、プロセスチェックに関する詳細を示します。ファイル名は、チェックの作成時刻を基準としたチェック時間 (分) で終わります。
node_disk_usage.csv	ノードのディスク使用量に関する詳細を示します。
node_resource_usage.csv	ノードのリソース使用状況の概要を示します。
processes_resource_usage.csv	各プロセスのリソース使用状況の概要を示します。

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

スコアリングスクリプトで 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)。データセットのソースにアクセスできないか、データが含まれていません。"

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

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

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

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

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

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

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

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

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

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

Azure Machine Learning スタジオで、失敗したバッチデプロイジョブの実行に移動し、[出力とログ] タブを選択します。
ファイル logs>user>error><node_identifier>>process<number>.txt を開きます。
init() または run() 関数によって生成されたエラーメッセージを見つけます。

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

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

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

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

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

Azure Machine Learning スタジオで、失敗したバッチデプロイジョブの実行に移動し、[出力とログ] タブを選択します。
ファイル logs>user>stdout><node_identifier>>process<number>.txt を開きます。
"ERROR:azureml:Error processing input file" など、ファイル入力エラーが記述されたエントリを探します。

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

成功したミニバッチなし

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

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

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

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

Azure Machine Learning スタジオで、失敗したバッチデプロイジョブの実行に移動し、[出力とログ] タブを選択します。
ファイル logs>user>stdout><node_identifier>>process<number>.txt を開きます。
ミニバッチの入力ファイルエラーを説明するエントリを探します ("Error processing input file." など)。詳細には、入力ファイルを正しく読み取れなかった理由が記載されています。

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

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

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

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

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

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

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

次の方法で共有

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

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

ログファイルを確認する

情報の概要を調査する

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

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

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

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

一般的なエラーを解決する

azureml というモジュールがない

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

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

ScriptExecution.StreamAccess.Authentication で例外発生

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

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

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

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

成功したミニバッチなし

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

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

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

ログ ファイルを確認する

情報の概要を調査する

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

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

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

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

一般的なエラーを解決する

azureml というモジュールがない

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

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

ScriptExecution.StreamAccess.Authentication で例外発生

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

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

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

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

成功したミニ バッチなし

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

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

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

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

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

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

関連するコンテンツ

フィードバック

その他のリソース

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

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

ログファイルを確認する

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

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

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

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

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

成功したミニバッチなし