compiler/one-cmds/how-to-use-one-commands.txt

   1 About
   2 -----
   3
   4 Last update: 2020-10-29
   5
   6 This document briefly explains how to use one-* commands.
   7 Detailed options are not explained here. Run the command to see options.
   8
   9 Compilation flow for running with onert;
  10 1) one-import will import model files generated from famous frameworks
  11 2) one-optimize will optimize models. This step is optional.
  12 3) one-quantize will quantize models. This step is also optional.
  13 4) one-pack will pack to nnpkg so that we can run the model with our onert
  14    runtime
  15
  16 Compilation flow for NPU
  17 1) one-import will import model files generated from famous frameworks
  18 2) one-optimize will optimize models. This step is optional.
  19 3) one-quantize will quantize models. Depending on the NPUs.
  20 4) one-codegen will compile to binary codes.
  21
  22
  23 common features
  24 ---------------
  25
  26 [configuration file]
  27
  28 You can run one-commands with configuration file as well as command line parameters. The
  29 configuration file should be written with the options the one-commands need to run.
  30
  31 ```
  32 # configuration_file.cfg
  33
  34 [The_driver_you_want_to_run]
  35 input_path=/input/path/to/convert
  36 output_path=...
  37 option_0=...
  38 option_1=...
  39 ...
  40
  41 ```
  42
  43 You can see a template file for how to write a configuration file in `one-build.template.cfg`.
  44
  45 [options to write]
  46
  47 Sometimes you want to change certain options without touching the configuration file. If you
  48 pass the option directly to the command line, the option is processed prior to the configuration
  49 file. A list of options can be found in each driver's help message with `-h` option.
  50
  51 e.g.
  52 ```
  53 $ ./one-import tf -C my-conf.cfg -i path/to/overwrite.pb
  54 ```
  55
  56
  57 one-build
  58 ---------
  59
  60 one-build is an integrated driver that can execute one-commands at once. It's nice to run each
  61 driver individually, but sometimes you'll want to put together the most frequently used commands
  62 and run them all at once. You can do this with one-build and its configuration file.
  63
  64 For one-build, the configuration file needs 'one-build' section that consists of list of driver.
  65
  66 ```
  67 # one-build.template.cfg
  68 [one-build]
  69 one-import-tf=True
  70 one-import-tflite=False
  71 one-import-bcq=False
  72 one-optimize=True
  73 one-quantize=False
  74 one-pack=True
  75 one-codegen=False
  76
  77 [one-import-tf]
  78 ...
  79
  80 [one-optimize]
  81 ...
  82
  83 [one-pack]
  84 ...
  85
  86 ```
  87 See 'one-build.template.cfg' for more details.
  88
  89
  90 one-import
  91 ----------
  92
  93 one-import will invokes one-import-* commands.
  94
  95 Syntax: one-import [framework] [options]
  96
  97 Currently supported frameworks are 'tf', 'tflite' for TensorFlow and TensorFlow
  98 lite.
  99
 100
 101 one-import-bcq
 102 --------------
 103
 104 This will convert Tensorflow model file (.pb) to our circle model file with applying BCQ.
 105 To execute this command, original Tensorflow model file must include BCQ information.
 106
 107 This command invokes following scripts internally.
 108 - generate_bcq_metadata : Generate BCQ metadata in the model
 109 - generate_bcq_info : Designate BCQ information nodes as model output automatically
 110 - tf2tfliteV2 : Convert Tensorflow model to tflite model
 111 - tflite2circle : Convert Tensorflow Lite model to circle model
 112 When this command is finished, BCQ information nodes will be removed if BCQ information
 113 was valid and applying BCQ is done correctly without any errors.
 114
 115 As tf2tfliteV2.py runs TensorFlow lite converter, you need to have TensorFlow
 116 installed in your system. We recommand to use 2.3.0 for now.
 117
 118 We provide python virtual environment and one-import-bcq will enter and leave
 119 this environment so that you don't need to explictly 'activate' virtual
 120 environment.
 121
 122
 123 one-import-tf
 124 -------------
 125
 126 This will convert TensorFlow model (.pb) file to our circle model. You can also
 127 directly call this command. one-import-tf invokes tf2tfliteV2.py script that
 128 will internally use TensorFlow lite converter and then invoke tflite2circle
 129 converter to convert tflite model to circle model.
 130
 131 As tf2tfliteV2.py runs TensorFlow lite converter, you need to have TensorFlow
 132 installed in your system. We recommand to use 2.3.0 for now.
 133
 134 We provide python virtual environment and one-import-tf will enter and leave
 135 this environment so that you don't need to explictly 'activate' virtual
 136 environment.
 137
 138
 139 one-import-tflite
 140 -----------------
 141
 142 You can use one-import-tflite to convert TensorFlow lite model (.tflite) file to
 143 our circle model. Internally this will invoke tflite2circle.
 144
 145
 146 one-optimize
 147 ------------
 148
 149 one-optimize provides network or operator transformation shown below.
 150
 151 Current transformation options are
 152 - disable_validation : This will turn off operator validations.
 153 - expand_broadcast_const : This will expand broadcastable constant node inputs
 154 - fold_add_v2 : This removes AddV2 operation which can be folded
 155 - fold_cast : This removes Cast operation which can be folded
 156 - fold_densify: This removes Densify operator which can be folded
 157 - fold_dequantize : This removes Dequantize operation which can be folded
 158 - fold_dwconv : This folds Depthwise Convolution operation which can be folded
 159 - fold_gather : This removes Gather operation which can be folded
 160 - fold_sparse_to_dense : This removes SparseToDense operation which can be folded
 161 - forward_reshape_to_unaryop: This will move Reshape after UnaryOp for centain condition
 162 - fuse_add_with_fully_connected: This fuses Add operator with the preceding FullyConnected operator if possible
 163 - fuse_add_with_tconv: This fuses Add operator with the preceding TConv operator if possible
 164 - fuse_batchnorm_with_conv : This fuses BatchNorm operator to convolution operator
 165 - fuse_batchnorm_with_dwconv : This fuses BatchNorm operator to depthwise convolution operator
 166 - fuse_batchnorm_with_tconv : This fuses BatchNorm operator to transpose convolution operator
 167 - fuse_bcq: This enables Binary-Coded-bases Quantized DNNs
 168    - read https://arxiv.org/abs/2005.09904 for detailed information
 169 - fuse_instnorm: This will convert instance normalization related operators to
 170   one InstanceNormalization operator that our onert provides for faster
 171   execution.
 172 - fuse_preactivation_batchnorm: This fuses batch normalization operators of pre-activations to Conv operators.
 173 - fuse_activation_function: This fuses Activation function to a preceding operator.
 174 - fuse_mean_with_mean: This fuses two consecutive ReduceMean operations into one.
 175 - fuse_transpose_with_mean: This fuses ReduceMean with a preceding Transpose under certain conditions.
 176 - make_batchnorm_gamma_positive: This makes negative gamma of batch normalization into a small positive value (1e-10).
 177   Note that this pass can change the execution result of the model.
 178   So, use it only when the impact is known to be acceptable.
 179 - mute_warnings : This will turn off warning messages.
 180 - generate_profile_data : This will turn on profiling data generation.
 181 - remove_fakequant : This will remove all fakequant operators.
 182 - remove_quantdequant : This will remove all Quantize-Dequantize sequence.
 183 - remove_redundant_quantize : This removes redundant quantize operators.
 184 - remove_redundant_reshape : This fuses or removes redundant reshape operators.
 185 - remove_redundant_transpose : This fuses or removes redundant transpose operators.
 186 - remove_unnecessary_reshape : This removes unnecessary reshape operators.
 187 - remove_unnecessary_slice : This removes unnecessary slice operators.
 188 - remove_unnecessary_strided_slice : This removes unnecessary strided slice operators.
 189 - remove_unnecessary_split : This removes unnecessary split operators.
 190 - replace_cw_mul_add_with_depthwise_conv: This will replace channel-wise Mul/Add with DepthwiseConv2D.
 191 - resolve_customop_add: This will convert Custom(Add) to normal Add operator
 192 - resolve_customop_batchmatmul: This will convert Custom(BatchMatMul) to
 193   normal BatchMatMul operator
 194 - resolve_customop_matmul: This will convert Custom(MatMul) to normal MatMul
 195   operator
 196 - resolve_customop_max_pool_with_argmax: This will convert Custom(MaxPoolWithArgmax)
 197   to net of builtin operators.
 198 - shuffle_weight_to_16x1float32 : This will convert weight format of FullyConnected to SHUFFLED16x1FLOAT32.
 199   Note that it only converts weights whose row is a multiple of 16.
 200 - substitute_pack_to_reshape : This will convert single input Pack to Reshape.
 201 - substitute_padv2_to_pad : This will convert certain condition PadV2 to Pad.
 202 - substitute_splitv_to_split : This will convert certain condition SplitV to Split.
 203 - substitute_squeeze_to_reshape : This will convert certain condition Squeeze to Reshape.
 204 - substitute_strided_slice_to_reshape : This will convert certain condition StridedSlice to Reshape.
 205 - substitute_transpose_to_reshape : This will convert certain condition Transpose to Reshape.
 206 - transform_min_max_to_relu6: This will transform Minimum-Maximum pattern to Relu6 operator.
 207 - transform_min_relu_to_relu6: This will transform Minimum(6)-Relu pattern to Relu6 operator.
 208
 209
 210 one-quantize
 211 ------------
 212
 213 one-quantize will quantize float32 model to uint8 so that the model can benefit
 214 for speed that our onert runtime and NPU provides. For convolution type
 215 operators we currently support layer-wise quantization. Later we will support
 216 int16 and channel-wise quantization.
 217
 218 Internally this calls circle-quantizer and record-minmax tools.
 219
 220
 221 one-pack
 222 --------
 223
 224 one-pack will generate a package from circle model to nnpackage for our onert
 225 runtime.
 226
 227 Output is a folder with the model(s) and meta information.
 228
 229 ex) if you have a model named '20200719.circle' and want to pack to 'testnnpack'
 230
 231 $ one-pack -i 20200709.circle -o testnnpack
 232
 233 $ tree testnnpack
 234 testnnpack
 235 └── 20200709
 236     ├── 20200709.circle
 237     └── metadata
 238         └── MANIFEST
 239
 240
 241 one-codegen
 242 -----------
 243
 244 one-codegen, like one-import will invoke backend code generation commands.
 245 As of now, our ONE repo does not provide any code generation commands yet.
 246
 247 Syntax: one-codegen [target-backend] [options]
 248
 249 This will invoke [target-backend]-compile command if available.