PaddleHub 图像分类模块 se_resnet18_vd_imagenet 实战指南:安装、预测 API 与 Serving 部署

原创2026-09-23 12:50:061,877 阅读
文章标签:人工智能深度学习微调迁移学习模型推理服务本地部署NLP计算机视觉CLI

PaddleHub 图像分类模块 se_resnet18_vd_imagenet 实战指南:安装、预测 API 与 Serving 部署

导读

本指南围绕 PaddleHub 官方图像分类模块 se_resnet18_vd_imagenet 展开,完整讲解该模块的安装方式、命令行与 Python API 两种预测用法、关键参数含义,以及基于 PaddleHub Serving 的在线服务部署流程。读完本文,你将掌握该模块从「本地安装 → 单张图片分类 → HTTP 服务化调用」的完整落地路径,并能结合仓库源码理解其预处理、推理与后处理的实现细节,便于迁移到其他 PaddleHub CV 模块。

模块基本信息

se_resnet18_vd_imagenet 是 PaddleHub 中面向图像分类任务的预训练模块,其关键信息如下表所示:

项目 内容
模块名称 se_resnet18_vd_imagenet
类别 image classification(图像分类)
网络结构 SE-ResNet
训练数据集 ImageNet-2012
是否支持微调(Fine-tuning) 否
模块大小 48MB
最新更新日期 -
数据指标 -

该模块基于 SE-ResNet 结构,在 ImageNet-2012 数据集上完成训练,可对尺寸为 224×224×3 的输入图像进行 1000 类分类预测。从源码看,模块类 SEResNet18vdImageNet 的元信息定义于 module.py,其摘要为 "SE_ResNet18_vd is a image classfication model, this module is trained with imagenet datasets",模块类型为 CV/image_classification,版本为 1.1.0,由 paddlepaddle 团队发布。

需要注意的是,原 README 中"基于 Res2Net"的表述与模块实际采用的 SE-ResNet 结构存在出入,本文以源码中的 @moduleinfo 声明与模块名 se_resnet18_vd_imagenet 为准。SE-ResNet 是在 ResNet 基础上引入 Squeeze-and-Excitation(SE)注意力机制的网络变体,通过显式建模通道间的相互依赖关系来提升表示能力。

环境依赖与模块安装

1、环境依赖

使用该模块前需要确保满足以下依赖:

  • paddlepaddle >= 1.6.2:底层深度学习框架(PaddleHub Serving 与 Inference 推理均依赖 PaddlePaddle 的 inference API,见下文源码分析);
  • paddlehub >= 1.6.0:模块管理与推理框架,安装指引可参考 PaddleHub 安装文档。

需要说明的是,安装文档 中针对当前仓库配套的 PaddleHub 版本建议了更高要求:操作系统支持 Windows/Mac/Linux,Python >= 3.6.2,PaddlePaddle >= 2.0.0,并推荐使用 pip install paddlehub==2.1.0 安装。实际使用时建议以仓库 requirements.txt 与安装文档的最新要求为准,以兼容当前 PaddlePaddle 与 PaddleHub 版本。

2、模块安装

通过 PaddleHub 命令行安装模块:

$ hub install se_resnet18_vd_imagenet

安装过程遇到问题时可参考对应平台的快速上手文档:Windows_Quickstart | Linux_Quickstart | Mac_Quickstart。

从 PaddleHub 命令行工具文档 可知,hub install 默认将模块安装到 ${HUB_HOME}/.paddlehub/modules 目录(未设置 ${HUB_HOME} 时使用 $HOME),安装完成后即可通过其他命令或 Python API 调用该模块。

模块 API 预测

1、命令行预测

安装完成后,可直接通过 hub run 命令对单张图片进行分类预测:

$ hub run se_resnet18_vd_imagenet --input_path "/PATH/TO/IMAGE"

--input_path 用于指定待分类图片路径。命令行的完整使用说明参见 PaddleHub Command Line Instruction。

该命令的执行链路在源码中有清晰对应:模块类中的 @runnable 装饰方法 run_cmd 定义了命令行入口(module.py),它通过 argparse 注册了三个参数——--use_gpu(默认 False)、--batch_size(默认 1)、--top_k(默认 1),以及输入参数 --input_path,最终调用 self.classification(paths=[args.input_path], ...) 完成预测。这说明命令行方式实际等价于以 paths 方式调用 classification API,且命令行默认不使用 GPU。

2、预测代码示例

在 Python 中以 API 方式调用模块:

import paddlehub as hub
import cv2

classifier = hub.Module(name="se_resnet18_vd_imagenet")
result = classifier.classification(images=[cv2.imread('/PATH/TO/IMAGE')])
# or
# result = classifier.classification(paths=['/PATH/TO/IMAGE'])

两种传参方式的差别在于:images 接收的是 numpy 数组(BGR 颜色空间),而 paths 接收的是图片文件路径。在 data_feed.py 的 reader 生成器中可以看到,paths 分支会校验文件是否真实存在(不存在则触发 AssertionError),而 images 分支会将 ndarray 通过 Image.fromarray(im[:, :, ::-1]) 转回 PIL 图像——注意这里做了 BGR 到 RGB 的通道反转。

仓库自带的 test.py 给出了对应的单元测试:test_classification1 与 test_classification2 分别验证 paths 与 images 两种调用方式,并对一张狗图片断言预测结果中包含 Pembroke 且概率大于 0.5;test_classification4 验证传入不存在的路径会抛出 AssertionError;test_classification5 验证以字符串列表作为 images 会抛出 TypeError。这些用例可以直接作为该模块的验收参考。

