教程：在边缘使用自定义视觉服务进行图像分类

适用于： IoT Edge 1.5 IoT Edge 1.4

Azure IoT Edge 可以将工作负荷从云移到边缘，让 IoT 解决方案更高效。 此功能非常适用于处理大量数据的服务，例如计算机视觉模型。 自定义视觉服务用于生成自定义图像分类器并将其作为容器部署到设备。 将这两项服务一起使用，可以从图像中获取见解，而无需先将所有数据从站点转移出来。 自定义视觉提供一个可以将图像与训练的模型进行比较的分类器，以便生成见解。

例如，IoT Edge 设备上的自定义视觉可以确定某条高速公路的交通流量是高于还是低于正常，或者某个室内停车场是否有连续的停车位。 这些见解可以与其他服务共享，方便采取行动。

在本教程中，你将了解如何执行以下操作：

如果没有 Azure 试用版订阅，请在开始前创建 Azure 试用版订阅。

• 通过完成教程：使用 Visual Studio Code 开发 IoT Edge 模块，为 Linux 容器开发配置环境。 完成教程后，开发环境中应该具备以下先决条件：

  • Azure 中的免费或标准层 IoT 中心。
  • 运行 Azure IoT Edge （支持 Linux 容器）的设备。 可以按照快速入门设置 Linux 设备或 Windows 设备。
  • 一个容器注册表，例如 Azure 容器注册表。
  • 配置了 Azure IoT Edge 和 Azure IoT 中心扩展的 Visual Studio Code。 适用于 Visual Studio Code 的 Azure IoT Edge 工具扩展处于维护模式。
  • 在开发计算机上下载并安装与 Docker 兼容的容器管理系统。 将其配置为运行 Linux 容器。

• 要使用自定义视觉设备开发 IoT Edge 模块，请在开发计算机上安装下述额外的必备组件：

  • Python
  • Git
  • 适用于 Visual Studio Code 的 Python 扩展

若要生成图像分类器，需创建自定义视觉项目并提供训练图像。

生成并训练图像分类器以后，即可将它作为 Docker 容器导出并部署到 IoT Edge 设备。

1. 在 Web 浏览器中，导航到自定义影像服务网页。

2. 选择“登录”，使用访问 Azure 资源时所用的帐户进行登录。

3. 选择“新建项目”。

4. 使用以下值来创建项目：

   Expandir tabla

   字段	值
   名称	为项目提供一个名称，例如 EdgeTreeClassifier。
   说明	可选项目说明。
   资源	选择一个包含自定义视觉服务资源的 Azure 资源组，或者如果尚未添加 Azure 资源组，则选择“新建” 。
   项目类型	分类
   分类类型	多类(一个图像一个标记)
   域	常规(精简)
   导出功能	基本平台（Tensorflow、CoreML、ONNX 等）

5. 选择“创建项目”。

创建图像分类器需要一组训练图像和测试图像。

1. 将示例图像从 Cognitive-CustomVision-Windows 存储库克隆或下载到本地开发计算机。

   git clone https://github.com/Microsoft/Cognitive-CustomVision-Windows.git
   

2. 返回到自定义视觉项目，选择“添加图像”。

3. 浏览到已克隆到本地的 git 存储库，导航到第一个图像文件夹 Cognitive-CustomVision-Windows / Samples / Images / Hemlock。 选择文件夹中的所有 10 个图像，然后单击“打开”。

4. 将标记“铁杉” 添加到此组图像，然后按 Enter 应用该标记。

5. 选择“上传 10 个文件”。

   

6. 成功上传图像以后，选择“完成”。

7. 再次选择“添加图像”。

8. 浏览到第二个图像文件夹 Cognitive-CustomVision-Windows / Samples / Images / Japanese Cherry。 选择文件夹中的所有 10 个图像，然后单击“打开”。

9. 将标记“日本樱花” 添加到此组图像，然后按 Enter 应用该标记。

10. 选择“上传 10 个文件”。 成功上传图像以后，选择“完成”。

11. 将两组图像标记并上传后，请选择“训练”，对分类器进行训练。

1. 训练分类器以后，请在分类器的“性能”页上选择“导出”。

   

2. 选择“DockerFile” 作为平台。

3. 选择“Linux” 作为版本。

4. 选择“导出”。

   

5. 导出完成后，选择“下载”，将 .zip 包保存到本地计算机。 从包中提取所有文件。 可使用这些文件创建一个包含图像分类服务器的 IoT Edge 模块。

