在 Visual Studio Code 中從本機偵錯線上端點

文章
10/16/2024

適用於：Azure CLI ml 延伸模組 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 伺服器	本機端點
更新本機 Python 環境，而「不」重建 Docker 映像	是	No
更新評分指令碼	Yes	Yes
更新部署設定 (部署、環境、程式碼、模型)	No	Yes
Visual Studio Code 偵錯工具整合	Yes	Yes

本指南假設您已在本機電腦上安裝下列項目。

如需詳細資訊，請參閱關於如何準備系統以部署線上端點的指南。

本文中的範例是以 azureml-examples GitHub 存放庫中包含的程式碼範例為基礎。若要在本機上執行命令，而不需要複製/貼上 YAML 和其他檔案，請複製存放庫，然後將目錄變更為 azureml-examples/cli：

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

如果您尚未設定 Azure CLI 的預設值，請儲存您的預設設定。若要避免多次傳遞訂閱、工作區和資源群組的值，請使用下列命令。將下列參數取代為特定設定值：

使用您的 Azure 訂用帳戶識別碼來取代 <subscription> 。
將您的 Azure Machine Learning 工作區名稱取代為 <workspace>。
將 <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 (目前)

本指南假設您已在本機電腦上安裝下列項目。

如需詳細資訊，請參閱關於如何準備系統以部署線上端點的指南。

本文中的範例可在 azureml-examples 存放庫內稱為在 Visual Studio Code 中偵錯線上端點的 Jupyter Notebook 中找到。若要在本機執行該程式碼，請將存放庫複製到筆記本的父目錄，sdk/endpoints/online/managed。

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

開啟 Jupyter Notebook 並匯入所需的模組：

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 開發容器 (dev 容器) 來組建和設定本機偵錯環境。透過開發容器，您可以從 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

重要

在 Windows 子系統 Linux 版 (WSL) 上，您必須更新 PATH 環境變數，以包含 Visual Studio Code 可執行檔的路徑，或使用 WSL Interop。如需詳細資訊，請參閱 Windows 與 Linux 的互通性。

Docker 映像會在本機建置。環境設定或模型檔案如有任何錯誤，都會在程序的這個階段顯現。

注意

第一次啟動新的或更新過的開發容器時，可能需要幾分鐘的時間。

映像成功建置之後，您的開發容器就會在 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 映像會在本機建置。環境設定或模型檔案如有任何錯誤，都會在程序的這個階段顯現。

注意

第一次啟動新的或更新過的開發容器可能需要幾分鐘的時間。

映像成功建置之後，您的開發容器就會在 Visual Studio Code 視窗中開啟。

您將使用一些 Visual Studio Code 擴充功能來偵錯開發容器中的部署。 Azure Machine Learning 會自動在開發容器中安裝這些擴充功能。

推斷偵錯
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：偵錯本機端點]，以開始在本機上偵錯端點。

在 [執行] 檢視的 [中斷點] 區段中，確認：
- 引發的例外狀況為未核取狀態
- 未攔截的例外狀況為已核取狀態
選取 [執行和偵錯] 下拉式清單旁的播放圖示，以啟動偵錯工作階段。

至此，系統會攔截 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 是您的端點接聽要求的位址。使用 ml 擴充功能即可取得評分 URI。

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 金鑰中找到。

至此，系統會攔截 run 函式中的任何中斷點。使用偵錯動作來逐步執行您的程式碼。如需偵錯動作的詳細資訊，請參閱偵錯動作指南。

編輯您的端點

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()

組建更新過的映像並啟動您的開發容器之後，請使用 Visual Studio Code 偵錯工具來測試和疑難排解更新過的端點。

分享方式：

在 Visual Studio Code 中從本機偵錯線上端點

必要條件

啟動開發容器

開始偵錯工作階段

為您的端點偵錯

編輯您的端點

意見反映

更多資源

分享方式：

在 Visual Studio Code 中從本機偵錯線上端點

必要條件

啟動開發容器

開始偵錯工作階段

為您的端點偵錯

編輯您的端點

相關內容

意見反映

更多資源