资讯 社区 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

UAPI使用文档

UAPI使用文档

1 简介

UAPI是飞桨模型超高层开发接口,提供统一的开发API,覆盖10+任务和40+模型,支持快速创建、训练、压缩、部署模型,具有一站式、高效率、标准化的开发体验。

UAPI具有如下特性:

  • 统一接口:提供简明统一的开发接口,学习成本低,可以快速上手
  • 多任务模型:支持10+任务,接入40+模型,真正一站式开发体验
  • 全流程能力:整合飞桨核心训压推开发能力,标准化全流程开发方式
  • 兼容套件:配置文件、模型等和开发套件兼容,轻松切换使用UAPI

overview.png

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

5 API文档

UAPI接口文档

上一篇
数据集规范
下一篇
UAPI接口文档