!1212 Fix README.md and description in cli

From: @moran3
Reviewed-by: 
Signed-off-by:

mindinsight/mindconverter/README.md

@@ -44,8 +44,9 @@ MindConverter currently only provides command-line interface. Here is the manual
 
 ```bash
 usage: mindconverter [-h] [--version] [--in_file IN_FILE]
-                     [--model_file MODEL_FILE] [--shape SHAPE]
-                     [--input_nodes INPUT_NODES] [--output_nodes OUTPUT_NODES]
+                     [--model_file MODEL_FILE] [--shape SHAPE [SHAPE ...]]
+                     [--input_nodes INPUT_NODES [INPUT_NODES ...]]
+                     [--output_nodes OUTPUT_NODES [OUTPUT_NODES ...]]
                      [--output OUTPUT] [--report REPORT]
                      [--project_path PROJECT_PATH]
 
@@ -59,17 +60,20 @@ optional arguments:
                         file path is expected to do script generation based on
                         graph schema. When `--in_file` and `--model_file` are
                         both provided, use AST schema as default.
-  --shape SHAPE         Optional, expected input tensor shape of
+  --shape SHAPE [SHAPE ...]
+                        Optional, expected input tensor shape of
                         `--model_file`. It is required when use graph based
-                        schema. Usage: --shape 1,3,244,244
-  --input_nodes INPUT_NODES
+                        schema. Both order and number should be consistent
+                        with `--input_nodes`. Usage: --shape 1,512 1,512
+  --input_nodes INPUT_NODES [INPUT_NODES ...]
                         Optional, input node(s) name of `--model_file`. It is
-                        required when use TensorFlow model. Usage:
-                        --input_nodes input_1:0,input_2:0
-  --output_nodes OUTPUT_NODES
+                        required when use TensorFlow and ONNX model. Both
+                        order and number should be consistent with `--shape`.
+                        Usage: --input_nodes input_1:0 input_2:0
+  --output_nodes OUTPUT_NODES [OUTPUT_NODES ...]
                         Optional, output node(s) name of `--model_file`. It is
-                        required when use TensorFlow model. Usage:
-                        --output_nodes output_1:0,output_2:0
+                        required when use TensorFlow and ONNX model. Usage:
+                        --output_nodes output_1:0 output_2:0
   --output OUTPUT       Optional, specify path for converted script file
                         directory. Default output directory is `output` folder
                         in the current working directory.
@@ -102,6 +106,8 @@ Please note that your original PyTorch project is included in the module search
 > Assume the project is located at `/home/user/project/model_training`, users can use this command to add the project to `PYTHONPATH` : `export PYTHONPATH=/home/user/project/model_training:$PYTHONPATH`  
 > MindConverter needs the original PyTorch scripts because of the reverse serialization.
 
+PyTorch(.pth) conversion only supports one input and one output model, it is recommended to convert multi-input or multi-output PyTorch script using ONNX conversion after converting PyTorch script to ONNX file.
+
 ### TensorFlow Model Scripts Migration
 
 **MindConverter provides computational graph based conversion for TensorFlow**: Transformation will be done given `--model_file`, `--shape`, `--input_nodes` and `--output_nodes`.
@@ -127,9 +133,8 @@ For the second demand, the Graph mode is recommended. As the computational graph
 
 Some typical image classification networks have been tested for the Graph mode. Note that:
 
-> 1. Currently, the Graph mode does not support models with multiple inputs. Only models with a single input and single output are supported.
-> 2. The Dropout operator will be lost after conversion because the inference mode is used to load the PyTorch or TensorFlow model. Manually re-implement is necessary.
-> 3. The Graph-based mode will be continuously developed and optimized with further updates.
+> 1. The Dropout operator will be lost after conversion because the inference mode is used to load the PyTorch or TensorFlow model. Manually re-implement is necessary.
+> 2. The Graph-based mode will be continuously developed and optimized with further updates.
 
 Supported models list (Models in below table have been tested based on PyTorch 1.5.0 and TensorFlow 1.15.0, X86 Ubuntu released version):
 
@@ -200,39 +205,6 @@ Here is an example of the conversion report:
 
 For non-transformed operators, suggestions are provided in the report. For instance, MindConverter suggests that replace `torch.nn.AdaptiveAvgPool2d` with `mindspore.ops.operations.ReduceMean`.
 
-Here is an example of the weight map:
-
-```json
-{
-    "resnet50": [
-        {
-            "converted_weight": {
-                "name": "conv2d_0.weight",
-                "shape": [
-                    64,
-                    3,
-                    7,
-                    7
-                ],
-                "data_type": "Float32"
-            },
-            "source_weight": {
-                "name": "conv1.weight",
-                "shape": [
-                    64,
-                    3,
-                    7,
-                    7
-                ],
-                "data_type": "float32"
-            }
-        }
-    ]
-}
-```
-
-Weight information in MindSpore (`converted_weight`) and that in source framework(`source_weight`) are saved in weight map separately.
-
 ### Graph-Based Conversion
 
 #### PyTorch Model Scripts Conversion
@@ -293,6 +265,39 @@ class Classifier(nn.Cell):
 
 > `--output` and `--report` are optional. MindConverter creates an `output` folder under the current working directory, and outputs generated scripts, MindSpore checkpoint file, weight map file and conversion reports to it.
 
+Here is an example of the weight map:
+
+```json
+{
+    "resnet50": [
+        {
+            "converted_weight": {
+                "name": "conv2d_0.weight",
+                "shape": [
+                    64,
+                    3,
+                    7,
+                    7
+                ],
+                "data_type": "Float32"
+            },
+            "source_weight": {
+                "name": "conv1.weight",
+                "shape": [
+                    64,
+                    3,
+                    7,
+                    7
+                ],
+                "data_type": "float32"
+            }
+        }
+    ]
+}
+```
+
+Weight information in MindSpore (`converted_weight`) and that in source framework(`source_weight`) are saved in weight map separately.
+
 #### TensorFlow Model Scripts Conversion
 
 To use TensorFlow model script migration, users need to export TensorFlow model to Pb format first, and obtain the model input node and output node name. For exporting pb model, please refer to [TensorFlow Pb model exporting](#tensorflow-pb-model-exporting).
@@ -307,7 +312,7 @@ mindconverter --model_file /home/user/xxx/frozen_model.pb --shape 1,224,224,3 \
               --report /home/user/output/report
 ```
 
