Vvisual Studio Code を使用してオンラインエンドポイントをローカルでデバッグする

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

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

Microsoft Visual Studio Code デバッガーを使用して、オンラインエンドポイントを Azure にデプロイする前にローカルでテストおよびデバッグする方法について説明します。

Azure Machine Learning のローカルエンドポイントは、スコアリングスクリプト、環境構成、コード構成、および機械学習モデルをローカルでテスト、デバッグするのに役立ちます。

重要

現在、この機能はパブリックプレビュー段階にあります。このプレビューバージョンはサービスレベルアグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。特定の機能はサポート対象ではなく、機能が制限されることがあります。

詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

エンドポイントをクラウドにデプロイする前にローカルでデバッグすることで、コードと構成のエラーを早期に発見することができます。 Visual Studio Code を使用してエンドポイントをローカルでデバッグするには、さまざまなオプションがあります。

Azure Machine Learning 推論 HTTP サーバー
ローカルエンドポイント

このガイドでは、ローカルエンドポイントに焦点を当てています。

次の表に、目的に適した方法を選択するのに役立つシナリオの概要を示しています。

シナリオ	推論 HTTP サーバー	ローカルエンドポイント
Docker イメージを再構築することなく、ローカルの Python 環境を更新する	はい	いいえ
スコアリングスクリプトを更新する	はい	はい
デプロイ構成を更新する (デプロイ、環境、コード、モデル)	いいえ	はい
Visual Studio Code デバッガーの統合	はい	はい

このガイドでは、PC に以下の項目がローカルにインストールされていることを前提としています。

詳細については、オンラインエンドポイントをデプロイするためにシステムを準備する方法に関するガイドを参照してください。

この記事の例は、azureml-examples GitHub リポジトリに含まれているコードサンプルを基にしています。 YAML などのファイルをコピーして貼り付けることなくコマンドをローカルで実行するには、リポジトリを複製してから、ディレクトリを azureml-examples/cli に変更します。

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

まだ Azure CLI の既定値を設定していない場合は、既定の設定を保存する必要があります。サブスクリプション、ワークスペース、およびリソースグループの値が複数回渡されることを防ぐには、以下のコマンドを使用します。次のパラメーターを、実際の構成の値に置き換えます。

<subscription> は、Azure サブスクリプション ID に置き換えてください。
<workspace> は、ご利用の Azure Machine Learning ワークスペース名に置き換えます。
<resource-group> は、ワークスペースが含まれている Azure リソースグループに置き換えます。
<location> は、ワークスペースが含まれている Azure リージョンに置き換えます。

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

ヒント

az configure -l コマンドを使用すると、現在の既定値を確認できます。

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

このガイドでは、PC に以下の項目がローカルにインストールされていることを前提としています。

詳細については、オンラインエンドポイントをデプロイするためにシステムを準備する方法に関するガイドを参照してください。

この記事の例は、azureml-examples リポジトリ内の「Visual Studio Code を使用してオンラインエンドポイントをローカルでデバッグする」という Jupyter ノートブックにあります。コードをローカルで実行するには、リポジトリを複製してから、ディレクトリをノートブックの親ディレクトリ sdk/endpoints/online/managed に変更します。

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples
cd sdk/python/endpoints/online/managed

Jupyter ノートブックを開いて、必要なモジュールをインポートします。

from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Model,
    CodeConfiguration,
    Environment,
)
from azure.identity import DefaultAzureCredential

ワークスペースとエンドポイントの変数を設定します。

subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace_name = "<AML_WORKSPACE_NAME>"

endpoint_name = "<ENDPOINT_NAME>"

開発コンテナーの起動

Azure CLI
Python

Azure Machine Learning のローカルエンドポイントは、Docker と Visual Studio Code の開発コンテナーを使用して、ローカルのデバッグ環境を構築および構成します。開発コンテナーを使用すると、Docker コンテナー内から Visual Studio Code の機能を利用できます。開発コンテナーの詳細については、開発コンテナーを作成する方法に関するページを参照してください。

オンラインエンドポイントを Visual Studio Code でローカルにデバッグするには、Azure Machine Learning のオンラインデプロイを作成または更新する際に --vscode-debug フラグを使用します。次のコマンドは、サンプルリポジトリのデプロイ例を使用しています。

