简介本资源为基于Python深度学习框架的GFPGAN图片修复算法实现源码面向具备一定Python编程与深度学习基础、希望深入研究图像修复与生成对抗网络的开发者及研究人员。项目聚焦面部图像的高质量修复与美化可应用于老旧照片修复、数字取证及艺术作品数字化等场景。压缩包共62个文件约6.22MB其中26个py文件承载算法核心实现与训练推理逻辑8个yml与2个yaml配置文件负责参数与实验设置5个md文档提供说明与常见问题解答另含png、jpg示例图、mdb数据集、pth权重及license等辅助文件。目录涵盖模型架构、数据加载、训练脚本与测试用例等模块结构完整。目前已有429人学习下载适合作为图像修复方向的实践参考与二次开发基础。1. 从一张糊到看不清五官的老照片说起GFPGAN 源码包能干什么翻出十年前的合影人脸区域糊成一团放大后全是噪点和马赛克——这是很多人做图片修复时最典型的起点。基于 Python 深度学习的 GFPGAN 图片修复算法实现源码解决的正是这类问题它不是简单锐化或插值放大而是用生成对抗网络把退化的人脸「重建」回接近真实的样子。这套源码包把 GFPGAN 的完整实现、预训练模型加载逻辑、推理脚本和训练配置都摊开给你适合两类人一是想直接跑通修复效果的 Python 开发者二是想拆开看 GAN 人脸先验怎么落到代码里的深度学习学习者。它不承诺一键修所有图但对人脸区域的修复能力在开源方案里属于第一梯队。2. 拆开源码包GFPGAN 的架构分层与文件职责2.1 从 gfpgan/ 目录看推理链路拿到源码包先别急着python inference_gfpgan.py。花十分钟把gfpgan/目录的调用关系理清楚后面调参和排错会省很多时间。核心链路是这样的inference_gfpgan.py负责解析命令行参数、读图、调用模型、保存结果gfpgan/utils.py里的GFPGANer类是真正的门面它把人脸检测、对齐、修复、背景融合串在一起gfpgan/models/gfpgan_model.py定义训练和推理时的网络组装逻辑gfpgan/archs/下面才是各个网络结构的实现。archs目录里有几个文件值得单独说。gfpganv1_arch.py是原始 GFPGAN 的生成器结构包含退化消除模块和人脸生成器gfpganv1_clean_arch.py是去掉了训练专用组件的干净版本推理时更轻stylegan2_clean_arch.py是 StyleGAN2 的干净实现作为生成器的骨干arcface_arch.py是 ArcFace 人脸识别网络训练时用来算身份损失保证修复后的人还是同一个人。restoreformer_arch.py是后来加入的 RestoreFormer 结构属于扩展选项。理解这个分层后你就能判断改哪里想换生成器骨干动stylegan2_clean_arch.py想调修复强度看gfpganv1_clean_arch.py里通道数和残差块数量想加自己的损失函数去gfpgan_model.py找gfpgan_forward和gfpgan_backward。2.2 配置文件与预训练模型怎么对应源码包里options/目录下的 YAML 文件决定了训练和推理的行为。train_gfpgan_v1.yml是完整训练配置train_gfpgan_v1_simple.yml是简化版适合显存有限的机器。推理时虽然不直接读这些 YAML但GFPGANer初始化时会根据你传入的模型版本选择对应的网络结构所以配置文件和模型权重必须匹配。常见做法是先看experiments/pretrained_models/里有没有现成权重没有的话按PaperModel.md里的说明下载对应版本。inference_gfpgan.py默认会去这个目录找模型。如果你把权重放在别处用--model_path指定绝对路径别用相对路径否则从不同工作目录运行时容易找不到。# 查看源码包内预训练模型目录结构 ls -la experiments/pretrained_models/ # 典型输出会包含 detection、arcface、gfpgan 等子目录 # detection 放人脸检测模型arcface 放身份特征模型gfpgan 放修复主模型这段命令的作用是确认模型文件是否齐全。detection目录通常需要 RetinaFace 或类似的人脸检测权重arcface目录放 ArcFace 的.pth文件gfpgan目录放主修复模型。缺任何一个推理时都会在对应环节报错。参数上--upscale控制输出放大倍数默认 2--bg_upsampler控制背景放大方式可选realesrgan或None。2.3 推理脚本的参数体系inference_gfpgan.py的参数不多但每个都影响结果。-i指定输入可以是单张图也可以是目录-o指定输出目录-v指定模型版本常用1.3和1.4-s是放大倍数--only_center_face只修复画面中心人脸--aligned表示输入已经是对齐好的人脸跳过检测对齐步骤。python inference_gfpgan.py \ -i inputs/whole_imgs \ -o results \ -v 1.4 \ -s 2 \ --bg_upsampler realesrgan这段命令的逻辑是读inputs/whole_imgs下的所有图用 1.4 版模型修复输出放大 2 倍背景用 Real-ESRGAN 放大。-v 1.4对应gfpganv1_clean_arch.py的结构如果你只有 1.3 的权重却传 1.4加载时会报unexpected key或missing key。--bg_upsampler realesrgan需要额外安装realesrgan包不装就设成None否则初始化阶段直接抛ImportError。3. 跑通第一次修复环境、权重与推理全流程3.1 环境依赖的版本边界这套源码对版本比较敏感尤其是 PyTorch 和 CUDA 的搭配。requirements.txt里列了基础依赖但没锁死版本。血泪经验是PyTorch 1.8 到 1.13 之间兼容性最好2.0 以上部分算子行为有变化stylegan2_clean_arch.py里的upfirdn2d可能报错。Python 用 3.8 或 3.93.10 以上有些旧版basicsr装不上。# 建议的安装顺序先建虚拟环境 conda create -n gfpgan python3.9 -y conda activate gfpgan # 装 PyTorch按你的 CUDA 版本选 pip install torch1.13.1cu117 torchvision0.14.1cu117 -f https://download.pytorch.org/whl/torch_stable.html # 再装项目依赖 pip install -r requirements.txt # 单独装 basicsr 和 facexlib这两个容易版本冲突 pip install basicsr1.4.2 facexlib0.2.5逻辑说明先固定 Python 和 PyTorch再装项目依赖最后单独处理basicsr和facexlib。参数上torch1.13.1cu117里的cu117表示 CUDA 11.7 编译版你的驱动要支持对应 CUDA 版本。如果装完basicsr后 import 报cannot import name degradations说明版本不对降到 1.4.2 通常能解决。3.2 权重文件的放置与校验预训练权重不随源码包直接提供需要按PaperModel.md的指引获取。常见做法是建一个experiments/pretrained_models目录把下载的.pth文件按子目录放好。放完后用一段小脚本校验加载是否正常。import torch # 校验 GFPGAN 主模型权重能否被干净架构加载 from gfpgan.archs.gfpganv1_clean_arch import GFPGANv1Clean # 注意这里只加载结构不跑推理用来确认权重和架构匹配 model GFPGANv1Clean( out_size512, num_style_feat512, channel_multiplier2, decoder_load_pathNone, fix_decoderFalse, num_mlp8, input_is_latentTrue, different_wTrue, narrow1, sft_halfTrue ) state_dict torch.load(experiments/pretrained_models/gfpgan/GFPGANv1.4.pth, map_locationcpu) # strictFalse 允许部分 key 不匹配但要看 missing 和 unexpected 的数量 model.load_state_dict(state_dict, strictFalse) print(权重加载完成可以进入推理阶段)这段代码的作用是提前暴露权重和架构不匹配的问题。参数channel_multiplier2对应 1.4 版1.3 版通常是 1。sft_halfTrue也是 1.4 的特征。如果load_state_dict报大量 missing keys说明你下的权重版本和代码里的架构对不上换权重或换-v参数。3.3 单张图与批量修复的实操差异单张图修复直接指定文件路径就行批量修复把-i指向目录。但批量时有个坑如果目录里混了非图片文件inference_gfpgan.py会直接崩。我一般先过滤一遍。# 批量修复前先清理输入目录只保留图片 mkdir -p inputs/clean find inputs/whole_imgs -type f \( -iname *.jpg -o -iname *.png -o -iname *.jpeg \) -exec cp {} inputs/clean/ \; # 再跑批量推理 python inference_gfpgan.py -i inputs/clean -o results_batch -v 1.4 -s 2逻辑说明find命令按扩展名筛选图片并复制到干净目录避免推理脚本读到.DS_Store或.txt时抛异常。参数-iname忽略大小写覆盖.JPG和.jpg。批量输出会按原文件名保存在results_batch下同时生成cropped_faces和restored_faces子目录方便对比修复前后的人脸区域。4. 避坑与排查GFPGAN 跑不起来时先看这几条4.1 报错ModuleNotFoundError: No module named basicsr现象是运行inference_gfpgan.py时直接提示找不到basicsr即使pip list里显示已安装。原因通常是basicsr装到了系统 Python 而不是当前虚拟环境或者装完后没重启终端导致路径没刷新。解决方法是先which python确认当前解释器路径再pip show basicsr看安装位置是否一致。不一致就python -m pip install basicsr1.4.2强制装到当前环境。装完还报错检查basicsr依赖的torch版本是否被降级覆盖了。4.2 推理结果人脸区域出现绿色或紫色色块现象是修复后的人脸部分颜色异常背景正常。原因是--bg_upsampler和主修复模型的输出通道顺序不一致常见于 Real-ESRGAN 版本不匹配。解决方法是先把--bg_upsampler设为None跑一遍确认主修复模型输出正常。如果正常再单独升级realesrgan到与basicsr兼容的版本。另一个可能是输入图是 CMYK 模式cv2.imread读进来通道错乱用 PIL 转成 RGB 再存一次。4.3 显存不足导致CUDA out of memory现象是处理稍大一点的图就崩报显存不够。原因是 GFPGAN 默认按整图处理人脸检测后裁剪的区域如果分辨率高生成器中间特征图占用很大。解决方法是加--upscale 1先不放大或者把输入图长边缩到 1024 以内再跑。如果还不行在GFPGANer初始化时把bg_upsampler关掉背景不放大能省不少显存。批量处理时改成逐张循环别一次性把所有图读进内存。4.4 修复后的人脸不像本人现象是修复效果清晰了但五官和原图差异大像换了个人。原因是--weight参数身份损失权重在推理时不可调模型默认偏向生成「标准好看脸」。解决方法是换用 1.3 版模型它的身份保持通常比 1.4 更稳或者在gfpganv1_clean_arch.py里把sft_half设为False再跑减少对原始特征的修改。如果对身份保持要求极高建议只修复背景人脸区域用原图叠加。4.5 输出目录生成了文件但打不开现象是results目录下有文件但双击提示损坏。原因是推理脚本保存时用了cv2.imwrite而输出路径包含中文或空格OpenCV 在部分系统上处理不了非 ASCII 路径。解决方法是把输出目录改成纯英文路径或者把保存逻辑换成PIL.Image.fromarray(...).save(...)。另外检查磁盘空间写了一半空间满也会产生损坏文件。5. 进阶技巧用 parse_landmark 和 convert 脚本做可控修复源码包里scripts/目录下有两个容易被忽略但很有用的脚本parse_landmark.py和convert_gfpganv_to_clean.py。前者用来提取人脸关键点后者用来把训练版权重转成推理版干净架构。掌握这两个你就能做更精细的控制。parse_landmark.py的用法是传入一张人脸图输出 68 个关键点坐标。这些坐标可以用来判断人脸姿态如果关键点分布明显偏转说明侧脸角度大GFPGAN 的修复效果会下降。我一般会在批量修复前先跑一遍关键点检测把侧脸超过 30 度的图单独挑出来避免修复后五官错位。from scripts.parse_landmark import parse_landmark import cv2 # 读取图片并提取关键点 img cv2.imread(inputs/cropped_faces/Adele_crop.png) landmarks parse_landmark(img) # landmarks 是 68x2 的数组前 17 个是下颌线后面是眉毛、鼻子、眼睛、嘴巴 # 用左右眼关键点估算偏转角 left_eye landmarks[36:42].mean(axis0) right_eye landmarks[42:48].mean(axis0) eye_center (left_eye right_eye) / 2 nose landmarks[30] # 鼻尖偏离双眼中心越多侧脸角度越大 offset abs(nose[0] - eye_center[0]) / (right_eye[0] - left_eye[0]) print(f侧脸偏移比例: {offset:.2f}超过 0.3 建议人工检查)这段代码的逻辑是用眼睛和鼻子的相对位置估算侧脸程度。参数上landmarks[36:42]是左眼六个点landmarks[42:48]是右眼六个点landmarks[30]是鼻尖。offset超过 0.3 时GFPGAN 的正面先验会强行「掰正」人脸导致不像本人。这时候要么换一张更正的图要么在GFPGANer里把only_center_face打开只修最正的那张脸。convert_gfpganv_to_clean.py解决的是权重格式问题。有些渠道拿到的权重是训练版保存的包含判别器和优化器状态直接加载到推理架构会报 key 不匹配。这个脚本把训练版权重里的生成器部分抽出来重新映射到干净架构的 key 名。# 把训练版权重转成推理版 python scripts/convert_gfpganv_to_clean.py \ --src experiments/pretrained_models/gfpgan/GFPGANv1.4_train.pth \ --dst experiments/pretrained_models/gfpgan/GFPGANv1.4_clean.pth # 转换后再跑推理指定 clean 权重 python inference_gfpgan.py -i inputs/whole_imgs -o results -v 1.4 -s 2逻辑说明--src是原始训练权重路径--dst是转换后保存路径。转换脚本会打印映射了多少个 key如果有大量 key 没映射上说明源权重版本和脚本预期的不一致。转换完成后inference_gfpgan.py会自动优先加载_clean后缀的权重。这个步骤在换用非官方渠道权重时特别有用能避免直接加载时的玄学报错。从那以后我每次拿到新的 GFPGAN 权重都强制先跑一遍convert_gfpganv_to_clean.py再推理不管它文件名里有没有clean。这个习惯帮我省掉了至少三次「权重明明在却加载失败」的排查时间。希望帮到你。本文还有配套的精品资源点击获取
简介本资源为基于Python深度学习框架的GFPGAN图片修复算法实现源码面向具备一定Python编程与深度学习基础、希望深入研究图像修复与生成对抗网络的开发者及研究人员。项目聚焦面部图像的高质量修复与美化可应用于老旧照片修复、数字取证及艺术作品数字化等场景。压缩包共62个文件约6.22MB其中26个py文件承载算法核心实现与训练推理逻辑8个yml与2个yaml配置文件负责参数与实验设置5个md文档提供说明与常见问题解答另含png、jpg示例图、mdb数据集、pth权重及license等辅助文件。目录涵盖模型架构、数据加载、训练脚本与测试用例等模块结构完整。目前已有429人学习下载适合作为图像修复方向的实践参考与二次开发基础。1. 从一张糊到看不清五官的老照片说起GFPGAN 源码包能干什么翻出十年前的合影人脸区域糊成一团放大后全是噪点和马赛克——这是很多人做图片修复时最典型的起点。基于 Python 深度学习的 GFPGAN 图片修复算法实现源码解决的正是这类问题它不是简单锐化或插值放大而是用生成对抗网络把退化的人脸「重建」回接近真实的样子。这套源码包把 GFPGAN 的完整实现、预训练模型加载逻辑、推理脚本和训练配置都摊开给你适合两类人一是想直接跑通修复效果的 Python 开发者二是想拆开看 GAN 人脸先验怎么落到代码里的深度学习学习者。它不承诺一键修所有图但对人脸区域的修复能力在开源方案里属于第一梯队。2. 拆开源码包GFPGAN 的架构分层与文件职责2.1 从 gfpgan/ 目录看推理链路拿到源码包先别急着python inference_gfpgan.py。花十分钟把gfpgan/目录的调用关系理清楚后面调参和排错会省很多时间。核心链路是这样的inference_gfpgan.py负责解析命令行参数、读图、调用模型、保存结果gfpgan/utils.py里的GFPGANer类是真正的门面它把人脸检测、对齐、修复、背景融合串在一起gfpgan/models/gfpgan_model.py定义训练和推理时的网络组装逻辑gfpgan/archs/下面才是各个网络结构的实现。archs目录里有几个文件值得单独说。gfpganv1_arch.py是原始 GFPGAN 的生成器结构包含退化消除模块和人脸生成器gfpganv1_clean_arch.py是去掉了训练专用组件的干净版本推理时更轻stylegan2_clean_arch.py是 StyleGAN2 的干净实现作为生成器的骨干arcface_arch.py是 ArcFace 人脸识别网络训练时用来算身份损失保证修复后的人还是同一个人。restoreformer_arch.py是后来加入的 RestoreFormer 结构属于扩展选项。理解这个分层后你就能判断改哪里想换生成器骨干动stylegan2_clean_arch.py想调修复强度看gfpganv1_clean_arch.py里通道数和残差块数量想加自己的损失函数去gfpgan_model.py找gfpgan_forward和gfpgan_backward。2.2 配置文件与预训练模型怎么对应源码包里options/目录下的 YAML 文件决定了训练和推理的行为。train_gfpgan_v1.yml是完整训练配置train_gfpgan_v1_simple.yml是简化版适合显存有限的机器。推理时虽然不直接读这些 YAML但GFPGANer初始化时会根据你传入的模型版本选择对应的网络结构所以配置文件和模型权重必须匹配。常见做法是先看experiments/pretrained_models/里有没有现成权重没有的话按PaperModel.md里的说明下载对应版本。inference_gfpgan.py默认会去这个目录找模型。如果你把权重放在别处用--model_path指定绝对路径别用相对路径否则从不同工作目录运行时容易找不到。# 查看源码包内预训练模型目录结构 ls -la experiments/pretrained_models/ # 典型输出会包含 detection、arcface、gfpgan 等子目录 # detection 放人脸检测模型arcface 放身份特征模型gfpgan 放修复主模型这段命令的作用是确认模型文件是否齐全。detection目录通常需要 RetinaFace 或类似的人脸检测权重arcface目录放 ArcFace 的.pth文件gfpgan目录放主修复模型。缺任何一个推理时都会在对应环节报错。参数上--upscale控制输出放大倍数默认 2--bg_upsampler控制背景放大方式可选realesrgan或None。2.3 推理脚本的参数体系inference_gfpgan.py的参数不多但每个都影响结果。-i指定输入可以是单张图也可以是目录-o指定输出目录-v指定模型版本常用1.3和1.4-s是放大倍数--only_center_face只修复画面中心人脸--aligned表示输入已经是对齐好的人脸跳过检测对齐步骤。python inference_gfpgan.py \ -i inputs/whole_imgs \ -o results \ -v 1.4 \ -s 2 \ --bg_upsampler realesrgan这段命令的逻辑是读inputs/whole_imgs下的所有图用 1.4 版模型修复输出放大 2 倍背景用 Real-ESRGAN 放大。-v 1.4对应gfpganv1_clean_arch.py的结构如果你只有 1.3 的权重却传 1.4加载时会报unexpected key或missing key。--bg_upsampler realesrgan需要额外安装realesrgan包不装就设成None否则初始化阶段直接抛ImportError。3. 跑通第一次修复环境、权重与推理全流程3.1 环境依赖的版本边界这套源码对版本比较敏感尤其是 PyTorch 和 CUDA 的搭配。requirements.txt里列了基础依赖但没锁死版本。血泪经验是PyTorch 1.8 到 1.13 之间兼容性最好2.0 以上部分算子行为有变化stylegan2_clean_arch.py里的upfirdn2d可能报错。Python 用 3.8 或 3.93.10 以上有些旧版basicsr装不上。# 建议的安装顺序先建虚拟环境 conda create -n gfpgan python3.9 -y conda activate gfpgan # 装 PyTorch按你的 CUDA 版本选 pip install torch1.13.1cu117 torchvision0.14.1cu117 -f https://download.pytorch.org/whl/torch_stable.html # 再装项目依赖 pip install -r requirements.txt # 单独装 basicsr 和 facexlib这两个容易版本冲突 pip install basicsr1.4.2 facexlib0.2.5逻辑说明先固定 Python 和 PyTorch再装项目依赖最后单独处理basicsr和facexlib。参数上torch1.13.1cu117里的cu117表示 CUDA 11.7 编译版你的驱动要支持对应 CUDA 版本。如果装完basicsr后 import 报cannot import name degradations说明版本不对降到 1.4.2 通常能解决。3.2 权重文件的放置与校验预训练权重不随源码包直接提供需要按PaperModel.md的指引获取。常见做法是建一个experiments/pretrained_models目录把下载的.pth文件按子目录放好。放完后用一段小脚本校验加载是否正常。import torch # 校验 GFPGAN 主模型权重能否被干净架构加载 from gfpgan.archs.gfpganv1_clean_arch import GFPGANv1Clean # 注意这里只加载结构不跑推理用来确认权重和架构匹配 model GFPGANv1Clean( out_size512, num_style_feat512, channel_multiplier2, decoder_load_pathNone, fix_decoderFalse, num_mlp8, input_is_latentTrue, different_wTrue, narrow1, sft_halfTrue ) state_dict torch.load(experiments/pretrained_models/gfpgan/GFPGANv1.4.pth, map_locationcpu) # strictFalse 允许部分 key 不匹配但要看 missing 和 unexpected 的数量 model.load_state_dict(state_dict, strictFalse) print(权重加载完成可以进入推理阶段)这段代码的作用是提前暴露权重和架构不匹配的问题。参数channel_multiplier2对应 1.4 版1.3 版通常是 1。sft_halfTrue也是 1.4 的特征。如果load_state_dict报大量 missing keys说明你下的权重版本和代码里的架构对不上换权重或换-v参数。3.3 单张图与批量修复的实操差异单张图修复直接指定文件路径就行批量修复把-i指向目录。但批量时有个坑如果目录里混了非图片文件inference_gfpgan.py会直接崩。我一般先过滤一遍。# 批量修复前先清理输入目录只保留图片 mkdir -p inputs/clean find inputs/whole_imgs -type f \( -iname *.jpg -o -iname *.png -o -iname *.jpeg \) -exec cp {} inputs/clean/ \; # 再跑批量推理 python inference_gfpgan.py -i inputs/clean -o results_batch -v 1.4 -s 2逻辑说明find命令按扩展名筛选图片并复制到干净目录避免推理脚本读到.DS_Store或.txt时抛异常。参数-iname忽略大小写覆盖.JPG和.jpg。批量输出会按原文件名保存在results_batch下同时生成cropped_faces和restored_faces子目录方便对比修复前后的人脸区域。4. 避坑与排查GFPGAN 跑不起来时先看这几条4.1 报错ModuleNotFoundError: No module named basicsr现象是运行inference_gfpgan.py时直接提示找不到basicsr即使pip list里显示已安装。原因通常是basicsr装到了系统 Python 而不是当前虚拟环境或者装完后没重启终端导致路径没刷新。解决方法是先which python确认当前解释器路径再pip show basicsr看安装位置是否一致。不一致就python -m pip install basicsr1.4.2强制装到当前环境。装完还报错检查basicsr依赖的torch版本是否被降级覆盖了。4.2 推理结果人脸区域出现绿色或紫色色块现象是修复后的人脸部分颜色异常背景正常。原因是--bg_upsampler和主修复模型的输出通道顺序不一致常见于 Real-ESRGAN 版本不匹配。解决方法是先把--bg_upsampler设为None跑一遍确认主修复模型输出正常。如果正常再单独升级realesrgan到与basicsr兼容的版本。另一个可能是输入图是 CMYK 模式cv2.imread读进来通道错乱用 PIL 转成 RGB 再存一次。4.3 显存不足导致CUDA out of memory现象是处理稍大一点的图就崩报显存不够。原因是 GFPGAN 默认按整图处理人脸检测后裁剪的区域如果分辨率高生成器中间特征图占用很大。解决方法是加--upscale 1先不放大或者把输入图长边缩到 1024 以内再跑。如果还不行在GFPGANer初始化时把bg_upsampler关掉背景不放大能省不少显存。批量处理时改成逐张循环别一次性把所有图读进内存。4.4 修复后的人脸不像本人现象是修复效果清晰了但五官和原图差异大像换了个人。原因是--weight参数身份损失权重在推理时不可调模型默认偏向生成「标准好看脸」。解决方法是换用 1.3 版模型它的身份保持通常比 1.4 更稳或者在gfpganv1_clean_arch.py里把sft_half设为False再跑减少对原始特征的修改。如果对身份保持要求极高建议只修复背景人脸区域用原图叠加。4.5 输出目录生成了文件但打不开现象是results目录下有文件但双击提示损坏。原因是推理脚本保存时用了cv2.imwrite而输出路径包含中文或空格OpenCV 在部分系统上处理不了非 ASCII 路径。解决方法是把输出目录改成纯英文路径或者把保存逻辑换成PIL.Image.fromarray(...).save(...)。另外检查磁盘空间写了一半空间满也会产生损坏文件。5. 进阶技巧用 parse_landmark 和 convert 脚本做可控修复源码包里scripts/目录下有两个容易被忽略但很有用的脚本parse_landmark.py和convert_gfpganv_to_clean.py。前者用来提取人脸关键点后者用来把训练版权重转成推理版干净架构。掌握这两个你就能做更精细的控制。parse_landmark.py的用法是传入一张人脸图输出 68 个关键点坐标。这些坐标可以用来判断人脸姿态如果关键点分布明显偏转说明侧脸角度大GFPGAN 的修复效果会下降。我一般会在批量修复前先跑一遍关键点检测把侧脸超过 30 度的图单独挑出来避免修复后五官错位。from scripts.parse_landmark import parse_landmark import cv2 # 读取图片并提取关键点 img cv2.imread(inputs/cropped_faces/Adele_crop.png) landmarks parse_landmark(img) # landmarks 是 68x2 的数组前 17 个是下颌线后面是眉毛、鼻子、眼睛、嘴巴 # 用左右眼关键点估算偏转角 left_eye landmarks[36:42].mean(axis0) right_eye landmarks[42:48].mean(axis0) eye_center (left_eye right_eye) / 2 nose landmarks[30] # 鼻尖偏离双眼中心越多侧脸角度越大 offset abs(nose[0] - eye_center[0]) / (right_eye[0] - left_eye[0]) print(f侧脸偏移比例: {offset:.2f}超过 0.3 建议人工检查)这段代码的逻辑是用眼睛和鼻子的相对位置估算侧脸程度。参数上landmarks[36:42]是左眼六个点landmarks[42:48]是右眼六个点landmarks[30]是鼻尖。offset超过 0.3 时GFPGAN 的正面先验会强行「掰正」人脸导致不像本人。这时候要么换一张更正的图要么在GFPGANer里把only_center_face打开只修最正的那张脸。convert_gfpganv_to_clean.py解决的是权重格式问题。有些渠道拿到的权重是训练版保存的包含判别器和优化器状态直接加载到推理架构会报 key 不匹配。这个脚本把训练版权重里的生成器部分抽出来重新映射到干净架构的 key 名。# 把训练版权重转成推理版 python scripts/convert_gfpganv_to_clean.py \ --src experiments/pretrained_models/gfpgan/GFPGANv1.4_train.pth \ --dst experiments/pretrained_models/gfpgan/GFPGANv1.4_clean.pth # 转换后再跑推理指定 clean 权重 python inference_gfpgan.py -i inputs/whole_imgs -o results -v 1.4 -s 2逻辑说明--src是原始训练权重路径--dst是转换后保存路径。转换脚本会打印映射了多少个 key如果有大量 key 没映射上说明源权重版本和脚本预期的不一致。转换完成后inference_gfpgan.py会自动优先加载_clean后缀的权重。这个步骤在换用非官方渠道权重时特别有用能避免直接加载时的玄学报错。从那以后我每次拿到新的 GFPGAN 权重都强制先跑一遍convert_gfpganv_to_clean.py再推理不管它文件名里有没有clean。这个习惯帮我省掉了至少三次「权重明明在却加载失败」的排查时间。希望帮到你。本文还有配套的精品资源点击获取
