简介本资源为基于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 python3.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())这段命令的逻辑很直白先隔离环境再按锁定的依赖装最后验证框架和显卡。参数上唯一要改的是python3.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 一个我踩过的坑有次我图省事直接把一批监控截图丢进去批量跑结果一半的图人脸检测失败输出全是背景放大后的糊图。后来我养成习惯批量跑之前先抽三五张跑单张确认检测和修复都正常再放全量。这个习惯帮我省了很多返工时间。从那以后我每次批量处理前都强制走一遍小样本验证希望这个习惯也能帮到你。本文还有配套的精品资源点击获取