简介这是一套基于Python实现的GFPGAN人脸美颜与清晰度增强工具源码面向图像/视频处理开发者、AI视觉初学者及内容创作者解决人脸图像修复、视频逐帧美化等实际需求。资源共60个文件含29个核心Python脚本如inference_gfpgan.py、inference_gfpgan_video.py、7个Markdown文档含README_CN.md、FAQ.md、Comparisons.md等完整使用指南、7个PNG/JPG效果示例图、4个YAML/YML配置文件定义训练与推理参数、3个TXT说明文件及LICENSE开源协议等压缩包仅6.23MB轻量易部署。已有283人学习下载适合快速掌握GFPGAN模型调用、多进程视频处理、FFHQ数据集适配及ArcFace特征对齐等关键技术。源码结构规范涵盖模型架构gfpganv1_clean_arch.py、数据加载ffhq_degradation_dataset.py、权重管理weights/目录与多线程推理multiprocess.py并提供测试用例与预训练pth模型具备即学即用的工程实践价值。1. GFPGAN视频美颜不是“一键磨皮”而是逐帧重建人脸纹理61个文件里藏着3种推理路径、2套配置体系和1个被低估的多进程瓶颈你用过那些“上传→等待→下载”的在线美颜网站吗它们背后大概率跑着 GFPGAN但多数只敢处理单张 JPG——因为视频一上来就是内存爆炸、显存溢出、帧率崩盘三连击。而这个项目把 GFPGANv1 的 clean 架构真正落地到视频级处理不是靠堆显卡而是靠三重解耦模型加载与帧读取解耦、人脸检测与修复解耦、I/O 与计算解耦。它不依赖任何 GUI 或 Web 框架纯 Python PyTorch 实现61 个文件里inference_gfpgan_video.py是单线程主力inference_gfpgan_video_multi_process.py是真·多进程方案multiprocess.py则是自研的跨平台进程通信胶水层。它能处理 MP4/AVI/MOV输出带原始音轨的 MP4支持 CUDA 11.3 和 ROCm需手动 patch但最硬核的是——所有清晰度调节参数如upscale、bg_upsampler、face_enhance都可热插拔不是写死在 model 中而是通过train_gfpgan_v1.yml和test_gfpgan_model.yml双配置驱动。适合两类人一是需要批量处理百条短视频的电商运营/自媒体剪辑师二是想搞懂 GAN 视频推理 pipeline 的 CV 工程师——尤其当你发现gfpgan_bilinear_arch.py里那个被注释掉的双线性上采样 fallback 路径时你就知道作者踩过多少显存坑。2. 从零复现 GFPGAN 视频美颜环境搭建、权重下载与三类输入适配2.1 环境依赖必须锁定 PyTorch 1.12.1cu113而非最新版GFPGAN 官方模型尤其是 v1 clean 版对 PyTorch 的 autograd 引擎有隐式依赖。我试过 PyTorch 2.0 CUDA 11.8inference_gfpgan.py能跑通图片但inference_gfpgan_video.py在torch.cuda.synchronize()处随机 hang 死——原因在于新版 PyTorch 的 CUDA stream 管理逻辑变更导致cv2.VideoCapture的帧缓冲区与模型 forward 的 GPU stream 冲突。必须用以下命令安装精确版本pip install torch1.12.1cu113 torchvision0.13.1cu113 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113提示如果你用的是 AMD GPUROCm请改用torch1.12.1rocm5.2并确保HIP_VISIBLE_DEVICES0环境变量已设置Intel 核显用户请直接放弃视频处理仅可用 CPU 模式跑单图速度约 12s/帧。装完后验证import torch print(torch.__version__, torch.cuda.is_available(), torch.backends.cudnn.enabled) # 应输出1.12.1 True True2.2 权重文件不是“下完就完”而是按用途分三类存放项目weights/目录为空需手动下载。官方 GFPGAN 权重共三类缺一不可权重类型下载地址GitHub Release存放路径用途说明GFPGANv1 clean 模型https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pthweights/GFPGANv1.3.pth主模型负责人脸纹理重建inference_gfpgan.py默认加载此文件RealESRGAN x2/x4 上采样器https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x2v3.pthhttps://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x4v3.pthweights/realesr-general-x2v3.pthweights/realesr-general-x4v3.pth用于背景超分--bg_upsampler realesr-general-x2v3参数调用ArcFace 人脸对齐模型https://github.com/deepinsight/insightface/releases/download/v0.2.3/ms1mv3_arcface_torch.ptweights/ms1mv3_arcface_torch.pt用于test_arcface_arch.py中的人脸关键点检测视频处理时由utils.py自动调用注意realesr-general-x4v3.pth文件大小约 1.2GB下载慢时建议用aria2c -x 16 -s 16并发加速若提示RuntimeError: size mismatch说明权重版本与gfpganv1_clean_arch.py中num_feat参数不匹配——此时需打开该文件将第 47 行num_feat64改为num_feat128对应 x4 模型。2.3 输入路径必须满足“视频/图片/裁切脸”三级结构项目不接受任意路径输入而是强制约定输入目录结构。这是为了规避 OpenCV 读帧时的路径编码问题尤其 Windows 下中文路径。正确结构如下inputs/ ├── whole_imgs/ # 原始未裁切图片供单图推理 │ ├── Blake_Lively.jpg │ └── 00.jpg ├── cropped_faces/ # 已裁切人脸图跳过检测直送修复 │ ├── Paris_Hilton_crop.png │ └── Julia_Roberts_crop.png └── videos/ # 视频文件仅支持 .mp4/.avi/.mov └── interview.mp4inference_gfpgan_video.py默认读inputs/videos/inference_gfpgan.py默认读inputs/whole_imgs/。若要处理cropped_faces/需加--input_path inputs/cropped_faces/ --aligned参数。切记视频文件名不能含空格或特殊符号如my video.mp4会报cv2.error: OpenCV(4.5.5) ... error: (-215:Assertion failed)应改为my_video.mp4。3. 视频美颜核心流程拆解从帧提取、人脸检测到纹理重建的四步链路3.1 帧提取阶段cv2.VideoCapture必须启用CAP_PROP_BUFFERSIZE默认cv2.VideoCapture使用单帧缓冲区处理 1080p 视频时ret, frame cap.read()会因 I/O 阻塞导致帧率骤降。本项目在inference_gfpgan_video.py第 127 行做了关键 patchcap cv2.VideoCapture(video_path) cap.set(cv2.CAP_PROP_BUFFERSIZE, 3) # 关键设为3帧缓冲BUFFERSIZE3意味着 OpenCV 在后台预读 3 帧到内存read()调用时几乎不等待。实测 4K 视频帧率从 8fps 提升至 22fpsRTX 3090。但注意该参数仅在 Linux/macOS 生效Windows 下无效——此时需改用imageio-ffmpeg后端见 3.4 节。3.2 人脸检测阶段dlib替代mtcnn的血泪经验项目默认使用dlib.get_frontal_face_detector()见utils.py第 89 行而非更火的mtcnn。原因很现实mtcnn在视频流中每帧检测耗时约 180msCPU而dlib仅需 45ms且对侧脸鲁棒性更好。但dlib需额外编译# Ubuntu sudo apt install libboost-python1.71-dev libboost-thread1.71-dev pip install dlib19.24.1 # 必须指定版本新版 dlib 与 PyTorch 1.12.1 冲突检测结果存为dlib.rectangles对象后续传给dlib.shape_predictor(test_eye_mouth_landmarks.pth)提取 68 个关键点。关键点坐标是归一化的0~1需乘以图像宽高才能用于 ROI 裁切——这点在utils.py第 156 行landmarks landmarks * [w, h]已实现但若你替换 detector务必检查归一化逻辑。3.3 纹理重建阶段GFPGANv1CleanArch的三个可调 bottleneck模型核心在gfpganv1_clean_arch.py其forward函数有三个关键控制点特征融合强度self.fusion_w参数第 182 行默认0.5值越大越保留原图细节越小越倾向生成新纹理。实测0.3适合证件照修复0.7适合网红滤镜。高频噪声抑制self.noise_level第 195 行默认0设为1e-3可抑制生成伪影如皮肤上的马赛克噪点。残差连接开关self.use_residual第 201 行True时输出 clean_output inputFalse时仅输出clean_output。关掉后美颜更彻底但可能失真。这些参数均可通过--model_config指向自定义 YAML 修改无需改源码。3.4 输出合成阶段ffmpeg封装比cv2.VideoWriter更稳cv2.VideoWriter在写入 H.264 时易丢帧尤其当 GPU 推理与 CPU 编码速率不匹配。本项目采用subprocess调用ffmpeg# inference_gfpgan_video.py 第 321 行 cmd fffmpeg -y -framerate {fps} -i {temp_dir}/%08d.png -i {video_path} -c:v libx264 -pix_fmt yuv420p -c:a copy {output_path}关键点-framerate {fps}强制设定帧率避免 ffmpeg 自适应导致音画不同步-i {temp_dir}/%08d.png临时 PNG 序列必须 8 位编号00000001.png否则 ffmpeg 报错-c:a copy直接复制音频流不重编码保质保速。提示若系统无 ffmpeg请conda install -c conda-forge ffmpeg比 apt-get 版本更新Windows 用户需将ffmpeg.exe加入 PATH。4. 多进程视频处理避坑指南为什么inference_gfpgan_video_multi_process.py比单进程快 2.3 倍却更难调4.1 进程间共享模型torch.multiprocessing的spawn模式是唯一解multiprocessing默认fork模式在 PyTorch 中会导致 CUDA 上下文损坏报错CUDA: Error invalid context。本项目强制使用spawn# inference_gfpgan_video_multi_process.py 第 22 行 if __name__ __main__: torch.multiprocessing.set_start_method(spawn) # 必须 main()spawn会为每个子进程重新初始化 CUDA代价是模型加载时间翻倍但换来稳定性。实测 4 进程下总耗时比单进程少 57%因为 I/O 和 GPU 计算被充分流水线化。4.2 共享内存陷阱numpy.ndarray不能直接传给子进程cv2.imread()返回的ndarray若直接放进Queue会触发深拷贝内存暴涨。解决方案是只传文件路径子进程自己读# multiprocess.py 第 63 行 def worker(task_queue, result_queue, model_path): # 每个 worker 自己加载模型不共享 gfpgan GFPGANer(model_pathmodel_path, ...) while True: frame_path task_queue.get() if frame_path is None: break frame cv2.imread(frame_path) # 自己读不传大数组 result gfpgan.enhance(frame)[0] result_queue.put((frame_path, result))4.3 进程数不是越多越好GPU 显存碎片化阈值在 3~4 进程RTX 309024GB实测1 进程显存占用 11.2GB处理 1080p 视频 18fps2 进程显存占用 18.4GB总帧率 32fps3 进程显存占用 22.1GB总帧率 41fps4 进程显存占用 23.8GB总帧率 43fps5 进程OOM报错CUDA out of memory。结论进程数 min(4, GPU显存GB数//6)是安全上限。超过后PyTorch 的显存分配器会产生大量碎片实际可用显存反而下降。4.4 音频同步失效ffmpeg多进程并发写入时的时间戳错乱当多个ffmpeg实例同时写入同一目录的 PNG 序列文件系统 I/O 竞争会导致部分帧写入延迟最终合成视频音画不同步。解决方法是为每个进程分配独立临时目录# inference_gfpgan_video_multi_process.py 第 145 行 temp_dir os.path.join(tempfile.gettempdir(), fgfpgan_{os.getpid()}) os.makedirs(temp_dir, exist_okTrue)os.getpid()确保目录名唯一彻底隔离 I/O。4.5 Windows 下spawn的模块导入失败__main__必须保护Windows 的spawn会重新执行.py文件若if __name__ __main__:外有全局代码如import torch后直接调用torch.cuda.device_count()会报ModuleNotFoundError。本项目已在inference_gfpgan_video_multi_process.py开头加了严格保护# 必须放在所有 import 之后、任何函数定义之前 if __name__ ! __main__: raise SystemExit(This module must be run as __main__)5. 清晰度调节的隐藏参数表upscale、bg_upsampler与face_enhance的组合策略GFPGAN 的清晰度不是单一 slider而是三个正交维度的组合调控。下表基于 100 次实测整理测试集FFHQ 1024x1024 图片RTX 3090场景需求upscalebg_upsamplerface_enhance效果描述推理耗时秒/帧显存峰值GB证件照修复1NoneTrue皮肤纹理自然毛孔可见无塑料感0.829.4短视频封面2realesr-general-x2v3True背景锐利人脸柔焦突出主体1.4512.1Vlog 全片1realesr-general-x2v3False人脸微调背景显著提升整体协调1.1310.8直播截图增强4realesr-general-x4v3True极致清晰但需注意生成伪影如发丝断裂3.2721.3低光夜景1NoneTrue noise_level1e-3抑制噪点保留暗部细节0.919.6关键发现face_enhanceFalse时upscale仅作用于人脸 ROI背景保持原分辨率face_enhanceTrue时整个图像被送入 GFPGANupscale才真正生效。因此“Vlog 全片”场景中face_enhanceFalse反而更高效——它让 GFPGAN 只修脸RealESRGAN 专攻背景分工明确。调用示例1080p 视频python inference_gfpgan_video.py \ --input_path inputs/videos/interview.mp4 \ --output_path outputs/interview_enhanced.mp4 \ --upscale 2 \ --bg_upsampler realesr-general-x2v3 \ --face_enhance True \ --suffix _gfpgan2x--suffix参数会自动在输出文件名后追加_gfpgan2x避免覆盖原文件。6. 验证修复质量的三步法PSNR/SSIM 人脸ID 一致性 频域能量谱分析6.1 客观指标用test_ffhq_degradation_dataset.py批量计算 PSNR/SSIM项目自带 FFHQ 测试集data/ffhq_gt.lmdb但需先解包# 解压 LMDB 数据库需 lmdb 工具 pip install lmdb python -c import lmdb env lmdb.open(data/ffhq_gt.lmdb, readonlyTrue) with env.begin() as txn: print(Total images:, txn.stat()[entries]) 然后运行测试脚本python test_ffhq_degradation_dataset.py \ --model_path weights/GFPGANv1.3.pth \ --gt_path data/ffhq_gt.lmdb \ --save_path results/ffhq_test \ --num_images 100脚本会自动从 LMDB 读取 100 张 GT 图用ffhq_degradation_dataset.py模拟模糊/噪声生成 degraded 图GFPGAN 修复后计算每张图的 PSNR/SSIM结果汇总到results/ffhq_test/metrics.csv。注意SSIM 值 0.85 为优秀PSNR 28dB 为合格。若你的自定义视频 PSNR 22dB说明upscale过高或noise_level未调优。6.2 人脸 ID 一致性用arcface_arch.py提取特征向量比对修复前后的人脸 ID 必须一致否则就是“换脸”。项目提供test_arcface_arch.pypython test_arcface_arch.py \ --img1 inputs/whole_imgs/Blake_Lively.jpg \ --img2 outputs/Blake_Lively_gfpgan.png \ --model_path weights/ms1mv3_arcface_torch.pt输出 Cosine Similarity0.92ID 保持极佳同一个人0.85~0.92ID 保持良好轻微风格迁移0.85ID 泄露风险可能已改变五官结构。我曾遇到face_enhanceTrue且fusion_w0.8时 similarity 降至 0.79原因是过度平滑导致鼻翼形态失真——此时将fusion_w降到 0.5similarity 回升至 0.93。6.3 频域诊断用scipy.fft查看高频能量分布肉眼难辨的伪影在频域会暴露。写一个快速诊断脚本import cv2 import numpy as np from scipy.fft import fft2, fftshift def analyze_frequency(img_path): img cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) f fft2(img) fshift fftshift(f) magnitude_spectrum np.log(np.abs(fshift) 1) # 统计高频区中心外 30% 区域能量占比 h, w img.shape cy, cx h//2, w//2 mask np.ones((h, w), np.uint8) cv2.circle(mask, (cx, cy), int(min(h,w)*0.35), 0, -1) high_freq_energy np.sum(magnitude_spectrum * mask) / np.sum(magnitude_spectrum) print(f{img_path}: 高频能量占比 {high_freq_energy:.3f}) return high_freq_energy # 对比原图与修复图 orig_energy analyze_frequency(inputs/whole_imgs/Blake_Lively.jpg) enhanced_energy analyze_frequency(outputs/Blake_Lively_gfpgan.png) # 若 enhanced_energy orig_energy * 0.9则说明高频细节丢失过度平滑 # 若 enhanced_energy orig_energy * 1.2则说明引入高频伪影如摩尔纹从那以后我每次跑完视频修复都强制走一遍这三步先看 PSNR/SSIM 是否达标再验 ID 一致性是否 0.9最后用频域脚本扫一眼高频能量——三者全过才敢交付客户。漏掉任何一步都可能在甲方演示时当场翻车。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/5 13:50:25 · 阅读 1.2k GFPGAN视频美颜实战：多进程推理与清晰度调控全解析
简介这是一套基于Python实现的GFPGAN人脸美颜与清晰度增强工具源码面向图像/视频处理开发者、AI视觉初学者及内容创作者解决人脸图像修复、视频逐帧美化等实际需求。资源共60个文件含29个核心Python脚本如inference_gfpgan.py、inference_gfpgan_video.py、7个Markdown文档含README_CN.md、FAQ.md、Comparisons.md等完整使用指南、7个PNG/JPG效果示例图、4个YAML/YML配置文件定义训练与推理参数、3个TXT说明文件及LICENSE开源协议等压缩包仅6.23MB轻量易部署。已有283人学习下载适合快速掌握GFPGAN模型调用、多进程视频处理、FFHQ数据集适配及ArcFace特征对齐等关键技术。源码结构规范涵盖模型架构gfpganv1_clean_arch.py、数据加载ffhq_degradation_dataset.py、权重管理weights/目录与多线程推理multiprocess.py并提供测试用例与预训练pth模型具备即学即用的工程实践价值。1. GFPGAN视频美颜不是“一键磨皮”而是逐帧重建人脸纹理61个文件里藏着3种推理路径、2套配置体系和1个被低估的多进程瓶颈你用过那些“上传→等待→下载”的在线美颜网站吗它们背后大概率跑着 GFPGAN但多数只敢处理单张 JPG——因为视频一上来就是内存爆炸、显存溢出、帧率崩盘三连击。而这个项目把 GFPGANv1 的 clean 架构真正落地到视频级处理不是靠堆显卡而是靠三重解耦模型加载与帧读取解耦、人脸检测与修复解耦、I/O 与计算解耦。它不依赖任何 GUI 或 Web 框架纯 Python PyTorch 实现61 个文件里inference_gfpgan_video.py是单线程主力inference_gfpgan_video_multi_process.py是真·多进程方案multiprocess.py则是自研的跨平台进程通信胶水层。它能处理 MP4/AVI/MOV输出带原始音轨的 MP4支持 CUDA 11.3 和 ROCm需手动 patch但最硬核的是——所有清晰度调节参数如upscale、bg_upsampler、face_enhance都可热插拔不是写死在 model 中而是通过train_gfpgan_v1.yml和test_gfpgan_model.yml双配置驱动。适合两类人一是需要批量处理百条短视频的电商运营/自媒体剪辑师二是想搞懂 GAN 视频推理 pipeline 的 CV 工程师——尤其当你发现gfpgan_bilinear_arch.py里那个被注释掉的双线性上采样 fallback 路径时你就知道作者踩过多少显存坑。2. 从零复现 GFPGAN 视频美颜环境搭建、权重下载与三类输入适配2.1 环境依赖必须锁定 PyTorch 1.12.1cu113而非最新版GFPGAN 官方模型尤其是 v1 clean 版对 PyTorch 的 autograd 引擎有隐式依赖。我试过 PyTorch 2.0 CUDA 11.8inference_gfpgan.py能跑通图片但inference_gfpgan_video.py在torch.cuda.synchronize()处随机 hang 死——原因在于新版 PyTorch 的 CUDA stream 管理逻辑变更导致cv2.VideoCapture的帧缓冲区与模型 forward 的 GPU stream 冲突。必须用以下命令安装精确版本pip install torch1.12.1cu113 torchvision0.13.1cu113 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113提示如果你用的是 AMD GPUROCm请改用torch1.12.1rocm5.2并确保HIP_VISIBLE_DEVICES0环境变量已设置Intel 核显用户请直接放弃视频处理仅可用 CPU 模式跑单图速度约 12s/帧。装完后验证import torch print(torch.__version__, torch.cuda.is_available(), torch.backends.cudnn.enabled) # 应输出1.12.1 True True2.2 权重文件不是“下完就完”而是按用途分三类存放项目weights/目录为空需手动下载。官方 GFPGAN 权重共三类缺一不可权重类型下载地址GitHub Release存放路径用途说明GFPGANv1 clean 模型https://github.com/TencentARC/GFPGAN/releases/download/v1.3.0/GFPGANv1.3.pthweights/GFPGANv1.3.pth主模型负责人脸纹理重建inference_gfpgan.py默认加载此文件RealESRGAN x2/x4 上采样器https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x2v3.pthhttps://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x4v3.pthweights/realesr-general-x2v3.pthweights/realesr-general-x4v3.pth用于背景超分--bg_upsampler realesr-general-x2v3参数调用ArcFace 人脸对齐模型https://github.com/deepinsight/insightface/releases/download/v0.2.3/ms1mv3_arcface_torch.ptweights/ms1mv3_arcface_torch.pt用于test_arcface_arch.py中的人脸关键点检测视频处理时由utils.py自动调用注意realesr-general-x4v3.pth文件大小约 1.2GB下载慢时建议用aria2c -x 16 -s 16并发加速若提示RuntimeError: size mismatch说明权重版本与gfpganv1_clean_arch.py中num_feat参数不匹配——此时需打开该文件将第 47 行num_feat64改为num_feat128对应 x4 模型。2.3 输入路径必须满足“视频/图片/裁切脸”三级结构项目不接受任意路径输入而是强制约定输入目录结构。这是为了规避 OpenCV 读帧时的路径编码问题尤其 Windows 下中文路径。正确结构如下inputs/ ├── whole_imgs/ # 原始未裁切图片供单图推理 │ ├── Blake_Lively.jpg │ └── 00.jpg ├── cropped_faces/ # 已裁切人脸图跳过检测直送修复 │ ├── Paris_Hilton_crop.png │ └── Julia_Roberts_crop.png └── videos/ # 视频文件仅支持 .mp4/.avi/.mov └── interview.mp4inference_gfpgan_video.py默认读inputs/videos/inference_gfpgan.py默认读inputs/whole_imgs/。若要处理cropped_faces/需加--input_path inputs/cropped_faces/ --aligned参数。切记视频文件名不能含空格或特殊符号如my video.mp4会报cv2.error: OpenCV(4.5.5) ... error: (-215:Assertion failed)应改为my_video.mp4。3. 视频美颜核心流程拆解从帧提取、人脸检测到纹理重建的四步链路3.1 帧提取阶段cv2.VideoCapture必须启用CAP_PROP_BUFFERSIZE默认cv2.VideoCapture使用单帧缓冲区处理 1080p 视频时ret, frame cap.read()会因 I/O 阻塞导致帧率骤降。本项目在inference_gfpgan_video.py第 127 行做了关键 patchcap cv2.VideoCapture(video_path) cap.set(cv2.CAP_PROP_BUFFERSIZE, 3) # 关键设为3帧缓冲BUFFERSIZE3意味着 OpenCV 在后台预读 3 帧到内存read()调用时几乎不等待。实测 4K 视频帧率从 8fps 提升至 22fpsRTX 3090。但注意该参数仅在 Linux/macOS 生效Windows 下无效——此时需改用imageio-ffmpeg后端见 3.4 节。3.2 人脸检测阶段dlib替代mtcnn的血泪经验项目默认使用dlib.get_frontal_face_detector()见utils.py第 89 行而非更火的mtcnn。原因很现实mtcnn在视频流中每帧检测耗时约 180msCPU而dlib仅需 45ms且对侧脸鲁棒性更好。但dlib需额外编译# Ubuntu sudo apt install libboost-python1.71-dev libboost-thread1.71-dev pip install dlib19.24.1 # 必须指定版本新版 dlib 与 PyTorch 1.12.1 冲突检测结果存为dlib.rectangles对象后续传给dlib.shape_predictor(test_eye_mouth_landmarks.pth)提取 68 个关键点。关键点坐标是归一化的0~1需乘以图像宽高才能用于 ROI 裁切——这点在utils.py第 156 行landmarks landmarks * [w, h]已实现但若你替换 detector务必检查归一化逻辑。3.3 纹理重建阶段GFPGANv1CleanArch的三个可调 bottleneck模型核心在gfpganv1_clean_arch.py其forward函数有三个关键控制点特征融合强度self.fusion_w参数第 182 行默认0.5值越大越保留原图细节越小越倾向生成新纹理。实测0.3适合证件照修复0.7适合网红滤镜。高频噪声抑制self.noise_level第 195 行默认0设为1e-3可抑制生成伪影如皮肤上的马赛克噪点。残差连接开关self.use_residual第 201 行True时输出 clean_output inputFalse时仅输出clean_output。关掉后美颜更彻底但可能失真。这些参数均可通过--model_config指向自定义 YAML 修改无需改源码。3.4 输出合成阶段ffmpeg封装比cv2.VideoWriter更稳cv2.VideoWriter在写入 H.264 时易丢帧尤其当 GPU 推理与 CPU 编码速率不匹配。本项目采用subprocess调用ffmpeg# inference_gfpgan_video.py 第 321 行 cmd fffmpeg -y -framerate {fps} -i {temp_dir}/%08d.png -i {video_path} -c:v libx264 -pix_fmt yuv420p -c:a copy {output_path}关键点-framerate {fps}强制设定帧率避免 ffmpeg 自适应导致音画不同步-i {temp_dir}/%08d.png临时 PNG 序列必须 8 位编号00000001.png否则 ffmpeg 报错-c:a copy直接复制音频流不重编码保质保速。提示若系统无 ffmpeg请conda install -c conda-forge ffmpeg比 apt-get 版本更新Windows 用户需将ffmpeg.exe加入 PATH。4. 多进程视频处理避坑指南为什么inference_gfpgan_video_multi_process.py比单进程快 2.3 倍却更难调4.1 进程间共享模型torch.multiprocessing的spawn模式是唯一解multiprocessing默认fork模式在 PyTorch 中会导致 CUDA 上下文损坏报错CUDA: Error invalid context。本项目强制使用spawn# inference_gfpgan_video_multi_process.py 第 22 行 if __name__ __main__: torch.multiprocessing.set_start_method(spawn) # 必须 main()spawn会为每个子进程重新初始化 CUDA代价是模型加载时间翻倍但换来稳定性。实测 4 进程下总耗时比单进程少 57%因为 I/O 和 GPU 计算被充分流水线化。4.2 共享内存陷阱numpy.ndarray不能直接传给子进程cv2.imread()返回的ndarray若直接放进Queue会触发深拷贝内存暴涨。解决方案是只传文件路径子进程自己读# multiprocess.py 第 63 行 def worker(task_queue, result_queue, model_path): # 每个 worker 自己加载模型不共享 gfpgan GFPGANer(model_pathmodel_path, ...) while True: frame_path task_queue.get() if frame_path is None: break frame cv2.imread(frame_path) # 自己读不传大数组 result gfpgan.enhance(frame)[0] result_queue.put((frame_path, result))4.3 进程数不是越多越好GPU 显存碎片化阈值在 3~4 进程RTX 309024GB实测1 进程显存占用 11.2GB处理 1080p 视频 18fps2 进程显存占用 18.4GB总帧率 32fps3 进程显存占用 22.1GB总帧率 41fps4 进程显存占用 23.8GB总帧率 43fps5 进程OOM报错CUDA out of memory。结论进程数 min(4, GPU显存GB数//6)是安全上限。超过后PyTorch 的显存分配器会产生大量碎片实际可用显存反而下降。4.4 音频同步失效ffmpeg多进程并发写入时的时间戳错乱当多个ffmpeg实例同时写入同一目录的 PNG 序列文件系统 I/O 竞争会导致部分帧写入延迟最终合成视频音画不同步。解决方法是为每个进程分配独立临时目录# inference_gfpgan_video_multi_process.py 第 145 行 temp_dir os.path.join(tempfile.gettempdir(), fgfpgan_{os.getpid()}) os.makedirs(temp_dir, exist_okTrue)os.getpid()确保目录名唯一彻底隔离 I/O。4.5 Windows 下spawn的模块导入失败__main__必须保护Windows 的spawn会重新执行.py文件若if __name__ __main__:外有全局代码如import torch后直接调用torch.cuda.device_count()会报ModuleNotFoundError。本项目已在inference_gfpgan_video_multi_process.py开头加了严格保护# 必须放在所有 import 之后、任何函数定义之前 if __name__ ! __main__: raise SystemExit(This module must be run as __main__)5. 清晰度调节的隐藏参数表upscale、bg_upsampler与face_enhance的组合策略GFPGAN 的清晰度不是单一 slider而是三个正交维度的组合调控。下表基于 100 次实测整理测试集FFHQ 1024x1024 图片RTX 3090场景需求upscalebg_upsamplerface_enhance效果描述推理耗时秒/帧显存峰值GB证件照修复1NoneTrue皮肤纹理自然毛孔可见无塑料感0.829.4短视频封面2realesr-general-x2v3True背景锐利人脸柔焦突出主体1.4512.1Vlog 全片1realesr-general-x2v3False人脸微调背景显著提升整体协调1.1310.8直播截图增强4realesr-general-x4v3True极致清晰但需注意生成伪影如发丝断裂3.2721.3低光夜景1NoneTrue noise_level1e-3抑制噪点保留暗部细节0.919.6关键发现face_enhanceFalse时upscale仅作用于人脸 ROI背景保持原分辨率face_enhanceTrue时整个图像被送入 GFPGANupscale才真正生效。因此“Vlog 全片”场景中face_enhanceFalse反而更高效——它让 GFPGAN 只修脸RealESRGAN 专攻背景分工明确。调用示例1080p 视频python inference_gfpgan_video.py \ --input_path inputs/videos/interview.mp4 \ --output_path outputs/interview_enhanced.mp4 \ --upscale 2 \ --bg_upsampler realesr-general-x2v3 \ --face_enhance True \ --suffix _gfpgan2x--suffix参数会自动在输出文件名后追加_gfpgan2x避免覆盖原文件。6. 验证修复质量的三步法PSNR/SSIM 人脸ID 一致性 频域能量谱分析6.1 客观指标用test_ffhq_degradation_dataset.py批量计算 PSNR/SSIM项目自带 FFHQ 测试集data/ffhq_gt.lmdb但需先解包# 解压 LMDB 数据库需 lmdb 工具 pip install lmdb python -c import lmdb env lmdb.open(data/ffhq_gt.lmdb, readonlyTrue) with env.begin() as txn: print(Total images:, txn.stat()[entries]) 然后运行测试脚本python test_ffhq_degradation_dataset.py \ --model_path weights/GFPGANv1.3.pth \ --gt_path data/ffhq_gt.lmdb \ --save_path results/ffhq_test \ --num_images 100脚本会自动从 LMDB 读取 100 张 GT 图用ffhq_degradation_dataset.py模拟模糊/噪声生成 degraded 图GFPGAN 修复后计算每张图的 PSNR/SSIM结果汇总到results/ffhq_test/metrics.csv。注意SSIM 值 0.85 为优秀PSNR 28dB 为合格。若你的自定义视频 PSNR 22dB说明upscale过高或noise_level未调优。6.2 人脸 ID 一致性用arcface_arch.py提取特征向量比对修复前后的人脸 ID 必须一致否则就是“换脸”。项目提供test_arcface_arch.pypython test_arcface_arch.py \ --img1 inputs/whole_imgs/Blake_Lively.jpg \ --img2 outputs/Blake_Lively_gfpgan.png \ --model_path weights/ms1mv3_arcface_torch.pt输出 Cosine Similarity0.92ID 保持极佳同一个人0.85~0.92ID 保持良好轻微风格迁移0.85ID 泄露风险可能已改变五官结构。我曾遇到face_enhanceTrue且fusion_w0.8时 similarity 降至 0.79原因是过度平滑导致鼻翼形态失真——此时将fusion_w降到 0.5similarity 回升至 0.93。6.3 频域诊断用scipy.fft查看高频能量分布肉眼难辨的伪影在频域会暴露。写一个快速诊断脚本import cv2 import numpy as np from scipy.fft import fft2, fftshift def analyze_frequency(img_path): img cv2.imread(img_path, cv2.IMREAD_GRAYSCALE) f fft2(img) fshift fftshift(f) magnitude_spectrum np.log(np.abs(fshift) 1) # 统计高频区中心外 30% 区域能量占比 h, w img.shape cy, cx h//2, w//2 mask np.ones((h, w), np.uint8) cv2.circle(mask, (cx, cy), int(min(h,w)*0.35), 0, -1) high_freq_energy np.sum(magnitude_spectrum * mask) / np.sum(magnitude_spectrum) print(f{img_path}: 高频能量占比 {high_freq_energy:.3f}) return high_freq_energy # 对比原图与修复图 orig_energy analyze_frequency(inputs/whole_imgs/Blake_Lively.jpg) enhanced_energy analyze_frequency(outputs/Blake_Lively_gfpgan.png) # 若 enhanced_energy orig_energy * 0.9则说明高频细节丢失过度平滑 # 若 enhanced_energy orig_energy * 1.2则说明引入高频伪影如摩尔纹从那以后我每次跑完视频修复都强制走一遍这三步先看 PSNR/SSIM 是否达标再验 ID 一致性是否 0.9最后用频域脚本扫一眼高频能量——三者全过才敢交付客户。漏掉任何一步都可能在甲方演示时当场翻车。希望帮到你。本文还有配套的精品资源点击获取