マイクロサービスとしてのオブジェクト検出モデルのデプロイ

サポートされるプラットフォーム: Linux^®、Windows^®、macOS

この例では、MATLAB^® オブジェクト検出モデルからマイクロサービスの Docker^® イメージを作成する方法を説明します。MATLAB Compiler SDK™ で作成されたマイクロサービスのイメージは、MATLAB コードにアクセスするための HTTP/HTTPS エンドポイントを提供します。

MATLAB 関数をデプロイ可能なアーカイブにパッケージ化し、アーカイブと最小限の MATLAB Runtime パッケージを含む Docker イメージを作成します。次に、Docker でイメージを実行し、任意の MATLAB Production Server™ クライアント API を使用して、サービスへの呼び出しを行います。

必要な製品

MATLAB コマンドプロンプトで「ver」と入力し、次の製品がインストールされているかどうかを確認します。

MATLAB
Image Processing Toolbox™
Deep Learning Toolbox™
Computer Vision Toolbox™
MATLAB Compiler™
MATLAB Compiler SDK

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 の Web サイトの指示に従って、Docker のインストールと設定を行います。
docs.docker.com/engine/install/
- Windows でマイクロサービスのイメージをビルドするには、Docker Desktop または Docker on Windows Subsystem for Linux v2 (WSL2) をインストールする必要があります。Docker Desktop をインストールする場合は、docs.docker.com/desktop/install/windows-install// を参照してください。
  WSL2 に Docker をインストールする方法の説明については、https://www.mathworks.com/matlabcentral/answers/1758410-how-do-i-install-docker-on-wsl2 を参照してください。
使用しているコンピューターがインターネットに接続していない場合、インターネットに接続しているコンピューターから Linux 用の MATLAB Runtime インストーラーをダウンロードし、そのインストーラーをインターネットに接続していないコンピューターに移す必要があります。次に、オフラインのマシンでコマンド compiler.runtime.createInstallerDockerImage(filepath) を実行します。ここで、filepath は MATLAB Runtime インストーラーアーカイブのパスです。
インストーラーは MathWorks^® の Web サイトからダウンロードできます。
https://www.mathworks.com/products/compiler/matlab-runtime.html

オブジェクトを検出する MATLAB 関数の作成

この例では、以下のコードを使用して、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);

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]

compiler.build.Results オブジェクト 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/r2024a/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 コマンドを使用し、入力引数 4 を指定してポート 9900 を介して JSON クエリをサービスに送信します。JSON リクエストの作成の詳細については、MATLAB データ型の JSON 表現 (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 の中央レジストリ Docker Hub にプッシュするか、プライベートレジストリにプッシュします。これが最も一般的なワークフローです。
イメージを tar アーカイブとして保存するか、他のユーザーと共有します。このワークフローは、ただちにテストを行う場合に適しています。

イメージを Docker Hub またはプライベートレジストリにプッシュする方法の詳細については、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

参考

compiler.package.microserviceDockerImage | compiler.build.productionServerArchive