在 Visual Studio Code 中对联机终结点进行本地调试

Artículo
08/29/2024

适用范围：Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）

了解如何使用 Microsoft Visual Studio Code 调试程序以在将联机终结点部署到 Azure 之前对其进行本地测试和调试。

Azure 机器学习本地终结点可帮助在本地测试和调试评分脚本、环境配置、代码配置和机器学习模型。

重要

此功能目前处于公开预览状态。此预览版在提供时没有附带服务级别协议，我们不建议将其用于生产工作负荷。某些功能可能不受支持或者受限。

有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

在将终结点部署到云之前对其进行本地调试，可以帮助提前捕获代码和配置中的错误。提供多种选项通过 Visual Studio Code 对终结点进行本地调试。

Azure 机器学习推理 HTTP 服务器
本地终结点

本指南重点介绍本地终结点。

下表对各个方案进行了概述，便于你选择最适合你的方案。

方案	推理 HTTP 服务器	本地终结点
更新本地 Python 环境，而无需重新生成 Docker 映像	是	否
更新评分脚本	是	是
更新部署配置（部署、环境、代码、模型）	否	是
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 机器学习工作区名称。
将 <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 机器学习本地终结点使用 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

重要

在适用于 Linux 的 Windows 子系统 (WSL) 上，需要更新 PATH 环境变量，以包括 Visual Studio Code 可执行文件的路径或使用 WSL 互操作。有关详细信息，请参阅 Windows 与 Linux 的互操作性。

Docker 映像是在本地生成的。此过程阶段会出现任何环境配置或模型文件错误。

注意

首次启动新的或更新的开发容器时，可能需要几分钟时间。

成功生成映像后，开发容器将在 Visual Studio Code 窗口中打开。

你将使用几个 Visual Studio Code 扩展，在开发容器中调试你的部署。 Azure 机器学习在开发容器中自动安装这些扩展。

推理调试
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 机器学习联机部署时设置 vscode-debug 和 local 标志。以下代码反映了示例存储库中的部署示例：

deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=endpoint_name,
    model=Model(path="../model-1/model"),
    code_configuration=CodeConfiguration(
        code="../model-1/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-1/environment/conda.yml",
        image="mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210727.v1",
    ),
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

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

重要

Docker 映像是在本地生成的。此过程阶段会出现任何环境配置或模型文件错误。

注意

首次启动新的或更新的开发容器时，可能需要几分钟时间。

成功生成映像后，开发容器将在 Visual Studio Code 窗口中打开。

你将使用几个 Visual Studio Code 扩展，在开发容器中调试你的部署。 Azure 机器学习在开发容器中自动安装这些扩展。

推理调试
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 作业视图。
在“运行和调试”下拉列表中，选择“Azure ML: 调试本地终结点”，以启动对终结点的本地调试。

在“运行”视图的“断点”部分中，检查：
- “引发的异常”处于未选中状态
- “未捕获的异常”处于选中状态
选择“运行和调试”下拉列表旁边的“播放”图标，以启动调试会话。

此时将捕获 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"),
    code_configuration=CodeConfiguration(
        code="../model-2/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-2/environment/conda.yml",
        image="mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210727.v1",
    ),
    instance_type="Standard_DS2_v2",
    instance_count=2,
)

ml_client.online_deployments.update(new_deployment, local=True, vscode_debug=True)

生成更新的映像并启动开发容器后，请使用 Visual Studio Code 调试程序对更新的终结点进行测试和故障排除。

Compartir a través de

在 Visual Studio Code 中对联机终结点进行本地调试

先决条件

启动开发容器

启动调试会话

调试终结点

编辑终结点

Recursos adicionales

Compartir a través de

在 Visual Studio Code 中对联机终结点进行本地调试

先决条件

启动开发容器

启动调试会话

调试终结点

编辑终结点

相关内容

Recursos adicionales