fix quantization api doc (PaddlePaddle#13)

docs/docs/api/quantization_api.md

@@ -1,8 +1,8 @@
-# paddleslim.quant API文档
 
-## 量化训练API
 
-### 量化配置
+## 量化配置
+通过字典配置量化参数
+
 ```
 quant_config_default = {
     'weight_quantize_type': 'abs_max',
@@ -20,37 +20,33 @@ quant_config_default = {
     'window_size': 10000,
     # The decay coefficient of moving average, default is 0.9
     'moving_rate': 0.9,
-    # if set quant_weight_only True, then only quantize parameters of layers which need to be quantized,
-    # and activations will not be quantized.
-    'quant_weight_only': False
 }
 ```
-设置量化训练需要的配置。
 
 **参数：**
 
 - **weight_quantize_type(str)** - 参数量化方式。可选``'abs_max'``,  ``'channel_wise_abs_max'``, ``'range_abs_max'``, ``'moving_average_abs_max'``。 默认``'abs_max'``。
 - **activation_quantize_type(str)** - 激活量化方式，可选``'abs_max'``, ``'range_abs_max'``, ``'moving_average_abs_max'``，默认``'abs_max'``。
 - **weight_bits(int)** - 参数量化bit数，默认8, 推荐设为8。
 - **activation_bits(int)** -  激活量化bit数，默认8， 推荐设为8。
-- **not_quant_pattern(str or list[str])** - 所有``name_scope``包含``'not_quant_pattern'``字符串的``op``，都不量化, 设置方式请参考``fluid.name_scope()``。
+- **not_quant_pattern(str | list[str])** - 所有``name_scope``包含``'not_quant_pattern'``字符串的``op``，都不量化, 设置方式请参考[*fluid.name_scope*](https://www.paddlepaddle.org.cn/documentation/docs/zh/api_cn/fluid_cn/name_scope_cn.html#name-scope)。
 - **quantize_op_types(list[str])** -  需要进行量化的``op``类型，目前支持``'conv2d', 'depthwise_conv2d', 'mul' ``。
 - **dtype(int8)** - 量化后的参数类型，默认 ``int8``, 目前仅支持``int8``。
 - **window_size(int)** -  ``'range_abs_max'``量化方式的``window size``，默认10000。
 - **moving_rate(int)** - ``'moving_average_abs_max'``量化方式的衰减系数，默认 0.9。
-- **quant_weight_only(bool)** - 是否只量化参数，如果设为``True``，则激活不进行量化，默认``False``。目前暂不支持设置为``True``。 设置为``True``时，只量化参数，这种方式不能减少显存占用和加速，只能用来减少带宽。
 
 
-### paddleslim.quant.quant_aware(program, place, config, scope=None, for_test=False)
-在``program``中加入量化和反量化``op``, 用于量化训练。
+## quant_aware
+paddleslim.quant.quant_aware(program, place, config, scope=None, for_test=False)[[源代码]](https://github.com/PaddlePaddle/PaddleSlim/blob/develop/paddleslim/quant/quanter.py)
+: 在``program``中加入量化和反量化``op``, 用于量化训练。
 
 
 **参数：**
 
 * **program (fluid.Program)** -  传入训练或测试``program``。
-* **place(fluid.CPUPlace or fluid.CUDAPlace)** -  该参数表示``Executor``执行所在的设备。
+* **place(fluid.CPUPlace | fluid.CUDAPlace)** -  该参数表示``Executor``执行所在的设备。
 * **config(dict)** -  量化配置表。
-* **scope(fluid.Scope, optional)** -  传入用于存储``Variable``的``scope``，需要传入``program``所使用的``scope``，一般情况下，是``fluid.global_scope()``。设置为``None``时将使用``fluid.global_scope()``，默认值为``None``。
+* **scope(fluid.Scope, optional)** -  传入用于存储``Variable``的``scope``，需要传入``program``所使用的``scope``，一般情况下，是[*fluid.global_scope()*](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api_cn/executor_cn/global_scope_cn.html)。设置为``None``时将使用[*fluid.global_scope()*](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api_cn/executor_cn/global_scope_cn.html)，默认值为``None``。
 * **for_test(bool)** -  如果``program``参数是一个测试``program``，``for_test``应设为``True``，否则设为``False``。
 
 **返回**
@@ -62,7 +58,7 @@ quant_config_default = {
 * 当``for_test=False``，返回类型为``fluid.CompiledProgram``， **注意，此返回值不能用于保存参数**。
 * 当``for_test=True``，返回类型为``fluid.Program``。
 
-**注意事项**
+!!! note "注意事项"
 
 * 此接口会改变``program``结构，并且可能增加一些``persistable``的变量，所以加载模型参数时请注意和相应的``program``对应。
 * 此接口底层经历了``fluid.Program``-> ``fluid.framework.IrGraph``->``fluid.Program``的转变，在``fluid.framework.IrGraph``中没有``Parameter``的概念，``Variable``只有``persistable``和``not persistable``的区别，所以在保存和加载参数时，请使用``fluid.io.save_persistables``和``fluid.io.load_persistables``接口。
@@ -71,30 +67,32 @@ quant_config_default = {
 
 
 
-### paddleslim.quant.convert(program, place, config, scope=None, save_int8=False)
+## convert 
+paddleslim.quant.convert(program, place, config, scope=None, save_int8=False)[[源代码]](https://github.com/PaddlePaddle/PaddleSlim/blob/develop/paddleslim/quant/quanter.py)
 
 
-把训练好的量化``program``，转换为可用于保存``inference model``的``program``。
+: 把训练好的量化``program``，转换为可用于保存``inference model``的``program``。
 
 **参数：**
+
 - **program (fluid.Program)** -  传入测试``program``。
-- **place(fluid.CPUPlace or fluid.CUDAPlace)** - 该参数表示``Executor``执行所在的设备。
+- **place(fluid.CPUPlace | fluid.CUDAPlace)** - 该参数表示``Executor``执行所在的设备。
 - **config(dict)** -  量化配置表。
-- **scope(fluid.Scope)** - 传入用于存储``Variable``的``scope``，需要传入``program``所使用的``scope``，一般情况下，是``fluid.global_scope()``。设置为``None``时将使用``fluid.global_scope()``，默认值为``None``。
+- **scope(fluid.Scope)** - 传入用于存储``Variable``的``scope``，需要传入``program``所使用的``scope``，一般情况下，是[*fluid.global_scope()*](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api_cn/executor_cn/global_scope_cn.html)。设置为``None``时将使用[*fluid.global_scope()*](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api_cn/executor_cn/global_scope_cn.html)，默认值为``None``。
 - **save_int8（bool)** -  是否需要返回参数为``int8``的``program``。该功能目前只能用于确认模型大小。默认值为``False``。
 
 **返回**
 
 - **program (fluid.Program)** - freezed program，可用于保存inference model，参数为``float32``类型，但其数值范围可用int8表示。
 - **int8_program (fluid.Program)** - freezed program，可用于保存inference model，参数为``int8``类型。当``save_int8``为``False``时，不返回该值。
 
-**注意事项**
+!!! note "注意事项"
 
 因为该接口会对``op``和``Variable``做相应的删除和修改，所以此接口只能在训练完成之后调用。如果想转化训练的中间模型，可加载相应的参数之后再使用此接口。
 
 **代码示例**
 
-```python
+```python hl_lines="27 28"
 #encoding=utf8
 import paddle.fluid as fluid
 import paddleslim.quant as quant
@@ -134,26 +132,15 @@ quant_train_program = quant_train_program.with_data_parallel(
 inference_prog = quant.convert(quant_eval_program, place, config)
 ```
 
-更详细的用法请参考 <a href='../../demo/quant/quant_aware/README.md'>量化训练demo</a>。
+更详细的用法请参考 <a href='https://github.com/PaddlePaddle/PaddleSlim/tree/develop/demo/quant/quant_aware'>量化训练demo</a>。
 
-## 离线量化API
-```
-paddleslim.quant.quant_post(executor,
-           model_dir,
-           quantize_model_path,
-           sample_generator,
-           model_filename=None,
-           params_filename=None,
-           batch_size=16,
-           batch_nums=None,
-           scope=None,
-           algo='KL',
-           quantizable_op_type=["conv2d", "depthwise_conv2d", "mul"])
+## quant_post
+paddleslim.quant.quant_post(executor, model_dir, quantize_model_path,sample_generator, model_filename=None, params_filename=None, batch_size=16,batch_nums=None, scope=None, algo='KL', quantizable_op_type=["conv2d", "depthwise_conv2d", "mul"])[[源代码]](https://github.com/PaddlePaddle/PaddleSlim/blob/develop/paddleslim/quant/quanter.py)
 
-```
-对保存在``${model_dir}``下的模型进行量化，使用``sample_generator``的数据进行参数校正。
+: 对保存在``${model_dir}``下的模型进行量化，使用``sample_generator``的数据进行参数校正。
 
 **参数:**
+
 - **executor (fluid.Executor)** - 执行模型的executor，可以在cpu或者gpu上执行。
 - **model_dir（str)** - 需要量化的模型所在的文件夹。
 - **quantize_model_path(str)** - 保存量化后的模型的路径
@@ -162,23 +149,23 @@ paddleslim.quant.quant_post(executor,
 - **params_filename(str)** - 参数文件名，如果需要量化的模型的参数存在一个文件中，则需要设置``params_filename``为参数文件的名称，否则设置为``None``即可。默认值是``None``。
 - **batch_size(int)** - 每个batch的图片数量。默认值为16 。
 - **batch_nums(int, optional)** - 迭代次数。如果设置为``None``，则会一直运行到``sample_generator`` 迭代结束， 否则，迭代次数为``batch_nums``, 也就是说参与对``Scale``进行校正的样本个数为 ``'batch_nums' * 'batch_size' ``.
-- **scope(fluid.Scope, optional)** - 用来获取和写入``Variable``, 如果设置为``None``,则使用``fluid.global_scope()``. 默认值是``None``.
+- **scope(fluid.Scope, optional)** - 用来获取和写入``Variable``, 如果设置为``None``,则使用[*fluid.global_scope()*](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api_cn/executor_cn/global_scope_cn.html). 默认值是``None``.
 - **algo(str)** - 量化时使用的算法名称，可为``'KL'``或者``'direct'``。该参数仅针对激活值的量化，因为参数值的量化使用的方式为``'channel_wise_abs_max'``. 当``algo`` 设置为``'direct'``时，使用校正数据的激活值的绝对值的最大值当作``Scale``值，当设置为``'KL'``时，则使用``KL``散度的方法来计算``Scale``值。默认值为``'KL'``。
 - **quantizable_op_type(list[str])** -  需要量化的``op``类型列表。默认值为``["conv2d", "depthwise_conv2d", "mul"]``。
 
 **返回**
 
 无。
 
-**注意事项**
+!!! note "注意事项"
 
 因为该接口会收集校正数据的所有的激活值，所以使用的校正图片不能太多。``'KL'``散度的计算也比较耗时。
 
 **代码示例**
 
 > 注： 此示例不能直接运行，因为需要加载``${model_dir}``下的模型，所以不能直接运行。
 
-```python
+```python hl_lines="9"
 import paddle.fluid as fluid
 import paddle.dataset.mnist as reader
 from paddleslim.quant import quant_post
@@ -197,18 +184,17 @@ quant_post(
         batch_size=16,
         batch_nums=10)
 ```
-更详细的用法请参考 <a href='../../demo/quant/quant_post/README.md'>离线量化demo</a>。
+更详细的用法请参考 <a href='https://github.com/PaddlePaddle/PaddleSlim/tree/develop/demo/quant/quant_post'>离线量化demo</a>。
 
-## Embedding量化API
-```
-paddleslim.quant.quant_embedding(program, place, config, scope=None)
-```
-对``Embedding``参数进行量化。
+## quant_embedding
+paddleslim.quant.quant_embedding(program, place, config, scope=None)[[源代码]](https://github.com/PaddlePaddle/PaddleSlim/blob/develop/paddleslim/quant/quant_embedding.py)
+: 对``Embedding``参数进行量化。
 
 **参数:**
+
 - **program(fluid.Program)** - 需要量化的program
-- **scope(fluid.Scope, optional)** - 用来获取和写入``Variable``, 如果设置为``None``,则使用``fluid.global_scope()``.
-- **place(fluid.CPUPlace or fluid.CUDAPlace)** - 运行program的设备
+- **scope(fluid.Scope, optional)** - 用来获取和写入``Variable``, 如果设置为``None``,则使用[*fluid.global_scope()*](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api_cn/executor_cn/global_scope_cn.html).
+- **place(fluid.CPUPlace | fluid.CUDAPlace)** - 运行program的设备
 - **config(dict)** - 定义量化的配置。可以配置的参数有：
     - ``'params_name'`` (str, required): 需要进行量化的参数名称，此参数必须设置。
     - ``'quantize_type'`` (str, optional): 量化的类型，目前支持的类型是``'abs_max'``, 待支持的类型有 ``'log', 'product_quantization'``。 默认值是``'abs_max'``.
@@ -225,7 +211,7 @@ paddleslim.quant.quant_embedding(program, place, config, scope=None)
 ``fluid.Program``
 
 **代码示例**
-```python
+```python hl_lines="22"
 import paddle.fluid as fluid
 import paddleslim.quant as quant
 
@@ -250,4 +236,4 @@ config = {'params_name': 'emb', 'quantize_type': 'abs_max'}
 quant_program = quant.quant_embedding(infer_program, place, config)
 ```
 
-更详细的用法请参考 <a href='../../demo/quant/quant_embedding/README.md'>Embedding量化demo</a>。
+更详细的用法请参考 <a href='https://github.com/PaddlePaddle/PaddleSlim/tree/develop/demo/quant/quant_embedding'>Embedding量化demo</a>。