Skip to content

Latest commit

 

History

History
215 lines (152 loc) · 10.2 KB

get_started.md

File metadata and controls

215 lines (152 loc) · 10.2 KB

快速上手

MMDeploy提供了一系列工具，帮助你更轻松的将OpenMMLab下的算法部署到各种设备与平台上。你可以使用我们设计的流程一“部”到位，也可以定制你自己的转换流程。这份指引将会向你展示MMDeploy的基本使用方式，并帮助你将 MMDeploy SDK 整合进你的应用。

准备工作

首先我们需要根据安装指南正确安装MMDeploy。注意！ 不同推理后端的安装方式略有不同。可以根据下面的介绍选择最适合你的推理后端：

  • ONNXRuntime: ONNX Runtime 是一个跨平台的机器学习训练推理加速器，通过图形优化和变换以及硬件加速器提供优秀的推理性能。拥有完善的对ONNX的支持。
  • TensorRT: NVIDIA® TensorRT™ 是一个用于高性能深度学习推理的开发工具包（SDK）。借助Nvidia的设备特性，TensorRT可以优化模型的推理，提供更低的推理延迟以及更高的吞吐量。如果你希望将模型部署在NVIDIA硬件设备上，那么TensorRT就是一个合适的选择。
  • ncnn: ncnn 是一个为手机端极致优化的高性能神经网络前向计算框架。ncnn 从设计之初深刻考虑手机端的部署和使用。无第三方依赖，跨平台。基于 ncnn，开发者能够将深度学习算法轻松移植到手机端高效执行，开发出人工智能 APP，将 AI 带到你的指尖。
  • PPLNN: PPLNN是一个为高效AI推理所开发的高性能深度学习推理引擎。可以用于各种ONNX模型的推理。并且对OpenMMLab有非常强的支持。
  • OpenVINO: OpenVINO™ 是一个为优化与部署AI推理开发的开源工具集。该工具集可无缝集成到 Intel 硬件平台，包括最新的神经网络加速芯片，Intel计算棒，边缘设备等。

选择最适合你的推理后端，点击对应的连接查看具体安装细节

模型转换

一旦你完成了MMDeploy的安装，就可以用一条指令轻松的将OpenMMLab的PyTorch模型转换成推理后端支持的格式！以 MMDetection 中的 Faster-RCNN 到 TensorRT 的转换为例：

# 本例假设 MMDeploy 所在目录为 ${MMDEPLOY_DIR}， MMDetection 所在目录为 ${MMDET_DIR}
# 如果你不知道具体的安装位置，可以在终端通过命令 `pip show mmdeploy` 和 `pip show mmdet` 查看

python ${MMDEPLOY_DIR}/tools/deploy.py \
    ${MMDEPLOY_DIR}/configs/mmdet/detection/detection_tensorrt_dynamic-320x320-1344x1344.py \
    ${MMDET_DIR}/configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py \
    ${CHECKPOINT_DIR}/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth \
    ${INPUT_IMG} \
    --work-dir ${WORK_DIR} \
    --device cuda:0 \
    --dump-info

${MMDEPLOY_DIR}/tools/deploy.py 是一个方便模型转换的工具。可以阅读 如何转换模型 了解更多细节。转换后的模型以及一些其他的信息将会被保存在 ${WORK_DIR} 中。MMDeploy SDK 可以使用这些信息进行模型推理。

detection_tensorrt_dynamic-320x320-1344x1344.py 是一个包含所有转换需要的可配置参数的配置文件。该文件的命名遵循如下规则：

<任务名>_<推理后端>-[后端特性]_<动态模型支持>.py

可以很容易的通过文件名来确定最适合的那个配置文件。如果你希望定制自己的转换配置，可以修改配置文件中的具体条目。我们提供了 如何编写配置文件 来指导你如何进行编辑。

模型推理

得到了转换后的模型之后，就可以使用推理后端提供的API来进行推理。也许你想绕过API的学习与开发，确认下转换后的模型效果。我们提供了对这些API的统一封装：

from mmdeploy.apis import inference_model

result = inference_model(model_cfg, deploy_cfg, backend_models, img=img, device=device)

inference_model会创建一个对后端模型的封装，通过该封装进行推理。推理的结果会保持与OpenMMLab中原模型同样的格式。

模型评估

转换后的模型是否会带来一些精度损失？推理后端是否为模型带来效率提升？我们提供了工具来帮助完成验证与评估工作。以TensorRT的Faster-RCNN模型为例：

python ${MMDEPLOY_DIR}/tools/test.py \
    ${MMDEPLOY_DIR}/configs/detection/detection_tensorrt_dynamic-320x320-1344x1344.py \
    ${MMDET_DIR}/configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py \
    --model ${BACKEND_MODEL_FILES} \
    --metrics ${METRICS} \
    --device cuda:0

请阅读 如何进行模型评估 了解关于 tools/test.py 的使用细节。

整合 MMDeploy SDK

请参考安装指南，在编译 MMDeploy 时开启MMDEPLOY_BUILD_SDK以安装 MMDeploy SDK。 成功安装后，安装目录的文件结构将会如下所示：

install
├── example
├── include
│   ├── c
│   └── cpp
└── lib

其中 include/c 和 include/cpp 分别对应 C 与 C++ API。

注意：C++的API尚处于不稳定阶段，可能会在未来发生变动，暂时不推荐使用

