无需手动下载权重：GPEN镜像预置模型缓存路径说明-开发者社区

无需手动下载权重：GPEN镜像预置模型缓存路径说明

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

1. 镜像环境说明

该镜像为GPEN人像修复任务提供了完整、稳定且高性能的运行环境。所有核心组件均经过严格版本控制与兼容性测试，确保用户在不同硬件平台上均可实现无缝部署和高效推理。

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

1.1 主要依赖库解析

facexlib: 提供人脸检测（dlib或RetinaFace）与关键点对齐功能，是前置处理的关键模块。
basicsr: 超分辨率基础框架，支持数据加载、模型定义与训练流程管理。
opencv-python,numpy<2.0: 图像读取与数值计算基础库，限制numpy版本以避免与旧版依赖冲突。
datasets==2.21.0,pyarrow==12.0.1: 支持大规模图像数据集的高效加载与缓存。
sortedcontainers,addict,yapf: 辅助工具库，分别用于有序容器管理、字典对象增强和代码格式化。

此环境通过Conda虚拟环境隔离，避免包依赖污染，可通过指定命令激活使用。

2. 快速上手

2.1 激活环境

启动容器后，首先激活预配置的深度学习环境：

conda activate torch25

该环境已包含所有必需依赖，无需额外安装即可执行后续操作。

2.2 模型推理 (Inference)

进入推理代码目录：

cd /root/GPEN

推理模式一：运行默认测试图

若未指定输入文件，脚本将自动加载内置测试图像（Solvay_conference_1927.jpg），适用于快速验证环境是否正常工作。

python inference_gpen.py

输出结果将保存为：output_Solvay_conference_1927.png

推理模式二：修复自定义图片

将待修复图像上传至项目目录（如./my_photo.jpg），并执行以下命令：

python inference_gpen.py --input ./my_photo.jpg

输出文件命名为：output_my_photo.jpg

推理模式三：自定义输入输出路径

支持通过-i和-o参数显式指定输入输出路径，提升调用灵活性：

python inference_gpen.py -i test.jpg -o custom_name.png

输出将保存为：custom_name.png

注意：所有推理结果默认保存在项目根目录下，建议定期备份重要输出。

推理效果示例：

3. 已包含权重文件

为保障“开箱即用”体验，本镜像已预下载并缓存全部必要模型权重，彻底免除用户手动下载的繁琐流程。

3.1 权重缓存路径

所有模型权重均通过ModelScope（魔搭）平台下载，并存储于标准缓存路径中：

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

该路径下包含以下核心模型组件：

生成器权重（Generator Checkpoint）：pretrained_models/GPEN-BFR-512.pth
人脸检测模型：基于RetinaFace的轻量级检测器
关键点对齐模型：用于精准定位五大人脸关键点（双眼、鼻尖、嘴角）

3.2 缓存机制优势

离线可用：即使在无网络环境下，仍可正常执行推理任务。
避免重复下载：每次运行不会重新拉取模型，显著提升启动效率。
路径标准化：遵循ModelScope官方规范，便于后期扩展其他模型集成。

提示：若需查看具体文件结构，可使用如下命令浏览缓存内容：
ls ~/.cache/modelscope/hub/iic/cv_gpen_image-portrait-enhancement/pretrained_models/

4. 常见问题

4.1 数据集准备

GPEN采用监督式训练方式，需提供高质量-低质量图像对作为训练样本。推荐构建策略如下：

原始数据源：使用FFHQ（Flickr-Faces-HQ）等公开高清人脸数据集作为高质量基准。
降质方法：利用RealESRGAN、BSRGAN等退化模型模拟模糊、噪声、压缩等真实退化过程，生成对应的低质量图像。
配对组织：按文件名一一对应存放于high_res/与low_res/目录中，便于DataLoader读取。

4.2 训练流程说明

尽管本镜像主要面向推理场景，但仍保留完整训练能力。如需微调或从头训练，请参考以下步骤：

准备好训练数据对目录；
修改配置文件中的dataroot_gt（高清图路径）与dataroot_lq（低清图路径）；
设置目标分辨率（建议512×512）；
调整优化器参数（如生成器学习率设为2e-4，判别器为1e-4）；
执行训练脚本：

python train_gpen.py --config configs/train_gpen_512.json

训练过程中可借助TensorBoard监控损失变化与生成效果。

5. 参考资料

官方GitHub仓库：yangxy/GPEN
包含完整代码、训练细节与模型架构设计文档。
魔搭社区模型页面：iic/cv_gpen_image-portrait-enhancement
提供在线体验、API调用接口及权重下载服务。
相关论文：GAN-Prior Based Null-Space Learning for Consistent Super-Resolution
发表于CVPR 2021，阐述GPEN核心技术原理。

6. 引用 (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} }