PaddleX单模型Python API使用指南：从入门到精通

PaddleX单模型Python API使用指南：从入门到精通

前言

PaddleX作为飞桨生态下的全流程开发工具，提供了简洁高效的模型推理API。本文将详细介绍如何使用PaddleX的Python API进行单模型推理，帮助开发者快速上手并应用于实际项目中。

一、快速开始：图像分类示例

让我们从一个简单的图像分类示例开始，直观感受PaddleX API的便捷性：

from paddlex import create_model

# 1. 创建模型实例
model = create_model(model_name="PP-LCNet_x1_0")

# 2. 执行预测
output = model.predict("demo_image.jpg", batch_size=1)

# 3. 处理结果
for res in output:
    res.print(json_format=False)  # 打印结果
    res.save_to_img("./output/")  # 保存可视化图片
    res.save_to_json("./output/res.json")  # 保存JSON格式结果

整个过程只需三步：创建模型、执行预测、处理结果，体现了PaddleX API设计的简洁性。

二、核心API详解

1. 模型创建：create_model()

create_model是模型推理的入口函数，负责加载和初始化模型。

关键参数说明：

• model_name：支持两种形式
  • 预训练模型名称（如"PP-LCNet_x1_0"）
  • 本地模型路径（如"/path/to/model_infer/"）
• model_dir：当使用本地模型时指定路径
• batch_size：推理批大小，影响内存占用和推理速度
• device：指定计算设备
  • "cpu"：使用CPU推理
  • "gpu:0"：使用第0号GPU
  • 也支持NPU、XPU等异构设备

典型用法：

# 使用预训练模型
model = create_model(model_name="ResNet50_vd")

# 使用本地模型
model = create_model(model_dir="./saved_model/")

2. 预测执行：predict()

predict方法支持多种输入形式，灵活应对不同场景。

输入类型支持：

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

输出处理： 返回生成器对象，可通过迭代逐条获取预测结果，内存效率高。

使用示例：

# 单张图片预测
output = model.predict("image.jpg")

# 批量预测目录下所有图片
output = model.predict("./image_dir/")

# 处理网络图片
output = model.predict("http://example.com/image.jpg")

三、结果处理与可视化

PaddleX提供了丰富的结果处理方式，满足不同需求。

1. 结果属性访问

result = next(output)  # 获取单个结果

# 获取不同格式的结果
str_result = str(result)    # 字符串表示
json_result = result.json   # JSON字典格式
img_result = result.img     # PIL.Image对象（可视化结果）

2. 结果输出方法

# 打印结果（支持JSON格式化）
result.print(json_format=True, indent=2)

# 保存为JSON文件
result.save_to_json("result.json")

# 保存可视化图片
result.save_to_img("vis_result.jpg")

# 其他格式保存（根据模型类型支持）
result.save_to_csv("result.csv")
result.save_to_html("result.html")

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

PaddleX通过PaddlePredictorOption提供细粒度的推理配置。

1. 设备与后端配置

from paddlex import PaddlePredictorOption

# 创建配置对象
option = PaddlePredictorOption()

# 设置GPU设备
option.device = "gpu:0"

# 设置TensorRT加速
option.run_mode = "trt_fp16"

# 查看支持的后端配置
print(option.get_support_run_mode())

2. CPU优化配置

# 启用MKLDNN加速
option.run_mode = "mkldnn"

# 设置CPU线程数
option.cpu_threads = 4

五、最佳实践建议

1. 批处理优化：适当增大batch_size可提升吞吐量，但需注意内存限制
2. 设备选择：GPU推理通常比CPU快10倍以上，优先考虑使用GPU
3. 后端选择：
   • 生产环境推荐使用TensorRT（trt_fp16/trt_int8）
   • CPU环境可使用MKLDNN加速
4. 结果处理：对于大批量预测，建议使用生成器逐条处理，避免内存溢出

六、常见问题解答

Q：如何知道模型支持哪些结果输出格式？ A：可通过dir(result)查看对象属性，或查阅具体模型文档。一般来说：

• 分类模型支持img/json
• 检测模型额外支持可视化图片
• 时序模型支持csv/xlsx

Q：推理时出现内存不足怎么办？ A：可尝试：

1. 减小batch_size
2. 使用更小的模型
3. 启用trt_int8量化减少显存占用

Q：如何在不同设备间切换？ A：只需修改device参数即可，代码无需其他改动：

# CPU推理
model = create_model(..., device="cpu")

# 切换回GPU
model = create_model(..., device="gpu:0")

结语

通过本文，您应该已经掌握了PaddleX单模型Python API的核心使用方法。PaddleX通过简洁的API设计，让模型推理变得异常简单，同时又不失灵活性。建议读者结合实际项目需求，尝试不同的配置组合，找到最适合自己应用场景的推理方案。