GPEN推理脚本参数详解：输入输出自定义配置实战教程
你是不是也遇到过这样的情况：下载了一个看起来很厉害的人像修复模型，双击运行却卡在命令行参数上？明明只想要把一张旧照片变清晰，结果被--input、--output、--size、--channel一堆参数绕得晕头转向？别急，这篇教程就是为你写的——不讲原理、不堆术语，只说怎么用、怎么改、怎么避免踩坑。
本文聚焦GPEN人像修复增强模型镜像中的核心推理脚本inference_gpen.py，带你从“只会跑默认示例”升级到“完全掌控输入输出路径、尺寸、格式和处理逻辑”。无论你是刚接触AI图像修复的新手，还是想批量处理客户照片的设计师，只要你会复制粘贴命令，就能立刻上手定制化修复流程。
1. 镜像环境与脚本定位：先搞清“我在哪，代码在哪”
在开始调参数之前，得先确认自己站在哪块“地盘”上。本镜像不是裸装PyTorch，而是一套为GPEN量身打造的即用型推理环境——所有依赖已预装、路径已固化、权重已就位。你不需要再 pip install、不用配 CUDA 版本、更不用手动下载模型文件。
1.1 环境关键信息速查
| 组件 | 版本 | 说明 |
|---|---|---|
| 核心框架 | PyTorch 2.5.0 | 支持最新算子，兼容性好 |
| CUDA 版本 | 12.4 | 适配 RTX 40 系列及 A100/H100 显卡 |
| Python 版本 | 3.11 | 兼容主流科学计算库 |
| 推理代码根目录 | /root/GPEN | 所有.py脚本、配置、测试图都在这里 |
小提醒：所有命令都默认在
/root/GPEN目录下执行。如果你不小心切到了其他路径，记得先cd /root/GPEN再操作，否则会提示No module named 'basicsr'或找不到inference_gpen.py。
1.2 推理脚本在哪里？它长什么样？
打开终端，输入：
ls -l inference_gpen.py你会看到这个文件真实存在。它不是封装好的黑盒，而是一个结构清晰、注释友好的 Python 脚本——你可以随时用nano或vim打开它看一眼（虽然本教程不建议新手直接改源码，但知道它可读、可查，心里就有底）。
它的本质是：接收你给的图片，调用 GPEN 模型做前向推理，再把修复后的结果存成新文件。而控制“怎么给”、“怎么存”、“存成什么样”的开关，就是我们接下来要拆解的命令行参数。
2. 参数全景图：每个选项到底管什么？
inference_gpen.py支持 9 个常用命令行参数。我们不按字母顺序罗列，而是按你实际使用的频率和重要性排序，从最常改的开始讲起。
2.1 最核心三件套：-i/--input、-o/--output、--size
这三项是你每天必碰的“铁三角”，它们决定了：修哪张图、修完存哪、修多大。
| 参数 | 短名 | 长名 | 类型 | 默认值 | 实际作用 | 小白一句话理解 |
|---|---|---|---|---|---|---|
-i | --input | 字符串 | ./Solvay_conference_1927.jpg | 指定你要修复的原始图片路径 | “我要修这张图” | |
-o | --output | 字符串 | output_Solvay_conference_1927.png | 指定修复后图片保存路径和文件名 | “修完放这儿，叫这个名字” | |
--size | — | 整数 | 512 | 控制模型内部处理分辨率（非输出尺寸） | “让模型用多大‘脑容量’来想这张图” |
实操演示：一次改全三个
假设你有一张名为family_old.jpg的老照片，想修复成高清 PNG，存为family_enhanced.png，并让模型以 1024 分辨率精细处理：
python inference_gpen.py -i ./family_old.jpg -o ./family_enhanced.png --size 1024注意：
--size不等于最终图片宽高！它只是模型内部特征图的尺度。输出图尺寸 = 原图尺寸（等比例缩放后对齐到--size的倍数）。所以原图是 800×600，输出仍是 800×600，只是细节更锐利。- 如果不加
-o，脚本会自动在原图名前加output_并改为.png；如果原图不在当前目录，必须写相对或绝对路径（如../photos/old.jpg）。
2.2 输出控制组：--channel、--save_face、--aligned
这三个参数决定“修出来的图，到底包含什么内容”。
| 参数 | 类型 | 默认值 | 作用说明 | 使用建议 |
|---|---|---|---|---|
--channel | 字符串 | "rgb" | 指定输出通道模式："rgb"（彩色）、"yuv"（亮度+色度分离，适合后续视频处理）、"gray"（灰度） | 日常修复选"rgb"即可；做风格迁移预处理可试"yuv" |
--save_face | 布尔开关 | False | 是否单独保存检测出的人脸区域（裁剪后+放大） | 强烈推荐开启！修复后能额外得到一张高清人脸特写，用于证件照、头像等场景 |
--aligned | 布尔开关 | False | 是否跳过人脸检测与对齐，直接处理整图（适用于已对齐的正脸图） | 如果你的图全是标准证件照，加这个能提速 20% |
组合实战：既要全身图，也要高清脸
python inference_gpen.py -i ./portrait.jpg -o ./enhanced_full.png --save_face --channel rgb运行后，你会得到两个文件：
enhanced_full.png：整张修复后的照片enhanced_full_face.png：仅人脸区域的高清裁剪版（自动居中、放大、去畸变）
2.3 进阶控制项：--model_path、--device、--half
这些参数面向有特定需求的用户，日常使用频率较低，但关键时刻能救命。
| 参数 | 类型 | 默认值 | 关键用途 | 什么情况下需要改？ |
|---|---|---|---|---|
--model_path | 字符串 | 自动查找缓存路径 | 手动指定.pth权重文件位置 | 镜像里预装的是 512 版本；你想换 1024 版本模型时才需指定 |
--device | 字符串 | "cuda" | 指定运行设备："cuda"、"cpu"、"cuda:0"（多卡时选卡） | GPU 显存不足报 OOM 时，临时切"cpu"跑通流程；或想测试 CPU 推理速度 |
--half | 布尔开关 | False | 启用 FP16 半精度推理 | 显存紧张时必开！RTX 3060（12G）以下显卡建议始终加上，速度提升 30%，显存占用减半 |
显存告急？一招解决
python inference_gpen.py -i ./big_group_photo.jpg -o ./group_fixed.png --half --device cuda提示：
--half和--device cuda必须同时使用才生效。单独加--half会报错。
3. 输入自定义实战：支持哪些图？怎么准备最省事？
GPEN 对输入图的要求其实很友好，但有几个“隐形门槛”容易被忽略，导致运行失败或效果打折。
3.1 格式与尺寸：没那么娇气，但有最佳实践
| 项目 | 支持情况 | 建议做法 | 原因 |
|---|---|---|---|
| 格式 | .jpg,.jpeg,.png,.bmp | 优先用.jpg（体积小、加载快） | .png无损但体积大，加载慢；.webp不支持 |
| 尺寸 | 无硬性上限，但 > 3000px 宽高会显著变慢 | 单边 ≤ 2000px 为佳 | 模型内部会 resize 到--size，过大图只是徒增预处理时间 |
| 色彩空间 | RGB 图像（非 CMYK、Lab） | 用 Photoshop 或convert转 RGB | CMYK 图导入后颜色异常，Lab 图会报错 |
| 人脸数量 | 支持多张人脸 | 无需手动裁剪，脚本自动检测 | GPEN 是端到端人脸修复，不是单脸模型 |
一键批量转格式 + 降尺寸（Linux/macOS）
# 把当前目录所有 PNG 转 JPG，并限制最长边为 1800px mogrify -format jpg -resize "1800x1800>" *.png # 删除原 PNG（谨慎！先备份） rm *.png3.2 特殊场景处理：模糊、严重遮挡、低光照怎么办？
GPEN 本身不负责“去模糊”或“补全缺失区域”，它专注在已有结构基础上增强细节与纹理。因此：
- 轻度模糊、噪点、轻微划痕：效果极佳，是它的主战场
- 运动模糊严重、大面积马赛克、五官被手/帽子遮挡超 50%：建议先用其他工具（如 Topaz DeNoise AI）做预处理，再送入 GPEN
- ❌纯黑/过曝区域、完全缺失的眼睛/嘴唇：GPEN 无法无中生有，会生成不自然的伪影
真实体验：我们用一张手机拍的老年合影（300dpi 扫描件，带泛黄+轻微抖动）测试，开启
--size 1024 --save_face --half，32 秒完成，输出图皮肤纹理清晰可见，连老人手背的皱纹都更立体了——但照片右下角被茶杯挡住的半张脸，修复后仍是模糊色块，未强行“脑补”。
4. 输出自定义实战：不只是改文件名
很多人以为-o只是改个名字，其实它还能帮你实现批量命名、分类保存、格式转换三大实用功能。
4.1 批量处理：用 Shell 循环搞定 100 张图
假设你有 100 张老照片放在./old_photos/目录下，想全部修复并存到./enhanced/，且保持原名（只是后缀变.png）：
mkdir -p ./enhanced for img in ./old_photos/*.jpg; do basename=$(basename "$img" .jpg) python inference_gpen.py -i "$img" -o "./enhanced/${basename}.png" --size 512 --half done进阶技巧：想让每张图都附带高清人脸特写？只需在循环里加--save_face，脚本会自动为每张图生成_face.png文件。
4.2 分类保存：按质量/用途自动建文件夹
你想把修复结果按“标准版”和“高清人脸版”分开存放？用--output配合路径即可：
# 标准修复图存这里 python inference_gpen.py -i ./photo.jpg -o ./output/standard/photo_enhanced.png # 同时生成高清人脸，存到另一文件夹 python inference_gpen.py -i ./photo.jpg -o ./output/face/photo_face.png --save_face4.3 格式自由切换：PNG 保真，JPG 省空间
GPEN 默认输出 PNG（无损），但如果你要发微信、传邮件，JPG 更友好：
# 输出 JPG，质量设为 95（0-100） python inference_gpen.py -i ./input.jpg -o ./output.jpg --quality 95注意：
--quality参数需配合.jpg后缀使用，否则无效。PNG 不支持质量压缩。
5. 常见问题直击：那些报错信息到底在说什么？
我们整理了 5 个最高频报错，附带一句话原因 + 一行解决命令，拒绝百度半小时。
| 报错信息（截取） | 原因 | 一行解决 |
|---|---|---|
OSError: [Errno 2] No such file or directory: './my_photo.jpg' | 输入路径错了，文件根本不存在 | ls ./my_photo.jpg确认路径；用pwd看当前目录 |
RuntimeError: CUDA out of memory | 显存不够，尤其--size 1024时 | 加--half --device cuda，或降--size到256 |
ModuleNotFoundError: No module named 'facexlib' | 没激活环境！conda 环境未生效 | conda activate torch25再运行 |
ValueError: Unsupported image mode 'CMYK' | 图片是印刷用 CMYK 模式 | convert input.jpg -colorspace RGB output.jpg（ImageMagick） |
AttributeError: 'NoneType' object has no attribute 'shape' | 图片损坏或人脸未检出 | 换一张图；或加--aligned（跳过检测，强制处理） |
终极排错口诀：先看路径，再看环境，接着显存，最后格式。90% 的问题按这个顺序查，3 分钟内解决。
6. 总结：你现在已经掌握的 7 个关键能力
回顾一下，通过这篇教程，你不再需要靠猜、靠试、靠搜报错，而是真正拥有了对 GPEN 推理流程的掌控力：
- 精准定位：清楚知道镜像里代码在哪、环境在哪、权重在哪；
- 参数破译：明白
-i、-o、--size这三个核心参数的真实作用，不再被文档绕晕； - 输出定制：能生成全身图 + 高清人脸双版本，还能指定通道与格式；
- 批量处理：用几行 Shell 命令搞定几十张图，告别手动点鼠标；
- 显存管理：遇到 OOM 不慌，
--half一加，立马跑通； - 输入预判：知道什么图效果好、什么图要预处理、什么图根本别试；
- 错误归因：看到报错第一反应是“路径？环境？显存？格式？”，而不是复制粘贴搜答案。
下一步，你可以尝试把这套参数逻辑迁移到其他图像修复模型（如 CodeFormer、GFPGAN），因为它们的命令行设计思路高度一致。真正的工程能力，从来不是记住多少参数，而是理解参数背后的意图。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