az ml online-deployment create --file endpoints/online/managed/sample/blue-deployment.yml --local --vscode-debug

重要

Linux 用 Windows サブシステム (WSL) では、PATH 環境変数を更新して Visual Studio Code の実行可能ファイルへのパスを含めるか、WSL 相互運用を使用する必要があります。詳細については、Linux と Windows の相互運用性に関する記事をご覧ください。

Docker イメージはローカルに構築されます。環境構成やモデルファイルのエラーは、この段階で表面化します。

Note

新規または更新された開発コンテナーを初めて起動するときには、数分かかることがあります。

イメージが正常に構築されると、開発コンテナーが Visual Studio Code ウィンドウで開きます。

開発コンテナーでデプロイをデバッグするには、いくつかの Visual Studio Code 拡張機能を使用します。 Azure Machine Learning の場合、これらの拡張機能は自動的に開発コンテナーにインストールされます。

推論のデバッグ
Pylance
Jupyter
Python

重要

デバッグセッションを開始する前に、開発コンテナーへの Visual Studio Code 拡張機能のインストールが完了していることを確認してください。

ワークスペースへのハンドルを取得します。

credential = DefaultAzureCredential()
ml_client = MLClient(
    credential,
    subscription_id=subscription_id,
    resource_group_name=resource_group,
    workspace_name=workspace_name,
)

オンラインエンドポイントを Visual Studio Code でローカルにデバッグするには、Azure Machine Learning のオンラインデプロイを作成または更新する際に vscode-debug と local のフラグを使用します。次のコードは、サンプルリポジトリのデプロイ例を反映しています。

deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=endpoint_name,
    model=Model(path="../model-1/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-1/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-1/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=1,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    deployment, local=True, vscode_debug=True
).result()

重要

Docker イメージはローカルに構築されます。環境構成やモデルファイルのエラーは、この段階で表面化します。

Note

新規または更新された開発コンテナーを初めて起動するときには、数分かかることがあります。

イメージが正常に構築されると、開発コンテナーが Visual Studio Code ウィンドウで開きます。

推論のデバッグ
Pylance
Jupyter
Python

重要

デバッグセッションを開始する前に、開発コンテナーへの Visual Studio Code 拡張機能のインストールが完了していることを確認してください。

デバッグセッションの開始

環境の設定が完了したら、Visual Studio Code デバッガーを使用して、デプロイをローカルでテストおよびデバッグします。

Visual Studio Code でスコアリングスクリプトを開きます。

ヒント

前にデプロイしたエンドポイントで使用されている score.py スクリプトは、クローンしたリポジトリの azureml-samples/cli/endpoints/online/managed/sample/score.py にあります。ただし、このガイドの手順では、どのスコアリングスクリプトでも機能します。
スコアリングスクリプト内の任意の場所にブレークポイントを設定します。
- スタートアップ動作をデバッグするには、init 関数内にブレークポイントを配置します。
- スコアリング動作をデバッグするには、run 関数内にブレークポイントを配置します。
Visual Studio Code のジョブビューを選択します。
[実行とデバッグ] ドロップダウンから [AzureML: ローカルエンドポイントのデバッグ] を選択して、エンドポイントのデバッグをローカルで開始します。

実行ビューの [ブレークポイント] セクションで、次のことを確認します。
- [Raised Exceptions](すべての例外) がオフになっている
- [Uncaught Exceptions](キャッチされない例外) がオンになっている
[実行とデバッグ] ドロップダウンの横にある再生アイコンを選択して、デバッグセッションを開始します。

この時点で、init 関数内のすべてのブレークポイントがキャッチされます。デバッグアクションを使用して、コードをステップ実行します。デバッグアクションの詳細については、デバッグアクションガイドのページを参照してください。

Visual Studio Code デバッガーの詳細については、デバッグに関するページを参照してください。

エンドポイントをデバッグする

Azure CLI
Python

アプリケーションがデバッガーで実行されたので、スコアリングスクリプトをデバッグするための予測を行います。

ml 拡張機能の invoke コマンドを使用して、ローカルエンドポイントに要求を行います。

az ml online-endpoint invoke --name <ENDPOINT-NAME> --request-file <REQUEST-FILE> --local

