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

適用於：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

必要條件

Azure CLI

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

• 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 的預設值，請儲存您的預設設定。 若要避免多次傳遞訂閱、工作區和資源群組的值，請使用下列命令。 將下列參數取代為特定設定值：

• 使用您的 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

適用於：Python SDK azure-ai-ml v2 (目前)

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

• Docker
• Visual Studio Code
• Azure CLI
• Azure CLI ml 擴充功能 （v2）
• Azure Machine Learning Python SDK (v2)
• Windows 子系統 Linux 版 (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 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

Azure 機器學習 本機端點會使用 Docker 和 Visual Studio Code 開發容器（開發容器）來建置和設定本機偵錯環境。 透過開發容器，您可以從 Docker 容器內利用 Visual Studio Code 功能。 如需開發容器的詳細資訊，請參閱建立開發容器。

若要在 Visual Studio Code 本機偵錯在線端點，請在建立或更新和 Azure 機器學習 在線部署時使用 --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 StudioCode視窗中開啟。

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

• 推斷偵錯
• Pylance
• Jupyter
• Python

重要

開始偵錯會話之前，請確定 Visual Studio Code 延伸模組已完成在開發容器中安裝。

Python

Azure 機器學習 本機端點會使用 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 機器學習 在線部署時設定 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()

重要

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

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

注意

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

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

您將使用一些 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：偵錯本機端點 ] 以開始在本機偵錯端點。

   在 [執行] 檢視的 [中斷點] 區段中，確認：

   • 引發的例外狀況為未核取狀態
   • 未攔截的例外狀況為已核取狀態

   

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 是您的端點接聽要求的位址。 使用 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 函式中的任何中斷點。 使用偵錯動作來逐步執行您的程式碼。 如需偵錯動作的詳細資訊，請參閱偵錯動作指南。

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 調試程式來測試和疑難解答更新的端點。

相關內容

• 使用線上端點部署和評分機器學習模型
• 對線上端點部署和評分進行疑難排解