Update README.md

MegEngine · Jun 22, 2022 · da3f80a · da3f80a
1 parent e90948d
commit da3f80a
Showing 1 changed file with 60 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -1,16 +1,36 @@
 # MgeConvert
 
-适用于 [MegEngine](https://github.com/MegEngine/MegEngine) 的各种转换器, 目前支持的框架有 [Caffe](https://github.com/BVLC/caffe)、[ONNX](https://github.com/onnx/onnx) 和 TFLite。
+MgeConvert 是适用于 [MegEngine](https://github.com/MegEngine/MegEngine) 模型的转换器, 可将MegEngine导出的[mge静态图模型](https://www.megengine.org.cn/doc/stable/zh/user-guide/model-development/serialization/index.html#dump-traced-model)或[TracedModule模型](https://www.megengine.org.cn/doc/stable/zh/user-guide/model-development/traced_module/quick-start.html#tracedmodule)转换为第三方模型文件。
+
+目前支持转换的第三方框架有 [Caffe](https://github.com/BVLC/caffe)、[ONNX](https://github.com/onnx/onnx) 和 [TFLite](https://www.tensorflow.org/lite/guide)，支持的模型包括 ResNet、ResNext、ShuffleNet 等，如果需要适配其他模型, 可能需要添加更多的算子支持。
 
-MgeConvert转换工具位于converters目录下，可直接调用其中的脚本将MegEngine导出的mge/TracedModule模型转换为第三方模型文件。
 目前，MgeConvert 亦支持将 ONNX 模型转换到 mge/TracedModule 模型。
 
+![mgeconvert](https://user-images.githubusercontent.com/15715998/174760137-1252ae3c-4be0-4cdd-9314-ab94edd7e439.png)
+
 MgeConvert转换器的结构包含前端、中间表示（IR）、后端三个部分：
 1. 前端的部分位于 `frontend` 目录下, 支持 mge 和 traced module 模型格式，可以将 MegEngine 序列化出来的计算图转为IR图结构
 2. IR部分位于 `converter_ir`目录下，包含图和 IR 算子定义、对计算图做变换的 transform rules 以及对量化模型处理的量化器
 3. 后端的部分位于 `backend` 目录下，包含caffe、onnx、tflite的转换器，可以将IR图结构转换为第三方框架的模型文件
 
-目前支持的模型包括 ResNet、ResNext、ShuffleNet 等，如果需要适配其他模型, 可能需要添加更多的算子支持。
+- [MgeConvert](#mgeconvert)
+  - [Feature 支持说明](#feature-支持说明)
+  - [依赖说明](#依赖说明)
+  - [安装方式](#安装方式)
+    - [pip 安装(推荐)](#pip-安装推荐)
+    - [源代码安装](#源代码安装)
+  - [使用方式](#使用方式)
+    - [1. 命令行使用](#1-命令行使用)
+    - [1.1 :sparkles: caffe模型转换](#11-sparkles-caffe模型转换)
+      - [1.1.1 float模型转换](#111-float模型转换)
+      - [1.1.2 QAT模型转换](#112-qat模型转换)
+    - [1.2 :sparkles: tflite模型转换](#12-sparkles-tflite模型转换)
+      - [1.2.1 float模型转换](#121-float模型转换)
+      - [1.2.2 QAT模型转换](#122-qat模型转换)
+    - [1.3 :sparkles: onnx模型互转](#13-sparkles-onnx模型互转)
+    - [2. python接口使用](#2-python接口使用)
+  - [FAQ 常见问题说明](#faq-常见问题说明)
+  - [算子支持列表](#算子支持列表)
 
 ## Feature 支持说明
 
@@ -31,9 +51,7 @@ MgeConvert转换器的结构包含前端、中间表示（IR）、后端三个
 | Float32             | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 
 
-## 安装方式
-
-### 依赖说明
+## 依赖说明
 
 MgeConvert 基于 MegEngine 工作，因此确保您的电脑已经安装 MegEngine(>=1.0)。
 
@@ -50,58 +68,44 @@ MgeConvert 基于 MegEngine 工作，因此确保您的电脑已经安装 MegEng
  - Python packages: pybind11==2.6.2
  - third party: [flatbuffers](https://github.com/google/flatbuffers.git)==1.12.0
 
-> :warning: 安装时以上依赖覆盖本地版本，建议在虚拟环境中安装mgeconvert
+> :warning: 安装时以上依赖覆盖本地版本
 
-如果安装过0.5.0及之前版本的mgeconvert，需要先卸载旧版本：
-
-```bash
-sudo pip3 uninstall mgeconvert
-```
 
+## 安装方式
 
-### pip 安装
-
-- 以 caffe 为例，下面这条指令将通过``pip``包管理器安装开发版本的 caffe 转换器并处理相关依赖：
+> 如果安装过0.5.0及之前版本的mgeconvert，重新安装前请先使用sudo权限卸载旧版本：
+> 
+> ```bash
+> sudo pip3 uninstall mgeconvert
+> ```
 
-```bash
-python3 -m pip install git+https://github.com/MegEngine/mgeconvert.git --user --install-option="--targets=caffe"
-```
+### pip 安装(推荐)
+mgeconvert v1.0.0 开始支持源码包安装:
 
-> 建议指定版本号安装release版本的转换器，如安装0.4.2版本：
+- 以 caffe 为例，下面这条指令将安装caffe 转换器并处理相关依赖：
 
 ```bash
-python3 -m pip install git+https://github.com/MegEngine/mgeconvert[email protected] --user --install-option="--targets=caffe"
+pip3 install mgeconvert --user --install-option="--targets=caffe"
 ```
 
-> :warning: 如果需要转换``TracedModule``模型，请安装0.5.0以上版本
-
-
-- ``--targets`` 的可选值有 ``caffe``、``onnx``、``tflite`` 和 `all`。
+> ``--targets`` 的可选值有 caffe、onnx、tflite 和 all。 `all` 代表安装全部转换器。可选值支持组合传入，比如 ``--targets=caffe,tflite`` 。
 
-`all` 代表安装全部转换器。可选值支持组合传入，比如 ``--targets=caffe,tflite`` 。
+> ``tflite`` 转换器的schema默认使用r2.3版本，支持使用参数 ``tfversion`` 选择tflite schema的版本, 比如 ``--install-option="--targets=tflite --tfversion=r2.4"``
 
-- ``tflite`` 转换器的schema默认使用r2.3版本，支持使用参数 ``tfversion`` 选择tflite schema的版本, 例如：
-
-```bash
---install-option="--targets=tflite --tfversion=r2.4"
-```
-
-`tflite`转换器依赖的 `libflatbuffers.so`位于 `$HOME/.local/lib`下，使用前需要执行：
-
-```bash
-export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
-```
 
 ### 源代码安装
 
-安装选项说明同上，以 caffe 为例，下面的命令将安装0.4.2版本的caffe转换器：
+安装选项说明同上，以 caffe 为例，下面的命令将安装0.5.0版本的caffe转换器：
 
 ```bash
-git clone https://github.com/MegEngine/mgeconvert.git@v0.4.2
+git clone https://github.com/MegEngine/mgeconvert.git@v0.5.0
 cd mgeconvert
 pip3 install . --user --install-option="--targets=caffe"
 ```
 
+> :warning: 如果需要转换``TracedModule``模型，请安装0.5.0及以上版本
+
+
 ## 使用方式
 
 转换器按输入模型格式主要分为两种：
@@ -126,9 +130,9 @@ convert -h
 convert mge_to_caffe -h
 ```
 
-#### caffe模型转换
+### 1.1 :sparkles: caffe模型转换
 
-##### float模型转换
+#### 1.1.1 float模型转换
 
 - 转换mge模型的参考命令：
 
@@ -142,7 +146,7 @@ convert mge_to_caffe -i model.mge -c out.prototxt -b out.caffemodel
 convert tracedmodule_to_caffe -i model.tm -c out.prototxt -b out.caffemodel
 ```
 
-##### QAT模型转换
+#### 1.1.2 QAT模型转换
 mgeconvert 支持将 QAT TracedModule 模型转换到caffe：
 - QAT模型转caffe默认会导出量化参数文件，通过 `quantize_file_path` 指定量化参数文件路径：
 
@@ -156,18 +160,18 @@ convert tracedmodule_to_caffe -i qat_model.tm -c out.prototxt -b out.caffemodel
 convert tracedmodule_to_caffe -i qat_model.tm -c out.prototxt -b out.caffemodel --quantize_file_path quant_params.json --param_fake_quant
 ```
 
-- 如果QAT模型中没有QuantStub对输入数据进行量化处理，可以在转换时指定输入数据的量化类型、scale和zero_point量化参数 ：
+- 如果QAT模型中没有QuantStub对输入数据进行量化处理，可以用 **`--input_data_type --input_scales --input_zero_points`** 在转换时指定输入数据的量化类型、scale和zero_point量化参数，如果有多个scale、zero point用逗号隔开 ：
 
 ```bash
 convert tracedmodule_to_caffe -i qat_model.tm -c out.prototxt -b out.caffemodel --quantize_file_path quant_params.json --input_data_type quint8 --input_scales 0.125 --input_zero_points 128
 ```
 
 
-#### tflite模型转换
+### 1.2 :sparkles: tflite模型转换
 
 TFlite转换器支持 float32 和量化的 TracedModule 转换。
 
-##### float模型转换
+#### 1.2.1 float模型转换
 
 转换float模型的命令参考：
 
@@ -179,33 +183,33 @@ convert mge_to_tflite -i model.mge -o out.tflite
 convert tracedmodule_to_tflite -i tracedmodule.tm -o out.tflite
 ```
 
-##### QAT模型转换
+#### 1.2.2 QAT模型转换
 
 - 对于QAT模型，可以通过添加tracedmodule_to_tflite转换器中的 `require_quantize` 选项，转换出tflite支持的量化数据类型（int8/uint8/int16/int32）量化后的Quantized 模型:
 
 ```bash
 convert tracedmodule_to_tflite -i tracedmodule.tm -o out.tflite --require_quantize
 ```
 
-也可不设置 `require_quantize` 选项，转换出float32模型和量化参数文件。
+也可不设置 **`--require_quantize`** 选项，转换出float32模型和量化参数文件。
 
 ```bash
 convert tracedmodule_to_tflite -i tracedmodule.tm -o out.tflite --quantize_file_path quant_params.json
 ```
 
-- 对于QAT模型，还可以通过设置 `param_fake_quant` 参数来选择是否对参数进行假量化。
+- 对于QAT模型，还可以通过设置 **`--param_fake_quant`** 参数来选择是否对参数进行假量化。
 
 ```bash
 convert tracedmodule_to_tflite -i tracedmodule.tm -o out.tflite --quantize_file_path quant_params.json --param_fake_quant
 ```
 
-- 如果QAT模型中没有QuantStub对输入数据进行量化处理，可以在转换时指定输入数据的量化类型、scale和zero_point量化参数,如果有多个scale、zero point用逗号隔开：
+- 如果QAT模型中没有QuantStub对输入数据进行量化处理，可以用 **`--input_data_type --input_scales --input_zero_points`** 在转换时指定输入数据的量化类型、scale和zero_point量化参数，如果有多个scale、zero point用逗号隔开：
 
 ```bash
 convert tracedmodule_to_tflite -i tracedmodule.tm -o out.tflite --input_data_type quint8 --input_scales 0.125,0.125 --input_zero_points 128,128 --require_quantize
 ```
 
-#### onnx模型互转
+### 1.3 :sparkles: onnx模型互转
 
 mgeconvert 转 onnx 模型支持 [opset](https://github.com/onnx/onnx/blob/master/docs/Operators.md) 7~12 的转换。
 onnx 转 mge/TracedModule 对各时期的 opset 变更均进行了适配，理论上没有 opset 的限制。
@@ -232,7 +236,7 @@ convert onnx_to_tracedmodule -i tracedmodule.onnx -o out.tm
 
 可参考[wiki](https://github.com/MegEngine/mgeconvert/wiki/Mgeconvert-Python-Api-Doc)中的例子。
 
-## 常见问题说明
+## FAQ 常见问题说明
 
 1. 安装时出现类似报错：
 
@@ -243,9 +247,9 @@ error removing /home/user/.local/lib/python3.6/site-packages/mgeconvert-0.5.0-py
 
 这是使用sudo安装过旧版本出现的权限问题，先卸载旧版本再安装：
 
-```bash
-sudo pip3 uninstall mgeconvert
-```
+> ```bash
+> sudo pip3 uninstall mgeconvert
+> ```
 
 2. 使用`tflite`转换器时`fbconverter.so`出现 `undefined symbol`错误：
 
@@ -254,9 +258,9 @@ ImportError: /home//lib/python3.6/site-packages/mgeconvert/backend/ir_to_tflite/
 ```
 这是链接的`libflatbuffers.so`版本和依赖版本不一致导致的问题，执行以下命令使用`mgeconvert`编译的`libflatbuffers.so` ：
 
-```bash
-export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
-```
+> ```bash
+> export LD_LIBRARY_PATH=$MGECONVERT_PATH/backend/ir_to_tflite/pyflexbuffers/lib:$LD_LIBRARY_PATH
+>```
 
 ## 算子支持列表