PaddleHub HRNet40 图像分类模型实战：从命令行预测到 Fine-tune 与 Serving 部署-平芜编程栈

人工智能
预训练
微调
模型推理服务

【免费下载链接】PaddleFormers

PaddleFormers is an easy-to-use library of pre-trained large language model zoo based on PaddlePaddle.

项目地址：https://gitcode.com/gh_mirrors/pa/PaddleFormers

本文以 PaddleHub 开源仓库中的hrnet40_imagenet图像分类模块（模块文档）为核心，系统讲解 HRNet 高分辨率网络的模型结构、环境安装、命令行与 Python API 预测、基于 Flowers 数据集的 Fine-tune 全流程，以及 PaddleHub Serving 服务化部署。读完本文，你将掌握在 PaddlePaddle 2.0 + PaddleHub 2.0 环境下，完整走通"加载预训练模型 → 数据预处理 → 微调训练 → 最优模型保存 → 在线服务部署"的端到端图像分类实战链路。

一、模型基本信息

hrnet40_imagenet是 PaddleHub 提供的图像分类预训练模块，核心信息如下：

项目	内容
模型名称	hrnet40_imagenet
类别	图像-图像分类
网络	HRNet
数据集	ImageNet-2012
是否支持 Fine-tuning	是
模型大小	333MB
指标	-
最新更新日期	2021-09-14
当前版本	1.0.0

HRNet（High-Resolution Net）是微软亚洲研究院在 2019 年提出的神经网络结构。与之前"先下采样提取深层语义、再恢复分辨率"的传统卷积网络不同，HRNet 在整个网络深层阶段依然保持高分辨率特征图的并行计算，因此输出的关键点热图在空间位置上更加精确。这种"全程保持高分辨率"的特性，使得它在对空间分辨率敏感的视觉任务（如关键点检测、目标检测、语义分割）中同样表现突出。

从仓库源码看，module.py 中通过@moduleinfo装饰器注册了该模块，type="CV/classification"，summary明确说明该模块使用 ImageNet 数据集训练，类别标签列表见 label_list.txt（共 1000 类，即 ImageNet-2012 标准类别）。

二、HRNet40 网络结构与源码实现解析

2.1 高分辨率多分支并行架构

在 module.py 的HRNet40类中，网络宽度self.width = 40，并通过self.channels字典定义了不同宽度（18/30/32/40/44/48/60/64）对应的分支通道数。对于 width=40：

第 2 阶段通道数：[40, 80]
第 3 阶段通道数：[40, 80, 160]
第 4 阶段通道数：[40, 80, 160, 320]

同时，num_modules_2, num_modules_3, num_modules_4 = 1, 4, 3表示第 2/3/4 阶段分别堆叠 1、4、3 个 HighResolutionModule。整个前向流程（forward）为：

两个 stride=2 的 3×3 卷积（conv_layer1_1、conv_layer1_2）对输入降采样；
Layer1堆叠 4 个 BottleneckBlock 提取初始特征；
依次经过tr1/st2、tr2/st3、tr3/st4三个"TransitionLayer + Stage"组合，逐步将单分支扩展为 2、3、4 个并行高分辨率分支；
分类头LastClsOut对各分支做 Bottleneck 处理，并通过cls_head_conv_list逐级融合多尺度特征；
经过 1×1 卷积、全局平均池化后，由nn.Linear(2048, class_dim)输出分类 logits。

2.2 核心组件的底层实现

从源码结构看，HRNet40 由以下可复用组件组成，各组件在 module.py 中均有对应实现：

ConvBNLayer：卷积 + BatchNorm 组合层，卷积默认不带 bias，BatchNorm 负责激活（act="relu"或None）；
BasicBlock/BottleneckBlock：标准残差块，支持downsample短接与可选的 SE 注意力模块（has_se，本模型未启用，self.has_se = False）；
Branches：并行分支，每个分支独立堆叠block_num=4个 BasicBlock；
FuseLayers：多分辨率特征融合层，高分辨率分支通过F.upsample(..., mode="nearest")上采样与低分辨率分支对齐相加，低分辨率分支通过 stride=2 卷积逐步降采样后相加；
HighResolutionModule：一个"分支计算 + 特征融合"的完整模块；
Stage：多个 HighResolutionModule 的顺序堆叠。

这种"多分支并行 + 反复跨分辨率融合"的设计，正是 HRNet 能在深层保持高分辨率特征的关键，也是它与 ResNet 等串行下采样网络的本质区别。

