リモートでのモデルデプロイのトラブルシューティング

2025-03-10

重要

この記事の Azure CLI コマンドの一部では、Azure Machine Learning 用に azure-cli-ml、つまり v1 の拡張機能を使用しています。 v1 拡張機能のサポートは、2025 年 9 月 30 日に終了します。その日付まで、v1 拡張機能をインストールして使用できます。

2025 年 9 月 30 日より前に、ml (v2) 拡張機能に移行することをお勧めします。 v2 拡張機能の詳細については、「Azure Machine Learning CLI 拡張機能と Python SDK v2」を参照してください。

重要

この記事では、Azure Machine Learning SDK v1 の使用に関する情報を提供します。 SDK v1 は 2025 年 3 月 31 日の時点で非推奨となり、サポートは 2026 年 6 月 30 日に終了します。 SDK v1 は、その日付までインストールして使用できます。

2026 年 6 月 30 日より前に SDK v2 に移行することをお勧めします。 SDK v2 の詳細については、「 Azure Machine Learning Python SDK v2 と SDK v2 リファレンスとは」を参照してください。

Azure Machine Learning を使用して Azure Container Instances (ACI) と Azure Kubernetes Service (AKS) にモデルをデプロイするときに発生する可能性がある一般的なエラーのトラブルシューティングと解決、または回避方法について説明します。

注意

Azure Kubernetes Service (AKS) にモデルをデプロイする場合は、そのクラスターに対して Azure Monitor を有効にすることをお勧めします。これは、クラスターの全体的な正常性とリソースの使用状況を理解するのに役立ちます。また、次のリソースも役立つ場合があります。

異常なクラスターまたはオーバーロードされたクラスターにモデルをデプロイしようとしている場合は、問題が発生することが予想されます。 AKS クラスターの問題のトラブルシューティングに関するヘルプが必要な場合は、AKS サポートにお問い合わせください。

前提条件

Azure サブスクリプション。無料版または有料版の Azure Machine Learning をお試しください。
Azure Machine Learning SDK。
Azure CLI。
Azure Machine Learning 用 CLI 拡張機能 v1。

機械学習モデルの Docker デプロイの手順

Azure Machine Learning で非ローカルコンピューティングにモデルをデプロイすると、次のことが行われます。

InferenceConfig の Environments オブジェクトに指定した Dockerfile が、ソースディレクトリの内容と共にクラウドに送信されます
以前にビルドされたイメージがコンテナーレジストリで利用できない場合は、新しい Docker イメージがクラウド内でビルドされ、ワークスペースの既定のコンテナーレジストリに格納されます。
コンテナーレジストリの Docker イメージが、コンピューティング先にダウンロードされます。
ワークスペースの既定の BLOB ストアがコンピューティング先にマウントされ、登録済みのモデルにアクセスできるようになります
エントリスクリプトの init() 関数を実行して、Web サーバーが初期化されます
デプロイされたモデルが要求を受け取ると、run() 関数によってその要求が処理されます

ローカルデプロイを使用する場合の主な違いは、コンテナーイメージがローカルコンピューターでビルドされることです。そのため、ローカルデプロイ用に Docker をインストールする必要があります。

こうした大まかな手順を理解することは、エラーが発生している場所を把握するのに役立ちます。

デプロイログを取得する

エラーをデバッグする最初の手順は、デプロイログを取得することです。最初に、こちらの手順に従って、ワークスペースに接続します。

Azure CLI
Python SDK

適用対象:Azure CLI ml extension v1

デプロイされた Web サービスからログを取得するには、以下を実行します。

az ml service get-logs --verbose --workspace-name <my workspace name> --name <service name>

適用対象:Python SDK azureml v1

azureml.core.Workspace と呼ばれる ws 型のオブジェクトがあると仮定した場合、以下を実行できます。

print(ws.webservices)

# Choose the webservice you are interested in

from azureml.core import Webservice

service = Webservice(ws, '<insert name of webservice>')
print(service.get_logs())

ローカルデバッグ

モデルを ACI または AKS にデプロイする際に問題が発生した場合は、ローカル Web サービスとしてデプロイしてください。ローカル Web サービスを使用すると、問題のトラブルシューティングが簡単になります。ローカルでのデプロイのトラブルシューティングについては、ローカルでのトラブルシューティングに関する記事を参照してください。

Azure Machine Learning 推論 HTTP サーバー

ローカル推論サーバーを使用すると、エントリスクリプト (score.py) をすばやくデバッグできます。基になるスコアスクリプトにバグがある場合、サーバーはモデルの初期化やサービスの提供に失敗します。代わりに、例外と、問題が発生した場所がスローされます。 Azure Machine Learning 推論 HTTP サーバーの詳細

