GPEN模型输入输出规范说明：文件格式与分辨率要求

本镜像基于GPEN人像修复增强模型构建，预装了完整的深度学习开发环境，集成了推理及评估所需的所有依赖，开箱即用。

1. 镜像环境说明

组件	版本
核心框架	PyTorch 2.5.0
CUDA 版本	12.4
Python 版本	3.11
推理代码位置	`/root/GPEN`

主要依赖库：

facexlib: 用于人脸检测与对齐
basicsr: 基础超分框架支持
opencv-python,numpy<2.0,datasets==2.21.0,pyarrow==12.0.1
sortedcontainers,addict,yapf

2. 快速上手

2.1 激活环境

在使用GPEN模型前，请先激活对应的Conda环境：

conda activate torch25

该环境已预配置好所有必要的Python包和CUDA驱动支持，确保推理过程稳定运行。

2.2 模型推理 (Inference)

进入模型主目录并调用推理脚本：

cd /root/GPEN

推理命令示例

GPEN提供灵活的命令行接口，支持多种输入输出方式。以下是典型使用场景：

# 场景 1：运行默认测试图 # 输出将保存为: output_Solvay_conference_1927.png python inference_gpen.py

此命令会加载内置测试图像Solvay_conference_1927.jpg并执行人像增强处理。

# 场景 2：修复自定义图片 # 输出将保存为: output_my_photo.jpg python inference_gpen.py --input ./my_photo.jpg

用户可将待处理图像上传至容器，并通过--input参数指定路径。

# 场景 3：直接指定输出文件名 # 输出将保存为: custom_name.png python inference_gpen.py -i test.jpg -o custom_name.png

支持使用-i（或--input）和-o（或--output）参数分别设置输入源与输出目标。

注意：所有输出结果默认保存在项目根目录下，文件名以output_开头或由用户显式指定。

3. 输入文件格式要求

为了保证GPEN模型能够正确解析并高效处理输入图像，需遵循以下输入规范。

3.1 支持的图像格式

GPEN目前支持以下常见无损/有损压缩格式：

.jpg/.jpeg（推荐）
.png
.bmp
.tiff（部分高位深图像可能需要额外转换）

OpenCV作为底层图像读取引擎，理论上支持其兼容的所有格式，但建议优先使用.jpg或.png格式以避免兼容性问题。

3.2 图像内容要求

必须包含清晰可识别的人脸区域：GPEN专为人像设计，对非人脸图像效果不佳。
建议人脸占据画面比例不低于1/4：过小的人脸可能导致细节恢复不完整。
避免严重遮挡或极端姿态：如侧脸角度超过60°、戴墨镜、口罩覆盖等会影响对齐与重建质量。

3.3 分辨率建议与限制

GPEN支持多尺度推理，但不同分辨率对应不同的处理策略和性能表现。

分辨率范围	处理模式	是否推荐	说明
< 256x256	上采样后处理	⚠️ 不推荐	图像太小导致信息缺失，修复效果有限
256x256 ~ 512x512	直接高保真增强	✅ 强烈推荐	最佳平衡点，细节丰富且速度较快
512x512 ~ 1024x1024	分块融合增强	✅ 推荐	自动分块处理，适合高清证件照或艺术写真
> 1024x1024	分块+降采样预处理	⚠️ 谨慎使用	可能引入拼接伪影，建议裁剪后再处理

实际操作建议

对于超高分辨率图像（如4K照片），建议先进行中心裁剪或人脸区域提取，再送入模型处理，以提升效率和一致性。

4. 输出结果规范

4.1 默认输出行为

若未指定-o参数，系统将自动生成输出文件名，规则如下：

output_{原文件名}.{扩展名}

例如：

输入portrait.jpg→ 输出output_portrait.jpg
输入family.png→ 输出output_family.png

4.2 输出图像格式

输出格式默认与输入保持一致。若输入为.jpg，则输出也为.jpg；若输入为.png，则保留PNG无损特性。

提示：若希望强制输出为特定格式，可在调用脚本前手动更改输出文件扩展名，如：
python inference_gpen.py -i input.jpg -o result.png

此时即使输入是JPG，输出也将保存为PNG格式。

4.3 输出分辨率说明

GPEN的输出分辨率取决于输入尺寸和所选模型版本：

模型版本	放大倍数	典型输出分辨率
GPEN-256	×1	256×256
GPEN-512	×1	512×512
GPEN-1024	×2	1024×1024（基于512输入）

实际输出尺寸遵循“输入决定基准，模型决定增强能力”的原则。例如：

输入 400×400 → 使用GPEN-512模型 → 自动缩放到512×512进行增强
输入 800×800 → 使用GPEN-1024模型 → 分块处理后合并为约1600×1600高清图像

5. 已包含权重文件

为保障离线可用性和快速部署，镜像内已预下载并缓存全部必要模型权重。

5.1 权重存储路径

所有模型文件均通过ModelScope平台自动加载，缓存于以下路径：

~/.cache/modelscope/hub/iic/cv_gpen_image-portrait-enhancement

包含组件：

Generator (G)：主生成网络，负责纹理重建与细节增强
Face Detection Model：基于RetinaFace的人脸检测器
Landmark Alignment Model：68点关键点定位模块，用于精准对齐

5.2 离线推理保障

即使在网络受限环境下，只要首次运行过推理脚本，后续无需联网即可完成全部处理任务。

警告：请勿删除~/.cache/modelscope目录，否则下次运行时将重新下载（约1.2GB）。

6. 常见问题

6.1 如何准备训练数据？

GPEN采用监督式训练方式，需成对的高质量（HQ）与低质量（LQ）人像图像。

推荐构建流程：

使用FFHQ等公开高清人脸数据集作为HQ源
应用BSRGAN、RealESRGAN等退化模型生成对应的LQ图像
按照{dataset}/hq/*.jpg和{dataset}/lq/*.jpg结构组织数据集

6.2 训练配置建议

若需微调模型，建议从以下参数入手：

# train_config.yaml 示例片段 resolution: 512 batch_size: 8 lr_g: 0.0001 # 生成器学习率 lr_d: 0.00005 # 判别器学习率 total_epochs: 200

训练脚本位于/root/GPEN/train.py，可通过修改配置文件启动训练任务。

6.3 性能优化技巧

GPU显存不足？：降低批量大小或启用--tile模式进行分块推理
输出有拼接痕迹？：增加重叠区域（tile_overlap），建议设为64~128像素
人脸偏移？：检查是否启用了--aligned参数（适用于已对齐图像）

7. 参考资料

官方仓库：yangxy/GPEN
魔搭社区地址：iic/cv_gpen_image-portrait-enhancement

8. 引用 (Citation)

@inproceedings{yang2021gpen, title={GAN-Prior Based Null-Space Learning for Consistent Super-Resolution}, author={Yang, Tao and Ren, Peiran and Xie, Xuansong and Zhang, Lei}, booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)}, year={2021} }