将目标检测模型部署为微服务

此示例说明如何从 MATLAB^® 目标检测模型创建微服务 Docker^® 镜像。通过 MATLAB Compiler™ 创建的微服务镜像提供一个可用于访问 MATLAB 代码的 HTTP/HTTPS 端点。

您可以先将 MATLAB 函数打包成可部署存档，然后创建包含该存档和最小 MATLAB Runtime 包的 Docker 镜像。之后，您可以在 Docker 中运行该镜像，并使用任何 MATLAB Production Server™ 客户端 API 调用服务。

示例文件列表

打开实时脚本

cvt.m

要下载示例文件，请在 MATLAB 命令行窗口中键入以下内容。

openExample("compilersdk/ObjectDetectionMicroserviceExample", workDir=pwd)

下载支持包

在 MATLAB 命令提示符下键入 matlabshared.supportpkg.getInstalled 以验证是否安装了以下附加功能：

Computer Vision Toolbox™ Model for YOLO v4 Object Detection

如果您需要安装该附加功能，请点击 MATLAB 工具条中的附加功能图标，然后搜索该附加功能。您也可以从 MathWorks File Exchange 下载并安装该附加功能。

前提条件

验证您是否已在开发计算机上安装了 MATLAB Compiler SDK™。
通过在 MATLAB 命令行窗口中键入 [~,msg] = system('docker version')，验证您是否已在开发计算机上安装并配置了 Docker。如果您使用的是 WSL，请改用命令 [~,msg] = system('wsl docker version')。
如果您尚未安装 Docker，请按照 Docker 网站上的说明安装并设置 Docker。有关详细信息，请参阅 docs.docker.com/engine/install/。
要在 Windows® 上构建微服务镜像，您必须安装 Docker Desktop 或在 Windows Subsystem for Linux v2 (WSL2) 上安装 Docker。要安装 Docker Desktop，请参阅 docs.docker.com/desktop/setup/install/windows-install/。有关如何在 WSL2 上安装 Docker 的说明，请参阅 https://www.mathworks.com/matlabcentral/answers/1758410-how-do-i-install-docker-on-wsl2。
如果您使用的计算机未连接到 Internet，则您必须从连接到 Internet 的计算机下载 Linux® 版的 MATLAB Runtime 安装程序，再将该安装程序传输到该未连接到 Internet 的计算机。然后，在该离线计算机上运行命令 compiler.runtime.createInstallerDockerImage，其中 filepath 是 MATLAB Runtime 安装程序存档的路径。您可以从 MathWorks® 网站下载该安装程序。有关详细信息，请参阅 https://www.mathworks.com/products/compiler/matlab-runtime.html。

创建 MATLAB 函数以检测目标

使用以下代码编写一个名为 cvt 的目标检测函数。将该函数保存在名为 cvt.m 的文件中。

function [bboxes, scores, labels] = cvt(imageUrl)
iminfo = imfinfo(imageUrl);
    % Read image
    % If indexed image, read colormap and convert to rgb
    if strcmp(iminfo.ColorType,'indexed') == 1
        [im, cmap] = webread(imageUrl, 'Timeout', 10);
        im = ind2rgb(im, cmap);
    else
        im = webread(imageUrl, 'Timeout', 10);
    end
% Add  pretrained YOLO v4 dataset tinyYOLOv4COCO.mat to MATLAB path for testing
% Comment or remove the next 2 lines of code prior to deploying as microservice
detectorPath = [matlabshared.supportpkg.getSupportPackageRoot, '/toolbox/vision/supportpackages/yolov4/data'];
addpath(detectorPath)
load('tinyYOLOv4COCO.mat', 'detector');

% Detect objects in image using detector
[bboxes,scores,labels] = detect(detector,im);
labels = cellstr(labels);
end

从 MATLAB 命令行测试该函数：

%% Specify image URL
imageUrl = "https://www.mathworks.com/help/examples/deeplearning_shared/win64/TrafficSignDetectionAndRecognitionExample_02.png"
%% Display image
imageFile = "trafficimage.jpg";
imageFileFullPath = websave(imageFile, imageUrl);
[im, cmap] = imread(imageFileFullPath);
imshow(im, cmap)
%% Detect objects in image
[bboxes, scores, labels] = cvt(imageUrl)