在 example 目录下有包含分类，目标检测，图像分割等数个范例。可以通过他们学习如何使用 MMDeploy SDK 以及如何将 ${MMDeploy_LIBS} 链接到应用程序。

从零开始进行模型部署

这章节将会展示如何从零开始进行 MMDetection 中 Faster-RCNN 的模型部署与推理。

创建虚拟环境并安装 MMDetection

请运行下面的指令在Anaconda环境中安装MMDetection。

conda create -n openmmlab python=3.7 -y
conda activate openmmlab

conda install pytorch==1.8.0 torchvision==0.9.0 cudatoolkit=10.2 -c pytorch -y

# 安装最新的mmcv
pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html

# 安装mmdetection
git clone https://github.com/open-mmlab/mmdetection.git
cd mmdetection
pip install -r requirements/build.txt
pip install -v -e .

下载 Faster R-CNN 的模型文件

请从本链接下载模型文件，放在{MMDET_ROOT}/checkpoints目录下。其中{MMDET_ROOT}为你的MMDetection的根目录。

安装 MMDeploy 以及 ONNX Runtime

请运行下面的指令在Anaconda环境中安装MMDeploy。

conda activate openmmlab

git clone https://github.com/open-mmlab/mmdeploy.git
cd mmdeploy
git submodule update --init --recursive
pip install -e .

一旦我们完成MMDeploy的安装，我们需要选择一个模型的推理引擎。这里我们以ONNX Runtime为例。运行下面命令来安装ONNX Runtime：

pip install onnxruntime==1.8.1

然后下载 ONNX Runtime Library来编译 MMDeploy 中的算子插件：

wget https://github.com/microsoft/onnxruntime/releases/download/v1.8.1/onnxruntime-linux-x64-1.8.1.tgz

tar -zxvf onnxruntime-linux-x64-1.8.1.tgz
cd onnxruntime-linux-x64-1.8.1
export ONNXRUNTIME_DIR=$(pwd)
export LD_LIBRARY_PATH=$ONNXRUNTIME_DIR/lib:$LD_LIBRARY_PATH

cd ${MMDEPLOY_DIR} # 到 MMDeploy 根目录下
mkdir -p build && cd build

# 编译自定义算子
cmake -DMMDEPLOY_TARGET_BACKENDS=ort -DONNXRUNTIME_DIR=${ONNXRUNTIME_DIR} ..
make -j$(nproc)

# 编译 MMDeploy SDK
cmake -DMMDEPLOY_BUILD_SDK=ON \
      -DCMAKE_CXX_COMPILER=g++-7 \
      -DOpenCV_DIR=/path/to/OpenCV/lib/cmake/OpenCV \
      -Dspdlog_DIR=/path/to/spdlog/lib/cmake/spdlog \
      -DONNXRUNTIME_DIR=${ONNXRUNTIME_DIR} \
      -DMMDEPLOY_TARGET_BACKENDS=ort \
      -DMMDEPLOY_CODEBASES=mmdet ..
make -j$(nproc) && make install

模型转换

当我们成功安装 MMDetection, MMDeploy, ONNX Runtime 以及编译ONNX Runtime的插件之后，我们就可以将 Faster-RCNN 转换成 ONNX 格式，以支持 ONNX Runtime 下的模型推理。运行下面指令来使用我们的部署工具：

# 本例假设 MMDeploy 所在目录为 ${MMDEPLOY_DIR}， MMDetection 所在目录为 ${MMDET_DIR}
# 如果你不知道具体的安装位置，可以在终端通过命令 `pip show mmdeploy` 和 `pip show mmdet` 查看

python ${MMDEPLOY_DIR}/tools/deploy.py \
    ${MMDEPLOY_DIR}/configs/mmdet/detection/detection_onnxruntime_dynamic.py \
    ${MMDET_DIR}/configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py \
    ${MMDET_DIR}/checkpoints/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth \
    ${MMDET_DIR}/demo/demo.jpg \
    --work-dir work_dirs \
    --device cpu \
    --show \
    --dump-info

如果脚本运行成功，屏幕上将先后显示两张图片。首先是ONNX Runtime推理结果的可视化，然后是PyTorch推理结果的可视化。同时，ONNX文件 end2end.onnx 以及数个json文件（供SDK使用）将会被生成在work_dirs目录下。

运行 MMDeploy SDK demo

进行模型转换后，SDK模型将被保存在work_dirs目录下。 可以用如下方法编译并运行 MMDeploy SDK demo。

cd build/install/example

# 配置ONNX Runtime库目录
export LD_LIBRARY_PATH=/path/to/onnxruntime/lib
mkdir -p build && cd build
cmake -DOpenCV_DIR=path/to/OpenCV/lib/cmake/OpenCV \
      -DMMDeploy_DIR=${MMDEPLOY_DIR}/build/install/lib/cmake/MMDeploy ..
make object_detection
# 设置log等级
export SPDLOG_LEVEL=warn
# 运行目标检测范例程序
./object_detection cpu ${work_dirs} ${path/to/an/image}

如果demo运行成功，将会生成一张名为"output_detection.png"的图片，展示模型输出的可视化效果。

新模型的支持？

如果你希望使用的模型尚未被 MMDeploy 所支持，你可以尝试自己添加对应的支持。我们准备了如下的文档：

最后，欢迎大家踊跃提PR。