此时，你已完成自定义视觉项目的创建和训练。 将在下一部分使用导出的文件，但现在已完成自定义视觉网页的操作。

现在，开发计算机上有了适用于容器版图像分类器的文件。 在此部分，请将图像分类器容器配置为以 IoT Edge 模块方式运行。 还创建了第二个模块，该模块与图像分类器一起部署。 第二个模块将请求发布到分类器，并将结果以消息形式发送到 IoT 中心。

可以通过解决方案以逻辑方式为单个 IoT Edge 部署开发和组织多个模块。 解决方案包含适用于一个或多个模块的代码，以及部署清单，声明如何在 IoT Edge 设备上配置模块。

1. 在 Visual Studio Code 中，选择“查看”>“命令面板”，以打开 Visual Studio Code 命令面板。

2. 在“命令面板”中，输入并运行 Azure IoT Edge：New IoT Edge solution 命令。 在命令面板中提供以下信息，以便创建解决方案：

   Expandir tabla

   字段	值
   选择文件夹	在适用于 Visual Studio Code 的开发计算机上选择用于创建解决方案文件的位置。
   提供解决方案名称	输入解决方案的描述性名称（例如 CustomVisionSolution），或者接受默认名称。
   选择模块模板	选择“Python 模块”。
   提供模块名称	将模块命名为 classifier。 必须确保此模块名称为小写。 IoT Edge 在引用模块时区分大小写，而此解决方案使用的库会将所有请求格式化为小写。
   为模块提供 Docker 映像存储库	映像存储库包含容器注册表的名称和容器映像的名称。 容器映像是在上一步预先填充的。 将 localhost:5000 替换为 Azure 容器注册表中的“登录服务器”值 。 可以在 Azure 门户的容器注册表的“概述”页中检索登录服务器。 最终的字符串类似于 <注册表名称>.azurecr.cn/classifier。

   

Visual Studio Code 窗口会加载 IoT Edge 解决方案工作区。

环境文件存储容器注册表的凭据，并将其与 IoT Edge 运行时共享。 此运行时需要这些凭据才能将专用映像拉取到 IoT Edge 设备中。

IoT Edge 扩展尝试从 Azure 中拉取容器注册表凭据并将其填充到环境文件中。 检查凭据是否已包含在内。 如果没有，请立即添加：

1. 在 Visual Studio Code 资源管理器中，打开 .env 文件。
2. 使用从 Azure 容器注册表复制的 username 和 password 值更新相关字段。
3. 保存此文件。

目前，Visual Studio Code 可以为 Linux AMD64 和 Linux ARM32v7 设备开发模块。 需要选择面向每个解决方案的体系结构，因为每种体系结构类型的容器的生成和运行方式均不相同。 默认值为 Linux AMD64，我们将在本教程中使用此功能。

1. 打开命令面板并搜索 Azure IoT Edge:Set Default Target Platform for Edge Solution，或选择窗口底部侧栏中的快捷方式图标。

2. 在命令面板中，从选项列表中选择目标体系结构。 在本教程中，我们使用 Ubuntu 虚拟机作为 IoT Edge 设备，因此保留默认的 amd64。

Visual Studio Code 中的 Python 模块模板包含一些可以在运行后对 IoT Edge 进行测试的示例代码。 在本方案中不需使用该代码。 请按照此部分的步骤将示例代码替换为以前导出的图像分类器容器。

1. 在文件资源管理器中，浏览到已下载并提取的自定义视觉包。 复制已提取包中的所有内容。 其中应该有两个文件夹（app 和 azureml）和两个文件（Dockerfile 和 README）。

2. 在文件资源管理器中，浏览到曾经要求 Visual Studio Code 在其中创建 IoT Edge 解决方案的目录。

3. 打开 classifier 模块文件夹。 如果在上一部分使用了建议的名称，则文件夹结构将类似于 CustomVisionSolution / modules / classifier。

4. 将文件粘贴到 classifier 文件夹中。

5. 返回到 Visual Studio Code 窗口。 解决方案工作区现在会显示模块文件夹中的图像分类器文件。

   

6. 打开 classifier 文件夹中的 module.json 文件。

7. 更新 platforms 参数，使其指向你添加的新 Dockerfile，并删除 AMD64 之外的所有选项，这是我们在本教程中唯一使用的体系结构。

   "platforms": {
       "amd64": "./Dockerfile"
   }
   

8. 保存所做更改。

