尧图网页设计 
CodeFormer 使用与原理全解基于 Codebook Lookup Transformer 的盲人脸复原实战指南NeurIPS 2022【免费下载链接】CodeFormer[NeurIPS 2022] Towards Robust Blind Face Restoration with Codebook Lookup Transformer项目地址: https://gitcode.com/gh_mirrors/co/CodeFormer本文以 CodeFormerNeurIPS 2022 论文Towards Robust Blind Face Restoration with Codebook Lookup Transformer官方仓库 README 为骨架系统讲解其在真实场景中的完整使用链路环境安装、预训练模型下载、测试数据对齐、四种推理模式裁剪人脸复原、整图增强、视频增强、着色与修复以及三阶段训练流程同时结合 inference_codeformer.py、codeformer_arch.py、face_restoration_helper.py 等源码深入解析w保真度权重、Codebook Lookup Transformer 架构与人脸-背景融合等底层原理。读者学完后即可独立复现论文级推理效果并理解如何将 CodeFormer 集成到自己的图像/视频增强管线中。CodeFormer 由南洋理工大学 S-Lab 的 Shangchen Zhou、Kelvin C.K. Chan、Chongyi Li 与 Chen Change Loy 提出用于解决盲人脸复原blind face restoration这一极具挑战性的问题——输入图片的退化类型与程度完全未知低分辨率、模糊、噪声、JPEG 压缩伪影等任意组合。项目基于 BasicSR 框架构建并集成 facelib 人脸检测/解析管线与 Real-ESRGAN 背景增强器提供人脸复原、颜色增强与复原、人脸修复inpainting、人脸着色colorization以及视频增强等开箱即用能力。一、核心思想为什么用 Codebook Lookup Transformer传统盲复原方法通常直接对退化图像做端到端映射容易丢失身份信息或产生过度平滑的结果。CodeFormer 的思路截然不同先学习一个高质量人脸先验词典codebook再在推理时用 Transformer 从词典中检索lookup出最匹配的干净人脸组件。从源码 codeformer_arch.py 可以看到CodeFormer类继承自VQAutoEncoder整体由三部分构成VQGAN 编码器将 512×512 人脸下采样为 16×16 的特征网格ch_mult[1, 2, 2, 4, 4, 8]总下采样 32 倍Codebook 预测 Transformern_layers9层TransformerSALayer自注意力 MLP LayerNorm对编码器输出特征做全局建模后通过idx_pred_layer输出每个 token 在 codebookcodebook_size1024上的 logits再经 softmax 选出最接近的码本条目quant_feat可控融合解码器Generator将检索到的干净特征与编码器各尺度的退化特征通过Fuse_sft_block融合生成最终复原结果。关键设计是解码阶段的分层融合。CodeFormer.forwardcodeformer_arch.py中编码器在分辨率 32/64/128/256 的特征会被保存解码器每经过若干残差块后调用一次Fuse_sft_block用w控制码本先验与输入细节的混合比例residual w * (dec_feat * scale shift) out dec_feat residual正是这个wfidelity weight让 CodeFormer 可以在高质量复原与高输入保真之间连续调节这也是下文推理参数的核心。二、环境依赖与安装官方 README 给出的环境要求如下PyTorch 1.7.1CUDA 10.1其余依赖见 requirements.txt推荐使用 Anaconda 创建独立环境以 Python 3.8 为例# 克隆仓库并进入目录 git clone https://github.com/sczhou/CodeFormer cd CodeFormer # 创建并激活 conda 环境 conda create -n codeformer python3.8 -y conda activate codeformer # 安装 Python 依赖 pip3 install -r requirements.txt # 以 develop 模式安装 BasicSRbasicsr/setup.py 中的编译含 CUDA 算子 python basicsr/setup.py develop # 仅当需要使用 dlib 做人脸检测/裁剪时 conda install -c conda-forge dlib需要说明python basicsr/setup.py develop会编译 basicsr/ops 下的 DCN可变形卷积、fused_act、upfirdn2d 等 CUDA 算子因此需要可用的 CUDA 编译工具链。仓库 inference_codeformer.py 中也有提示CPU 上运行 Real-ESRGAN 背景增强会很慢若在 CPU 环境建议去掉--bg_upsampler与--face_upsample参数。三、预训练模型下载推理前必须下载两类模型统一放入weights/目录。仓库提供 download_pretrained_models.py 一键脚本内部封装了load_file_from_url断点续传并显示进度# 1) 人脸检测/解析模型facelib必须 python scripts/download_pretrained_models.py facelib # 2) 仅当使用 dlib 人脸检测器时需要 python scripts/download_pretrained_models.py dlib # 3) CodeFormer 复原主模型必须 python scripts/download_pretrained_models.py CodeFormer也可以从官方 Releases 的 v0.1.0 版本手动下载后放入对应目录。从脚本源码download_pretrained_models.py可确认各文件用途目标目录文件用途weights/facelib/detection_Resnet50_Final.pthRetinaFace 人脸检测weights/facelib/parsing_parsenet.pthBiSeNet/ParseNet 人脸解析用于边界融合掩码weights/dlib/mmod_human_face_detector-4cb19393.datdlib CNN 人脸检测器weights/dlib/shape_predictor_5_face_landmarks-c4b1e980.datdlib 5 点关键点模型weights/CodeFormer/codeformer.pthCodeFormer 复原主模型Stage III 训练产出训练相关模型vqgan_code1024.pth、latent_gt_code1024.pth、codeformer_stage2.pth可通过python scripts/download_pretrained_models.py CodeFormer_train获取详见后文训练章节。着色与修复模型codeformer_colorization.pth、codeformer_inpainting.pth则在推理脚本运行时由 inference_colorization.py 与 inference_inpainting.py 自动下载到weights/CodeFormer/。四、准备测试数据人脸检测、裁剪与对齐CodeFormer 的核心输入是 512×512 的对齐人脸。对于整图输入推理脚本会内置完成检测与对齐但如果你的数据是普通照片且想复用为裁剪对齐人脸例如批量处理、或论文对比实验需要先用脚本预处理# 需要 dlib 环境 python scripts/crop_align_face.py -i [input folder] -o [output folder]该脚本crop_align_face.py采用 FFHQ 数据集的经典对齐方案先用 dlib 正脸检测器定位人脸默认只保留面积最大的一张提取 68 点关键点后依据双眼连线与嘴部位置计算仿射矩阵将人脸旋转、缩放并裁剪为 512×512输出统一转为.png。对齐后的结果可直接放入inputs/cropped_faces/或供着色/修复任务使用。仓库自带示例数据可直接体验整图输入inputs/whole_imgs裁剪对齐人脸inputs/cropped_faces灰度人脸着色任务inputs/gray_faces白笔遮挡人脸修复任务inputs/masked_faces五、快速推理人脸复原核心命令复原推理统一入口为 inference_codeformer.py支持三种输入形式单张图片路径、图片文件夹、视频文件视频以.mp4/.mov/.avi结尾。论文对比注意事项README 原文强调若要在论文中对比 CodeFormer请务必添加--has_aligned参数使用裁剪对齐人脸输入。整图推理涉及人脸-背景融合过程可能损伤边界处的头发纹理导致不公平比较。5.1 裁剪对齐人脸复原512×512python inference_codeformer.py -w 0.5 --has_aligned --input_path [image folder]|[image path]5.2 整图增强# 基础整图复原 python inference_codeformer.py -w 0.7 --input_path [image folder]|[image path] # 使用 Real-ESRGAN 增强背景区域推荐 python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --input_path [image folder]|[image path] # 进一步用 Real-ESRGAN 上采样已复原的人脸 python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --face_upsample --input_path [image folder]|[image path]5.3 视频增强# Windows/Mac 用户需先安装 ffmpeg conda install -c conda-forge ffmpeg# 视频路径必须以 .mp4 / .mov / .avi 结尾 python inference_codeformer.py --bg_upsampler realesrgan --face_upsample -w 1.0 --input_path [video path]视频处理在源码中有完整闭环inference_codeformer.pyVideoReader逐帧读取含音频提取逐帧复原后由VideoWriter以原 fps或--save_video_fps指定重新封装为 mp4。注意视频场景推荐-w 1.0以保证帧间身份一致性。5.4 理解 fidelity weightww是 CodeFormer 最核心的推理参数取值范围[0, 1]。README 给出的经验准则一般而言较小的w倾向于产生更高质量更生成的结果较大的w产生更高保真更贴近原输入的结果。在源码层面codeformer_arch.pyw0时解码器完全信任码本先验、跳过所有融合块输出最干净但可能偏离输入w1时融合块以全强度注入编码器细节输出最忠实于退化输入。对应关系追求美观修复老照片w取 0.3~0.7追求身份保真视频、论文对比w取 0.8~1.0更多场景可结合--bg_upsampler realesrgan与--face_upsample获得更高分辨率输出。所有结果默认保存到results/目录子目录结构为cropped_faces/裁剪人脸、restored_faces/单张复原人脸、final_results/整图/视频帧复原结果。六、进阶任务一灰度照片着色Face Colorization对 512×512 裁剪对齐的黑白或褪色照片可用 inference_colorization.py 一键着色# 输入为裁剪对齐人脸512x512 python inference_colorization.py --input_path [image folder]|[image path]源码关键点inference_colorization.py网络配置为codebook_size512、connect_list[32,64,128]比复原任务少了 256 分辨率融合层w被固定为 0、adainTrue——代码注释明确说明w is fixed to 0 since we didnt train the Stage III for colorization未训练着色版 Stage III因此输出完全依赖码本先验输入必须严格为 512×512脚本通过assert强制校验结果保存于results/input_name/支持--suffix与--output_path参数。示例数据见 inputs/gray_faces。值得注意的是CodeFormer 的着色本质是在灰度输入上利用码本先验恢复颜色分布其效果在下文颜色增强与复原结果图中亦有体现。七、进阶任务二人脸修复Face Inpainting对人脸区域存在遮挡/缺损的图像用 Photoshop 等工具以白色画笔标记待修复区域可用 inference_inpainting.py 修复# 输入为裁剪对齐人脸512x512白笔掩码示例见 inputs/masked_faces python inference_inpainting.py --input_path [image folder]|[image path]该脚本的掩码生成逻辑非常巧妙inference_inpainting.py由于输入是 512×512 对齐人脸脚本将每个像素的三通道 RGB 求和sum 3即纯白的像素视为掩码区域随后以w1、adainFalse推理并将掩码内像素替换为模型输出、掩码外像素保留原图mask[m_ind 3] 1.0 output_face net(input_face, w1, adainFalse)[0] output_face (1 - mask) * input_face mask * output_face即只有被白笔覆盖的区域被重建其余区域严格保真这与着色任务全图重建形成鲜明对比。修复模型的 codebook 大小为 512同样要求输入严格 512×512。八、推理脚本与底层管线深度解析8.1 全部命令行参数来自 inference_codeformer.py参数默认值说明-i, --input_path./inputs/whole_imgs输入图片/视频/文件夹-o, --output_pathNone输出目录默认results/输入名_w-w, --fidelity_weight0.5质量与保真度平衡权重范围 [0, 1]-s, --upscale2最终上采样倍数--has_alignedFalse输入为已裁剪对齐人脸跳过检测/对齐--only_center_faceFalse仅复原画面中心的人脸--draw_boxFalse在输出图中绘制检测框--detection_modelretinaface_resnet50人脸检测器retinaface_resnet50、retinaface_mobile0.25、YOLOv5l、YOLOv5n、dlib--bg_upsamplerNone背景上采样器可选realesrgan--face_upsampleFalse复原后用 Real-ESRGAN 额外上采样人脸--bg_tile400背景上采样的分块尺寸省显存--suffixNone输出文件名后缀--save_video_fpsNone输出视频帧率默认沿用输入源码注释提示检测模型分两档大模型YOLOv5l/retinaface_resnet50精度更高小模型YOLOv5n/retinaface_mobile0.25速度更快。README 更新日志还提到dlib检测器produces more accurate face identity人脸身份更准确。8.2 复原网络与数据预处理推理脚本固定按以下配置实例化网络inference_codeformer.py与 Stage II/III 训练配置保持一致net ARCH_REGISTRY.get(CodeFormer)(dim_embd512, codebook_size1024, n_head8, n_layers9, connect_list[32, 64, 128, 256])输入预处理为像素归一化到[0,1]→ BGR 转 RGB → 以均值/方差(0.5,0.5,0.5)做标准化推理在torch.no_grad()下进行输出经tensor2img(..., min_max(-1,1))还原为 uint8 图。加载权重时取 checkpoint 中的params_ema字段EMA 权重这也是 BasicSR 框架的标准约定。8.3 整图处理管线从检测到融合回贴整图输入时FaceRestoreHelper 承载完整流水线inference_codeformer.py读取与预处理read_image处理 16-bit、灰度、带 alpha 通道等输入短边不足 512 自动放大人脸检测与关键点get_face_landmarks_5先将图缩放到短边 640 再检测默认eye_dist_threshold5过滤过小/侧脸支持only_center_face/只保留最大脸等策略对齐裁剪align_warp_face用 5 点关键点FFHQ 标准模板估计仿射矩阵并裁剪 512×512 人脸人脸复原CodeFormer 逐张推理灰度输入自动检测is_gray并在回贴阶段转回灰度、做 AdaIN 颜色迁移以保持灰度风格背景增强bg_upsamplerReal-ESRGAN x2增强背景face_upsample可选地再对人脸做一次超分融合回贴paste_faces_to_input_image将复原人脸经逆仿射变换贴回先用膨胀腐蚀生成软掩码再调用ParseNet 人脸解析use_parseTrueface_restoration_helper.py生成五官级掩码仅融合脸部区域而保留发际线等边界纹理——这正是 README 提醒整图命令可能损伤边界头发纹理的原因也是论文对比须用--has_aligned的原因。九、三阶段训练流程Training训练命令与说明详见 docs/train.md另有 docs/train_CN.md 中文版。训练数据使用 FFHQ 数据集。项目采用 BasicSR 框架分布式训练入口统一为basicsr/train.py -opt 配置 --launcher pytorchPyTorch 1.10 时请将python -m torch.distributed.launch替换为torchrun。Stage I训练 VQGAN 码本python -m torch.distributed.launch --nproc_per_nodegpu_num --master_port4321 \ basicsr/train.py -opt options/VQGAN_512_ds32_nearest_stage1.yml --launcher pytorch配置见 VQGAN_512_ds32_nearest_stage1.ymlVQAutoEncodernf64, ch_mult[1,2,2,4,4,8], quantizernearest, codebook_size1024配VQGANDiscriminator训练 160 万迭代损失为 L1 LPIPS hinge GAN。训练完成后建议预计算整个数据集的码序列以加速后续阶段python scripts/generate_latent_gt.py若不想自训 VQGAN可直接使用官方预训练vqgan_code1024.pth与对应的latent_gt_code1024.pth通过download_pretrained_models.py CodeFormer_train获取。Stage II训练 Code Sequence Predictionw0python -m torch.distributed.launch --nproc_per_nodegpu_num --master_port4322 \ basicsr/train.py -opt options/CodeFormer_stage2.yml --launcher pytorch配置见 CodeFormer_stage2.yml模型类型CodeFormerIdxModelfidelity_weight: 0冻结quantize与generatorfix_modules仅训练 Transformer 的码索引预测模块损失为交叉熵cross_entropy_loss权重 0.5 高分辨率特征损失use_hq_feat_loss权重 1.0共 50 万迭代。此阶段数据采用大退化blur_sigma: [1,15]、downsample_range: [4,30]、noise_range: [0,20]、jpeg_range: [30,80]以覆盖重度损坏输入。Stage III训练可控融合模块w1python -m torch.distributed.launch --nproc_per_nodegpu_num --master_port4323 \ basicsr/train.py -opt options/CodeFormer_stage3.yml --launcher pytorch配置见 CodeFormer_stage3.yml模型类型CodeFormerJointModel从 Stage II 权重pretrain_network_g与判别器权重恢复训练中w随机采样使模型学会全范围保真度控制。损失叠加 L1、LPIPS、hinge GANscale_adaptive_gan_weight: 0.1并采用大退化 小退化联合采样*_large参数共 15 万迭代ema_decay: 0.997。最终产出的codeformer.pth即推理脚本使用的复原主模型。十、在线体验与生态集成官方维护的在线 Demo 部署于 Hugging Face Space、Replicate 与 OpenXLab 平台2022.09–2023.07 陆续集成见 README Update 记录无需本地环境即可体验老照片修复与 AI 生成人脸的修复效果。README 同时列出大量第三方非官方的网站、API 平台与开源工具集成如 Stable Diffusion WebUI、ComfyUI、ChaiNNer 等 GUI/工具链对 CodeFormer 的集成并特别警示除官方三平台外其余均为第三方部署、未获作者授权使用时需自行甄别合法性以避免财产损失。仓库内还提供了可参考的部署实现web-demos/hugging_face/app.py 与 web-demos/replicate/predict.py。十一、引用与许可项目遵循NTU S-Lab License 1.0见 LICENSE。若你的研究使用了 CodeFormer请按 README 中的 BibTeX 引用 NeurIPS 2022 论文。项目致谢中说明其基于 BasicSR 构建部分代码来自 Unleashing Transformers、YOLOv5-face 与 FaceXLib并采用 Real-ESRGAN 支持背景增强。十二、常见问题与实用建议CPU 运行慢Real-ESRGAN 背景增强在 CPU 上未经优化、速度很慢纯 CPU 场景建议移除--bg_upsampler/--face_upsampleinference_codeformer.py 有运行时警告显存不足调小--bg_tile默认 400可显著降低背景上采样的显存占用多脸照片默认复原所有检测到的人脸--only_center_face只处理中心人脸--draw_box可可视化检测框辅助调试灰度老照片整图复原时脚本会自动检测灰度输入并在回贴阶段执行灰度还原与颜色迁移adain_npy避免着色失真输入路径必须以.mp4/.mov/.avi结尾才会被识别为视频否则会被当作文件夹扫描glob只匹配 jpg/png无匹配文件会抛出FileNotFoundError着色/修复必须用 512×512 对齐人脸脚本会assert校验分辨率未对齐输入请先用scripts/crop_align_face.py预处理。【免费下载链接】CodeFormer[NeurIPS 2022] Towards Robust Blind Face Restoration with Codebook Lookup Transformer项目地址: https://gitcode.com/gh_mirrors/co/CodeFormer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CodeFormer 使用与原理全解：基于 Codebook Lookup Transformer 的盲人脸复原实战指南（NeurIPS 2022）
CodeFormer 使用与原理全解基于 Codebook Lookup Transformer 的盲人脸复原实战指南NeurIPS 2022【免费下载链接】CodeFormer[NeurIPS 2022] Towards Robust Blind Face Restoration with Codebook Lookup Transformer项目地址: https://gitcode.com/gh_mirrors/co/CodeFormer本文以 CodeFormerNeurIPS 2022 论文Towards Robust Blind Face Restoration with Codebook Lookup Transformer官方仓库 README 为骨架系统讲解其在真实场景中的完整使用链路环境安装、预训练模型下载、测试数据对齐、四种推理模式裁剪人脸复原、整图增强、视频增强、着色与修复以及三阶段训练流程同时结合 inference_codeformer.py、codeformer_arch.py、face_restoration_helper.py 等源码深入解析w保真度权重、Codebook Lookup Transformer 架构与人脸-背景融合等底层原理。读者学完后即可独立复现论文级推理效果并理解如何将 CodeFormer 集成到自己的图像/视频增强管线中。CodeFormer 由南洋理工大学 S-Lab 的 Shangchen Zhou、Kelvin C.K. Chan、Chongyi Li 与 Chen Change Loy 提出用于解决盲人脸复原blind face restoration这一极具挑战性的问题——输入图片的退化类型与程度完全未知低分辨率、模糊、噪声、JPEG 压缩伪影等任意组合。项目基于 BasicSR 框架构建并集成 facelib 人脸检测/解析管线与 Real-ESRGAN 背景增强器提供人脸复原、颜色增强与复原、人脸修复inpainting、人脸着色colorization以及视频增强等开箱即用能力。一、核心思想为什么用 Codebook Lookup Transformer传统盲复原方法通常直接对退化图像做端到端映射容易丢失身份信息或产生过度平滑的结果。CodeFormer 的思路截然不同先学习一个高质量人脸先验词典codebook再在推理时用 Transformer 从词典中检索lookup出最匹配的干净人脸组件。从源码 codeformer_arch.py 可以看到CodeFormer类继承自VQAutoEncoder整体由三部分构成VQGAN 编码器将 512×512 人脸下采样为 16×16 的特征网格ch_mult[1, 2, 2, 4, 4, 8]总下采样 32 倍Codebook 预测 Transformern_layers9层TransformerSALayer自注意力 MLP LayerNorm对编码器输出特征做全局建模后通过idx_pred_layer输出每个 token 在 codebookcodebook_size1024上的 logits再经 softmax 选出最接近的码本条目quant_feat可控融合解码器Generator将检索到的干净特征与编码器各尺度的退化特征通过Fuse_sft_block融合生成最终复原结果。关键设计是解码阶段的分层融合。CodeFormer.forwardcodeformer_arch.py中编码器在分辨率 32/64/128/256 的特征会被保存解码器每经过若干残差块后调用一次Fuse_sft_block用w控制码本先验与输入细节的混合比例residual w * (dec_feat * scale shift) out dec_feat residual正是这个wfidelity weight让 CodeFormer 可以在高质量复原与高输入保真之间连续调节这也是下文推理参数的核心。二、环境依赖与安装官方 README 给出的环境要求如下PyTorch 1.7.1CUDA 10.1其余依赖见 requirements.txt推荐使用 Anaconda 创建独立环境以 Python 3.8 为例# 克隆仓库并进入目录 git clone https://github.com/sczhou/CodeFormer cd CodeFormer # 创建并激活 conda 环境 conda create -n codeformer python3.8 -y conda activate codeformer # 安装 Python 依赖 pip3 install -r requirements.txt # 以 develop 模式安装 BasicSRbasicsr/setup.py 中的编译含 CUDA 算子 python basicsr/setup.py develop # 仅当需要使用 dlib 做人脸检测/裁剪时 conda install -c conda-forge dlib需要说明python basicsr/setup.py develop会编译 basicsr/ops 下的 DCN可变形卷积、fused_act、upfirdn2d 等 CUDA 算子因此需要可用的 CUDA 编译工具链。仓库 inference_codeformer.py 中也有提示CPU 上运行 Real-ESRGAN 背景增强会很慢若在 CPU 环境建议去掉--bg_upsampler与--face_upsample参数。三、预训练模型下载推理前必须下载两类模型统一放入weights/目录。仓库提供 download_pretrained_models.py 一键脚本内部封装了load_file_from_url断点续传并显示进度# 1) 人脸检测/解析模型facelib必须 python scripts/download_pretrained_models.py facelib # 2) 仅当使用 dlib 人脸检测器时需要 python scripts/download_pretrained_models.py dlib # 3) CodeFormer 复原主模型必须 python scripts/download_pretrained_models.py CodeFormer也可以从官方 Releases 的 v0.1.0 版本手动下载后放入对应目录。从脚本源码download_pretrained_models.py可确认各文件用途目标目录文件用途weights/facelib/detection_Resnet50_Final.pthRetinaFace 人脸检测weights/facelib/parsing_parsenet.pthBiSeNet/ParseNet 人脸解析用于边界融合掩码weights/dlib/mmod_human_face_detector-4cb19393.datdlib CNN 人脸检测器weights/dlib/shape_predictor_5_face_landmarks-c4b1e980.datdlib 5 点关键点模型weights/CodeFormer/codeformer.pthCodeFormer 复原主模型Stage III 训练产出训练相关模型vqgan_code1024.pth、latent_gt_code1024.pth、codeformer_stage2.pth可通过python scripts/download_pretrained_models.py CodeFormer_train获取详见后文训练章节。着色与修复模型codeformer_colorization.pth、codeformer_inpainting.pth则在推理脚本运行时由 inference_colorization.py 与 inference_inpainting.py 自动下载到weights/CodeFormer/。四、准备测试数据人脸检测、裁剪与对齐CodeFormer 的核心输入是 512×512 的对齐人脸。对于整图输入推理脚本会内置完成检测与对齐但如果你的数据是普通照片且想复用为裁剪对齐人脸例如批量处理、或论文对比实验需要先用脚本预处理# 需要 dlib 环境 python scripts/crop_align_face.py -i [input folder] -o [output folder]该脚本crop_align_face.py采用 FFHQ 数据集的经典对齐方案先用 dlib 正脸检测器定位人脸默认只保留面积最大的一张提取 68 点关键点后依据双眼连线与嘴部位置计算仿射矩阵将人脸旋转、缩放并裁剪为 512×512输出统一转为.png。对齐后的结果可直接放入inputs/cropped_faces/或供着色/修复任务使用。仓库自带示例数据可直接体验整图输入inputs/whole_imgs裁剪对齐人脸inputs/cropped_faces灰度人脸着色任务inputs/gray_faces白笔遮挡人脸修复任务inputs/masked_faces五、快速推理人脸复原核心命令复原推理统一入口为 inference_codeformer.py支持三种输入形式单张图片路径、图片文件夹、视频文件视频以.mp4/.mov/.avi结尾。论文对比注意事项README 原文强调若要在论文中对比 CodeFormer请务必添加--has_aligned参数使用裁剪对齐人脸输入。整图推理涉及人脸-背景融合过程可能损伤边界处的头发纹理导致不公平比较。5.1 裁剪对齐人脸复原512×512python inference_codeformer.py -w 0.5 --has_aligned --input_path [image folder]|[image path]5.2 整图增强# 基础整图复原 python inference_codeformer.py -w 0.7 --input_path [image folder]|[image path] # 使用 Real-ESRGAN 增强背景区域推荐 python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --input_path [image folder]|[image path] # 进一步用 Real-ESRGAN 上采样已复原的人脸 python inference_codeformer.py -w 0.7 --bg_upsampler realesrgan --face_upsample --input_path [image folder]|[image path]5.3 视频增强# Windows/Mac 用户需先安装 ffmpeg conda install -c conda-forge ffmpeg# 视频路径必须以 .mp4 / .mov / .avi 结尾 python inference_codeformer.py --bg_upsampler realesrgan --face_upsample -w 1.0 --input_path [video path]视频处理在源码中有完整闭环inference_codeformer.pyVideoReader逐帧读取含音频提取逐帧复原后由VideoWriter以原 fps或--save_video_fps指定重新封装为 mp4。注意视频场景推荐-w 1.0以保证帧间身份一致性。5.4 理解 fidelity weightww是 CodeFormer 最核心的推理参数取值范围[0, 1]。README 给出的经验准则一般而言较小的w倾向于产生更高质量更生成的结果较大的w产生更高保真更贴近原输入的结果。在源码层面codeformer_arch.pyw0时解码器完全信任码本先验、跳过所有融合块输出最干净但可能偏离输入w1时融合块以全强度注入编码器细节输出最忠实于退化输入。对应关系追求美观修复老照片w取 0.3~0.7追求身份保真视频、论文对比w取 0.8~1.0更多场景可结合--bg_upsampler realesrgan与--face_upsample获得更高分辨率输出。所有结果默认保存到results/目录子目录结构为cropped_faces/裁剪人脸、restored_faces/单张复原人脸、final_results/整图/视频帧复原结果。六、进阶任务一灰度照片着色Face Colorization对 512×512 裁剪对齐的黑白或褪色照片可用 inference_colorization.py 一键着色# 输入为裁剪对齐人脸512x512 python inference_colorization.py --input_path [image folder]|[image path]源码关键点inference_colorization.py网络配置为codebook_size512、connect_list[32,64,128]比复原任务少了 256 分辨率融合层w被固定为 0、adainTrue——代码注释明确说明w is fixed to 0 since we didnt train the Stage III for colorization未训练着色版 Stage III因此输出完全依赖码本先验输入必须严格为 512×512脚本通过assert强制校验结果保存于results/input_name/支持--suffix与--output_path参数。示例数据见 inputs/gray_faces。值得注意的是CodeFormer 的着色本质是在灰度输入上利用码本先验恢复颜色分布其效果在下文颜色增强与复原结果图中亦有体现。七、进阶任务二人脸修复Face Inpainting对人脸区域存在遮挡/缺损的图像用 Photoshop 等工具以白色画笔标记待修复区域可用 inference_inpainting.py 修复# 输入为裁剪对齐人脸512x512白笔掩码示例见 inputs/masked_faces python inference_inpainting.py --input_path [image folder]|[image path]该脚本的掩码生成逻辑非常巧妙inference_inpainting.py由于输入是 512×512 对齐人脸脚本将每个像素的三通道 RGB 求和sum 3即纯白的像素视为掩码区域随后以w1、adainFalse推理并将掩码内像素替换为模型输出、掩码外像素保留原图mask[m_ind 3] 1.0 output_face net(input_face, w1, adainFalse)[0] output_face (1 - mask) * input_face mask * output_face即只有被白笔覆盖的区域被重建其余区域严格保真这与着色任务全图重建形成鲜明对比。修复模型的 codebook 大小为 512同样要求输入严格 512×512。八、推理脚本与底层管线深度解析8.1 全部命令行参数来自 inference_codeformer.py参数默认值说明-i, --input_path./inputs/whole_imgs输入图片/视频/文件夹-o, --output_pathNone输出目录默认results/输入名_w-w, --fidelity_weight0.5质量与保真度平衡权重范围 [0, 1]-s, --upscale2最终上采样倍数--has_alignedFalse输入为已裁剪对齐人脸跳过检测/对齐--only_center_faceFalse仅复原画面中心的人脸--draw_boxFalse在输出图中绘制检测框--detection_modelretinaface_resnet50人脸检测器retinaface_resnet50、retinaface_mobile0.25、YOLOv5l、YOLOv5n、dlib--bg_upsamplerNone背景上采样器可选realesrgan--face_upsampleFalse复原后用 Real-ESRGAN 额外上采样人脸--bg_tile400背景上采样的分块尺寸省显存--suffixNone输出文件名后缀--save_video_fpsNone输出视频帧率默认沿用输入源码注释提示检测模型分两档大模型YOLOv5l/retinaface_resnet50精度更高小模型YOLOv5n/retinaface_mobile0.25速度更快。README 更新日志还提到dlib检测器produces more accurate face identity人脸身份更准确。8.2 复原网络与数据预处理推理脚本固定按以下配置实例化网络inference_codeformer.py与 Stage II/III 训练配置保持一致net ARCH_REGISTRY.get(CodeFormer)(dim_embd512, codebook_size1024, n_head8, n_layers9, connect_list[32, 64, 128, 256])输入预处理为像素归一化到[0,1]→ BGR 转 RGB → 以均值/方差(0.5,0.5,0.5)做标准化推理在torch.no_grad()下进行输出经tensor2img(..., min_max(-1,1))还原为 uint8 图。加载权重时取 checkpoint 中的params_ema字段EMA 权重这也是 BasicSR 框架的标准约定。8.3 整图处理管线从检测到融合回贴整图输入时FaceRestoreHelper 承载完整流水线inference_codeformer.py读取与预处理read_image处理 16-bit、灰度、带 alpha 通道等输入短边不足 512 自动放大人脸检测与关键点get_face_landmarks_5先将图缩放到短边 640 再检测默认eye_dist_threshold5过滤过小/侧脸支持only_center_face/只保留最大脸等策略对齐裁剪align_warp_face用 5 点关键点FFHQ 标准模板估计仿射矩阵并裁剪 512×512 人脸人脸复原CodeFormer 逐张推理灰度输入自动检测is_gray并在回贴阶段转回灰度、做 AdaIN 颜色迁移以保持灰度风格背景增强bg_upsamplerReal-ESRGAN x2增强背景face_upsample可选地再对人脸做一次超分融合回贴paste_faces_to_input_image将复原人脸经逆仿射变换贴回先用膨胀腐蚀生成软掩码再调用ParseNet 人脸解析use_parseTrueface_restoration_helper.py生成五官级掩码仅融合脸部区域而保留发际线等边界纹理——这正是 README 提醒整图命令可能损伤边界头发纹理的原因也是论文对比须用--has_aligned的原因。九、三阶段训练流程Training训练命令与说明详见 docs/train.md另有 docs/train_CN.md 中文版。训练数据使用 FFHQ 数据集。项目采用 BasicSR 框架分布式训练入口统一为basicsr/train.py -opt 配置 --launcher pytorchPyTorch 1.10 时请将python -m torch.distributed.launch替换为torchrun。Stage I训练 VQGAN 码本python -m torch.distributed.launch --nproc_per_nodegpu_num --master_port4321 \ basicsr/train.py -opt options/VQGAN_512_ds32_nearest_stage1.yml --launcher pytorch配置见 VQGAN_512_ds32_nearest_stage1.ymlVQAutoEncodernf64, ch_mult[1,2,2,4,4,8], quantizernearest, codebook_size1024配VQGANDiscriminator训练 160 万迭代损失为 L1 LPIPS hinge GAN。训练完成后建议预计算整个数据集的码序列以加速后续阶段python scripts/generate_latent_gt.py若不想自训 VQGAN可直接使用官方预训练vqgan_code1024.pth与对应的latent_gt_code1024.pth通过download_pretrained_models.py CodeFormer_train获取。Stage II训练 Code Sequence Predictionw0python -m torch.distributed.launch --nproc_per_nodegpu_num --master_port4322 \ basicsr/train.py -opt options/CodeFormer_stage2.yml --launcher pytorch配置见 CodeFormer_stage2.yml模型类型CodeFormerIdxModelfidelity_weight: 0冻结quantize与generatorfix_modules仅训练 Transformer 的码索引预测模块损失为交叉熵cross_entropy_loss权重 0.5 高分辨率特征损失use_hq_feat_loss权重 1.0共 50 万迭代。此阶段数据采用大退化blur_sigma: [1,15]、downsample_range: [4,30]、noise_range: [0,20]、jpeg_range: [30,80]以覆盖重度损坏输入。Stage III训练可控融合模块w1python -m torch.distributed.launch --nproc_per_nodegpu_num --master_port4323 \ basicsr/train.py -opt options/CodeFormer_stage3.yml --launcher pytorch配置见 CodeFormer_stage3.yml模型类型CodeFormerJointModel从 Stage II 权重pretrain_network_g与判别器权重恢复训练中w随机采样使模型学会全范围保真度控制。损失叠加 L1、LPIPS、hinge GANscale_adaptive_gan_weight: 0.1并采用大退化 小退化联合采样*_large参数共 15 万迭代ema_decay: 0.997。最终产出的codeformer.pth即推理脚本使用的复原主模型。十、在线体验与生态集成官方维护的在线 Demo 部署于 Hugging Face Space、Replicate 与 OpenXLab 平台2022.09–2023.07 陆续集成见 README Update 记录无需本地环境即可体验老照片修复与 AI 生成人脸的修复效果。README 同时列出大量第三方非官方的网站、API 平台与开源工具集成如 Stable Diffusion WebUI、ComfyUI、ChaiNNer 等 GUI/工具链对 CodeFormer 的集成并特别警示除官方三平台外其余均为第三方部署、未获作者授权使用时需自行甄别合法性以避免财产损失。仓库内还提供了可参考的部署实现web-demos/hugging_face/app.py 与 web-demos/replicate/predict.py。十一、引用与许可项目遵循NTU S-Lab License 1.0见 LICENSE。若你的研究使用了 CodeFormer请按 README 中的 BibTeX 引用 NeurIPS 2022 论文。项目致谢中说明其基于 BasicSR 构建部分代码来自 Unleashing Transformers、YOLOv5-face 与 FaceXLib并采用 Real-ESRGAN 支持背景增强。十二、常见问题与实用建议CPU 运行慢Real-ESRGAN 背景增强在 CPU 上未经优化、速度很慢纯 CPU 场景建议移除--bg_upsampler/--face_upsampleinference_codeformer.py 有运行时警告显存不足调小--bg_tile默认 400可显著降低背景上采样的显存占用多脸照片默认复原所有检测到的人脸--only_center_face只处理中心人脸--draw_box可可视化检测框辅助调试灰度老照片整图复原时脚本会自动检测灰度输入并在回贴阶段执行灰度还原与颜色迁移adain_npy避免着色失真输入路径必须以.mp4/.mov/.avi结尾才会被识别为视频否则会被当作文件夹扫描glob只匹配 jpg/png无匹配文件会抛出FileNotFoundError着色/修复必须用 512×512 对齐人脸脚本会assert校验分辨率未对齐输入请先用scripts/crop_align_face.py预处理。【免费下载链接】CodeFormer[NeurIPS 2022] Towards Robust Blind Face Restoration with Codebook Lookup Transformer项目地址: https://gitcode.com/gh_mirrors/co/CodeFormer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考