简介：本资源为基于Python深度学习框架的GFPGAN图片修复算法实现源码，面向具备一定Python编程与深度学习基础、关注图像修复与生成对抗网络应用的开发者与研究者，可用于老旧照片修复、面部图像增强及数字取证等场景的研究与二次开发。压缩包共62个文件，约6.22MB，以26个py源码文件为核心，涵盖模型架构、训练与推理脚本；辅以8个yml与2个yaml配置、5个md文档、7个png与2个jpg示例图片，以及pth权重、mdb数据集、txt说明等，目录结构清晰，便于按模块查阅。目前已有430人学习下载。源码完整呈现GFPGAN的生成器与判别器实现、StyleGAN2与ArcFace等网络结构、预训练模型加载及推理流程，并附FAQ、对比说明与论文模型文档，可帮助读者快速理解算法原理、复现修复效果并在此基础上调整细节，适配不同图像处理需求。
1. 拿到 GFPGAN 源码包先别急着跑：这套 64 文件工程到底能修什么
很多人第一次接触人脸修复，是拿一张模糊的老照片丢进在线工具，几秒钟出来一张「磨皮磨到亲妈都不认识」的图。GFPGAN 想解决的恰恰是另一个问题：在把低分辨率、有噪点、有压缩伪影的人脸放大并修复的同时，尽量保住人物身份特征，而不是生成一张「看起来像人但换了个人」的脸。这套源码包就是 GFPGAN 的完整工程实现，用 Python 写，基于深度学习里的生成对抗网络思路，核心是 26 个 Python 源文件加 8 个 YAML 配置，覆盖了从模型结构定义、训练脚本到推理入口的全链路。
它适合谁？如果你手上有老旧照片、监控截图、低质量头像需要批量修复，或者你在做图像修复方向的二次开发、想改网络结构、想换训练数据，这份源码能直接给你一个可跑的基线。但如果你只是想找个开箱即用的修图软件，那它需要你先配好 Python 深度学习环境，门槛不算低。下面我按「先看懂工程结构、再跑通推理、最后避坑和进阶」的顺序拆一遍，尽量让你少走弯路。
2. 工程结构与模型选型：26 个 Python 文件是怎么分工的
2.1 目录骨架与关键文件定位
拿到压缩包解压后，先别打开inference_gfpgan.py就运行。花五分钟把目录结构过一遍，后面排错会快很多。这套工程大致分四块：推理入口、模型定义、训练配置、测试与工具脚本。
根目录下最该先看的是这几个：
inference_gfpgan.py：推理主入口，负责读图、调模型、写结果。setup.py/requirements.txt：依赖声明，环境装不上多半卡在这。gfpgan/：核心包，模型和工具都在这。options/：训练用的 YAML 配置，推理一般用不到，但改模型行为时会看。experiments/：测试配置和测试数据，验证环境是否装对很有用。scripts/：辅助脚本，比如模型格式转换、关键点解析。
进到gfpgan/里面，结构是这样的：
gfpgan/ ├── __init__.py ├── utils.py ├── data/ │ └── ffhq_degradation_dataset.py ├── models/ │ └── gfpgan_model.py └── archs/ ├── gfpganv1_clean_arch.py ├── gfpganv1_arch.py ├── gfpgan_bilinear_arch.py ├── stylegan2_clean_arch.py ├── stylegan2_bilinear_arch.py ├── arcface_arch.py └── restoreformer_arch.pyarchs/是重点。gfpganv1_arch.py是主网络结构，stylegan2_clean_arch.py是生成器的骨干，arcface_arch.py负责身份特征提取，restoreformer_arch.py是另一条修复分支。理解这几个文件的关系，比死记参数有用得多。
2.2 为什么是 StyleGAN2 + ArcFace 这套组合
GFPGAN 的生成器骨干用的是 StyleGAN2 的干净版结构，判别器和身份约束则借了 ArcFace 的思路。选型逻辑不复杂：StyleGAN2 在生成高分辨率、纹理自然的人脸图上已经被验证过，它的风格调制机制能把「结构」和「纹理」解耦，修复时先保证五官位置对，再补细节。而单纯用 GAN 做修复最大的风险是身份漂移——修完不像本人了。ArcFace 提取的身份向量作为约束加进损失里，等于给生成器套了个「别改太多」的缰绳。
常见做法是：生成器输出修复图，同时把修复图和原图都过一遍 ArcFace 拿身份特征，算一个身份损失，再叠加像素级重建损失和对抗损失。这套组合在gfpganv1_arch.py里能对应上，你读代码时会看到几个 loss 相关的分支。
提示：如果你只是做推理，不需要完全吃透损失函数；但如果你要微调模型，身份损失这一块是必须看懂的，否则很容易训出「好看但不像」的结果。
2.3 推理前必须确认的三件事
在敲命令之前，先确认三件事，能省掉后面一半的报错。
第一，Python 版本。这套工程对版本敏感，建议 3.8 到 3.10 之间，太新或太旧都可能在某些依赖上翻车。第二，深度学习框架。工程依赖 PyTorch，装的时候注意和你的显卡驱动、CUDA 版本匹配，CPU 也能跑但慢到怀疑人生。第三，预训练权重。源码包里experiments/pretrained_models/目录是放权重的地方，但权重文件通常不随源码一起分发，需要你单独准备，否则推理脚本会直接报找不到模型。
# 建议先建独立环境，别污染系统 Python conda create -n gfpgan python=3.9 -y conda activate gfpgan # 装依赖，requirements.txt 里锁了版本，别手动乱升 pip install -r requirements.txt # 确认 PyTorch 能识别到 GPU python -c "import torch; print(torch.__version__, torch.cuda.is_available())"这段命令的逻辑很直白：先隔离环境，再按锁定的依赖装，最后验证框架和显卡。参数上唯一要改的是python=3.9，如果你机器上已有合适版本可以换。torch.cuda.is_available()返回False就说明要么没装 GPU 版 PyTorch，要么驱动不匹配，这时候别急着跑推理，先解决这个。
3. 跑通推理：从单张修复到批量处理的完整命令
3.1 单张图片修复的最小命令
环境装好、权重放到位之后，推理其实就一条命令。但这条命令的参数值得逐个说清楚，因为不同参数出来的效果差别很大。
python inference_gfpgan.py \ -i inputs/whole_imgs \ -o results \ -v 1.3 \ -s 2 \ --bg_upsampler realesrgan \ --face_upsample逐项解释：
-i指定输入目录，工程里自带了inputs/whole_imgs，里面有几张示例图，第一次跑建议先用它验证流程。-o是输出目录，跑完会生成修复后的图和对比图。-v 1.3是模型版本，对应不同的权重，版本号要和你的权重文件匹配，写错会加载失败。-s 2是放大倍数，2 表示输出是输入的 2 倍分辨率。--bg_upsampler realesrgan指定背景放大用的模型，人脸之外的区域交给它处理。--face_upsample开启人脸区域单独放大，这一步对最终清晰度影响明显。
跑完之后去results/看，通常会有cmp（对比图）和restored_faces（修复后的人脸）两类输出。第一次跑建议先看对比图，直观判断效果是否符合预期。
3.2 输入目录的组织方式与裁剪逻辑
这套工程对输入目录的结构有隐含要求，很多人第一次跑效果差，问题就出在输入没组织好。它内部会做人脸检测和裁剪，如果你的图里人脸太小、角度太偏、或者一张图里有多张脸，检测环节就可能漏检或错检。
我一般会这样组织输入：
inputs/ ├── whole_imgs/ # 整图，脚本自动检测人脸 └── cropped_faces/ # 已裁剪好的人脸，跳过检测直接修复如果你已经自己裁好了人脸，直接丢进cropped_faces那类目录，能绕开检测环节的不确定性。工程里自带的Paris_Hilton_crop.png、Julia_Roberts_crop.png这些就是裁剪好的示例。反过来，如果你的图是合影或者人脸占比很小，建议先手动裁一下再喂进去，比指望脚本自动检测靠谱。
注意：人脸检测对侧脸、遮挡、低光照都不太友好。如果你的素材是监控截图这类质量，先做一轮预处理，别直接上。
3.3 批量处理与输出结果解读
批量处理不需要改代码，把要修的图全丢进输入目录，脚本会遍历。但批量跑有两个现实问题：显存和耗时。图片多、分辨率高的时候，显存容易爆，表现是跑到一半进程被杀。这时候要么调小放大倍数，要么分批跑。
# 分批处理，每次只放 20 张进输入目录 mkdir -p batch_input ls inputs/whole_imgs/*.jpg | head -20 | xargs -I {} cp {} batch_input/ python inference_gfpgan.py -i batch_input -o results_batch -v 1.3 -s 2 --face_upsample这段脚本先用head -20取前 20 张拷进临时目录，再对这一批跑推理。参数上-s是控制显存占用的关键，从 2 降到 1 能明显降显存，代价是输出分辨率低。输出结果里，restored_faces是修复后的人脸区域，cmp是原图、修复图并排的对比，方便你快速筛掉效果差的。
3.4 用测试脚本验证环境是否装对
如果你跑推理一直报错，又说不清是环境问题还是权重问题，可以先跑工程自带的测试。tests/目录下有test_gfpgan_arch.py、test_stylegan2_clean_arch.py这些，它们不依赖权重，只验证网络结构能不能正常前向传播。
# 跑架构测试，验证模型定义和环境 pytest tests/test_gfpgan_arch.py -v pytest tests/test_stylegan2_clean_arch.py -v如果这两个测试能过，说明 PyTorch 环境和代码结构没问题，报错就大概率出在权重路径或推理参数上。如果测试本身就挂，那就是依赖版本的问题，回去检查requirements.txt有没有装全。这个排查顺序能帮你快速定位问题在哪一层。
4. 避坑与常见问题：这几处翻车我替你踩过了
4.1 报错找不到模型权重
现象：运行推理脚本，直接抛FileNotFoundError或者提示某个.pth文件不存在。
原因：源码包通常不含预训练权重，experiments/pretrained_models/目录是空的，或者你下载的权重文件名和脚本里写死的名字对不上。
解决：确认权重文件放进了正确目录，并且文件名和脚本里引用的名字一致。如果版本号参数-v和权重不匹配，也会加载失败，检查你下的权重对应哪个版本。
4.2 显存不足进程被杀
现象：跑到一半进程突然消失，终端只留下Killed，没有详细报错。
原因：批量处理高分辨率图时显存超了，系统直接杀进程。
解决：把-s放大倍数调小，或者分批处理，一次别喂太多图。也可以在代码里限制单次处理的图片数量。CPU 跑虽然不会爆显存，但速度慢到不适合批量。
4.3 修复后的人脸不像本人
现象：图是清晰了，但五官和原图对不上，像换了个人。
原因：身份约束没生效，或者输入人脸质量太差导致检测阶段就偏了。也可能是放大倍数开太大，生成器自由发挥过头。
解决：先把-s降到 1 试试，看是不是放大导致的漂移。如果输入是侧脸或遮挡严重，先换一张正脸清晰的图验证流程。身份保持这块和 ArcFace 分支有关，如果自己改了模型结构，检查身份损失有没有被正确计算。
4.4 背景区域出现奇怪纹理
现象：人脸修得还行，但背景出现莫名其妙的噪点或扭曲。
原因：背景放大模型和人脸修复模型的分工没处理好，或者背景本身质量太差被过度放大。
解决：确认--bg_upsampler参数指定的模型可用。如果背景不重要，可以考虑只输出人脸区域，不做整图放大。工程里restored_faces就是只含人脸的输出，可以优先看这个。
4.5 依赖版本冲突导致导入失败
现象：import gfpgan就报错，提示某个包版本不兼容。
原因：手动升级了某个依赖，和requirements.txt里锁定的版本冲突。
解决：别手动改依赖版本，老老实实按requirements.txt装。如果已经装乱了，重建一个干净环境重装。深度学习工程的依赖链很脆，一个包升错版本能连锁报错。
5. 进阶玩法：改网络结构、换训练数据与效果验证
5.1 从推理转向微调：训练配置怎么读
如果你想用自己的数据微调模型，入口在options/下的 YAML 配置。train_gfpgan_v1.yml是完整版，train_gfpgan_v1_simple.yml是简化版，新手建议从简化版入手，参数少、好调。
# train_gfpgan_v1_simple.yml 里几个关键项 datasets: train: name: FFHQDegradationDataset dataroot_gt: data/ffhq_gt.lmdb # 高清真值数据 io_backend: type: lmdb scale: 1 # 退化尺度 gt_size: 512 # 训练裁剪尺寸dataroot_gt指向高清真值数据，工程里带了ffhq_gt.lmdb这个数据库文件，是 FFHQ 数据集的子集。gt_size控制训练时裁剪的尺寸，显存不够就调小。scale是退化尺度，决定模型学的是几倍修复。改这些参数前，先确认你的数据格式和ffhq_degradation_dataset.py里的读取逻辑对得上，否则训练会直接报数据加载错误。
5.2 模型格式转换脚本的用途
scripts/convert_gfpganv_to_clean.py这个脚本容易被忽略，但它解决一个实际问题：训练出来的模型和推理用的干净版结构可能不一致，需要转换。如果你自己训了模型但推理加载失败，先看看是不是需要跑一遍这个转换。
python scripts/convert_gfpganv_to_clean.py \ --src experiments/pretrained_models/你的模型.pth \ --dst experiments/pretrained_models/转换后.pth参数--src是原始模型，--dst是转换后输出。转换的本质是把训练时的辅助结构剥掉，只留推理需要的部分。这一步不做，推理脚本可能因为多出来的分支报错。
5.3 效果验证：别只看一张图
验证修复效果，我习惯用固定的一组测试图，每次改完参数都跑同一组，横向对比。工程里experiments/下有测试配置和测试数据，可以直接拿来用。判断标准分三层：清晰度是否提升、身份是否保持、有没有引入伪影。清晰度看细节纹理，身份保持看五官比例，伪影看背景和边缘。
| 验证维度 | 观察位置 | 合格标准 |
|---|---|---|
| 清晰度 | 眼睛、发丝、皮肤纹理 | 细节可辨，无糊块 |
| 身份保持 | 五官比例、脸型 | 与原图一致，不换人 |
| 伪影 | 背景、人脸边缘 | 无扭曲、无异常纹理 |
| 稳定性 | 同一组图多次跑 | 结果一致，不随机漂移 |
这张表是我自己排查时用的，你可以按需调整。重点是把「感觉还行」变成可对照的标准，否则改参数全靠玄学。
5.4 一个我踩过的坑
有次我图省事，直接把一批监控截图丢进去批量跑，结果一半的图人脸检测失败，输出全是背景放大后的糊图。后来我养成习惯：批量跑之前先抽三五张跑单张，确认检测和修复都正常，再放全量。这个习惯帮我省了很多返工时间。从那以后我每次批量处理前都强制走一遍小样本验证，希望这个习惯也能帮到你。
本文还有配套的精品资源，点击获取