azureml-inference-server-http フィードからパッケージをインストールします。
```
python -m pip install azureml-inference-server-http
```
サーバーを起動し、エントリスクリプトとして score.py を設定します。
```
azmlinfsrv --entry_script score.py
```
curl を使用して、スコアリング要求をサーバーに送信します。
```
curl -p 127.0.0.1:5001/score
```

注意

Azure Machine Learning 推論 HTTP サーバーについてよく寄せられる質問について説明します。

コンテナーをスケジュールできない

Azure Kubernetes Service コンピューティングターゲットにサービスをデプロイするときに、Azure Machine Learning では、要求された量のリソースを使用してサービスをスケジュールすることを試みます。 5 分後、適切な量のリソースがある利用可能なノードがクラスターにない場合、デプロイは失敗します。エラーメッセージは Couldn't Schedule because the kubernetes cluster didn't have available resources after trying for 00:05:00 です。このエラーに対処するには、ノードを追加するか、ノードの SKU を変更するか、またはサービスのリソース要件を変更します。

通常、このエラーメッセージでは、追加する必要があるリソースが示されます。たとえば、"0/3 nodes are available: 3 Insufficient nvidia.com/gpu" というエラーメッセージが表示された場合、これは、サービスに GPU が必要であり、クラスターの 3 つのノードには利用可能な GPU がないことを意味します。これに対処するには、ノードを追加するか (GPU SKU を使用している場合)、GPU 対応の SKU に切り替えるか (SKU が GPU 対応でない場合)、GPU を必要としないように環境を変更します。

サービスを起動できない

イメージが正常にビルドされると、デプロイ構成を使用して、コンテナーの起動が試行されます。コンテナーの起動プロセスの一部として、スコアリングスクリプトの init() 関数が呼び出されます。 init() 関数でキャッチされない例外がある場合、エラーメッセージに CrashLoopBackOff エラーが表示されることがあります。

Docker ログの検査に関する記事の情報を使用してください。

コンテナー azureml-fe-aci 起動が失敗する

Azure Container Instances コンピューティング先にサービスをデプロイするとき、Azure Machine Learning では、推論要求に名前 azureml-fe-aci が与えられるフロントエンドコンテナーの作成が試行されます。 azureml-fe-aci がクラッシュした場合、az container logs --name MyContainerGroup --resource-group MyResourceGroup --subscription MySubscription --container-name azureml-fe-aci を実行することでログを閲覧できます。ログに含まれるエラーメッセージに従って修正できます。

azureml-fe-aci の最も一般的なエラーは、指定された SSL 証明書またはキーが無効になっていることです。

get_model_path() 関数が失敗する

多くの場合、スコアリングスクリプトの init() 関数では、コンテナー内のモデルファイルまたはモデルファイルのフォルダーを見つける目的で Model.get_model_path() 関数が呼び出されます。モデルファイルまたはフォルダーが見つからない場合、この関数は失敗します。このエラーをデバッグする最も簡単な方法は、Container シェルで以下の Python コードを実行することです。

適用対象:Python SDK azureml v1

from azureml.core.model import Model
import logging
logging.basicConfig(level=logging.DEBUG)
print(Model.get_model_path(model_name='my-best-model'))

この例では、スコアリングスクリプトによってモデルファイルまたはフォルダーの存在が予期されるコンテナー内のローカルパス (/var/azureml-app の相対パス) が出力されます。その後、ファイルまたはフォルダーが想定される場所であるかどうかを確認できます。

ログレベルを DEBUG に設定すると、追加情報がログに記録される可能性があり、エラーの特定に役立つ場合があります。

run(input_data) 関数が失敗する

サービスが正常にデプロイされたが、スコアリングエンドポイントにデータを投稿するとクラッシュする場合、代わりに詳細なエラーメッセージが返されるように run(input_data) 関数にエラーをキャッチするステートメントを追加できます。次に例を示します。

def run(input_data):
    try:
        data = json.loads(input_data)['data']
        data = np.array(data)
        result = model.predict(data)
        return json.dumps({"result": result.tolist()})
    except Exception as e:
        result = str(e)
        # return error message back to the client
        return json.dumps({"error": result})

注:run(input_data) 呼び出しからエラーメッセージを返すことは、デバッグ目的のみで行ってください。セキュリティ上の理由から、運用環境ではこの方法でエラーメッセージを返さないでください。

HTTP 状態コード 502

502 状態コードは、サービスが例外をスローしたか、score.py ファイルの run() メソッドでクラッシュしたことを示します。この記事の情報を使用して、ファイルをデバッグします。

HTTP 状態コード 503

Azure Kubernetes Service のデプロイでは、自動スケールがサポートされているため、レプリカを加えて、追加の負荷に対応することができます。自動スケールは、段階的な負荷の変化に対処するように設計されています。 1 秒あたりに受信する要求の量が急増した場合、クライアントは HTTP 状態コード 503 を受信する可能性があります。オートスケーラーは迅速に反応しますが、AKS で追加のコンテナーを作成するにはかなりの時間がかかります。

