新手必看！GPEN人像修复镜像避坑使用指南
你是不是也遇到过这些情况：翻出老照片想修复，结果卡在环境配置上一整天？下载一堆模型权重却不知道哪个该放哪？运行命令报错，满屏红色文字看得头皮发麻？别急——这篇指南就是为你写的。它不讲原理、不堆参数，只说你真正需要知道的：怎么让GPEN镜像稳稳跑起来，修出清晰自然的人脸，避开90%新手踩过的坑。
我们用的是预装好所有依赖的GPEN人像修复增强模型镜像，不是从零搭环境的原始仓库。这意味着：不用手动装CUDA驱动、不用反复试PyTorch版本兼容性、不用翻墙下模型、更不用改十处路径。但“开箱即用”不等于“闭眼乱按”——镜像里藏着几个关键细节，没注意就会白忙活。下面带你一条一条理清楚。
1. 先搞懂这个镜像到底“装了什么”
很多新手一上来就cd进目录敲python，结果报错ModuleNotFoundError: No module named 'facexlib'，其实问题不在代码，而在没激活环境。这个镜像不是直接用系统Python，而是用conda管理的独立环境，名字叫torch25——它对应PyTorch 2.5.0 + CUDA 12.4 + Python 3.11这套黄金组合。为什么强调这个？因为GPEN对PyTorch版本极其敏感：用2.4会缺算子，用2.6又可能触发新API报错，而镜像里预装的正是经过实测能跑通全部功能的版本。
| 组件 | 版本 | 关键说明 |
|---|---|---|
| 核心框架 | PyTorch 2.5.0 | 必须激活torch25环境才能调用，否则所有依赖都不可见 |
| CUDA 版本 | 12.4 | 镜像已适配NVIDIA驱动470+，旧显卡需确认是否支持 |
| Python 版本 | 3.11 | numpy<2.0等限制已内置，无需额外降级 |
| 推理代码位置 | /root/GPEN | 所有操作必须在此目录下进行，路径写错会找不到模型 |
你可能会问：“为什么不用pip装而用conda？”答案很实在：facexlib和basicsr这两个库在pip安装时容易因编译器版本不匹配导致人脸检测失败或超分结果发虚，而conda环境已预编译好二进制包，启动即稳定。另外提醒一句：镜像里没装Jupyter，别浪费时间找.ipynb文件——它是个纯命令行推理镜像，专注快、准、稳。
2. 三步走通：从启动到出图，不绕弯路
别被文档里一堆命令吓住。实际用起来就三步：激活环境 → 进入目录 → 运行脚本。每一步都有坑，我们挨个填平。
2.1 激活环境：这一步漏掉，后面全白干
打开终端第一件事，不是cd，不是python，而是：
conda activate torch25验证是否成功？输入python --version，看到Python 3.11.x；再输python -c "import torch; print(torch.__version__)"，输出2.5.0。如果显示Command 'conda' not found，说明你没用镜像自带的shell（比如误点了Ubuntu原生终端），请重启镜像并确保进入的是预配置环境。
避坑提示：千万别用
source activate torch25，这是旧版conda语法，镜像里会报错；也别试图用pip install torch覆盖——会破坏环境一致性，导致facexlib人脸对齐失准，修复后眼睛歪斜、嘴角变形。
2.2 进入正确目录：路径错一个字符，模型就找不到
激活环境后，立刻执行：
cd /root/GPEN注意：是/root/GPEN，不是/home/user/GPEN，也不是/root/gpen（小写）。镜像里只有这一个标准路径，里面包含：
inference_gpen.py：主推理脚本（别去碰demo.py，那是原始仓库的，镜像已优化替换）weights/：预置模型权重文件夹（含GPEN-BFR-512等核心模型）examples/：测试图片存放目录（含经典的Solvay_conference_1927.jpg）
如果你把照片放在/root/my_photo.jpg，却在命令里写--input my_photo.jpg，脚本会去当前目录找，找不到就报错File not found。正确做法是写绝对路径：--input /root/my_photo.jpg，或者先把照片复制进/root/GPEN/examples/imgs/再用相对路径。
2.3 运行推理：参数怎么选，效果差十倍
镜像里的inference_gpen.py比原始demo.py更轻量，参数精简为最常用三个：
# 最简命令：直接跑默认测试图（Solvay会议照） python inference_gpen.py # 修自己的照片（推荐！自动适配尺寸，不拉伸不变形） python inference_gpen.py --input /root/my_photo.jpg # 指定输出名（避免覆盖，方便批量处理） python inference_gpen.py -i /root/photo1.jpg -o repaired_1.png重点说说参数逻辑：
--input（或-i）：必须是完整路径，镜像不支持相对路径查找--output（或-o）：不指定时默认生成output_原文件名.png，注意是PNG格式，即使输入是JPG- 没有
--model参数？因为镜像已默认加载GPEN-BFR-512，这是平衡速度与质量的最佳选择。想换模型？得手动改inference_gpen.py第32行的model_path，新手不建议。
真实效果对比：我们用一张模糊的老年证件照测试。默认参数输出后，皱纹细节清晰、肤色均匀、无塑料感；若错误加上
--use_sr --sr_scale 2（镜像已禁用该参数），反而出现边缘锯齿和发色失真。记住：镜像的默认配置=实测最优解，乱加参数=自找麻烦。
3. 图片怎么放？模型在哪？这些细节决定成败
新手最容易栽在“文件位置”上。镜像里所有路径都是硬编码的，错一点就中断。我们画张简图说清数据流向：
你的照片 → 放进 /root/GPEN/examples/imgs/ （推荐） ↓ 推理脚本读取 → 自动调用 /root/GPEN/weights/GPEN-BFR-512.pth ↓ 修复结果 → 保存在 /root/GPEN/ （同级目录，不是子文件夹！）所以操作前，请先做这两件事：
- 整理照片：把要修的图统一放到
/root/GPEN/examples/imgs/。支持JPG、PNG、BMP，单张大小建议<5MB（太大显存溢出）。 - 确认模型存在：运行
ls /root/GPEN/weights/，应看到GPEN-BFR-512.pth等文件。如果为空，说明镜像下载不完整，需重拉。
常见报错及解法：
OSError: [Errno 2] No such file or directory: 'weights/GPEN-BFR-512.pth'
→ 进入/root/GPEN/，执行wget https://public-vigen-video.oss-cn-shanghai.aliyuncs.com/robin/models/GPEN-BFR-512.pth -P weights/cv2.error: OpenCV(4.9.0) ... error: (-215:Assertion failed) ...
→ 照片分辨率太高（>2000px），用convert -resize 1500x /root/my_photo.jpg /root/my_photo_small.jpg先缩放RuntimeError: CUDA out of memory
→ 显存不足，加参数--batch_size 1（默认是4），或换小图测试
4. 效果不好？先别怪模型，检查这四点
修出来的图发灰、五官错位、背景糊成一片？90%不是GPEN不行，而是输入或设置有问题。按顺序快速排查：
4.1 照片本身是否适合GPEN？
GPEN专为人脸设计，对以下情况效果打折：
- 适合：正面/微侧脸、光照均匀、人脸占画面1/3以上、无严重遮挡（如口罩、墨镜）
- ❌慎用：全身照（只修脸，身体不管）、多人合影（默认只修最大人脸）、逆光剪影（检测不到五官）、艺术滤镜图（颜色失真干扰对齐）
实测案例：一张逆光拍摄的毕业照，修复后皮肤惨白、眼窝发黑。解决方案？用手机相册“自动增强”调亮后再输入，效果立竿见影。
4.2 有没有意外开启“超分”模式？
原始GPEN支持超分，但镜像默认关闭——因为超分会放大噪声，老照片本就颗粒多，越修越糊。如果你在命令里加了--use_sr，立刻删掉。专注“修复”而非“放大”，才是GPEN的强项。
4.3 输出格式是否被误判？
镜像强制输出PNG，但有些设备预览PNG会偏色。用eog（Eye of GNOME）或gthumb打开，别用系统默认图片查看器。或者转成JPG验证：
convert output_my_photo.png output_my_photo.jpg4.4 是否期待过高？
GPEN不是魔法棒。它能恢复模糊、轻微划痕、低分辨率缺失的细节，但无法凭空生成闭着的眼睛、补全被裁掉的半张脸、或修复烧毁的照片。合理预期：让一张“能看清五官”的旧照，变成“能看清毛孔和发丝”的高清照，这就已经是巨大提升。
5. 进阶技巧：让修复效果更自然、更可控
当你跑通基础流程，可以试试这几个小技巧，效果提升明显：
5.1 批量处理：一次修100张，不用重复敲命令
把所有照片放进/root/GPEN/examples/imgs/，然后执行：
for img in /root/GPEN/examples/imgs/*.jpg; do filename=$(basename "$img" .jpg) python inference_gpen.py -i "$img" -o "/root/GPEN/output_${filename}.png" done输出全部集中在/root/GPEN/，用ls output_*一眼看齐。
5.2 局部微调：只修脸，不动背景
GPEN默认修复整张图。如果背景是重要信息（如风景、文字），加参数--only_face（需确认镜像已集成，若报错则跳过）。更稳妥的方法：用GIMP或Photopea先抠出人脸，保存为PNG（透明背景），再喂给GPEN——修复后合成回原图，背景零失真。
5.3 色彩校正：修复后肤色太黄/太白？
镜像输出是sRGB色彩空间，但老照片常是Adobe RGB。用ImageMagick一键校正：
convert output_my_photo.png -profile /usr/share/color/icc/colord/sRGB.icc corrected.png6. 总结：新手上路，记住这五句话
你不需要成为深度学习专家，也能用好GPEN镜像。最后用五句大白话收尾，建议截图保存：
- 第一句：永远先
conda activate torch25，这是钥匙，丢了打不开任何门。 - 第二句：照片放
/root/GPEN/examples/imgs/，命令里写--input examples/imgs/xxx.jpg，路径宁可多写不省略。 - 第三句：别加
--use_sr、--model等多余参数，默认就是最佳配置。 - 第四句：修不好先看照片——正面、清晰、人脸够大，这三点不满足，换模型也没用。
- 第五句：输出在
/root/GPEN/，文件名带output_前缀，用ls命令确认生成成功再关机。
现在，关掉这篇指南，打开终端，敲下那三行命令。三分钟后，你会看到一张焕然一新的脸——不是AI幻觉，是真实存在的细节，正从时光里浮现出来。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
