学术研究利器：GPEN复现实验环境搭建详细步骤-育师

学术研究利器：GPEN复现实验环境搭建详细步骤

你是不是也遇到过这样的情况：论文里看到一个惊艳的人像修复效果，想复现却卡在环境配置上？下载权重、编译CUDA、调试依赖……一通操作下来，半天过去了，连第一张图都没跑出来。别急，这次我们不讲原理、不堆参数，就用最直白的方式，带你把 GPEN 这个学术圈公认靠谱的人像增强模型，从镜像拉起、到跑通推理、再到理解怎么用，一步到位。

这不是一份“理论上可行”的教程，而是一份我在实验室真实踩过坑、调过参、修过报错后整理出来的实操笔记。全程不需要你手动装 PyTorch、不用翻墙下模型、更不用对着报错信息百度两小时——所有麻烦事，镜像已经替你干完了。

下面我们就从“打开就能用”开始，手把手搭好你的学术研究小工作站。

1. 镜像到底装了什么？一句话说清

先别急着敲命令，咱们先把底子摸清楚：这个 GPEN 镜像不是简单打包了个代码，而是为你配齐了一整套“开箱即用”的科研工作台。它就像一台预装好专业软件的笔记本电脑，插电就能写论文。

你拿到的不是一个空壳，而是一个已经调好所有齿轮的精密仪器。核心组件版本明确、路径固定、依赖完整，没有隐藏的兼容性雷区。我们来看这张表，它比任何文字描述都更实在：

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

再补充几个关键点，帮你快速建立认知：

facexlib不是可有可无的插件，它是 GPEN 能精准定位眼睛、鼻子、嘴巴的前提——人脸对齐不准，后面所有增强都是空中楼阁；
basicsr是超分领域的“瑞士军刀”，GPEN 的生成器结构、损失函数、数据加载逻辑，都深度依赖它；
所有 Python 包版本都经过实测匹配，比如numpy<2.0和datasets==2.21.0这些看似琐碎的约束，其实是为避免 PyTorch 2.5 下的 tensor 兼容问题和数据集读取崩溃。

换句话说，你不用再花三天时间去查“为什么 facexlib 报错找不到 face_detector”，也不用纠结“PyTorch 2.4 和 CUDA 12.2 能不能混用”。这些，镜像已经替你验证过了。

2. 三步跑通第一张修复图：不绕弯、不跳步

很多教程喜欢从“安装conda”开始，但咱们不走那条老路。既然镜像已经准备好，那就直接进入最让你有成就感的环节：看到修复效果。

2.1 激活专属环境

镜像里预装了多个 conda 环境，GPEN 使用的是专为其优化的torch25环境。执行这一行，就完成了环境切换：

conda activate torch25

你不需要记住这个环境名，只需要知道：这是为 GPEN 量身定制的运行空间，里面所有库的版本、编译选项、甚至 CUDA 的加载方式，都已对齐。

2.2 进入代码主目录

所有操作都在/root/GPEN下进行，这是镜像为你设定的“主战场”：

cd /root/GPEN

这里就是你接下来所有命令的起点。别担心路径记不住，复制粘贴就行。

2.3 三种推理方式，总有一种适合你

GPEN 的推理脚本inference_gpen.py设计得非常友好，支持三种常用场景，我们一个个来试：

场景 1：零输入，跑默认测试图（最快验证）

这是最省心的方式，不用准备任何图片，直接看效果：

python inference_gpen.py

运行完成后，你会在当前目录下看到一张名为output_Solvay_conference_1927.png的图片。这个名字有点长，但它背后是一张经典历史照片——1927年索尔维会议合影。GPEN 就是用这张图来验证自己能否清晰还原百年前模糊人像的细节。

场景 2：修复你自己的照片（最实用）

把你想修复的照片（比如一张手机拍的旧照）上传到镜像的/root/GPEN/目录下，假设文件名叫my_photo.jpg，然后执行：

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

输出会自动命名为output_my_photo.jpg，保存在同一目录。注意：--input后面跟的是相对路径，./表示当前目录。

场景 3：自定义输出名（最灵活）

如果你希望结果文件名更直观，或者要批量处理多张图，可以用-i和-o参数组合：

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

这样，无论输入文件叫什么，输出永远是你指定的名字。这对写论文时整理实验结果特别有用——你可以把不同参数下的输出分别命名为result_lr.png、result_hr.png，一目了然。

