Merge pull request #1770 from cuicheng01/develop

polish docs

Author: cuicheng01

README.md

@@ -61,12 +61,9 @@ PaddleX 3.0 集成飞桨生态优势能力，覆盖7大场景任务，构建 16
 - [数据标注](./docs/tutorials/data/annotation/README.md)
 - [数据校验](./docs/tutorials/data/dataset_check.md)
 
-#### 3. 模型训练
-- [模型训练/评估](./docs/tutorials/base/README.md)
-- [模型优化](./docs/tutorials/base/model_optimize.md)
+#### 3. 模型训练/评估/推理
+- [模型训练/评估/推理](./docs/tutorials/base/README.md)
 
-#### 4. 模型推理
-- [模型推理](./docs/tutorials/base/README.md)
 
 ### 二、模型产线开发工具 🔥
 本节将介绍 PaddleX3.0 模型产线的全流程开发流程，包括数据准备、模型训练/评估、模型推理的使用方法。PaddleX3.0 支持的模型产线可以参考 [PaddleX 模型产线列表](./docs/tutorials/pipelines/support_pipeline_list.md)

docs/tutorials/INSTALL.md

@@ -85,7 +85,6 @@ git clone https://gitee.com/paddlepaddle/PaddleX.git
 
 参考下述命令，按提示操作，完成 PaddleX 依赖的安装。
 
-<!-- 这里需要指明安装成功的状态， 廷权 -->
 ```bash
 cd PaddleX
 
@@ -95,6 +94,9 @@ pip install -e .
 
 # 安装 PaddleX 相关依赖
 paddlex --install
+
+# 完成安装后会有如下提示：
+# All packages are installed.
 ```
 
 **注 :** 在安装过程中，需要克隆 Paddle 官方模型套件，`--platform` 可以指定克隆源，可选 `github.com`，`gitee.com`，分别代表这些套件从 github 上和 gitee 上克隆，默认为 `github.com`。

docs/tutorials/INSTALL_OTHER_DEVICES.md

@@ -20,7 +20,7 @@ docker run -it --name paddle-npu-dev -v $(pwd):/work \
     -e ASCEND_RT_VISIBLE_DEVICES="0,1,2,3,4,5,6,7" \
     registry.baidubce.com/device/paddle-npu:cann80RC1-ubuntu20-x86_64-gcc84-py39 /bin/bash
 ```
-### 1.2 安装paddle包
+### 1.2 安装 paddle 包
 当前提供 Python3.9 的 wheel 安装包。如有其他 Python 版本需求，可以参考[飞桨官方文档](https://www.paddlepaddle.org.cn/install/quick)自行编译安装。
 
 - 1.下载安装 Python3.9 的 wheel 安装包
@@ -59,7 +59,7 @@ docker run -it --name paddle-mlu-dev -v $(pwd):/work \
   -v /usr/bin/cnmon:/usr/bin/cnmon \
   registry.baidubce.com/device/paddle-mlu:ctr2.15.0-ubuntu20-gcc84-py310 /bin/bash
 ```