三、环境依赖与模块安装

3.1 环境依赖

使用hrnet40_imagenet需要满足以下版本要求：

paddlepaddle >= 2.0.0
paddlehub >= 2.0.0

3.2 安装模块

执行以下命令安装模块：

$ hub install hrnet40_imagenet

若安装过程中遇到问题，可参考仓库内的零基础安装文档：

零基础 Windows 安装
零基础 Linux 安装
零基础 MacOS 安装

四、模型 API 预测

4.1 命令行预测

hub run命令通过 paddlehub/commands/run.py 中的RunCommand实现：它加载指定 Module，调用被@runnable装饰的run_cmd方法（见 cv_module.py），该方法会解析--input_path与--top_k两个参数并执行预测：

$ hub run hrnet40_imagenet --input_path "/PATH/TO/IMAGE" --top_k 5

参数说明：

--input_path：待预测图片的路径（必填）；
--top_k：返回置信度最高的前 k 个分类结果，默认值为 1。

4.2 Python 代码预测

import paddle import paddlehub as hub if __name__ == '__main__': model = hub.Module(name='hrnet40_imagenet') result = model.predict(['flower.jpg'])

predict方法定义在 cv_module.py 的ImageClassifierModule中，其内部流程为：

将模型切换为 eval 模式，并在paddle.no_grad()下推理；
对输入图像依次执行模块内置的transforms预处理；
前向得到 logits 后经F.softmax转为概率；
通过np.argsort(preds)[:, ::-1][:, :top_k]取出 Top-k 类别索引，并映射为self.labels中的类别名称；
返回形如[{'类别名': 概率值}, ...]的字典列表。

其中transforms在 module.py 中定义，与 Fine-tune 阶段保持一致（Resize 256 → CenterCrop 224 → 按 ImageNet 均值/方差归一化）。

五、基于 Flowers 数据集进行 Fine-tune

在完成 PaddlePaddle 与 PaddleHub 安装后，执行python train.py即可使用hrnet40_imagenet对 Flowers 数据集进行 Fine-tune。完整代码参考 demo/image_classification/train.py（该示例默认使用resnet50_vd_imagenet_ssld，将name替换为hrnet40_imagenet即可无缝切换）。下面按四步拆解。

Step 1：定义数据预处理方式

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数据增强模块（实现见 paddlehub/vision/transforms.py）提供了丰富的数据预处理方式，用户可按需替换：

T.Compose：按顺序组合多个预处理算子；to_rgb=True表示将 OpenCV 读入的 BGR 图像转为 RGB，channel_first默认为 True，最终输出[C, H, W]布局；
T.Resize((256, 256))：将图像缩放到 256×256，支持NEAREST/LINEAR/CUBIC/AREA/LANCZOS4/RANDOM等插值模式，默认LINEAR；
T.CenterCrop(224)：从图像中心裁剪出 224×224 区域；
T.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])：使用 ImageNet 数据集的均值与标准差做标准化，与该预训练模型的训练分布保持一致。

Step 2：下载数据集并使用

from paddlehub.datasets import Flowers flowers = Flowers(transforms) flowers_validate = Flowers(transforms, mode='val')

参数说明：

transforms：数据预处理方式；
mode：数据模式，可选项有train、test、val，默认为train。

Flowers数据集的实现见 paddlehub/datasets/flowers.py：它是一个 5 分类花卉数据集（num_classes = 5），通过@download_data装饰器在首次使用时自动从网络下载并解压到用户目录下的$HOME/.paddlehub/dataset目录（源码中对应hubenv.DATA_HOME下的flower_photos目录），随后按train_list.txt/test_list.txt/validate_list.txt读取样本路径与标签。

Step 3：加载预训练模型

model = hub.Module(name="hrnet40_imagenet", label_list=["roses", "tulips", "daisy", "sunflowers", "dandelion"])

参数说明：

name：预训练模型的名字，即hrnet40_imagenet；
label_list：设置输出分类类别，默认为 ImageNet-2012 的 1000 类（对应 label_list.txt）；传入自定义列表后，模型最后的全连接层输出维度会动态调整为len(label_list)。

加载时，module.py 会从模块目录加载预训练权重model.pdparams；若指定了load_checkpoint参数，则优先加载该路径下的微调权重。

Step 4：选择优化策略和运行配置

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)

优化策略：PaddlePaddle 2.0 提供了SGD、Adam、Adamax等多种优化器，其中Adam常用参数：

