UAPI使用文档
更新时间：2024-03-25
UAPI使用文档
1 简介
UAPI是飞桨模型超高层开发接口，提供统一的开发API，覆盖10+任务和40+模型，支持快速创建、训练、压缩、部署模型，具有一站式、高效率、标准化的开发体验。
UAPI具有如下特性：
- 统一接口：提供简明统一的开发接口，学习成本低，可以快速上手
- 多任务模型：支持10+任务，接入40+模型，真正一站式开发体验
- 全流程能力：整合飞桨核心训压推开发能力，标准化全流程开发方式
- 兼容套件：配置文件、模型等和开发套件兼容，轻松切换使用UAPI
2 核心接口
UAPI中关键类模块：
- Config类与Model类：UAPI遵循『配置-执行』的使用范式，即首先进行参数配置，然后根据配置信息实际执行。对应的两个类是Config与Model：Config类负责更新配置信息，Model类负责执行模型训压推。
- Predictor类：Model类提供了模型推理能力，但是可能无法满足实际场景的需求。Predictor类提供强化版的静态图模型推理能力，功能强大、全程可控、支持自定义前后处理，非常适合多个模型串联推理。
UAPI主要提供接口：
-
uapi.Config- 接受模型名称和配置文件作为输入参数（配置文件非必须），用于初始化创建Config类对象。
- Config类提供一组方法，用于设置常见参数配置，例如
config.update_dataset更新数据集路径、config.update_learning_rate更新基准学习率。
-
uapi.PaddleModel- 接受一个Config类对象作为输入参数，用于创建Model类对象。
- Model类提供一组方法，每个方法对应一个模型开发阶段。例如：
model.check_dataset用于执行数据集校验，model.train用于执行模型训练，model.evaluate用于执行模型精度验证，model.predict用于执行动态图模型推理，model.export用于导出静态图模型，model.infer用于执行静态图模型的推理。
-
uapi.infer.Predictor- 接受模型名称和静态图模型路径作为输入参数，也支持设置前后处理操作，用于创建Predictor类对象。
- Predictor类提供run方法对输入数据执行预测，并返回结果。
3 快速上手
UAPI的典型用法如下：
- 使用
uapi.Config创建Config类对象，需要传入支持的”模型名称“或者“模型名称+配置文件”； - 调用Config接口设置数据集路径等配置项；
- 基于Config，使用
uapi.PaddleModel创建Model类对象； - 调用Model接口执行模型训练、验证、导出、推理等；
- 调用Predictor接口执行静态图模型的推理。
UAPI的开发接口，既追求统一性，也具备可扩展性，可以兼容特定任务模型的差异。例如，针对特定任务模型，Config类可以提供接口用于设置专有的参数配置，Model类可以在训压推接口中新增输入参数。因此，请参考不同任务模型的API文档，了解具体接口细节，以便顺利完成开发工作。
3.1 模型训练 - 简单示例
from uapi import PaddleModel, Config
from uapi import download_and_extract
# 下载并解压示例数据集
# 请注意，download_and_extract不对下载的数据做安全性检查，因此只应该被用于信任的数据源
download_and_extract(
"https://paddle-model-ecology.bj.bcebos.com/uapi/data/seg_optic_examples.tar",
'data', 'seg_optic_examples')
# 通过模型名称创建Config
config = Config('PP-LiteSeg-Tiny')
# 或者，基于模型名称和的配置文件创建Config，后续以配置文件中的信息为准进行训压推
# config = Config('PP-LiteSeg-Tiny', config_path="path/to/custom-config.yaml")
# 更新类别数
config.update_num_classes(2)
# 更新数据集路径
config.update_dataset("data/seg_optic_examples")
# 通过Config创建Model
model = PaddleModel(config=config)
# 执行模型训练
model.train(
epochs_iters=1000,
save_dir="output")
# 执行模型精度验证
model.evaluate(weight_path="output/best_model/model.pdparams")3.2 模型训压推 - 详细示例
from uapi import PaddleModel, Config
from uapi import download_and_extract
# 下载并解压示例数据集
# 请注意，download_and_extract不对下载的数据做安全性检查，因此只应该被用于信任的数据源
download_and_extract(
"https://paddle-model-ecology.bj.bcebos.com/uapi/data/seg_optic_examples.tar",
'data', 'seg_optic_examples')
# 通过模型名称创建Config
config = Config('PP-LiteSeg-Tiny')
# 或者，基于模型名称和的配置文件创建Config，后续以配置文件中的信息为准进行训压推
# config = Config('PP-LiteSeg-Tiny', config_path="path/to/custom-config.yaml")
# 调用Config接口更新必要的配置项
# 更新类别数
config.update_num_classes(2)
# 更新数据集路径
config.update_dataset("data/seg_optic_examples")
# 通过Config创建Model
model = PaddleModel(config=config)
# 调用Model接口执行数据集校验
ds_meta = model.check_dataset(
# 指定数据集路径
dataset_dir="data/seg_optic_examples",
# 指定数据集类型，'SegDataset'是PaddleX定义的一种分割数据集规范格式
dataset_type='SegDataset',
# 指定数据集校验模式，'fast'表示快速校验（只检查最关键的部分），'full'表示完整校验
mode='fast')
assert ds_meta['res_flag'], "数据集校验未通过"
# 调用Model接口执行模型训练
model.train(
# 指定mini-batch大小
batch_size=4,
# 指定初始学习率大小
learning_rate=0.001,
# 指定训练总迭代数
epochs_iters=1000,
# 指定使用的设备，'gpu'表示GPU单机单卡
device='gpu',
# 启用动转静训练
dy2st=False,
# 使用O1等级的自动混合精度训练
amp='OFF',
# 指定训练过程中输出文件存储路径
save_dir="output")
# 调用Model接口执行模型精度验证
model.evaluate(
# 指定要加载的模型权重文件路径
weight_path="output/best_model/model.pdparams",
# 指定使用的设备，'gpu:0,1'表示GPU单机2卡（使用编号为0和1的GPU）
device='gpu:0,1',
# 指定用于数据读取的子进程数量
num_workers=2)
# 调用Model接口执行模型的预测
model.predict(
# 指定要加载的模型权重文件路径
weight_path="output/best_model/model.pdparams",
# 指定使用的设备，'cpu'表示使用CPU
device='cpu',
# 指定输入图像路径
input_path="data/seg_optic_examples/JPEGImages/P0088.jpg",
# 指定预测结果存储路径
save_dir="output/pred")
# 调用Model接口导出静态图模型
model.export(
# 指定要加载的模型权重文件路径
weight_path="output/best_model/model.pdparams",
# 指定导出结果存储路径
save_dir="output/export",
# Seg Suite模型特有参数，指定输入张量的形状
input_shape=[1, 3, 512, 512])
# 调用Model接口加载静态图模型进行推理
model.infer(
# 指定静态图模型的存储路径
model_dir="output/export",
# 指定输入图像路径
input_path="data/seg_optic_examples/JPEGImages/P0088.jpg",
# 指定预测结果存储路径
save_dir="output/infer")3.3 模型推理 - 简单示例
from uapi.infer import Predictor
from uapi.infer import Transform as T
from uapi import download, download_and_extract
# 下载示例图片
download(
"https://paddle-model-ecology.bj.bcebos.com/uapi/data/infer/cityscapes_demo.png",
"data/cityscapes_demo.png")
# 下载并解压静态图模型
# 请注意，download_and_extract不对下载的数据做安全性检查，因此只应该被用于信任的数据源
download_and_extract(
"https://paddle-model-ecology.bj.bcebos.com/uapi/infer_fd/pp_liteseg_stdc1/model.zip",
'data', 'PP-LiteSeg-Tiny')
# 创建模型预处理和后处理操作
pre_transforms = None # 使用默认的预处理操作
post_transforms = [
# 生成伪彩色图像
T.seg.GeneratePCMap(),
# 保存分割结果
T.seg.SaveSegResults(
save_dir="output", save_pc_map=True)
]
# 创建Predictor
predictor = Predictor(
model_name='PP-LiteSeg-Tiny',
model_dir="data/PP-LiteSeg-Tiny",
prd_config={'device': 'gpu'},
pre_transforms=pre_transforms,
post_transforms=post_transforms)
# 设置单张图像输入信息
data = {'image_path': "data/cityscapes_demo.png"}
# 执行单张图像推理
pred = predictor.run(data)
# 设置多张图像输入信息
batch_data = [{'image_path': "data/cityscapes_demo.png"} for _ in range(4)]
# 执行批量推理
batch_pred = predictor.run(data, batch_size=4)4 支持的任务与模型
| 任务 | 模型名称 |
|---|---|
| 图像分类 | CLIP_vit_base_patch16_224, MobileNetV3_small_x1_0, PPHGNet_small, PP-HGNetv2-B0, PP-HGNetv2-B4, PP-HGNetv2-B6, PPLCNet_x1_0, ResNet50, SwinTransformer_base_patch4_window7_224 |
| 识图 | PPLCNetV2_base_ShiTu |
| 文本检测 | ch_PP-OCRv4_det, ch_PP-OCRv4_det_server |
| 文本识别 | ch_PP-OCRv4_rec, ch_PP-OCRv4_rec_server |
| 表格识别 | slanet |
| 目标检测 | PP-PicoDet_s_320_LCNet, PP-PicoDet_l_640_LCNet, PP-YOLOE+_crn_l_80e, PP-YOLOE+_crn_s_80e, RT-DETR-L, RT-DETR-H，pp_shituv2_det, picodet_layout_1x |
| 语义分割 | OCRNet_HRNetW48, PP-LiteSeg-Tiny |
| 多视角3D目标检测 | PETRv1_v99, PETRv2_v99 |
| 单目图像3D目标检测 | CaDDN_ocrnet_hrnet_w18 |
| 点云3D目标检测 | CenterPoint_pillars_02voxel |
| 长时序预测 | PP-TS, TiDE, TimesNet, PatchTST, DLinear, NLinear, RLinear, Nonstationary, XGBoost |
| 时序分类 | TimesNet_CLS |
| 时序异常检测 | TimesNet_AD |