在实际的自定义视觉部署中，会有一个提供实时图像或视频流的摄像头。 在本方案中，请生成一个可以向图像分类器发送测试图像的模块来模拟摄像头。

在此部分，请将新模块添加到同一 CustomVisionSolution 并提供创建模拟摄像头所需的代码。

1. 在同一 Visual Studio Code 窗口中，使用命令面板运行 Azure IoT Edge: Add IoT Edge Module”。 在命令面板中提供新模块所需的以下信息：

   Expandir tabla

   Prompt	值
   选择部署模板文件	选择 CustomVisionSolution 文件夹中的 deployment.template.json 文件。
   选择模块模板	选择“Python 模块”
   提供模块名称	将模块命名为 cameraCapture
   为模块提供 Docker 映像存储库	将 localhost:5000 替换为 Azure 容器注册表的登录服务器值。 最终的字符串类似于 <registryname>.azurecr.cn/cameracapture。

   Visual Studio Code 窗口会加载解决方案工作区中的新模块，并更新 deployment.template.json 文件。 现在会看到两个模块文件夹：classifier 和 cameraCapture。

2. 打开 modules / cameraCapture 文件夹中的 main.py 文件。

3. 将整个文件替换为以下代码。 此示例代码将 POST 请求发送到在 classifier 模块中运行的图像处理服务。 我们提供的此模块容器包含可在请求中使用的示例图像。 此示例代码随后将响应打包为 IoT 中心消息并发送到输出队列。

   # Copyright (c) Microsoft. All rights reserved.
   # Licensed under the MIT license. See LICENSE file in the project root for
   # full license information.
   
   import time
   import sys
   import os
   import requests
   import json
   from azure.iot.device import IoTHubModuleClient, Message
   
   # global counters
   SENT_IMAGES = 0
   
   # global client
   CLIENT = None
   
   # Send a message to IoT Hub
   # Route output1 to $upstream in deployment.template.json
   def send_to_hub(strMessage):
       message = Message(bytearray(strMessage, 'utf8'))
       CLIENT.send_message_to_output(message, "output1")
       global SENT_IMAGES
       SENT_IMAGES += 1
       print( "Total images sent: {}".format(SENT_IMAGES) )
   
   # Send an image to the image classifying server
   # Return the JSON response from the server with the prediction result
   def sendFrameForProcessing(imagePath, imageProcessingEndpoint):
       headers = {'Content-Type': 'application/octet-stream'}
   
       with open(imagePath, mode="rb") as test_image:
           try:
               response = requests.post(imageProcessingEndpoint, headers = headers, data = test_image)
               print("Response from classification service: (" + str(response.status_code) + ") " + json.dumps(response.json()) + "\n")
           except Exception as e:
               print(e)
               print("No response from classification service")
               return None
   
       return json.dumps(response.json())
   
   def main(imagePath, imageProcessingEndpoint):
       try:
           print ( "Simulated camera module for Azure IoT Edge. Press Ctrl-C to exit." )
   
           try:
               global CLIENT
               CLIENT = IoTHubModuleClient.create_from_edge_environment()
           except Exception as iothub_error:
               print ( "Unexpected error {} from IoTHub".format(iothub_error) )
               return
   
           print ( "The sample is now sending images for processing and will indefinitely.")
   
           while True:
               classification = sendFrameForProcessing(imagePath, imageProcessingEndpoint)
               if classification:
                   send_to_hub(classification)
               time.sleep(10)
   
       except KeyboardInterrupt:
           print ( "IoT Edge module sample stopped" )
   
   if __name__ == '__main__':
       try:
           # Retrieve the image location and image classifying server endpoint from container environment
           IMAGE_PATH = os.getenv('IMAGE_PATH', "")
           IMAGE_PROCESSING_ENDPOINT = os.getenv('IMAGE_PROCESSING_ENDPOINT', "")
       except ValueError as error:
           print ( error )
           sys.exit(1)
   
       if ((IMAGE_PATH and IMAGE_PROCESSING_ENDPOINT) != ""):
           main(IMAGE_PATH, IMAGE_PROCESSING_ENDPOINT)
       else: 
           print ( "Error: Image path or image-processing endpoint missing" )
   

4. 保存 main.py 文件。

5. 打开 requirements.txt 文件。

6. 为将要包括在容器中的库添加新的一行。

   requests
   

7. 保存 requirements.txt 文件。

