PaddleHub 人脸动漫化实践：UGATIT_83w 图像风格转换模块安装、预测与 Serving 部署全指南

本指南以 PaddleHub 仓库中的 UGATIT_83w 模块（README_en.md）为核心，系统讲解基于 U-GAT-IT 网络的人脸到动漫风格转换模块的环境安装、Python API 调用、参数语义、底层推理实现以及基于 PaddleHub Serving 的在线服务部署。读完本文，你将能够在 PaddlePaddle/PaddleHub 环境下独立完成该风格转换模型的本地预测与 HTTP 服务化调用。

一、模块基本信息

UGATIT_83w 是 PaddleHub 提供的一个图像风格转换模块，其核心能力是把输入的人脸照片转换为动漫风格。模块基本信息如下表：

项目	说明
Module Name	UGATIT_83w
Category	Image editing（图像编辑）
Network	U-GAT-IT
Dataset	selfie2anime
Fine-tuning supported or not	否（不支持微调）
Module Size	41MB
Latest update date	2021-02-26
Data indicators	-

从命名可以看出，仓库中还存在同系列模型 UGATIT_92w 与 UGATIT_100w（见 style_transfer 目录），三者网络结构、数据集与模型大小一致，区别主要在于训练步数/迭代轮次对应的权重版本，读者可按需选用。由于该模块不支持 Fine-tuning，使用方式以直接加载预训练权重进行推理为主。

二、环境依赖与安装

1. 环境依赖

运行 UGATIT_83w 需要满足以下最低版本要求：

• paddlepaddle >= 1.8.2
• paddlehub >= 1.8.0

其中 PaddleHub 提供了模块加载、推理封装与 Serving 服务化能力，PaddlePaddle 则提供底层算力执行环境。若在安装 PaddleHub 或本模块过程中遇到环境配置问题，可参考仓库内的分平台零基础安装文档：Windows 快速开始 | Linux 快速开始 | Mac 快速开始。

2. 模块安装

使用 PaddleHub 命令行工具一键安装：

$ hub install UGATIT_83w

安装成功后，即可在 Python 中通过 hub.Module(name='UGATIT_83w') 加载该模块。如需回退到历史版本（如 1.0.0），可参考同系列模块文档中的指定版本安装方式 hub install UGATIT_83w==1.0.0。

三、模块 API 预测

1. 预测代码示例

import cv2
import paddlehub as hub

model = hub.Module(name='UGATIT_83w', use_gpu=False)
result = model.style_transfer(images=[cv2.imread('/PATH/TO/IMAGE')])
# or
# result = model.style_transfer(paths=['/PATH/TO/IMAGE'])

要点说明：

• cv2.imread 读入的图像通道顺序为 BGR，ndarray 形状为 [H, W, C]；
• images 与 paths 两种传参方式二选一：images 直接传解码后的 ndarray 列表，paths 传本地图片路径列表；
• use_gpu 控制推理设备，默认 False 使用 CPU。

2. style_transfer API 详解

def style_transfer(
    self,
    images=None,
    paths=None,
    batch_size=1,
    output_dir='output',
    visualization=False
)

该 API 将输入的人脸图像转换为动漫风格，各参数语义如下：

参数	类型	默认值	说明
images	list[numpy.ndarray]	None	图片数据，ndarray.shape 为 [H, W, C]，通道顺序 BGR
paths	list[str]	None	图片路径列表，默认 None
batch_size	int	1	batch 大小
visualization	bool	False	是否将识别结果保存为图片文件
output_dir	str	output	可视化结果图片的保存目录

注意：paths 与 images 必须且只需提供一个作为数据来源。返回结果为 res (list[numpy.ndarray])，每个元素是形状为 [H, W, C] 的输出图像数据。

从源码看，style_transfer 的完整调用链为：module.py 中的 style_transfer 方法 → Processor 数据预处理 → Model.predict 推理 → Processor.postprocess 后处理：

def style_transfer(self, images=None, paths=None, batch_size=1, output_dir='output', visualization=False):
    # 加载数据处理器
    processor = Processor(images, paths, output_dir, batch_size)
    # 模型预测
    outputs = self.model.predict(processor.input_datas)
    # 结果后处理
    results = processor.postprocess(outputs, visualization)
    # 返回结果
    return results

3. 底层实现原理（源码级解析）

为了帮助你理解输入输出约定与调优方向，下面结合模块目录下的三个核心文件展开讲解。

（1）预处理与后处理管线

UGATIT_83w 的预处理与后处理逻辑集中在 processor.py 中：

