preprocess/detectron2/tools/deploy/README.md

See deployment tutorial for some high-level background about deployment.

This directory contains the following examples:

1. An example script export_model.py that exports a detectron2 model for deployment using different methods and formats.

2. A C++ example that runs inference with Mask R-CNN model in TorchScript format.

Build

Deployment depends on libtorch and OpenCV. Some require more dependencies:

• Running TorchScript-format models produced by --export-method=caffe2_tracing requires libtorch to be built with caffe2 enabled.
• Running TorchScript-format models produced by --export-method=tracing/scripting requires libtorchvision (C++ library of torchvision).

All methods are supported in one C++ file that requires all the above dependencies. Adjust it and remove code you don't need. As a reference, we provide a Dockerfile that installs all the above dependencies and builds the C++ example.

Use

We show a few example commands to export and execute a Mask R-CNN model in C++.

• export-method=tracing, format=torchscript:

./export_model.py --config-file ../../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \
    --output ./output --export-method tracing --format torchscript \
    MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl \
    MODEL.DEVICE cuda

./build/torchscript_mask_rcnn output/model.ts input.jpg tracing

• export-method=scripting, format=torchscript:

./export_model.py --config-file ../../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \
    --output ./output --export-method scripting --format torchscript \
    MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl \

./build/torchscript_mask_rcnn output/model.ts input.jpg scripting

• export-method=caffe2_tracing, format=torchscript:

./export_model.py --config-file ../../configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x.yaml \
    --output ./output --export-method caffe2_tracing --format torchscript \
    MODEL.WEIGHTS detectron2://COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_3x/137849600/model_final_f10217.pkl \

./build/torchscript_mask_rcnn output/model.ts input.jpg caffe2_tracing

Notes:

1. Tracing/Caffe2-tracing requires valid weights & sample inputs. Therefore the above commands require pre-trained models and COCO dataset. You can modify the script to obtain sample inputs in other ways instead of from COCO.

2. --run-eval is implemented only for tracing mode to evaluate the exported model using the dataset in the config. It's recommended to always verify the accuracy in case the conversion is not successful. Evaluation can be slow if model is exported to CPU or dataset is too large ("coco_2017_val_100" is a small subset of COCO useful for evaluation). caffe2_tracing accuracy may be slightly different (within 0.1 AP) from original model due to numerical precisions between different runtime.