我们将使用单个测试图像，而不会通过实际摄像头来提供此方案的图像源。 测试图像包含在 GitHub 存储库中，你在本教程前面已下载适用于训练图像的该库。

1. 导航到 Cognitive-CustomVision-Windows / Samples / Images / Test 中的测试图像。

2. 复制 test_image.jpg

3. 浏览到 IoT Edge 解决方案目录，将测试图像粘贴到 modules / cameraCapture 文件夹中。 该图像应该置于你在上一部分编辑的 main.py 文件所在的文件夹中。

4. 在 Visual Studio Code 中打开适用于 cameraCapture 模块的 Dockerfile.amd64 文件。

5. 在建立工作目录 WORKDIR /app 的行后面，添加以下代码行：

   ADD ./test_image.jpg .
   

6. 保存 Dockerfile。

到目前为止，你已在本教程中训练了一个用于对树的图像分类的自定义视觉模型，并且已将该模型打包成一个 IoT Edge 模块。 然后，你创建了另一个模块，该模块可以查询图像分类服务器并将其结果报告回 IoT 中心。 现在可以创建部署清单了。该清单会告知 IoT Edge 设备如何同时启动并运行这两个模块。

适用于 Visual Studio Code 的 IoT Edge 扩展在每个 IoT Edge 解决方案中提供了一个模板，用于创建部署清单。

1. 在解决方案文件夹中打开 deployment.template.json 文件。

2. 找到 modules 节，其中应包含三个模块：两个你创建的，即 classifier 和 cameraCapture，第三个是默认包含的，即 SimulatedTemperatureSensor。

3. 删除 SimulatedTemperatureSensor 模块及其所有参数。 包括此模块是为了提供测试方案的示例数据，但我们在此部署中不需要它。

4. 如果为图像分类模块提供了 classifier 之外的名称，现在请检查该名称，确保其采用全小写形式。 cameraCapture 模块调用 classifier 模块时使用的请求库可以将所有请求格式化为小写，而 IoT Edge 区分大小写。

5. 使用以下 JSON 更新 cameraCapture 模块的 createOptions 参数。 此信息在模块容器中创建环境变量，该容器是在 main.py 进程中检索的。 将此信息包含在部署清单中即可更改图像或终结点，不需重新生成模块图像。

   "createOptions": "{\"Env\":[\"IMAGE_PATH=test_image.jpg\",\"IMAGE_PROCESSING_ENDPOINT=http://classifier/image\"]}"
   

   如果为自定义视觉模块提供了 classifier 之外的名称，请更新图像处理终结点值，使之匹配。

6. 在文件底部，更新 $edgeHub 模块的 routes 参数。 你希望将预测结果从 cameraCapture 路由到 IoT 中心。

       "routes": {
         "cameraCaptureToIoTHub": "FROM /messages/modules/cameraCapture/outputs/* INTO $upstream"
       },
   

   如果为第二个模块提供了 cameraCapture 之外的名称，请更新路由值，使之匹配。

7. 保存 deployment.template.json 文件。

创建两个模块并配置部署清单模板以后，即可生成容器映像并将其推送到容器注册表。

映像位于注册表中以后，即可将解决方案部署到 IoT Edge 设备。 可以通过 IoT 中心设置设备上的模块，但是也可以通过 Visual Studio Code 访问 IoT 中心和设备。 在此部分，请先设置对 IoT 中心的访问权限，然后使用 Visual Studio Code 将解决方案部署到 IoT Edge 设备。

首先，生成解决方案并将其推送到容器注册表。

1. 选择“查看”>“终端”，打开 Visual Studio Code 集成终端 。

2. 在终端中输入以下命令，以登录到 Docker。 使用 Azure 容器注册表中的用户名、密码和登录服务器登录。 可以在 Azure 门户中从注册表的“访问密钥”部分检索这些值。

   docker login -u <ACR username> -p <ACR password> <ACR login server>
   

   可能会收到一条安全警告，推荐使用 --password-stdin。 这条最佳做法是针对生产方案建议的，这超出了本教程的范畴。 有关详细信息，请参阅 docker login azure --cloud-name AzureChinaCloud 参考。

3. 在 Visual Studio Code 资源管理器中，右键单击 deployment.template.json 文件，然后选择“生成并推送 IoT Edge 解决方案”。

   “生成并推送”命令会启动三项操作。 首先，它在解决方案中创建名为 config 的新文件夹，用于保存基于部署模板和其他解决方案文件中的信息生成的完整部署清单。 其次，它会运行 docker build，以基于目标体系结构的相应 dockerfile 生成容器映像。 然后，它会运行 docker push，以将映像存储库推送到容器注册表。

   首次执行此过程可能需要几分钟时间，但下次运行命令时速度会变快。