bboxes =
  2×4 single matrix
  445.3871  326.4009  223.3270   98.7086
  504.2861  271.4571   45.7471   41.0955
scores =
  2×1 single column vector
    0.9151
    0.6610
labels =
  2×1 cell array
    {'truck'    }
    {'stop sign'}

创建可部署存档

在创建可部署档案之前，请在 cvt.m 文件中注释以下代码行。

% detectorPath = [matlabshared.supportpkg.getSupportPackageRoot, '/toolbox/vision/supportpackages/yolov4/data'];
% addpath(detectorPath)

使用 compiler.build.productionServerArchive 函数将 cvt 函数打包成可部署存档。

您可以使用名称-值参量在 compiler.build 命令中指定其他选项。有关详细信息，请参阅compiler.build.productionServerArchive。

buildResults = compiler.build.productionServerArchive('cvt.m', ...
    'ArchiveName','yolov4od','Verbose',true, ...
    'SupportPackages',{'Computer Vision Toolbox Model for YOLO v4 Object Detection'});

buildResults = 
  Results with properties:

                  BuildType: 'productionServerArchive'
                      Files: {'/home/mluser/work/yolov4odproductionServerArchive/yolov4od.ctf'}
    IncludedSupportPackages: {'Computer Vision Toolbox Model for YOLO v4 Object Detection'}
                    Options: [1×1 compiler.build.ProductionServerArchiveOptions]
        RuntimeDependencies: [1×1 compiler.runtime.Dependencies]

buildResults 对象包含有关编译类型、生成的文件、包含的支持包和编译选项的信息。

编译完成后，该函数会在您的当前目录中创建一个名为 yolov4odproductionServerArchive 的文件夹来存储可部署存档。

将存档打包成微服务 Docker 镜像

使用您创建的 buildResults 对象构建微服务 Docker 镜像。

您可以使用名称-值参量在 compiler.build 命令中指定其他选项。有关详细信息，请参阅compiler.package.microserviceDockerImage。

compiler.package.microserviceDockerImage(buildResults,...
    'ImageName','yolov4od-microservice',...
    'DockerContext',fullfile(pwd,'microserviceDockerContext'));

该函数会在当前工作目录中名为 microserviceDockerContext 的文件夹中生成以下文件：

applicationFilesForMATLABCompiler/yolov4od.ctf - 可部署存档文件。
Dockerfile - 指定 Docker 运行时选项的 Docker 文件。
GettingStarted.txt - 包含部署信息的文本文件。

测试 Docker 镜像

在系统命令行窗口中，确认您的 yolov4od-microservice 镜像在 Docker 镜像列表中。

docker images

REPOSITORY                                      TAG           IMAGE ID            CREATED             SIZE
yolov4od-microservice                           latest        4401fa2bc057        33 seconds ago      7.56GB
matlabruntime/r2022b/update0/4200000000000000   latest        5259656e4a32        24 minutes ago      7.04GB

从系统命令提示符运行 yolov4od-microservice 微服务镜像。

docker run --rm -p 9900:9910 yolov4od-microservice -l trace &

端口 9910 是 Docker 容器内微服务公开的默认端口。您可以将微服务映射到主机上的任何可用端口。对于此示例，微服务映射到端口 9900。

您可以在 Docker 命令中指定其他选项。有关完整选项列表，请参阅微服务命令参量。

当微服务容器在 Docker 中运行后，您可以通过在 Web 浏览器中转至以下 URL 来检查服务的状态：http://hostname:9900/api/health

如果服务已准备就绪，可以接收请求，您将看到以下消息："status: ok"

测试正在运行的服务。在终端中，使用 curl 命令通过端口 9900 向服务发送 JSON 查询。有关构造 JSON 请求的详细信息，请参阅MATLAB 数据类型的 JSON 表示 (MATLAB Production Server) (MATLAB Production Server)。

curl -v -H Content-Type:application/json \
-d '{"nargout":3,"rhs":["https://www.mathworks.com/help/examples/deeplearning_shared/win64/TrafficSignDetectionAndRecognitionExample_02.png"]}' \ 
"http://hostname:9900/yolov4od/cvt" | jq -c