小提示：所有输出图片都默认保存在/root/GPEN/目录下，无需额外指定路径。如果你在 Jupyter 或 WebIDE 中操作，刷新左侧文件树就能立刻看到新生成的图片。

3. 权重文件在哪？离线也能跑

学术研究最怕什么？网络突然断掉，模型下载一半失败，或者服务器限速到 1KB/s。这个镜像早就考虑到了。

所有必需的权重文件，都已经提前下载并存放在本地缓存中，路径非常明确：

ModelScope 缓存路径：~/.cache/modelscope/hub/iic/cv_gpen_image-portrait-enhancement

这个路径下包含三类关键模型：

主生成器（Generator）：负责从低质输入重建高质人脸，是 GPEN 的“大脑”；
人脸检测器（Face Detector）：快速框出图像中所有人脸区域，避免背景干扰；
关键点对齐器（Landmark Aligner）：精确定位68个面部关键点，确保修复时五官比例自然。

这意味着：你完全可以在无网环境下完成全部推理任务。即使你是在图书馆临时借的电脑、或在没有公网的校内服务器上做实验，只要镜像启动成功，就能立刻开始工作。

如果你好奇这些文件有多大，可以进缓存目录看看：

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

你会发现，核心权重文件generator.pth大约 120MB，整个缓存目录加起来不到 200MB。相比动辄几个GB的训练数据集，这点空间占用几乎可以忽略。

4. 想自己训练？这些准备你得知道

镜像主打“开箱即用”，所以默认只提供推理能力。但如果你是研究生、博士生，正需要基于 GPEN 做算法改进或对比实验，那训练环节也得心里有数。

4.1 数据准备：不是随便找几张图就行

GPEN 是监督式学习模型，它的训练目标很明确：给一张模糊/低质人脸，输出一张清晰/高质人脸。所以你需要的不是单张图，而是成对的数据（pair）。

官方推荐使用FFHQ（Flickr-Faces-HQ）数据集作为高清源。它包含 7 万张高质量人脸图像，分辨率统一为 1024×1024。

但 FFHQ 只是“高清端”，你还得生成对应的“低质端”。常见做法是用已有模型对高清图做“降质”：

用RealESRGAN添加真实感噪声与模糊；
用BSRGAN模拟手机拍摄中的压缩失真；
或者简单用 OpenCV 的cv2.GaussianBlur+cv2.resize模拟老照片退化。

重点来了：不要用 JPEG 二次压缩这种“假低质”。GPEN 对退化类型很敏感，训练时用的退化方式，必须和你实际想解决的问题一致。比如你要修复监控截图，就该用运动模糊+低分辨率模拟；要是修复扫描老照片，就得加颗粒+褪色。

4.2 训练启动：三步走，不碰底层代码

镜像里其实已经预留了训练入口，只是没默认启用。你只需按顺序做三件事：

准备数据对路径：把高清图放在datasets/ffhq/hr/，对应低质图放在datasets/ffhq/lr/；
修改配置文件：编辑options/train_gpen.yml，调整scale: 1（表示 1× 超分，即修复）、num_gpu: 1（单卡训练）、lr_G: 2e-4（生成器学习率）等关键项；
启动训练：运行python train.py -opt options/train_gpen.yml。

整个过程不需要改模型结构、不重写数据加载器。你真正要花时间的，是调参和观察 loss 曲线——而这，才是科研的核心。

5. 遇到问题？先看这三条

在实验室反复部署的过程中，我总结出新手最容易卡住的三个点，它们比报错信息本身更重要：

问题一：“ModuleNotFoundError: No module named 'facexlib'”
别急着 pip install。先确认是否激活了torch25环境（conda env list查看星号），再检查是否误入了其他 Python 环境。镜像里 facexlib 是通过 conda 安装的，pip 安装可能版本冲突。
问题二：推理输出图是全黑/全灰/只有半张脸
这大概率是输入图里没人脸，或者人脸太小、角度太偏。GPEN 对输入有一定要求：人脸需占画面 1/3 以上，正面或微侧脸最佳。试试用test.jpg（镜像自带的测试图）先跑通，再换自己的图。
问题三：GPU 显存爆了（CUDA out of memory）
默认配置是按 12GB 显存设计的。如果你用的是 8GB 卡，只需在推理命令后加--bs 1（batch size 设为 1），或者在配置里把crop_size从 512 改成 384，显存占用立刻下降 40%。

这些问题，都不是模型不行，而是使用姿势不对。就像一把好刀，用对地方才能切菜，拿去砍树就容易崩口。