-After executed, MindSpore script, Mindspore checkpoint file, weight map file and report file can be found in corresponding directory.
+After executed, MindSpore script, MindSpore checkpoint file, weight map file and report file can be found in corresponding directory.
 
 Since the graph based scheme is a generative method, the original TensorFlow script is not referenced in the conversion process. Therefore, the code line and column numbers involved in the generated conversion report refer to the generated script.
 
@@ -335,9 +340,9 @@ In addition, for operators that are not converted successfully, the input and ou
 
 ## Caution
 
-1. PyTorch, TensorFlow are not an explicitly stated dependency libraries in MindInsight. The Graph conversion requires the consistent PyTorch or TensorFlow version as the model is trained. (For MindConverter, PyTorch 1.5.0 is supported while PyTorch 1.4.x is unsupported; PyTorch 1.6.x and PyTorch 1.7.x are untested.)
+1. PyTorch, TensorFlow are not an explicitly stated dependency libraries in MindInsight. The Graph conversion requires the consistent PyTorch or TensorFlow version as the model is trained. (For MindConverter, PyTorch 1.5.0 is supported while PyTorch 1.4.x is unsupported; PyTorch 1.6.x and PyTorch 1.7.x are untested.).
 2. This script conversion tool relies on operators which supported by MindConverter and MindSpore. Unsupported operators may not be successfully mapped to MindSpore operators. You can manually edit, or implement the mapping based on MindConverter, and contribute to our MindInsight repository. We appreciate your support for the MindSpore community.
-3. MindConverter can only guarantee that the converted model scripts require a minor revision or no revision when the inputs' shape fed to the generated model script are equal to the value of `--shape` (The batch size dimension is not limited).
+3. MindConverter converts dynamic input shape to constant one based on `--shape` while using graph based scheme, as a result, it is required that inputs shape used to retrain or inference in MindSpore are the same as that used to convert using MindConverter. If inputs shape has changed, rerunning MindConverter with new `--shape` or fixing shape related parameters in old script manually is necessary.
 4. MindSpore script, MindSpore checkpoint file and weight map file are saved in the same file folder path.
 
 ## Unsupported situation of AST mode