スケールアップ/スケールダウンの決定は、コンテナーの現在のレプリカの使用率に基づきます。ビジー状態 (要求を処理中) のレプリカの数を現在のレプリカの総数で除算した数が、現在の使用率です。この数が autoscale_target_utilization を超えると、さらにレプリカが作成されます。これが下回ると、レプリカが減少します。レプリカの追加は、集中的かつ迅速に決定されます (約 1 秒)。レプリカの削除は慎重に決定されます (約 1 分)。既定では、自動スケールの目標使用率は 70% に設定されています。これは、1 秒あたりに受信する要求の量 (RPS) が最大 30% 増加した場合まで対処できることを意味します。

状態コード 503 を防ぐには、次の 2 つのことが役立ちます。

ヒント

これらの 2 つの方法は、個別に使用することも、組み合わせて使用することもできます。

自動スケールによって新しいレプリカが作成される使用率レベルを変更します。使用率の目標を調整するには、autoscale_target_utilization をより小さい値に設定します。

重要

この変更により、レプリカの作成 が高速化されることはありません。その代わり、より低い使用率しきい値で作成されます。サービスの使用率が 70% になるまで待機するのでなく値を 30% に変更すると、使用率が 30% になった段階でレプリカが作成されます。

現在の最大数のレプリカが Web サービスによって既に使用されていて、状態コード 503 が引き続き発生する場合は、autoscale_max_replicas の値を大きくして、レプリカの最大個数を増やします。
レプリカの最小個数を変更します。レプリカの最小個数を増やすと、着信トラフィックの急増に対処するためのプールが大きくなります。

レプリカの最小個数を増やすには、autoscale_min_replicas をより大きな値に設定します。必要なレプリカ個数は次のコードを使用して計算できるので、値をご利用のプロジェクトに固有の値に置換します。
```
from math import ceil
# target requests per second
targetRps = 20
# time to process the request (in seconds)
reqTime = 10
# Maximum requests per container
maxReqPerContainer = 1
# target_utilization. 70% in this example
targetUtilization = .7

concurrentRequests = targetRps * reqTime / targetUtilization

# Number of container replicas
replicas = ceil(concurrentRequests / maxReqPerContainer)
```
注意

新しい最小レプリカが処理できるよりも大きい要求スパイクを受信した場合は、再び 503 を受け取る可能性があります。たとえば、ご利用のサービスへのトラフィックが増えた場合、レプリカの最小個数を増やすことが必要な場合があります。

autoscale_target_utilization、autoscale_max_replicas、autoscale_min_replicas の設定方法の詳細については、AksWebservice モジュールリファレンスを参照してください。

HTTP 状態コード 504

504 状態コードは、要求がタイムアウトしたことを示します。既定のタイムアウトは 1 分です。

タイムアウト値を増やすか、score.py を変更して不要な呼び出しを削除することで、サービスの高速化を試みることができます。これらのアクションで問題が解決しない場合は、この記事の情報を使用して score.py ファイルをデバッグします。コードが応答しない状態または無限ループである可能性があります。

その他のエラーメッセージ

次のエラーに対して、これらのアクションを実行します。

エラー	解像度
409 競合エラー	操作が既に進行中の場合、同じ Web サービスでの新しい操作は、409 競合エラーで応答します。たとえば、Web サービスの作成または更新操作の進行中に、新しい削除操作がトリガーされた場合、エラーがスローされます。
Web サービスのデプロイ時のイメージ構築エラー	イメージ構成用の pip の依存関係として "pynacl==1.2.1" を Conda ファイルに追加します。
`['DaskOnBatch:context_managers.DaskOnBatch', 'setup.py']' died with <Signals.SIGKILL: 9>`	デプロイで使用される VM の SKU を、メモリがより多い SKU に変更します。
FPGA エラー	FPGA クォータを要求して承認されるまでは、FPGA にモデルをデプロイできません。アクセスを要求するには、クォータ要求フォーム https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR2nac9-PZhBDnNSV2ITz0LNUN0U5S0hXRkNITk85QURTWk9ZUUFUWkkyTC4u に入力します。

高度なデバッグ

モデルデプロイに含まれる Python コードを対話的にデバッグする必要が生じることがあります。たとえば、エントリスクリプトが失敗し、追加のログ記録によっても理由を特定できない場合がこれにあたります。 Visual Studio Code と debugpy を使用すると、Docker コンテナー内で実行されているコードにアタッチできます。

詳細については、VS Code での対話型デバッグのガイドを参照してください。

モデルデプロイユーザーフォーラム

次のステップ

デプロイの詳細については、以下を参照してください。