-### 2.2 安装paddle包
+### 2.2 安装 paddle 包
 当前提供 Python3.10 的 wheel 安装包。有其他 Python 版本需求，可以参考[飞桨官方文档](https://www.paddlepaddle.org.cn/install/quick)自行编译安装。
 
 - 1.下载安装 Python3.10 的wheel 安装包。
@@ -97,7 +97,7 @@ docker run -it --name=xxx -m 81920M --memory-swap=81920M \
     registry.baidubce.com/device/paddle-xpu:kylinv10-aarch64-gcc82 bash
 ```
 
-## 3.2 安装paddle包
+## 3.2 安装 paddle 包
 当前提供 Python3.10 的 wheel 安装包。有其他 Python 版本需求，可以参考[飞桨官方文档](https://www.paddlepaddle.org.cn/install/quick)自行编译安装。
 
 - 1.安装 Python3.10 的 wheel 安装包

docs/tutorials/base/README.md

@@ -25,7 +25,7 @@ PaddleX 中每个模型都提供了模型开发的配置文件，用于设置相
 
 更多超参数介绍，请参考 [PaddleX 超参数介绍](./hyperparameters_introduction.md)。
 
-**注：** 
+**注：**
 - 以上参数可以通过追加令行参数的形式进行设置，如指定模式为模型训练：`-o Global.mode=train`；指定前 2 卡 GPU 训练：`-o Global.device=gpu:0,1`；设置训练轮次数为 10：`-o Train.epochs_iters=10`。
 - 模型训练过程中，PaddleX 会自动保存模型权重文件，默认为`output`，如需指定保存路径，可通过配置文件中 `-o Global.output` 字段进行设置。
 - 在 OCR 和语义分割任务模块中，参数 `epochs_iters` 对应训练 Step 数，在其他任务模块中，参数 `epochs_iters` 对应训练 Epoch 数。
@@ -55,12 +55,20 @@ python main.py -c paddlex/configs/image_classification/PP-LCNet_x1_0.yaml \
     -o Predict.input_path="https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg"
 ```
 
-**注：** PaddleX 允许使用 wheel 包进行推理，在此处，当您验证好自己的模型之后，即使用 PaddleX 的 wheel 包进行推理，方便地将模型集成到您自己的项目中。模型推理方法请参考 [PaddleX 单模型开发工具](../tools/model_tools.md)。
+**注：** PaddleX 允许使用 wheel 包进行推理，在此处，当您验证好自己的模型之后，即使用 PaddleX 的 wheel 包进行推理，方便地将模型集成到您自己的项目中。模型推理方法请参考 [PaddleX 单模型开发工具推理预测](../models/model_inference_tools.md)。
 
 ## 4. 须知事项
+
 ### 4.1 训练须知事项
+
 - 训练其他模型时，需要的指定相应的配置文件，模型和配置的文件的对应关系，可以详情[模型库](../models/support_model_list.md)。
 - PaddleX 对您屏蔽了动态图权重和静态图权重的概念，在模型训练的过程中，会同时产出动态图和静态图的权重，在模型推理时，默认选择静态图权重推理。
-<!-- 这里需要补充说明，廷权 -->
+
 ### 4.2 训练产出解释
-<!-- 这里需要补充说明，廷权 -->
+
+在完成模型训练后，所有产出保存在指定的输出目录（默认为`./output/`）下，通常有以下产出：
+
+* train_result.json：训练结果记录文件，记录了训练任务是否正常完成，以及产出的权重指标、相关文件路径等；
+* train.log：训练日志文件，记录了训练过程中的模型指标变化、loss 变化等；
+* config.yaml：训练配置文件，记录了本次训练的超参数的配置；
+* .pdparams\.pdema\.pdopt\.pdstate\.pdiparams\.pdmodel：模型权重相关文件，包括网络参数、优化器、EMA、静态图网络参数、静态图网络结构等；

docs/tutorials/base/hyperparameters_introduction.md

@@ -1,7 +1,9 @@
 # PaddleX 超参数介绍
+
 PaddleX 暴露了模型迭代中最常修改的参数，方便您在配置文件中或者命令行中进行修改。训练模型的基础配置和高级配置参数如下：
 
 ## 1. 基础参数
+
 对于非时序任务模块，基础参数包括`epochs_iters`，`batch_size`，`class_num`，`learning_rate`，相关的参数解释如下：
 - `epochs_iters`：Epochs 或者 Steps，模型对训练数据的重复学习次数，一般来说，轮次越大，模型训练时间越长，模型精度越高，但是如果设置特别大，可能会导致模型过拟合。如果对轮次没有特别的要求，可以使用默认值进行训练。
 - `batch_size`：批大小，由于训练数据量一般较大，模型每轮次的训练是分批读取数据的，批大小是每一批数据的数据量，和显存直接相关，批大小越大模型训练的速度越快，显存占用越高。
@@ -17,6 +19,7 @@ PaddleX 暴露了模型迭代中最常修改的参数，方便您在配置文件
 - `seq_len`：群组编号，须结合自己的数据设置指定群组编号的列名称, 如：group_id, 群组编号表示的是每个时序样本。
 
 ## 2. 进阶参数
+
 - `resune_path`：断点训练权重：在模型训练过程中发生人为或意外终止的情况时，加载训练中断之前保存的断点权重路径，完成继续训练，避免算力资源浪费。
 - `pretrain_weight_path`：预训练权重：基于已经在大数据集上训练好的模型权重进行微调训练，可提高模型训练开始前的初始经验，提高训练效率。
 - `warmup_steps`：热启动步数(WarmUp Steps)：在训练初始阶段以较小学习率缓慢增加到设置学习率的批次数量，该值的设置可以避免模型在初始阶段以较大学习率迭代模型最终破坏预训练权重，一定程度上提升模型的精度。
@@ -27,6 +30,13 @@ PaddleX 暴露了模型迭代中最常修改的参数，方便您在配置文件
 **注：** 在**目标检测**和**实例分割**任务模块中，评估、保存间隔为统一参数 `eval_interval`。
 
 ## 3. 更多参数
+
 在 PaddleX 中，除了常见的参数修改之外，也支持您修改更多的参数。
-<!-- 这里简单解释不同config的逻辑，以及参数覆盖逻辑，廷权 -->
 
+PaddleX 中的参数设置有三种方式，其优先级为：
+
+1. 命令行追加 `-o` 参数，如：`-o Global.mode=train`；
+2. 编辑 `paddlex/configs/` 目录下对应的 yaml 配置文件，如 `paddlex/configs/image_classification/ResNet50.yaml`；
+3. 编辑 `paddlex/repo_apis/xxx_api/configs/` 目录下的 yaml 配置文件，如 `paddlex/repo_apis/PaddleClas_api/configs/ResNet50.yaml`；
+
+**基础参数**和**进阶参数**均可通过【1.】和【2.】方式修改，**更多参数**可以通过【3.】的方式修改，比如视觉类任务中需要修改训练图像尺寸等。

docs/tutorials/base/model_optimize.md

@@ -22,9 +22,43 @@ python main.py -c paddlex/configs/image_classification/PP-LCNet_x1_0.yaml \
     -o Global.dataset_dir=./dataset/cls_flowers_examples
 ```
 
-执行上述命令后，PaddleX 会对数据集进行校验，并统计数据集的基本信息。相关信息会保存在当前目录的 `./output/check_dataset` 目录下。
+执行上述命令后，PaddleX 会对数据集进行校验，并统计数据集的基本信息。命令运行成功后会在log中打印出 `Check dataset passed !` 信息，同时相关产出会保存在当前目录的 `./output/check_dataset` 目录下，产出目录中包括可视化的示例样本图片和样本分布直方图。校验结果文件保存在 `./output/check_dataset_result.json`，校验结果文件具体内容为
+```
+{
+  "done_flag": true,
+  "check_pass": true,
+  "attributes": {
+    "label_file": "dataset/label.txt",
+    "num_classes": 102,
+    "train_samples": 1020,
+    "train_sample_paths": [
+      "check_dataset/demo_img/image_01904.jpg",
+      "check_dataset/demo_img/image_06940.jpg"
+    ],
+    "val_samples": 1020,
+    "val_sample_paths": [
+      "check_dataset/demo_img/image_01937.jpg",
+      "check_dataset/demo_img/image_06958.jpg"
+    ]
+  },
+  "analysis": {
+    "histogram": "check_dataset/histogram.png"
+  },
+  "dataset_path": "./dataset/cls_flowers_examples",
+  "show_type": "image",
+  "dataset_type": "ClsDataset"
+}
+```
+上述校验结果中，check_pass 为 True 表示数据集格式符合要求，其他部分指标的说明如下：
 
-<!-- 这里需要增加输出的说明，以及产出的说明，畅达 -->
+- attributes.num_classes：该数据集类别数为 102；
+- attributes.train_samples：该数据集训练集样本数量为 1020；
+- attributes.val_samples：该数据集验证集样本数量为 1020；
+- attributes.train_sample_paths：该数据集训练集样本可视化图片相对路径列表；
+- attributes.val_sample_paths：该数据集验证集样本可视化图片相对路径列表；
+
+另外，数据集校验还对数据集中所有类别的样本数量分布情况进行了分析，并绘制了分布直方图（histogram.png）：
+![样本分布直方图](https://github.com/PaddlePaddle/PaddleX/assets/142379845/e2cada1f-337f-4062-8504-077c90a3b8da)
 
 **注**：只有通过数据校验的数据才可以训练和评估。
 
@@ -36,15 +70,12 @@ python main.py -c paddlex/configs/image_classification/PP-LCNet_x1_0.yaml \
 数据集校验相关的参数可以通过修改配置文件中 `CheckDataset` 下的字段进行设置，配置文件中部分参数的示例说明如下：
 
 * `CheckDataset`:
-    <!-- 这里需要增加详细的说明，比如图像分类这里不支持转换，也需要说明，畅达 -->
-    * `dst_dataset_name`: 生成的数据集目录名，PaddleX 在数据校验时，会产生一个新的数据集；
-
     * `convert`:
-        * `enable`: 是否进行数据集格式转换；
-        * `src_dataset_type`: 如果进行数据集格式转换，则需设置源数据集格式；
+        * `enable`: 是否进行数据集格式转换，图像分类不支持格式转换，默认为 `False`;
+        * `src_dataset_type`: 如果进行数据集格式转换，则需设置源数据集格式，图像分类不支持数据转换，默认为 `null`；
     * `split`:
-        * `enable`: 是否进行重新划分数据集；
-        * `train_percent`: 如果重新划分数据集，则需要设置训练集的百分比；
-        * `val_percent`: 如果重新划分数据集，则需要设置验证集的百分比；
+        * `enable`: 是否进行重新划分数据集，为 `True` 时进行数据集格式转换，默认为 `False`；
+        * `train_percent`: 如果重新划分数据集，则需要设置训练集的百分比，类型为0-100之间的任意整数，需要保证和 `val_percent` 值加和为100；
+        * `val_percent`: 如果重新划分数据集，则需要设置验证集的百分比，类型为0-100之间的任意整数，需要保证和 `train_percent` 值加和为100；
 
-以上参数同样支持通过追加命令行参数的方式进行设置，如重新划分数据集并设置训练集与验证集比例：`-o CheckDataset.split=True -o CheckDataset.train_percent=0.8 -o CheckDataset.val_percent=0.2`。
+数据转换和数据划分支持同时开启，对于数据划分原有标注文件会被在原路径下重命名为 `xxx.bak`，以上参数同样支持通过追加命令行参数的方式进行设置，例如如重新划分数据集并设置训练集与验证集比例：`-o CheckDataset.split.enable=True -o CheckDataset.split.train_percent=80 -o CheckDataset.split.val_percent=20`。

docs/tutorials/data/README.md

@@ -7,7 +7,5 @@
 |    图像分类   |   [文档链接](ClsAnnoTools.md)  |
 |    目标检测   |   [文档链接](DetAnnoTools.md)  |
 |    语义分割   |   [文档链接](SegAnnoTools.md)  |
-|    实例分割   |   [文档链接](InsSegAnnoTools.md)  |
+|    实例分割   |   [文档链接](InstSegAnnoTools.md)  |
 |    OCR/表格识别   |   [文档链接](OCRAnnoTools.md)  |
-
-

docs/tutorials/data/annotation/README.md

@@ -1 +1,103 @@
-# 单模型 Python API 推理文档
+# PaddleX 单模型推理 Python API 文档
+
+PaddleX 预置了丰富的模型，并提供了 Python API 调用接口，可以方便的集成到其他项目中，或是实现多模型串联，自定义产线。
+
+## 1. 安装 PaddleX
+
+首先需要安装 PaddleX 的 wheel 包，安装方式请参考 [PaddleX 安装文档](../INSTALL.md)。
+
+## 2. Python API 介绍
+
+使用 Python API 调用模型进行预测，仅需几行代码，如下示例：
+
+```python
+from paddlex import PaddleInferenceOption, create_model
+
+model_name = "PP-LCNet_x1_0"
+
+# 实例化 PaddleInferenceOption 设置推理配置
+kernel_option = PaddleInferenceOption()
+kernel_option.set_device("gpu")
+
+# 调用 create_model 函数实例化预测模型
+model = create_model(model_name=model_name, kernel_option=kernel_option)
+
+# 调用预测模型 model 的 predict 方法进行预测
+result = model.predict({'input_path': "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg"})
+```
+
+具体来说，需要简单几步：1. 实例化 PaddleInferenceOption 进行推理相关设置；2. 调用 create_model 实例化预测模型对象；3. 调用预测模型对象的 predict 方法进行推理预测。
+
+#### 1. 实例化 PaddleInferenceOption 进行推理相关设置
+
+* set_deivce：设置推理设备；
+    * 参数：
+        * device_setting：str 类型，推理设备类型及卡号，设备类型支持可选 'gpu', 'cpu', 'npu', 'xpu', 'mlu'，当使用加速卡时，支持指定卡号，如使用 0 号 gpu 卡：'gpu:0'，默认为 'gpu:0'；
+    * 返回值：None
+
+* set_run_mode：设置推理后端；
+    * 参数：
+        * run_mode：str 类型，推理后端，支持可选 'paddle'，'trt_fp32'，'trt_fp16'，'trt_int8'，'mkldnn'，'mkldnn_bf16'，其中 'mkldnn' 仅当推理设备使用 CPU 时可选，默认为 'paddle'；
+    * 返回值：None
+
+* set_cpu_threads：设置 CPU 加速库计算线程数，仅当推理设备使用 CPU 时候有效；
+    * 参数：
+        * cpu_threads：int 类型，CPU 推理时加速库计算线程数；
+    * 返回值：None
+
+* get_support_run_mode：获取支持的推理后端设置；
+    * 参数：无；
+    * 返回值：list 类型，可选的推理后端设置；
+
+* get_support_device：获取支持的运行设备类型
+    * 参数：无；
+    * 返回值：list 类型，可选的设备类型；
+
+* get_device：获取当前设置的设备；
+    * 参数：无；
+    * 返回值：str 类型
+
+<!--
+* set_batch_size：设置推理批大小；
+    * 参数：
+        * batch_size：int 类型，推理的批大小；
+    * 返回值：None
+
+* set_min_subgraph_size：设置 TensorRT 后端的最小子图大小；
+    * 参数：
+        * min_subgraph_size：TensorRT 后端的最小子图大小，仅当使用 trt_fp32、trt_fp16、trt_int8 后端时有效；
+    * 返回值：None
+
+* set_shape_info_filename：
+    * 参数：
+        * shape_info_filename：
+    * 返回值：None
+
+* set_trt_calib_mode：
+    * 参数：
+        * trt_calib_mode
+    * 返回值：None
+
+* set_trt_use_static：
+    * 参数：
+        * trt_use_static
+    * 返回值：None -->
+
+#### 2. 调用 create_model 实例化预测模型对象
+
+* create_model：实例化预测模型对象（BasePredictor）
+    * 参数：
+        * model_name：str 类型，模型名
+        * kernel_option：PaddleInferenceOption 类型，表示模型预测相关设置
+    * 返回值：BasePredictor 类型
+
+#### 3. 调用预测模型对象的 predict 方法进行推理预测
+
+* predict：使用定义的预测模型，对输入数据进行预测；
+    * 参数：
+        * input：dict 类型，传入待预测数据，字典的 key 可通过 get_input_keys 方法获得；
+    * 返回值：dict 类型，包括待预测结果和预测数据等在内的数据，如 `{'input_path': 'a/b/c.jpg', 'image': ndarray(), 'cls_pred': [0.026 0.974], 'cls_result': [{'class_ids': [2, 1]}]}`，具体内容与模型及任务相关；
+
+* get_input_keys：
+    * 参数：无
+    * 返回值：list 类型，表示 predict 方法的字典参数 input 所需指定的 key，如 `['path', 'size']` 表示字典参数 input 必须包含 `'path'` 和 `'size'` 两个 key，如 `[['input_path', 'size'], ['input_data']]` 表示字典参数 input 必须包含 `'input_path'` 和 `'size'` 两个 key，**或是**包含 `'input_data'`。

docs/tutorials/models/model_inference_api.md

@@ -3,7 +3,8 @@
 PaddleX 提供了丰富的单模型，其是完成某一类任务的子模块的最小单元，模型开发完后，可以方便地集成到各类系统中。PaddleX 中的每个模型提供了官方权重，支持通过命令行方式直接推理预测和调用 Python API 预测。命令行方式直接推理预测可以快速体验模型推理效果，而 Python API 预测可以方便地集成到自己的项目中进行预测。
 
 ## 1.安装 PaddleX
-在使用单模型开发工具之前，首先需要安装 PaddleX 的 wheel 包，安装方式请参考 [PaddleX 安装文档](./INSTALL.md)。
+
+在使用单模型开发工具之前，首先需要安装 PaddleX 的 wheel 包，安装方式请参考 [PaddleX 安装文档](../INSTALL.md)。
 
 ## 2.PaddleX 单模型开发工具使用方式
 
@@ -20,10 +21,11 @@ model_name = "PP-LCNet_x1_0"
 kernel_option = PaddleInferenceOption()
 kernel_option.set_device("gpu")
 
+# 调用 create_model 函数实例化预测模型
 model = create_model(model_name=model_name, kernel_option=kernel_option)
 
-# 预测
+# 调用预测模型 model 的 predict 方法进行预测
 result = model.predict({'input_path': "https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_image_classification_001.jpg"})
 ```
 
-PaddleX 提供的所有模型均支持以上 Python API 的调用，关于模型列表，您可以参考 [PaddleX 模型列表](../models/support_model_list.md)，关于 Python API 的更多介绍，您可以参考 [PaddleX 模型推理 API](../API.md)。
+PaddleX 提供的所有模型均支持以上 Python API 的调用，关于模型列表，您可以参考 [PaddleX 模型列表](../models/support_model_list.md)，关于 Python API 的更多介绍，您可以参考 [PaddleX 模型推理 API](model_inference_api.md)。