PaddleHub 图像分类实战:hrnet48_imagenet_ssld 模型的安装、推理、Fine-tune 与 Serving 部署指南
PaddleHub 图像分类实战:hrnet48_imagenet_ssld 模型的安装、推理、Fine-tune 与 Serving 部署指南
本文是一份围绕 PaddleHub 预训练图像分类模型 hrnet48_imagenet_ssld 的完整技术指南。该模型以微软亚洲研究院提出的高分辨率网络 HRNet 为骨干,在 ImageNet-2012 上预训练,可用于图像分类任务的快速推理、迁移学习(Fine-tune)与在线服务化部署。读完本文,你将掌握该模型的环境安装、命令行/Python API 预测、基于 Flowers 数据集的 Fine-tune 全流程,以及通过 PaddleHub Serving 将模型部署为 HTTP 在线分类服务的完整方法。
一、模型基本信息
hrnet48_imagenet_ssld 是 PaddleHub 提供的图像分类预训练模块,其基本信息如下表所示:
| 模型名称 | hrnet48_imagenet_ssld |
|---|---|
| 类别 | 图像-图像分类 |
| 网络 | HRNet |
| 数据集 | ImageNet-2012 |
| 是否支持 Fine-tuning | 是 |
| 模型大小 | 446MB |
| 指标 | - |
| 最新更新日期 | 2021-09-14 |
模型介绍
HRNet(High-Resolution Net)是微软亚洲研究院在 2019 年提出的全新神经网络。与以往的卷积神经网络不同,该网络在网络的深层依然可以保持高分辨率,因此预测的关键点热图更加准确,空间位置上也更加精确。此外,该网络在其他对分辨率敏感的视觉任务(如目标检测、语义分割)中同样表现突出,图像分类正是其典型应用场景之一。
从源码看网络结构
仓库中该模块的实现位于 modules/image/classification/hrnet48_imagenet_ssld/module.py,核心类为 HRNet48(继承自 paddle.nn.Layer,通过 @moduleinfo 装饰器注册为 PaddleHub 模块,type 为 CV/classification)。从源码可以清晰看到 HRNet48 的典型组织方式:
- 宽度参数:
self.width = 48,通道配置channels字典中 48 对应[[48, 96], [48, 96, 192], [48, 96, 192, 384]],即三个分辨率阶段分别使用 2、3、4 个并行分支。 - 阶段配置:
num_modules_2, num_modules_3, num_modules_4 = 1, 4, 3,配合Stage、TransitionLayer完成分支数量的逐级增加与分辨率保持。 - 基础组件:
ConvBNLayer(卷积 + BatchNorm)、BasicBlock、BottleneckBlock、SELayer(Squeeze-and-Excitation 通道注意力,本模型has_se=False)、HighResolutionModule(多分支并行 +FuseLayers跨分辨率融合)、LastClsOut分类头。 - 前向流程:两次 stride=2 的卷积下采样 →
Layer1→ 三级TransitionLayer + Stage→ 分类头多尺度特征累加 →AdaptiveAvgPool2D→ 全连接层输出类别 logits 与特征向量,forward返回(y, feature)二元组。
分类类别定义在模块目录下的 label_list.txt,共 1000 行,即 ImageNet-2012 的标准类别。若未显式传入 label_list,HRNet48.__init__ 会从该文件读取类别并确定 class_dim。
二、安装
1、环境依赖
使用该模型前,请确保满足以下依赖版本:
- paddlepaddle >= 2.0.0
- paddlehub >= 2.0.0
2、安装模块
通过 PaddleHub 命令行即可安装该预训练模型:
$ hub install hrnet48_imagenet_ssld
如您在安装时遇到问题,可参考各平台的零基础安装文档:零基础Windows安装 | 零基础Linux安装 | 零基础MacOS安装。
三、模型 API 预测
1、命令行预测
安装完成后,可直接通过 hub run 命令对单张图片进行推理:
$ hub run hrnet48_imagenet_ssld --input_path "/PATH/TO/IMAGE" --top_k 5
其中 --input_path 为输入图片路径,--top_k 控制输出前 k 个置信度最高的类别。这两个参数由基类 ImageClassifierModule 在 paddlehub/module/cv_module.py 中通过 run_cmd 方法注册:--top_k 默认值为 1,--input_path 为必填输入。命令执行时会调用 self.predict(images=[args.input_path], top_k=args.top_k),最终返回每个输入图片的分类结果字典。
2、预测代码示例
在 Python 中加载模块并进行预测只需几行代码:
import paddle
import paddlehub as hub
if __name__ == '__main__':
model = hub.Module(name='hrnet48_imagenet_ssld')
result = model.predict(['flower.jpg'])
model.predict 的签名与内部逻辑(见 paddlehub/module/cv_module.py 中 ImageClassifierModule.predict)说明如下:
images:待预测图片列表,元素为 BGR 格式的np.ndarray(也可直接传图片路径,由transforms处理);batch_size:预测批大小,默认 1;top_k:每张图片输出 Top-K 个结果,默认 1;- 推理在
eval()模式与paddle.no_grad()下进行,图片先经过模块内置的transforms预处理(Resize 到 256×256 → CenterCrop 224 → 按 ImageNet 均值方差归一化,to_rgb=True),再经softmax得到概率分布,最后按argsort取前top_k个类别,返回形如[{'daisy': 0.9, ...}]的列表。
3、如何开始 Fine-tune
在完成 PaddlePaddle 与 PaddleHub 安装后,通过执行 python train.py 即可使用 hrnet48_imagenet_ssld 对 Flowers 等数据集进行 Fine-tune。完整的可运行示例可参考 demo/image_classification/train.py(其中将 name 换成 hrnet48_imagenet_ssld 即可无缝切换本模型)。整体分为以下代码步骤:
Step1:定义数据预处理方式
import paddlehub.vision.transforms as T
transforms = T.Compose([T.Resize((256, 256)),
T.CenterCrop(224),
T.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])],
to_rgb=True)
transforms 数据增强模块定义了丰富的数据预处理方式,用户可按照需求替换自己需要的数据预处理方式。这里的参数与模块内置 transforms(见 module.py 中 HRNet48.transforms)保持一致,保证训练与推理时的输入分布一致。
Step2:下载数据集并使用
from paddlehub.datasets import Flowers
flowers = Flowers(transforms)
flowers_validate = Flowers(transforms, mode='val')
transforms:数据预处理方式。mode:选择数据模式,可选项有train、test、val,默认为train。
数据集的准备代码可以参考 paddlehub/datasets/flowers.py。hub.datasets.Flowers() 通过 @download_data 装饰器自动从网络下载 flower_photos.tar.gz 并解压到用户目录下的 $HOME/.paddlehub/dataset 目录。该数据集为 5 分类花卉数据集(num_classes = 5),训练/测试/验证分别对应 train_list.txt、test_list.txt、validate_list.txt。
Step3:加载预训练模型
model = hub.Module(name="hrnet48_imagenet_ssld", label_list=["roses", "tulips", "daisy", "sunflowers", "dandelion"])
name:选择预训练模型的名字,此处为hrnet48_imagenet_ssld。label_list:设置输出分类类别,默认为 Imagenet2012 类别(即模块目录下的label_list.txt)。
传入 label_list 后,源码会根据 len(label_list) 动态调整最后一层全连接输出维度,从而实现迁移学习中的分类头替换。
Step4:选择优化策略和运行配置
optimizer = paddle.optimizer.Adam(learning_rate=0.001, parameters=model.parameters())
trainer = Trainer(model, optimizer, checkpoint_dir='img_classification_ckpt')
trainer.train(flowers, epochs=100, batch_size=32, eval_dataset=flowers_validate, save_interval=1)
- 优化策略:示例选用 Adam 优化器,
learning_rate为全局学习率(示例 0.001),parameters为待优化的模型参数。Paddle 2.0 还提供SGD、Adamax等多种优化器可选。 - 运行配置:
Trainer主要控制 Fine-tune 的训练,包含以下可控制的参数(定义见 paddlehub/finetune/trainer.py):model:被优化模型;optimizer:优化器选择;use_gpu:是否使用 GPU 训练(默认 False,源码中通过paddle.set_device切换设备);use_vdl:是否使用 VisualDL 可视化训练过程(默认 True,会在 checkpoint 目录下创建visualization日志目录);checkpoint_dir:保存模型参数的地址(不指定时默认生成ckpt_<timestamp>目录);compare_metrics:保存最优模型的衡量指标比较函数,默认取验证指标字典的第一个主指标,越大越好。
trainer.train主要控制具体的训练过程,包含以下可控制的参数:train_dataset:训练时所用的数据集;epochs:训练轮数;batch_size:训练的批大小,如果使用 GPU,请根据实际情况调整 batch_size;num_workers:数据加载子进程数量,默认为 0;eval_dataset:验证集,设置后会在每个save_interval轮次执行评估;log_interval:打印日志的间隔,单位为执行批训练的次数(默认 10);save_interval:保存模型的间隔频次,单位为执行训练的轮数(默认 10);collate_fn:自定义 mini-batch 拼接函数,默认对样本各字段按 axis=0 堆叠。
从 trainer.py 的实现看,训练流程为:DistributedBatchSampler(shuffle=True)构造批采样器 → DataLoader 加载数据 → 每步执行 training_step 前向计算损失 → optimizer.step() 更新参数 → clear_gradients() 清零梯度;每个 save_interval 轮次末自动调用 evaluate,若验证指标优于历史最优,则通过 compare_metrics 判定并把最优模型保存到 ${checkpoint_dir}/best_model;同时按 epoch_{n} 目录保存每轮 checkpoint(内含 model.pdparams 与 model.pdopt,另以 metrics.pkl 记录历史最优指标)。
模型预测(Fine-tune 后)
当完成 Fine-tune 后,训练过程在验证集上表现最优的模型会被保存在 ${CHECKPOINT_DIR}/best_model 目录下,其中 ${CHECKPOINT_DIR} 目录为 Fine-tune 时所选择的保存 checkpoint 的目录。我们使用该模型来进行预测,predict.py 脚本如下:
import paddle
import paddlehub as hub
if __name__ == '__main__':
model = hub.Module(name='hrnet48_imagenet_ssld',
label_list=["roses", "tulips", "daisy", "sunflowers", "dandelion"],
load_checkpoint='/PATH/TO/CHECKPOINT')
result = model.predict(['flower.jpg'])
NOTE: 进行预测时,所选择的 module、checkpoint_dir、dataset 必须和 Fine-tune 所用的一样。load_checkpoint 指向的 checkpoint 会被 HRNet48.__init__ 通过 paddle.load 加载并 set_dict 到模型中;若未指定,则默认加载模块目录下的预训练权重 model.pdparams(源码输出 load pretrained checkpoint success)。
四、服务部署
PaddleHub Serving 可以部署一个在线分类任务服务,对外提供 HTTP 接口。
第一步:启动 PaddleHub Serving
运行启动命令:
$ hub serving start -m hrnet48_imagenet_ssld
这样就完成了一个分类任务服务化 API 的部署,默认端口号为 8866。
NOTE: 如使用 GPU 预测,则需要在启动服务之前设置 CUDA_VISIBLE_DEVICES 环境变量,否则不用设置。
服务端采用 Flask(Windows)/ gunicorn(Linux)承载,推理通过 ImageClassifierModule.serving_method 完成:接收 base64 编码的图片列表与 top_k 参数,解码后调用 predict,将结果封装为 {'data': [...]} 返回(见 paddlehub/module/cv_module.py)。
第二步:发送预测请求
配置好服务端,以下代码即可实现发送预测请求、获取预测结果:
import requests
import json
import cv2
import base64
import numpy as np
def cv2_to_base64(image):
data = cv2.imencode('.jpg', image)[1]
return base64.b64encode(data.tostring()).decode('utf8')
def base64_to_cv2(b64str):
data = base64.b64decode(b64str.encode('utf8'))
data = np.fromstring(data, np.uint8)
data = cv2.imdecode(data, cv2.IMREAD_COLOR)
return data
# 发送HTTP请求
org_im = cv2.imread('/PATH/TO/IMAGE')
data = {'images': [cv2_to_base64(org_im)], 'top_k': 2}
headers = {"Content-type": "application/json"}
url = "http://127.0.0.1:8866/predict/hrnet48_imagenet_ssld"
r = requests.post(url=url, headers=headers, data=json.dumps(data))
data = r.json()["results"]['data']
请求体中的 images 为 base64 编码的图片列表,top_k 指定返回置信度最高的类别数量;响应中 results.data 即为分类结果。相关请求处理逻辑可进一步参考 paddlehub/serving/http_server.py。
五、更新历史
- 1.0.0:初始发布(2021-09-14)。
使用提示:以上所有命令与代码均面向当前仓库对应的 PaddleHub 2.0+ 版本体系,运行前请确认 paddlepaddle >= 2.0.0 与 paddlehub >= 2.0.0 已正确安装;若需在自定义数据集上进行迁移学习,只需按 Step2 替换数据集,并同步调整 Step3 中的 label_list 与最后一层分类维度即可。