PaddleX模型产线Python API详解与实战指南

最新推荐文章于 2025-06-08 09:00:45 发布

原创最新推荐文章于 2025-06-08 09:00:45 发布 · 372 阅读

8 ·

CC 4.0 BY-SA版权

PaddleX模型产线Python API详解与实战指南

PaddleX PaddlePaddle End-to-End Development Toolkit（『飞桨』深度学习全流程开发工具）项目地址: https://gitcode.com/gh_mirrors/pa/PaddleX

前言

PaddleX作为飞桨生态下的全流程开发工具，提供了高效的模型产线(Pipeline)功能，能够帮助开发者快速实现从数据输入到预测输出的完整流程。本文将深入解析PaddleX模型产线的Python API使用方法，通过实例演示如何利用这些API完成高效的模型推理任务。

一、环境准备与安装

在使用PaddleX模型产线前，需要确保已完成以下准备工作：

安装PaddlePaddle深度学习框架
安装PaddleX工具包
准备待推理的模型文件或使用PaddleX预训练模型

建议使用Python 3.6+环境，并确保安装的PaddleX版本与PaddlePaddle版本兼容。

二、快速入门示例

让我们从一个简单的图像分类任务开始，了解PaddleX模型产线的基本使用流程：

from paddlex import create_pipeline

# 第一步：创建图像分类产线
pipeline = create_pipeline("image_classification")

# 第二步：进行预测推理
output = pipeline.predict(
    "demo_image.jpg",  # 输入图像路径
    batch_size=1,      # 批处理大小
    topk=5            # 返回前5个最可能类别
)

# 第三步：处理预测结果
for res in output:
    # 打印预测结果
    res.print(json_format=False)
    
    # 保存可视化结果
    res.save_to_img("./output/")
    
    # 保存JSON格式结果
    res.save_to_json("./output/res.json")

这个示例展示了PaddleX模型产线使用的三个核心步骤：创建产线、执行预测和处理结果。

三、核心API详解

1. 产线创建：create_pipeline()

create_pipeline()是使用PaddleX模型产线的入口函数，主要参数包括：

pipeline = create_pipeline(
    pipeline="image_classification",  # 产线名称或配置文件路径
    device="gpu:0",                  # 运行设备
    pp_option=None                   # 推理后端配置
)

参数说明：

pipeline：支持两种形式：
- 字符串形式的预定义产线名称，如"image_classification"、"object_detection"等
- 本地YAML配置文件的路径，用于自定义产线配置
device：指定运行设备，格式为"设备类型:卡号"，如：
- "cpu"：使用CPU
- "gpu:0"：使用第0号GPU卡
- "npu:1"：使用第1号NPU卡
pp_option：高级推理配置，类型为PaddlePredictorOption，用于设置推理后端等参数

2. 预测执行：predict()

predict()方法是产线的核心功能，负责执行实际推理任务：

output = pipeline.predict(
    input,        # 输入数据
    batch_size=1, # 批处理大小
    **kwargs      # 其他产线特定参数
)

输入数据支持多种格式：

单个文件路径（字符串）
包含多个文件的目录路径
网络URL地址
numpy数组（CV任务）
pandas DataFrame（时序任务）
上述类型的列表组合

不同产线的特有参数：

图像分类：topk指定返回前N个类别
目标检测：score_threshold设置置信度阈值
语义分割：apply_softmax控制是否应用softmax

3. 结果处理与可视化

预测结果提供了丰富的处理方法和属性：

常用属性

result.str    # 字符串格式结果
result.json   # JSON字典格式结果
result.img    # PIL.Image可视化图像
result.html   # HTML格式结果

结果保存方法

result.save_to_img("output.jpg")   # 保存可视化图像
result.save_to_json("result.json") # 保存JSON结果
result.save_to_csv("data.csv")     # 保存CSV格式
result.save_to_html("page.html")   # 保存HTML页面

结果打印方法

result.print()                   # 基本打印
result.print(json_format=True)   # JSON美化打印
result.print(indent=2)          # 控制缩进

四、高级配置：推理后端优化

PaddleX支持多种推理后端配置，通过PaddlePredictorOption实现性能优化：

from paddlex import PaddlePredictorOption

# 创建推理配置
pp_option = PaddlePredictorOption()
pp_option.device = "gpu:0"       # 使用GPU 0
pp_option.run_mode = "trt_fp16"  # 使用TensorRT FP16加速
pp_option.cpu_threads = 4        # CPU线程数

# 应用配置创建产线
pipeline = create_pipeline("image_classification", pp_option=pp_option)

支持的推理后端模式：

'paddle'：默认Paddle原生推理
'trt_fp32'：TensorRT FP32加速
'trt_fp16'：TensorRT FP16加速
'trt_int8'：TensorRT INT8量化
'mkldnn'：CPU MKLDNN加速
'mkldnn_bf16'：CPU MKLDNN BF16加速

实用方法：

pp_option.get_support_run_mode()  # 获取当前设备支持的推理模式
pp_option.get_support_device()    # 获取支持的设备类型

五、不同任务的产线使用示例

1. 目标检测任务

# 创建目标检测产线
det_pipeline = create_pipeline("object_detection")

# 执行预测
results = det_pipeline.predict(
    "test_image.jpg",
    score_threshold=0.5,  # 置信度阈值
    nms_threshold=0.3     # NMS阈值
)

# 处理结果
for res in results:
    res.save_to_img("det_result.jpg")  # 保存带检测框的图像

2. 语义分割任务

# 创建语义分割产线
seg_pipeline = create_pipeline("semantic_segmentation")

# 执行预测
results = seg_pipeline.predict(
    "test_image.jpg",
    apply_softmax=True  # 应用softmax
)

# 处理结果
for res in results:
    res.save_to_img("seg_result.png")  # 保存分割结果图