learning_rate：全局学习率，默认 1e-3；
parameters：待优化的模型参数。

运行配置：Trainer主要控制 Fine-tune 的训练（实现见 paddlehub/finetune/trainer.py），包含以下可控制参数：

参数	说明
`model`	被优化模型，必须是`paddle.nn.Layer`实例
`optimizer`	优化器选择
`use_gpu`	是否使用 GPU 训练（设为 True 时调用`paddle.set_device('gpu')`）
`use_vdl`	是否使用 VisualDL 可视化训练过程（默认 True，日志写入`checkpoint_dir/visualization`）
`checkpoint_dir`	保存模型参数的地址，未指定时默认为`ckpt_<时间戳>`
`compare_metrics`	保存最优模型的衡量指标比较方法；默认取验证指标字典第一个 key，越大越好

trainer.train主要控制具体的训练过程，参数如下：

参数	说明
`train_dataset`	训练时所用的数据集
`epochs`	训练轮数
`batch_size`	训练的批大小，使用 GPU 时请根据显存实际情况调整
`num_workers`	数据加载子进程数量，默认为 0
`eval_dataset`	验证集；设置后每个`save_interval`轮执行一次评估
`log_interval`	打印日志的间隔，单位为执行的批训练次数（默认 10）
`save_interval`	保存模型的间隔频次，单位为训练轮数（默认 10）

从 trainer.py 的实现可以看到：每个 epoch 结束时若满足save_interval条件，Trainer 会先对验证集执行evaluate，再通过compare_metrics判断当前验证指标是否优于历史最优；若更优，则将模型权重与优化器状态保存到${checkpoint_dir}/best_model，同时记录metrics.pkl。每个 epoch 的 checkpoint（model.pdparams+model.pdopt）也会按轮保存，断点续训时_load_checkpoint会自动恢复最近一轮的状态。训练日志（loss、acc、lr、ETA）由logger.train输出，并同步写入 VisualDL。

模型预测（加载 Fine-tune 结果）

Fine-tune 完成后，验证集上表现最优的模型保存在${CHECKPOINT_DIR}/best_model目录下（${CHECKPOINT_DIR}为训练时选择的 checkpoint 目录）。使用该模型预测的脚本（参考 demo/image_classification/predict.py）如下：

import paddle import paddlehub as hub if __name__ == '__main__': model = hub.Module(name='hrnet40_imagenet', label_list=["roses", "tulips", "daisy", "sunflowers", "dandelion"], load_checkpoint='/PATH/TO/CHECKPOINT') result = model.predict(['flower.jpg'])

NOTE：预测时使用的 module、checkpoint_dir、dataset 必须与 Fine-tune 时保持一致，否则类别映射与权重维度不匹配会导致预测错误。

六、服务部署：PaddleHub Serving

PaddleHub Serving 可以将hrnet40_imagenet部署为一个在线分类任务服务，整体分两步完成。

第一步：启动 PaddleHub Serving

$ hub serving start -m hrnet40_imagenet

执行该命令即完成分类任务服务化 API 的部署，默认端口号为8866。

NOTE：如使用 GPU 预测，需要在启动服务之前设置CUDA_VISIBLE_DEVICES环境变量，否则无需设置。

第二步：发送预测请求

服务端配置完成后，以下代码即可发送预测请求并获取结果：

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/hrnet40_imagenet" r = requests.post(url=url, headers=headers, data=json.dumps(data)) data = r.json()["results"]['data']

服务端处理逻辑由 cv_module.py 中被@serving装饰的serving_method承担：它接收 base64 编码的图片列表，解码为 BGR 图像后调用predict（支持top_k参数），并将每个类别的概率统一转换为float后封装进{'data': ...}返回给客户端。

七、更新历史

1.0.0：初始发布。

八、延伸阅读

图像分类 Fine-tune 通用流程文档：docs/docs_ch/finetune/image_classification.md
自定义数据集接入指南：docs/docs_ch/finetune/customized_dataset.md
训练器实现：paddlehub/finetune/trainer.py
数据集实现：paddlehub/datasets/flowers.py
数据预处理算子：paddlehub/vision/transforms.py

本仓库modules/image/classification目录下还提供了大量可直接替换的 ImageNet 预训练分类模块（如 resnet、mobilenet、efficientnet、resnext、hrnet 全系列等），只需将hub.Module(name=...)中的模型名替换即可复用本文介绍的完整流程。