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

適用対象: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 デバッガーの統合	はい	はい

前提条件

Azure CLI

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

• Docker
• Visual Studio Code
• Azure CLI
• Azure CLI ml 拡張機能 (v2)

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

この記事の例は、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

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

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

• Docker
• Visual Studio Code
• Azure CLI
• Azure CLI ml 拡張機能 (v2)
• Azure Machine Learning Python SDK (v2)
• Linux 用 Windows サブシステム (WSL)

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

この記事の例は、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

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 拡張機能のインストールが完了していることを確認してください。

Python

Azure Machine Learning のローカル エンドポイントは、Docker と Visual Studio Code の開発コンテナーを使用して、ローカルのデバッグ環境を構築および構成します。 開発コンテナーを使用すると、Docker コンテナー内から 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()

重要

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 拡張機能のインストールが完了していることを確認してください。

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

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

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

   ヒント

   前にデプロイしたエンドポイントで使用されている score.py スクリプトは、クローンしたリポジトリの azureml-samples/cli/endpoints/online/managed/sample/score.py にあります。 ただし、このガイドの手順では、どのスコアリング スクリプトでも機能します。

2. スコアリング スクリプト内の任意の場所にブレークポイントを設定します。

   • スタートアップ動作をデバッグするには、init 関数内にブレークポイントを配置します。
   • スコアリング動作をデバッグするには、run 関数内にブレークポイントを配置します。

3. Visual Studio Code のジョブ ビューを選択します。

4. [実行とデバッグ] ドロップダウンから [AzureML: ローカル エンドポイントのデバッグ] を選択して、エンドポイントのデバッグをローカルで開始します。

   実行ビューの [ブレークポイント] セクションで、次のことを確認します。

   • [Raised Exceptions](すべての例外) がオフになっている
   • [Uncaught Exceptions](キャッチされない例外) がオンになっている

   

5. [実行とデバッグ] ドロップダウンの横にある再生アイコンを選択して、デバッグ セッションを開始します。

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

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

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

Azure CLI

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

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

Python

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

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 キーで確認できます。

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

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

Azure CLI

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

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

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

注意

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

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

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

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

Python

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

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

1. コードを更新します。
2. コマンド パレットの 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()

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

関連するコンテンツ

• オンライン エンドポイントを使用して機械学習モデルをデプロイおよびスコア付けする
• オンライン エンドポイントのデプロイとスコアリングのトラブルシューティング