From 21c8666af05fcbaff48e22c9d40b9c62a77a7516 Mon Sep 17 00:00:00 2001 From: jiangjiajun Date: Mon, 18 May 2020 17:03:49 +0800 Subject: [PATCH] add docs --- docs/datasets.md | 204 +++++++++++++++++++++++ docs/quick_start.md | 39 +++-- docs/tutorials/deploy/deploy.md | 33 ++++ docs/tutorials/deploy/depoly_openvino.md | 103 ++++++++++++ docs/tutorials/deploy/encryption.md | 49 ++++++ 5 files changed, 413 insertions(+), 15 deletions(-) create mode 100644 docs/datasets.md mode change 100755 => 100644 docs/quick_start.md create mode 100644 docs/tutorials/deploy/depoly_openvino.md create mode 100644 docs/tutorials/deploy/encryption.md diff --git a/docs/datasets.md b/docs/datasets.md new file mode 100644 index 0000000..841f433 --- /dev/null +++ b/docs/datasets.md @@ -0,0 +1,204 @@ +# 数据集格式说明 + +--- +## 图像分类ImageNet + +图像分类ImageNet数据集包含对应多个标签的图像文件夹、标签文件及图像列表文件。 +参考数据文件结构如下： +``` +./dataset/ # 数据集根目录 +|--labelA # 标签为labelA的图像目录 +| |--a1.jpg +| |--... +| └--... +| +|--... +| +|--labelZ # 标签为labelZ的图像目录 +| |--z1.jpg +| |--... +| └--... +| +|--train_list.txt # 训练文件列表文件 +| +|--val_list.txt # 验证文件列表文件 +| +└--labels.txt # 标签列表文件 + +``` +其中，相应的文件名可根据需要自行定义。 + +`train_list.txt`和`val_list.txt`文本以空格为分割符分为两列，第一列为图像文件相对于dataset的相对路径，第二列为图像文件对应的标签id(从0开始)。如下所示： +``` +labelA/a1.jpg 0 +labelZ/z1.jpg 25 +... +``` + +`labels.txt`: 每一行为一个单独的类别，相应的行号即为类别对应的id（行号从0开始)，如下所示： +``` +labelA +labelB +... +``` +[点击这里](https://bj.bcebos.com/paddlex/datasets/vegetables_cls.tar.gz)，下载蔬菜分类分类数据集 +在PaddleX中，使用`paddlex.cv.datasets.ImageNet`([API说明](./apis/datasets.html#imagenet))加载分类数据集 + +## 目标检测VOC +目标检测VOC数据集包含图像文件夹、标注信息文件夹、标签文件及图像列表文件。 +参考数据文件结构如下： +``` +./dataset/ # 数据集根目录 +|--JPEGImages # 图像目录 +| |--xxx1.jpg +| |--... +| └--... +| +|--Annotations # 标注信息目录 +| |--xxx1.xml +| |--... +| └--... +| +|--train_list.txt # 训练文件列表文件 +| +|--val_list.txt # 验证文件列表文件 +| +└--labels.txt # 标签列表文件 + +``` +其中，相应的文件名可根据需要自行定义。 + +`train_list.txt`和`val_list.txt`文本以空格为分割符分为两列，第一列为图像文件相对于dataset的相对路径，第二列为标注文件相对于dataset的相对路径。如下所示： +``` +JPEGImages/xxx1.jpg Annotations/xxx1.xml +JPEGImages/xxx2.jpg Annotations/xxx2.xml +... +``` + +`labels.txt`: 每一行为一个单独的类别，相应的行号即为类别对应的id（行号从0开始)，如下所示： +``` +labelA +labelB +... +``` +[点击这里](https://bj.bcebos.com/paddlex/datasets/insect_det.tar.gz)，下载昆虫检测数据集 +在PaddleX中，使用`paddlex.cv.datasets.VOCDetection`([API说明](./apis/datasets.html#vocdetection))加载目标检测VOC数据集 + +## 目标检测和实例分割COCO +目标检测和实例分割COCO数据集包含图像文件夹及图像标注信息文件。 +参考数据文件结构如下： +``` +./dataset/ # 数据集根目录 +|--JPEGImages # 图像目录 +| |--xxx1.jpg +| |--... +| └--... +| +|--train.json # 训练相关信息文件 +| +└--val.json # 验证相关信息文件 + +``` +其中，相应的文件名可根据需要自行定义。 + +`train.json`和`val.json`存储与标注信息、图像文件相关的信息。如下所示： + +``` +{ + "annotations": [ + { + "iscrowd": 0, + "category_id": 1, + "id": 1, + "area": 33672.0, + "image_id": 1, + "bbox": [232, 32, 138, 244], + "segmentation": [[32, 168, 365, 117, ...]] + }, + ... + ], + "images": [ + { + "file_name": "xxx1.jpg", + "height": 512, + "id": 267, + "width": 612 + }, + ... + ] + "categories": [ + { + "name": "labelA", + "id": 1, + "supercategory": "component" + } + ] +} +``` +每个字段的含义如下所示： + +| 域名 | 字段名 | 含义 | 数据类型 | 备注 | +|:-----|:--------|:------------|------|:-----| +| annotations | id | 标注信息id | int | 从1开始 | +| annotations | iscrowd | 标注框是否为一组对象 | int | 只有0、1两种取值 | +| annotations | category_id | 标注框类别id | int | | +| annotations | area | 标注框的面积 | float | | +| annotations | image_id | 当前标注信息所在图像的id | int | | +| annotations | bbox | 标注框坐标 | list | 长度为4，分别代表x,y,w,h | +| annotations | segmentation | 标注区域坐标 | list | list中有至少1个list，每个list由每个小区域坐标点的横纵坐标(x,y)组成 | +| images | id | 图像id | int | 从1开始 | +| images | file_name | 图像文件名 | str | | +| images | height | 图像高度 | int | | +| images | width | 图像宽度 | int | | +| categories | id | 类别id | int | 从1开始 | +| categories | name | 类别标签名 | str | | +| categories | supercategory | 类别父类的标签名 | str | | + + +[点击这里](https://bj.bcebos.com/paddlex/datasets/garbage_ins_det.tar.gz)，下载垃圾实例分割数据集 +在PaddleX中，使用`paddlex.cv.datasets.COCODetection`([API说明](./apis/datasets.html#cocodetection))加载COCO格式数据集 + +## 语义分割数据 +语义分割数据集包含原图、标注图及相应的文件列表文件。 +参考数据文件结构如下： +``` +./dataset/ # 数据集根目录 +|--images # 原图目录 +| |--xxx1.png +| |--... +| └--... +| +|--annotations # 标注图目录 +| |--xxx1.png +| |--... +| └--... +| +|--train_list.txt # 训练文件列表文件 +| +|--val_list.txt # 验证文件列表文件 +| +└--labels.txt # 标签列表 + +``` +其中，相应的文件名可根据需要自行定义。 + +`train_list.txt`和`val_list.txt`文本以空格为分割符分为两列，第一列为图像文件相对于dataset的相对路径，第二列为标注图像文件相对于dataset的相对路径。如下所示： +``` +images/xxx1.png annotations/xxx1.png +images/xxx2.png annotations/xxx2.png +... +``` + +`labels.txt`: 每一行为一个单独的类别，相应的行号即为类别对应的id（行号从0开始)，如下所示： +``` +labelA +labelB +... +``` + +标注图像为单通道图像，像素值即为对应的类别,像素标注类别需要从0开始递增， +例如0，1，2，3表示有4种类别，标注类别最多为256类。其中可以指定特定的像素值用于表示该值的像素不参与训练和评估（默认为255）。 + +[点击这里](https://bj.bcebos.com/paddlex/datasets/optic_disc_seg.tar.gz)，下载视盘语义分割数据集 +在PaddleX中，使用`paddlex.cv.datasets.SegReader`([API说明](./apis/datasets.html#segreader))加载语义分割数据集 + diff --git a/docs/quick_start.md b/docs/quick_start.md old mode 100755 new mode 100644 index 6810046..dafb902 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -17,16 +17,16 @@ tar xzvf vegetables_cls.tar.gz ## 3. 训练代码开发 PaddleX的所有模型训练和预测均只涉及到5个API接口，分别是 -> - [transforms](apis/transforms/index) 图像数据处理 -> - [datasets](apis/datasets.md) 数据集加载 -> - [models](apis/models.md) 模型类型定义 -> - [train](apis/models.md) 开始训练 -> - [predict](apis/models.md) 模型预测 +> - [transforms](apis/transforms/index.html) 图像数据处理 +> - [datasets](apis/datasets/classification.md) 数据集加载 +> - [models](apis/models/classification.md) 模型类型定义 +> - [train](apis/models/classification.html#train) 开始训练 +> - [predict](apis/models/classification.html#predict) 模型预测 在本示例，通过如下`train.py`代码进行训练, 训练环境为1张Tesla P40 GPU卡。 ### 3.1 定义`transforms`数据处理流程 -由于训练时数据增强操作的加入，因此模型在训练和验证过程中，数据处理流程需要分别进行定义。如下所示，代码在`train_transforms`中加入了[RandomCrop](apis/transforms/cls_transforms.html#RandomCrop)和[RandomHorizontalFlip](apis/transforms/cls_transforms.html#RandomHorizontalFlip)两种数据增强方式 +由于训练时数据增强操作的加入，因此模型在训练和验证过程中，数据处理流程需要分别进行定义。如下所示，代码在`train_transforms`中加入了[RandomCrop](apis/transforms/cls_transforms.html#RandomCrop)和[RandomHorizontalFlip](apis/transforms/cls_transforms.html#RandomHorizontalFlip)两种数据增强方式, 更多方法可以参考[数据增强文档](apis/transforms/augment.md)。 ``` from paddlex.cls import transforms train_transforms = transforms.Compose([ @@ -41,7 +41,8 @@ eval_transforms = transforms.Compose([ ]) ``` -> 定义数据集，`pdx.datasets.ImageNet`表示读取ImageNet格式的分类数据集 +### 3.2 定义`dataset`加载数据集 +定义数据集，`pdx.datasets.ImageNet`表示读取ImageNet格式的分类数据集, 更多数据集细节可以查阅[数据集格式说明](datasets.md)和[ImageNet接口文档](apis/datasets/classification.md) ``` train_dataset = pdx.datasets.ImageNet( data_dir='vegetables_cls', @@ -55,11 +56,17 @@ eval_dataset = pdx.datasets.ImageNet( label_list='vegetables_cls/labels.txt', transforms=eval_transforms) ``` -> 模型训练 +### 3.3 定义分类模型 +本文档中使用百度基于蒸馏方法得到的MobileNetV3预训练模型，模型结构与MobileNetV3一致，但精度更高。PaddleX内置了20多种分类模型，查阅[PaddleX模型库](appendix/model_zoo.md)了解更多分类模型。 ``` num_classes = len(train_dataset.labels) -model = pdx.cls.MobileNetV2(num_classes=num_classes) +model.pdx.cls.MobileNetV3_small_ssld(num_classes=num_classes) +``` + +### 3.4 定义训练参数 +定义好模型后，即可直接调用`train`接口，定义训练时的参数，分类模型内置了`piecewise_decay`学习率衰减策略，相关参数见[分类train接口文档](apis/models/classification.html#train)。 +``` model.train(num_epochs=10, train_dataset=train_dataset, train_batch_size=32, @@ -70,19 +77,21 @@ model.train(num_epochs=10, use_vdl=True) ``` -## 3. 模型训练 -> `train.py`与解压后的数据集目录`vegetables_cls`放在同一目录下，在此目录下运行`train.py`即可开始训练。如果您的电脑上有GPU，这将会在10分钟内训练完成，如果为CPU也大概会在30分钟内训练完毕。 +## 4. 模型开始训练 +`train.py`与解压后的数据集目录`vegetables_cls`放在同一目录下，在此目录下运行`train.py`即可开始训练。如果您的电脑上有GPU，这将会在10分钟内训练完成，如果为CPU也大概会在30分钟内训练完毕。 ``` python train.py ``` -## 4. 训练过程中查看训练指标 -> 模型在训练过程中，所有的迭代信息将以标注输出流的形式，输出到命令执行的终端上，用户也可通过visualdl以可视化的方式查看训练指标的变化，通过如下方式启动visualdl后，在浏览器打开https://0.0.0.0:8001即可。 + +## 5. 训练过程中查看训练指标 +模型在训练过程中，所有的迭代信息将以标注输出流的形式，输出到命令执行的终端上，用户也可通过visualdl以可视化的方式查看训练指标的变化，通过如下方式启动visualdl后，在浏览器打开https://0.0.0.0:8001 (或 https://localhost:8001)即可。 ``` visualdl --logdir output/mobilenetv2/vdl_log --port 8000 ``` ![](./images/vdl1.jpg) -## 5. 训练完成使用模型进行测试 -> 如使用训练过程中第8轮保存的模型进行测试 + +## 6. 训练完成使用模型进行测试 +如下代码使用训练过程中第8轮保存的模型进行测试。 ``` import paddlex as pdx model = pdx.load_model('output/mobilenetv2/epoch_8') diff --git a/docs/tutorials/deploy/deploy.md b/docs/tutorials/deploy/deploy.md index c7d1545..7193dc3 100755 --- a/docs/tutorials/deploy/deploy.md +++ b/docs/tutorials/deploy/deploy.md @@ -39,6 +39,39 @@ C++部署方案位于目录`deploy/cpp/`下，且独立于PaddleX其他模块。 - Linux平台：[linux](deploy_cpp_linux.md) - window平台：[windows](deploy_cpp_win_vs2019.md) +### OpenVINO部署demo + +OpenVINO部署demo位于目录`deploy/openvino/`下，且独立于PaddleX其他模块，该demo目前支持在 Linux 完成编译和部署运行。目前PaddleX到OpenVINO的部署流程如下： + +graph LR + PaddleX --> ONNX --> OpenVINO IR --> OpenVINO Inference Engine +#### step1 + +PaddleX输出ONNX模型方法如下： + +``` +paddlex --export_onnx --model_dir=./xiaoduxiong_epoch_12 --save_dir=./onnx_model +``` + +|目前支持的模型| +|-----| +|ResNet18| +|ResNet34| +|ResNet50| +|ResNet101| +|ResNet50_vd| +|ResNet101_vd| +|ResNet50_vd_ssld| +|ResNet101_vd_ssld +|DarkNet53| +|MobileNetV1| +|MobileNetV2| +|DenseNet121| +|DenseNet161| +|DenseNet201| + +得到ONNX模型后，OpenVINO的部署参考：[OpenVINO部署](deploy_openvino.md) + ### 预测性能对比 #### 测试环境 diff --git a/docs/tutorials/deploy/depoly_openvino.md b/docs/tutorials/deploy/depoly_openvino.md new file mode 100644 index 0000000..30a0c3f --- /dev/null +++ b/docs/tutorials/deploy/depoly_openvino.md @@ -0,0 +1,103 @@ +# OpenVINO 分类demo编译 + +## 说明 +本文档在 `Ubuntu`使用`GCC 4.8.5` 进行了验证，如果需要使用更多G++版本和平台的OpenVino编译，请参考: [OpenVINO](https://github.com/openvinotoolkit/openvino/blob/2020/build-instruction.md)。 + +## 验证环境 +* Ubuntu* 16.04 (64-bit) with GCC* 4.8.5 +* CMake 3.12 +* Python 2.7 or higher + +请确保系统已经安装好上述基本软件，**下面所有示例以工作目录 `/root/projects/`演示**。 + + `git clone https://github.com/PaddlePaddle/PaddleX.git` + +**说明**：其中`C++`预测代码在`/root/projects/PaddleX/deploy/openvino` 目录，该目录不依赖任何`PaddleX`下其他目录。 + +### Step1: 软件依赖 + +- openvino: +[编译文档](https://github.com/openvinotoolkit/openvino/blob/2020/build-instruction.md#build-steps) + +- gflags: +[编译文档](https://gflags.github.io/gflags/#download) + +- opencv: +[编译文档](https://docs.opencv.org/master/d7/d9f/tutorial_linux_install.html) +说明：/root/projects/PaddleX/deploy/openvino/scripts/bootstrap.sh提供了预编译版本下载，也可自行编译。 + +- ngraph: +说明：openvino编译的过程中会生成ngraph的lib文件，位于{openvino根目录}/bin/intel64/Release/lib/下。 + +### Step2: 编译demo + + +编译`cmake`的命令在`scripts/build.sh`中，请根据Step1中编译软件的实际情况修改主要参数，其主要内容说明如下： +``` +# openvino预编译库的路径 +OPENVINO_DIR=/path/to/inference_engine/ +# gflags预编译库的路径 +GFLAGS_DIR=/path/to/gflags +# ngraph lib的路径，编译openvino时通常会生成 +NGRAPH_LIB=/path/to/ngraph/lib/ +# opencv预编译库的路径, 如果使用自带预编译版本可不修改 +OPENCV_DIR=$(pwd)/deps/opencv3gcc4.8/ +# 下载自带预编译版本 +sh $(pwd)/scripts/bootstrap.sh +rm -rf build +mkdir -p build +cd build +cmake .. \ + -DOPENCV_DIR=${OPENCV_DIR} \ + -DGFLAGS_DIR=${GFLAGS_DIR} \ + -DOPENVINO_DIR=${OPENVINO_DIR} \ + -DNGRAPH_LIB=${NGRAPH_LIB} +make +``` + +修改脚本设置好主要参数后，执行`build`脚本： + ```shell + sh ./scripts/build.sh + ``` + +### Step3: 模型转换 + +将[]()生成的onnx文件转换为OpencVINO支持的格式，请参考：[Model Optimizer文档](https://docs.openvinotoolkit.org/latest/_docs_MO_DG_Deep_Learning_Model_Optimizer_DevGuide.html) + +### Step4: 预测 +编译成功后，预测demo的可执行程序分别为`build/classifer`，其主要命令参数说明如下： + +| 参数 | 说明 | +| ---- | ---- | +| --model_dir | Model Optimizer生成的.xml文件路径，请保证Model Optimizer生成的三个文件在同一路径下| +| --image | 要预测的图片文件路径 | +| --image_list | 按行存储图片路径的.txt文件 | +| --device | 运行的平台, 默认值为"CPU" | + + +## 样例 + +可使用[小度熊识别模型](deploy.md#导出inference模型)中导出的`inference_model`和测试图片进行预测。 + +`样例一`： + +测试图片 `/path/to/xiaoduxiong.jpeg` + +```shell +./build/classifier --model_dir=/path/to/inference_model --image=/path/to/xiaoduxiong.jpeg +``` + + +`样例二`: + +预测多个图片`/path/to/image_list.txt`，image_list.txt内容的格式如下： +``` +/path/to/images/xiaoduxiong1.jpeg +/path/to/images/xiaoduxiong2.jpeg +... +/path/to/images/xiaoduxiongn.jpeg +``` +```shell +./build/classifier --model_dir=/path/to/models/inference_model --image_list=/root/projects/images_list.txt - +``` + diff --git a/docs/tutorials/deploy/encryption.md b/docs/tutorials/deploy/encryption.md new file mode 100644 index 0000000..8d83315 --- /dev/null +++ b/docs/tutorials/deploy/encryption.md @@ -0,0 +1,49 @@ +# Paddle模型加密方案 + +飞桨团队推出模型加密方案，使用业内主流的AES加密技术对最终模型进行加密。飞桨用户可以通过PaddleX导出模型后，使用该方案对模型进行加密，预测时使用解密SDK进行模型解密并完成推理，大大提升AI应用安全性和开发效率。 + +## 1. 方案介绍 + +### 1.1 工具组成 + +[链接](http://wiki.baidu.com/pages/viewpage.action?pageId=1128566963) + +下载并解压后，目录包含内容为： +``` +paddle_model_encrypt +├── include # 头文件：paddle_model_decrypt.h(解密)和paddle_model_encrypt.h(加密) +| +├── lib # libpmodel-encrypt.so和libpmodel-decrypt.so动态库 +| +└── tool # paddle_encrypt_tool +``` + +### 1.2 二进制工具 + +#### 1.2.1 生成密钥 + +产生随机密钥信息（用于AES加解密使用）（32字节key + 16字节iv， 注意这里产生的key是经过base64编码后的，这样可以扩充选取key的范围） + +``` +paddle_encrypt_tool -g +``` +#### 1.2.1 文件加密 + +``` + paddle_encrypt_tool -e -key keydata -infile infile -outfile outfile +``` + +#### 1.3 SDK + +``` +// 加密API +int paddle_encrypt_model(const char* keydata, const char* infile, const char* outfile); +// 加载加密模型API： +int paddle_security_load_model( + paddle::AnalysisConfig *config, + const char *key, + const char *model_file, + const char *param_file); +``` + +## 2. PaddleX C++加密部署 -- GitLab