• 读取数据：load_datas 优先遍历 paths（校验 os.path.isfile 后经 cv2.imread 读取）；若传入了 images 则直接使用 ndarray 列表；
• 预处理（preprocess）：对每张图依次执行 cv2.resize 到 (256, 256) → 归一化 (img / 255.0 - 0.5) / 0.5（即映射到 [-1, 1]）→ 转置为 CHW → np.expand_dims 增加 batch 维。随后按 batch_size 通过 np.array_split 切分输入：

  split_num = len(self.datas) // self.batch_size + 1 if len(self.datas) % self.batch_size != 0 \
              else len(self.datas) // self.batch_size
  input_datas = np.array_split(input_datas, split_num)
  

  因此 batch_size 实际控制的是推理时每个 batch 送入预测器的图片数量；
• 后处理（postprocess）：对模型输出执行 (output * 0.5 + 0.5) * 255. 反归一化 → np.clip(img, 0, 255).astype(np.uint8) 限幅 → 转置回 HWC。当 visualization=True 时，通过 check_dir 确保输出目录存在，并以 {图片id}_{时间戳}.jpg 的命名写入 output_dir：

  cv2.imwrite(os.path.join(self.output_dir, '%d_%d.jpg' % (im_id, time.time())), img)
  

  这也解释了为什么模型输出是 256×256 分辨率的图像——预处理阶段已将所有输入统一缩放到该尺寸。

（2）推理引擎封装

Model 类位于 model.py，基于 Paddle Inference 的 create_predictor 实现：

• 预测器配置：use_gpu=True 时启用 config.enable_use_gpu(100, 0)（显存 100MB、设备 0），并会检查 CUDA_VISIBLE_DEVICES 环境变量是否设置，否则回退到 CPU；CPU 模式默认开启 config.enable_mkldnn() 加速；同时启用了 switch_ir_optim(True) 与 enable_memory_optim() 等推理优化；
• 权重加载：模块以 combined 方式加载，即从模型目录读取 __model__ 与 __params__ 两个文件；
• 预测流程：predict 遍历预处理后的每个 batch，通过输入/输出 handle 完成 copy_from_cpu → predictor.run() → copy_to_cpu，最后用 np.concatenate(outputs, 0) 合并所有 batch 的结果，再交给后处理。

模块入口 module.py 通过 @moduleinfo 声明元信息（name="UGATIT_83w"、type="CV/style_transfer"、version="1.0.1"），并在初始化时把模型目录指向 self.directory 下的 UGATIT_83w 子目录。

四、基于 PaddleHub Serving 的服务化部署

PaddleHub Serving 可将风格转换任务部署为在线服务，对外提供 HTTP API。

第一步：启动 PaddleHub Serving

$ hub serving start -m UGATIT_83w

执行后即完成风格转换在线服务 API 的部署，默认监听端口为 8866。

注意：若使用 GPU 进行预测，需要在启动服务前设置 CUDA_VISIBLE_DEVICES 环境变量（例如 export CUDA_VISIBLE_DEVICES=0）；仅使用 CPU 时无需设置。

Serving 模式下，模块会走 module.py 中的 serving_method：接收 base64 编码的图像 → base64_to_cv2 解码 → 调用 style_transfer 完成转换 → 将结果经 cv2_to_base64 重新编码后返回，从而在 HTTP 层完成图像数据的传输。base64_to_cv2 与 cv2_to_base64 的实现同样位于 processor.py。

第二步：发送预测请求

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

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')


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

# 打印预测结果
print(r.json()["results"])

请求要点：

• 请求体 data 中的 images 字段需为 base64 编码字符串列表；
• URL 路径为 http://127.0.0.1:8866/predict/UGATIT_83w，其中模块名与 URL 中的名称必须一致；
• 响应中的 results 字段为转换后图像的 base64 编码列表，客户端可自行解码保存。

五、版本更新记录

• 1.0.0：初始发布（First release）。

六、延伸阅读与进一步探索

• 模块完整文档：README_en.md
• 模块源码：入口 module.py、推理封装 model.py、数据管线 processor.py
• 同系列模型：UGATIT_92w、UGATIT_100w（style_transfer 目录），可用于对比不同训练版本的效果差异
• 其他图像风格转换模块：如 animegan_v2_* 系列、lapstyle_* 系列、msgnet、stylepro_artistic 等（同目录下可见），可按风格需求替换

需要注意的是，UGATIT_83w 不支持 Fine-tuning，因此无法在该模块基础上进行二次训练；若需要自定义风格迁移训练，建议参考仓库中可微调的风格迁移模型（如 style_transfer 演示 所对应的训练流程）。