3、classification API 详解

def classification(images=None,
                   paths=None,
                   batch_size=1,
                   use_gpu=False,
                   top_k=1):

参数说明:

  • images(list[numpy.ndarray]):图像数据列表,每个 ndarray 的形状为 [H, W, C],颜色空间为 BGR;
  • paths(list[str]):图像路径列表;
  • batch_size(int):批大小,控制每次送入推理引擎的图片数量,默认 1;
  • use_gpu(bool):是否使用 GPU 进行预测;若使用 GPU,必须先设置 CUDA_VISIBLE_DEVICES 环境变量;
  • top_k(int):返回概率最高的前 k 个分类结果,默认 1。

返回值:

  • res(list[dict]):分类结果列表,每个元素为一个 dict,key 为标签名称,value 为对应概率。

上述参数语义在 module.py 的 classification 实现中得到了完整验证:

  • 当 use_gpu=True 时,若环境变量 CUDA_VISIBLE_DEVICES 未正确设置,会抛出 RuntimeError 提示;GPU 推理通过 Config.enable_use_gpu(memory_pool_init_size_mb=1000, device_id=0) 配置 1000MB 显存池;
  • batch_size 通过 np.ceil(total_num / batch_size) 计算批次数,并对不足一批的尾数做了容错处理;
  • 预测器(predictor)在首次调用时通过 _set_config() 惰性初始化,使用 PaddlePaddle Inference 的 create_predictor 加载 .pdmodel 与 .pdiparams 模型文件,并默认 disable_gpu() 构建 CPU 预测器,同时依据 CUDA_VISIBLE_DEVICES 判断是否额外构建 GPU 预测器。

底层推理流程(源码级):

完整调用链可分为三个阶段:

  1. 预处理(data_feed.py 的 process_image):先将图像短边缩放到 256(resize_short,使用 LANCZOS 插值),再从中心裁剪出 224×224 区域(crop_image,center=True);若图像非 RGB 则转换颜色空间;最后转为 float32、除以 255 归一化,并按 ImageNet 数据集的均值/标准差做标准化(mean = 0.485, 0.456, 0.406],std = [0.229, 0.224, 0.225])。模块类中的 get_expected_image_width/get_expected_image_height 也印证了输入尺寸固定为 224×224([module.py);
  2. 推理:将预处理后的批数据通过 input_handle.copy_from_cpu 送入 predictor 并执行 predictor.run();
  3. 后处理(processor.py 的 postprocess):对网络输出逐样本执行 softmax 得到各类别概率,按概率降序取前 top_k 个,再通过 label_list.txt(共 1000 行,对应 ImageNet 1000 类标签,格式为 "标签名, 别名")将索引映射为标签名,最终组装为 {label: probability} 形式的 dict。

Server 部署(PaddleHub Serving)

PaddleHub Serving 可以将该图像分类模块一键部署为在线服务,方便以 HTTP 接口形式对外提供分类能力。

Step 1:启动 PaddleHub Serving

运行如下命令启动服务:

$ hub serving start -m se_resnet18_vd_imagenet

服务启动后默认监听 8866 端口,该默认值在 serving.py 与 serving.py 中均有定义(self.args_config.get('port', 8866) 与 --port 参数默认值),也支持通过 -p/--port 参数自定义端口。

NOTE: 若使用 GPU 进行预测,需在启动服务前设置 CUDA_VISIBLE_DEVICES 环境变量;否则无需设置。

Step 2:发送预测请求

服务启动后,可通过 HTTP POST 请求完成图片分类:

import requests
import json
import cv2
import base64

def cv2_to_base64(image):
    data = cv2.imencode('.jpg', image)[1]
    return base64.b64encode(data.tostring()).decode('utf8')

# Send an HTTP request
data = {'images':[cv2_to_base64(cv2.imread("/PATH/TO/IMAGE"))]}
headers = {"Content-type": "application/json"}
url = "http://127.0.0.1:8866/predict/se_resnet18_vd_imagenet"
r = requests.post(url=url, headers=headers, data=json.dumps(data))

# print prediction results
print(r.json()["results"])

请求流程说明:客户端先将图片以 base64 字符串编码放入 images 字段并序列化为 JSON,POST 到 /predict/se_resnet18_vd_imagenet 端点;服务端收到请求后,由模块中的 @serving 装饰方法 serving_method 处理(module.py),它调用 processor.py 中的 base64_to_cv2 将 base64 字符串解码还原为 cv2 图像(cv2.imdecode),再交由 classification 完成推理,最后返回分类结果。

版本发布说明

版本 说明
1.0.0 首次发布
1.1.0 移除 Fluid API

若需要安装指定版本,可通过带版本号的安装命令完成:

$ hub install se_resnet18_vd_imagenet==1.1.0

当前仓库中模块的 @moduleinfo 声明的版本即为 1.1.0(module.py),与发布说明中的最新版本一致。在 PaddlePaddle 2.x 时代,PaddleHub 模块普遍采用基于 Inference 的 create_predictor 推理方式(本模块即如此),不再依赖已废弃的 Fluid API。

延伸阅读

  • 若要深入了解该模块的推理细节与测试方法,可继续阅读仓库中的 module.py、processor.py、data_feed.py 与 test.py;
  • PaddleHub 命令行工具的完整命令说明见 cmd_usage.rst;
  • 如需在本地将模块导出为独立推理模型(save_inference_model),可参考 test.py 中 test_save_inference_model 的用法:导出后生成 model.pdmodel 与 model.pdiparams 两个文件,可直接供 PaddlePaddle Inference 加载使用。
登录后查看全文
PaddleFormers