この場合、<REQUEST-FILE> は、以下の JSON と同様に、モデルが予測を行うための入力データサンプルを含む JSON ファイルです。

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

ヒント

スコアリング URI は、エンドポイントが要求をリッスンするアドレスです。スコアリング URI を取得するには、ml 拡張機能を使用します。

az ml online-endpoint show --name <ENDPOINT-NAME> --local

出力は次のようになります。

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

スコアリング URI は、scoring_uri プロパティで確認できます。

この時点で、run 関数内のすべてのブレークポイントがキャッチされます。デバッグアクションを使用して、コードをステップ実行します。デバッグアクションの詳細については、デバッグアクションガイドのページを参照してください。

アプリケーションがデバッガーで実行されたので、スコアリングスクリプトをデバッグするための予測を行います。

MLClient オブジェクトの invoke メソッドを使用して、ローカルエンドポイントに要求を行います。

endpoint = ml_client.online_endpoints.get(name=endpoint_name, local=True)

request_file_path = "../model-1/sample-request.json"

ml_client.online_endpoints.invoke(endpoint_name, request_file_path, local=True)

この場合、<REQUEST-FILE> は、以下の JSON と同様に、モデルが予測を行うための入力データサンプルを含む JSON ファイルです。

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

ヒント

スコアリング URI は、エンドポイントが要求をリッスンするアドレスです。エンドポイントオブジェクトの as_dict メソッドは、Azure CLI の show と同様の情報を返します。エンドポイントオブジェクトは、.get を使用して取得できます。

print(endpoint)

出力は次のようになります。

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

スコアリング URI は、scoring_uri キーで確認できます。

エンドポイントを編集する

Azure CLI
Python

アプリケーションのデバッグとトラブルシューティングを行う際は、スコアリングスクリプトと構成を更新する必要がある場面に遭遇します。

コードに変更を適用するには、以下の手順を実行します。

コードを更新します。
コマンドパレットの Developer: Reload Window コマンドを使用して、デバッグセッションを再起動します。詳細については、コマンドパレットのドキュメントを参照してください。

注意

コードとエンドポイント資産が格納されているディレクトリは開発コンテナーにマウントされているため、開発コンテナーで行ったすべての変更はローカルのファイルシステムと同期されます。

環境やエンドポイントの構成の更新を含む、より広範囲な変更を行う場合は、ml 拡張機能の update コマンドを使用してください。これにより、変更した内容でイメージの完全な再構築が行われます。

az ml online-deployment update --file <DEPLOYMENT-YAML-SPECIFICATION-FILE> --local --vscode-debug

更新されたイメージが構築され、開発コンテナーが起動したら、Visual Studio Code デバッガーを使用して、更新されたエンドポイントをテストおよびトラブルシューティングします。

アプリケーションのデバッグとトラブルシューティングを行う際は、スコアリングスクリプトと構成を更新する必要がある場面に遭遇します。

コードに変更を適用するには、以下の手順を実行します。

コードを更新します。
コマンドパレットの Developer: Reload Window コマンドを使用して、デバッグセッションを再起動します。詳細については、コマンドパレットのドキュメントを参照してください。

注意

環境やエンドポイントの構成の更新を含む、より広範囲な変更を行う場合は、MLClient の online_deployments.update モジュールまたはメソッドを使用してください。これにより、変更した内容でイメージの完全な再構築が行われます。

new_deployment = ManagedOnlineDeployment(
    name="green",
    endpoint_name=endpoint_name,
    model=Model(path="../model-2/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-2/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-2/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=2,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    new_deployment, local=True, vscode_debug=True
).result()

次の方法で共有

Vvisual Studio Code を使用してオンラインエンドポイントをローカルでデバッグする

前提条件

開発コンテナーの起動

デバッグセッションの開始

エンドポイントをデバッグする

エンドポイントを編集する

フィードバック

その他のリソース

次の方法で共有

Vvisual Studio Code を使用してオンライン エンドポイントをローカルでデバッグする

前提条件

開発コンテナーの起動

デバッグ セッションの開始

エンドポイントをデバッグする

エンドポイントを編集する

関連するコンテンツ

フィードバック

その他のリソース

Vvisual Studio Code を使用してオンラインエンドポイントをローカルでデバッグする

デバッグセッションの開始