使用 Visual Studio Code 资源管理器和 Azure IoT Edge 扩展将模块项目部署到 IoT Edge 设备。 你已经为方案准备了部署清单，即 config 文件夹中的 deployment.amd64.json 文件。 现在需要做的就是选择一个设备来接收部署。

确保 IoT Edge 设备已启动并运行。

1. 在 Visual Studio Code 资源管理器中的“Azure IoT 中心”部分下，展开“设备”可查看 IoT 设备的列表。

2. 右键单击 IoT Edge 设备的名称，然后选择“为单个设备创建部署”。

3. 选择 config 文件夹中的 deployment.amd64.json 文件，然后选择 Edge 部署清单。 请勿使用 deployment.template.json 文件。

4. 在设备下，展开“模块”可查看已部署的正在运行的模块的列表。 选择“刷新”按钮。 此时应看到新的 classifier 和 cameraCapture 模块与 $edgeAgent 和 $edgeHub 一起运行 。

也可查看设备本身上的所有模块是否都已启动并运行。 在 IoT Edge 设备上运行以下命令，以便查看模块的状态。

iotedge list

启动模块可能需要数分钟时间。 IoT Edge 运行时需要接收其新的部署清单，从容器运行时下拉模块映像，然后启动每个新模块。

可以通过两种方式来查看模块的结果，一种是生成和发送消息时在设备本身上查看，另一种是在消息到达 IoT 中心时通过 Visual Studio Code 查看。

通过设备查看 cameraCapture 模块的日志，了解发送消息以后系统确认 IoT 中心接收到消息这一过程。

iotedge logs cameraCapture

例如，你应该会看到如下输出：

admin@vm:~$ iotedge logs cameraCapture
Simulated camera module for Azure IoT Edge. Press Ctrl-C to exit.
The sample is now sending images for processing and will indefinitely.
Response from classification service: (200) {"created": "2023-07-13T17:38:42.940878", "id": "", "iteration": "", "predictions": [{"boundingBox": null, "probability": 1.0, "tagId": "", "tagName": "hemlock"}], "project": ""}

Total images sent: 1
Response from classification service: (200) {"created": "2023-07-13T17:38:53.444884", "id": "", "iteration": "", "predictions": [{"boundingBox": null, "probability": 1.0, "tagId": "", "tagName": "hemlock"}], "project": ""}

你还可以从 Visual Studio Code 查看消息。 右键单击 IoT Edge 设备的名称，选择“开始监视内置事件终结点”。

[IoTHubMonitor] [2:43:36 PM] Message received from [vision-device/cameraCapture]:
{
  "created": "2023-07-13T21:43:35.697782",
  "id": "",
  "iteration": "",
  "predictions": [
    {
      "boundingBox": null,
      "probability": 1,
      "tagId": "",
      "tagName": "hemlock"
    }
  ],
  "project": ""
}

自定义视觉模块中的结果是从 cameraCapture 模块作为消息发送的，其中包括图像为铁杉树或樱花树的概率。 由于图像为铁杉，因此会看到概率为 1.0。

如果打算继续学习下一篇建议的文章，可以保留已创建的资源和配置，以便重复使用。 还可以继续使用相同的 IoT Edge 设备作为测试设备。

否则，可以删除本文中使用的本地配置和 Azure 资源，以免产生费用。

删除 Azure 资源和资源组的操作不可逆。 请确保不要意外删除错误的资源组或资源。 如果在现有的包含要保留资源的资源组中创建了 IoT 中心，请只删除 IoT 中心资源本身，而不要删除资源组。

若要删除资源，请执行以下操作：

1. 登录到 Azure 门户，然后选择“资源组”。

2. 选择包含 IoT Edge 测试资源的资源组的名称。

3. 查看资源组包含的资源列表。 若要删除这一切，可以选择“删除资源组”。 如果只需删除部分，可以选择每个资源以单独删除。

在本教程中，你训练了一个自定义视觉模型并将其作为模块部署到了 IoT Edge 设备中。 然后，你生成了一个模块，该模块可以查询图像分类服务并将其结果报告回 IoT 中心。

继续阅读后续教程，了解如何使用 Azure IoT Edge 通过其他方式将数据转化为边缘业务见解。