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

适用范围:Azure CLI ml 扩展 v2(最新版)Python SDK azure-ai-ml v2(最新版)

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

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

重要

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

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

联机终结点本地调试

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

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

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

方案 推理 HTTP 服务器 本地终结点
更新本地 Python 环境,而无需重新生成 Docker 映像
更新评分脚本
更新部署配置(部署、环境、代码、模型)
VS Code 调试程序集成

先决条件

本指南假定你已在本地 PC 上安装了以下各项。

有关详细信息,请参阅如何准备系统以部署联机终结点指南。

本文中的示例基于 azureml-examples 存储库中包含的代码示例。 若要在不复制/粘贴 YAML 和其他文件的情况下在本地运行命令,请克隆存储库,然后将目录更改为存储库中的 cli 目录:

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

如果尚未为 Azure CLI 指定默认设置,则应保存默认设置。 若要避免多次传入订阅、工作区和资源组的值,请使用以下命令。 将以下参数替换为特定配置的值:

  • <subscription> 替换为你的 Azure 订阅 ID。
  • <workspace> 替换为 Azure 机器学习工作区名称。
  • <resource-group> 替换为包含你的工作区的 Azure 资源组。
  • <location> 替换为包含你的工作区的 Azure 区域。

提示

可以使用 az configure -l 命令查看当前的默认值。

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

启动开发容器

Azure 机器学习本地终结点使用 Docker 和 VS Code 开发容器来生成和配置本地调试环境。 使用开发容器可以利用 Docker 容器中的 VS Code 功能。 有关开发容器的详细信息,请参阅创建开发容器

若要在 VS Code 中对联机终结点进行本地调试,请在创建或更新 Azure 机器学习联机部署时使用 --vscode-debug 标志。 以下命令使用示例存储库中的部署示例:

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

重要

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

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

备注

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

成功生成映像后,开发容器将在 VS Code 窗口中打开。

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

重要

在启动调试会话之前,请确保 VS Code 扩展已在开发容器中完成安装。


启动调试会话

设置环境后,使用 VS Code 调试程序对部署进行本地测试和调试。

  1. 在 Visual Studio Code 中打开评分脚本。

    提示

    先前部署的终结点所使用的 score.py 脚本位于所克隆的存储库的 azureml-samples/cli/endpoints/online/managed/sample/score.py 中。 但是本指南中的步骤适用于任何评分脚本。

  2. 在评分脚本的任意位置设置一个断点。

    • 若要调试启动行为,请在 init 函数内放置断点。
    • 若要调试评分行为,请在 run 函数内放置断点。
  3. 选择 VS Code“作业”视图。

  4. 在“运行和调试”下拉列表中,选择“Azure ML: 调试本地终结点”,以启动对终结点的本地调试。

    在“运行”视图的“断点”部分中,检查:

    • “引发的异常”处于未选中状态
    • “未捕获的异常”处于选中状态

    Configure Azure Machine Learning Debug Local Environment debug profile

  5. 选择“运行和调试”下拉列表旁边的“播放”图标,以启动调试会话。

    此时将捕获 init 函数中的所有断点。 使用调试操作以逐步执行代码。 有关调试操作的详细信息,请参阅调试操作指南

有关 VS Code 调试程序的详细信息,请参阅在 VS Code 中调试

调试终结点

现在,应用程序正在调试程序中运行,请尝试预测以调试评分脚本。

使用 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 函数中的所有断点。 使用调试操作以逐步执行代码。 有关调试操作的详细信息,请参阅调试操作指南

编辑终结点

对应用程序进行调试和故障排除时,某些方案中需要更新评分脚本和配置。

若要对代码应用更改:

  1. 更新代码
  2. 使用命令面板中的 Developer: Reload Window 命令重新启动调试会话。 有关详细信息,请参阅命令面板文档

备注

由于包含代码和终结点资产的目录已装载到开发容器中,因此在开发容器中所做的任何更改都将与本地文件系统同步。

对于涉及环境和终结点配置更新的更多更改,请使用 ml 扩展 update 命令。 执行此操作将触发一个完整映像的重新生成,该映像包含所做的更改。

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

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

后续步骤