输出为：

{"lhs":[{"mwdata":[445.387146,504.286102,326.40094,271.457092,223.327026,45.7471,98.7086487,41.09552],"mwsize":[2,4],"mwtype":"single"},
{"mwdata":[0.91510725,0.661022],"mwsize":[2,1],"mwtype":"single"},
{"mwdata":[{"mwdata":["truck"],"mwsize":[1,5],"mwtype":"char"},
{"mwdata":["stop sign"],"mwsize":[1,9],"mwtype":"char"}],"mwsize":[2,1],"mwtype":"cell"}]}

您也可以从 MATLAB 桌面进行测试：

%% Import MATLAB HTTP interface packages
import matlab.net.*
import matlab.net.http.*
import matlab.net.http.fields.*

%% Setup message body
body = MessageBody;
body.Payload = ...
    '{"nargout": 3,"rhs": ["https://www.mathworks.com/help/examples/deeplearning_shared/win64/TrafficSignDetectionAndRecognitionExample_02.png"]}';

%% Setup request
requestUri = URI('http://hostname:9900/yolov4od/cvt');
options = matlab.net.http.HTTPOptions('ConnectTimeout',20,...
    'ConvertResponse',false);
request = RequestMessage;
request.Header = HeaderField('Content-Type','application/json');
request.Method = 'POST';
request.Body = body;

%% Send request & view raw response
response = request.send(requestUri, options);
disp(response.Body.Data)

%% Decode JSON
lhs = mps.json.decoderesponse(response.Body.Data);

%% Clean up printed output
for i = 1:length(lhs)
    [r,c] = size(lhs{i});
    if ~iscell(lhs{i}) && c==1
        tmp(:,i) = num2cell(lhs{i});
    elseif ~iscell(lhs{i}) && c~=1
        tmp(:,i) = num2cell(lhs{i},2);
    else
        tmp(:,i) = lhs{i};
    end
end
%% Display response as a table
T = cell2table(tmp,'VariableNames',{'Boxes', 'Scores', 'Labels'})

输出为：

T =

  2×3 table

                   Boxes                    Scores        Labels    
    ____________________________________    _______    _____________

    445.39     326.4    223.33    98.709    0.91511    {'truck'    }
    504.29    271.46    45.747    41.096    0.66102    {'stop sign'}

要停止服务，请使用以下命令显示容器 ID。

docker ps

CONTAINER ID        IMAGE                   COMMAND                  CREATED             STATUS              PORTS                    NAMES
f372b8b574e8        yolov4od-microservice   "/opt/matlabruntime/…"   6 hours ago         Up 6 hours          0.0.0.0:9900->9910/tcp   distracted_panini

使用指定的容器 ID 停止服务。

docker stop f372b8b574e8

共享 Docker 镜像

您的 Docker 镜像可以通过多种方式共享。

将您的镜像推送到 Docker 的中央注册表 DockerHub，或者推送到您的私有注册表。这是最常见的工作流。
将您的镜像保存为 tar 存档，然后与他人共享。该工作流适合于立即测试。

有关将您的镜像推送到 DockerHub 或您的私有注册表的详细信息，请查阅 Docker 文档。

将 Docker 镜像保存为 Tar 存档

要将您的 Docker 镜像保存为 tar 存档，请打开系统命令行窗口，导航到 Docker 上下文文件夹，然后键入以下命令。

docker save yolov4od-microservice -o yolov4od-microservice.tar

此命令会在当前文件夹中创建一个名为 yolov4od-microservice.tar 的文件。在与其他用户共享 tarball 之前，请设置适当的权限（例如，使用 chmod 进行设置）。

从 Tar 存档加载 Docker 镜像

在最终用户计算机上加载 tarball 中包含的镜像。

docker load --input yolov4od-microservice.tar

验证镜像是否已加载。

docker images

运行 Docker 镜像

docker run --rm -p 9900:9910 yolov4od-microservice

另请参阅

matlabshared.supportpkg.getInstalled | compiler.build.productionServerArchive | compiler.package.microserviceDockerImage | compiler.runtime.createInstallerDockerImage

主题

创建微服务 Docker 镜像