mindinsight/mindconverter/README_CN.md

@@ -44,8 +44,9 @@ MindConverter提供命令行（Command-line interface, CLI）的使用方式，
 
 ```bash
 usage: mindconverter [-h] [--version] [--in_file IN_FILE]
-                     [--model_file MODEL_FILE] [--shape SHAPE]
-                     [--input_nodes INPUT_NODES] [--output_nodes OUTPUT_NODES]
+                     [--model_file MODEL_FILE] [--shape SHAPE [SHAPE ...]]
+                     [--input_nodes INPUT_NODES [INPUT_NODES ...]]
+                     [--output_nodes OUTPUT_NODES [OUTPUT_NODES ...]]
                      [--output OUTPUT] [--report REPORT]
                      [--project_path PROJECT_PATH]
 
@@ -59,17 +60,20 @@ optional arguments:
                         file path is expected to do script generation based on
                         graph schema. When `--in_file` and `--model_file` are
                         both provided, use AST schema as default.
-  --shape SHAPE         Optional, expected input tensor shape of
+  --shape SHAPE [SHAPE ...]
+                        Optional, expected input tensor shape of
                         `--model_file`. It is required when use graph based
-                        schema. Usage: --shape 1,3,244,244
-  --input_nodes INPUT_NODES
+                        schema. Both order and number should be consistent
+                        with `--input_nodes`. Usage: --shape 1,512 1,512
+  --input_nodes INPUT_NODES [INPUT_NODES ...]
                         Optional, input node(s) name of `--model_file`. It is
-                        required when use TensorFlow model. Usage:
-                        --input_nodes input_1:0,input_2:0
-  --output_nodes OUTPUT_NODES
+                        required when use TensorFlow and ONNX model. Both
+                        order and number should be consistent with `--shape`.
+                        Usage: --input_nodes input_1:0 input_2:0
+  --output_nodes OUTPUT_NODES [OUTPUT_NODES ...]
                         Optional, output node(s) name of `--model_file`. It is
-                        required when use TensorFlow model. Usage:
-                        --output_nodes output_1:0,output_2:0
+                        required when use TensorFlow and ONNX model. Usage:
+                        --output_nodes output_1:0 output_2:0
   --output OUTPUT       Optional, specify path for converted script file
                         directory. Default output directory is `output` folder
                         in the current working directory.
@@ -101,6 +105,8 @@ optional arguments:
 > 假设用户项目目录为`/home/user/project/model_training`，用户可通过如下命令手动将项目添加至包搜索路径中：`export PYTHONPATH=/home/user/project/model_training:$PYTHONPATH`；
 > 此处MindConverter需要引用原PyTorch脚本，是因为PyTorch模型反向序列化过程中会引用原脚本。
 
+PyTorch(.pth)模型转换仅支持单输入、单输出的PyTorch模型，如需转换多输入、多输出模型，建议转换为ONNX之后，使用ONNX进行转换。
+
 ### TensorFlow模型脚本迁移
 
 **MindConverter提供基于图结构的脚本生成方案**：指定`--model_file`、`--shape`、`--input_nodes`、`--output_nodes`进行脚本迁移。
@@ -117,7 +123,7 @@ optional arguments:
 
 MindConverter提供两种技术方案，以应对不同脚本迁移场景：
 
-1. 用户希望迁移后脚本保持原脚本结构（包括变量、函数、类命名等与原脚本保持一致）；
+1. 用户希望迁移后脚本保持原脚本结构（包括变量、函数、类命名等与原脚本保持一致）。
 2. 用户希望迁移后脚本保持较高的转换率，尽量少的修改、甚至不需要修改，即可实现迁移后模型脚本的执行。
 
 对于上述第一种场景，推荐用户使用基于AST的方案进行转换（AST方案仅支持PyTorch脚本转换），AST方案通过对原PyTorch脚本的抽象语法树进行解析、编辑，将其替换为MindSpore的抽象语法树，再利用抽象语法树生成代码。理论上，AST方案支持任意模型脚本迁移，但语法树解析操作受原脚本用户编码风格影响，可能导致同一模型的不同脚本最终的转换率存在一定差异。
@@ -126,9 +132,8 @@ MindConverter提供两种技术方案，以应对不同脚本迁移场景：
 
 目前已基于典型图像分类网络对图结构的脚本转换方案进行测试。
 
-> 1. 基于图结构的脚本生成方案，目前仅支持单输入、单输出模型，对于多输入模型暂不支持；
-> 2. 基于图结构的脚本生成方案，由于要加载PyTorch、TensorFlow模型，会导致转换后网络中Dropout算子丢失，需要用户手动补齐；
-> 3. 基于图结构的脚本生成方案持续优化中。
+> 1. 基于图结构的脚本生成方案，由于要加载PyTorch、TensorFlow模型，会导致转换后网络中Dropout算子丢失，需要用户手动补齐。
+> 2. 基于图结构的脚本生成方案持续优化中。
 
 支持的模型列表（如下模型已基于x86 Ubuntu发行版，PyTorch 1.5.0以及TensorFlow 1.15.0测试通过）:
 
@@ -201,39 +206,6 @@ line x:y: [UnConvert] 'operator' didn't convert. ...
 对于部分未成功转换的算子，报告中会提供修改建议，如`line 157:23`，MindConverter建议将`torch.nn.AdaptiveAvgPool2d`
 替换为`mindspore.ops.operations.ReduceMean`。
 
-权重映射表示例如下所示：
-
-```json
-{
-    "resnet50": [
-        {
-            "converted_weight": {
-                "name": "conv2d_0.weight",
-                "shape": [
-                    64,
-                    3,
-                    7,
-                    7
-                ],
-                "data_type": "Float32"
-            },
-            "source_weight": {
-                "name": "conv1.weight",
-                "shape": [
-                    64,
-                    3,
-                    7,
-                    7
-                ],
-                "data_type": "float32"
-            }
-        }
-    ]
-}
-```
-
-映射表中分别保存算子在MindSpore中的权重信息（`converted_weight`）和在原始框架中的权重信息（`source_weight`）。
-
 ### 基于图结构的脚本生成示例
 
 #### PyTorch模型脚本生成示例
@@ -301,6 +273,39 @@ class Classifier(nn.Cell):
 
 > 其中`--output`与`--report`参数可省略，若省略，该命令将在当前工作目录（Working directory）下自动创建`output`目录，将生成的脚本、权重文件、权重映射表、转换报告输出至该目录。
 
+权重映射表示例如下所示：
+
+```json
+{
+    "resnet50": [
+        {
+            "converted_weight": {
+                "name": "conv2d_0.weight",
+                "shape": [
+                    64,
+                    3,
+                    7,
+                    7
+                ],
+                "data_type": "Float32"
+            },
+            "source_weight": {
+                "name": "conv1.weight",
+                "shape": [
+                    64,
+                    3,
+                    7,
+                    7
+                ],
+                "data_type": "float32"
+            }
+        }
+    ]
+}
+```
+
+映射表中分别保存算子在MindSpore中的权重信息（`converted_weight`）和在原始框架中的权重信息（`source_weight`）。
+
 #### TensorFlow模型脚本生成示例
 
 使用TensorFlow模型脚本迁移，需要先将TensorFlow模型导出为pb格式，并且获取模型输入节点、输出节点名称。TensorFlow pb模型导出可参考[TensorFlow Pb模型导出](#tensorflow-pb模型导出)
@@ -344,9 +349,9 @@ mindconverter --model_file /home/user/xxx/model.onnx --shape 1,3,224,224 \
 
 ## 注意事项
 
-1. PyTorch、TensorFlow不作为MindInsight明确声明的依赖库。若想使用基于图结构的脚本生成工具，需要用户手动安装与生成PyTorch模型版本一致的PyTorch库（MindConverter使用PyTorch 1.5.0进行测试，不支持PyTorch 1.4.x; PyTorch 1.6.x、PyTorch 1.7.x未进行测试。），或TensorFlow；
+1. PyTorch、TensorFlow不作为MindInsight明确声明的依赖库。若想使用基于图结构的脚本生成工具，需要用户手动安装与生成PyTorch模型版本一致的PyTorch库（MindConverter使用PyTorch 1.5.0进行测试，不支持PyTorch 1.4.x; PyTorch 1.6.x、PyTorch 1.7.x未进行测试。），或TensorFlow。
 2. 脚本转换工具本质上为算子驱动，对于MindConverter未维护的PyTorch或ONNX算子与MindSpore算子映射，将会出现相应的算子无法转换的问题，对于该类算子，用户可手动修改，或基于MindConverter实现映射关系，向MindInsight仓库贡献。
-3. MindConverter仅保证转换后模型脚本在输入数据尺寸与`--shape`一致的情况下，可达到无需人工修改或少量修改（`--shape`中batch size维度不受限）。
+3. 在使用基于计算图的迁移时，MindConverter会根据`--shape`参数将模型输入的批次大小（batch size）、句子长度（sequence length）、图片尺寸（image shape）等尺寸相关参数固定下来，用户需要保证基于MindSpore重训练、推理时输入shape与转换时一致；若需要调整输入尺寸，请重新指定`--shape`进行转换或修改转换后脚本中涉及张量尺寸变更操作相应的操作数。
 4. 脚本文件、权重文件和权重映射表输出于同一个目录下。
 
 ## AST方案不支持场景

mindinsight/mindconverter/cli.py

@@ -320,7 +320,7 @@ parser.add_argument(
     help="""
             PyTorch(.pth), Tensorflow(.pb) or ONNX(.onnx) model file path 
             is expected to do script generation based on graph schema. When 
-            `--in_file` and `--model_file` are both provided,
+            `--in_file` and `--model_file` are both provided, 
             use AST schema as default.
         """)
 
@@ -333,9 +333,9 @@ parser.add_argument(
     nargs="+",
     help="""
             Optional, expected input tensor shape of
-            `--model_file`. It's required when use graph based
-            schema. 
-            Usage: --shape 1,3,244,244
+            `--model_file`. It is required when use graph based
+            schema. Both order and number should be consistent with `--input_nodes`. 
+            Usage: --shape 1,512 1,512
         """)
 
 parser.add_argument(
@@ -346,8 +346,8 @@ parser.add_argument(
     required=False,
     nargs="+",
     help="""
-            Optional, input node(s) name of `--model_file`. It's required when use Tensorflow model.
-            Usage: --input_nodes input_1:0,input_2:0
+            Optional, input node(s) name of `--model_file`. It is required when use TensorFlow and ONNX model. 
+            Both order and number should be consistent with `--shape`. Usage: --input_nodes input_1:0 input_2:0
         """)
 
 parser.add_argument(
@@ -358,8 +358,8 @@ parser.add_argument(
     required=False,
     nargs="+",
     help="""
-            Optional, output node(s) name of `--model_file`. It's required when use Tensorflow model.
-            Usage: --output_nodes output_1:0,output_2:0
+            Optional, output node(s) name of `--model_file`. It is required when use TensorFlow and ONNX model. 
+            Usage: --output_nodes output_1:0 output_2:0
         """)
 
 parser.add_argument(

mindinsight/mindconverter/graph_based_converter/framework.py

@@ -264,11 +264,11 @@ def main_graph_base_converter(file_config):
     Args:
         file_config (dict): The config of file which to convert.
     """
-    if api_implementation.Type() != 'cpp' \
-        or os.getenv('PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION') != 'cpp':
-        log_console.warning("Protobuf is currently implemented in \"Python\". \
-            The conversion process may take a long time. \
-            Please use the \"C++\" backend version")
+
+    if api_implementation.Type() != 'cpp' or os.getenv('PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION') != 'cpp':
+        log_console.warning("Protobuf is currently implemented in \"Python\". "
+                            "The conversion process may take a long time. Please use the \"C++\" backend version.")
+
     graph_path = file_config['model_file']
     frame_type = get_framework_type(graph_path)
     if not file_config.get("shape"):

mindinsight/mindconverter/graph_based_converter/mapper/impl/ops/einsum_mapper.py

@@ -91,7 +91,7 @@ class EinSumMapper(ONNXToMindSporeMapper):
         default_shape = input_shape[:2]
         inputs_in_construct = [
             f"{{{ExchangeMessageKeywords.VariableScope.value.INPUTS.value}}}"
-            f".view({default_shape[0] * default_shape[1]}, -1)"]
+            f".view({default_shape[0]} * {default_shape[1]}, -1)"]
 
         if weights:
             tensor = EinSumMapper._find_val_by_index(0, weights)