与 Stable Diffusion、FLUX 等生成模型不同，CodeFormer 是一个专用的人脸修复与增强模型。它的定位不是“从无到有生成图像”，而是“从差到好修复图像”——针对老照片、低分辨率人像、AI 生成图像中的面部崩坏、视频马赛克等场景，恢复细节和色彩。
第一部分：CodeFormer 版本全景概览
CodeFormer 的版本演进与其他图像模型有本质区别。绝大多数图像模型通过参数规模扩大和架构重构来划分版本，而 CodeFormer 的核心模型架构从 2022 年发布以来没有发生根本性变化。其版本分化主要体现在功能扩展和生态集成两个维度。
从版本谱系来看，CodeFormer 的演进可归纳为以下几条主线：
核心模型版本线（v0.1.0） ：CodeFormer v0.1.0 于 2022 年 8 月 10 日发布，这是该项目唯一的正式 tagged release。后续的新权重文件（上色、修复、stage2）虽然陆续发布，但均归入 v0.1.0 的 release 桶中，没有创建新的版本号。这意味着 CodeFormer 的“版本”更多体现为模型权重的迭代而非软件版本的升级。
功能扩展线：2022 年 7 月 16 日发布推理代码 → 2022 年 7 月 29 日集成 RetinaFace 和 YOLOv5 检测器 → 2022 年 8 月 7 日集成 Real-ESRGAN 支持背景增强 → 2022 年 9 月 4 日新增面部上采样 → 2022 年 10 月 5 日支持视频输入 → 2023 年 2 月 10 日新增 dlib 检测器 → 2023 年 4 月 9 日新增面部修复和上色功能 → 2023 年 4 月 19 日发布训练代码。
生态集成线：Colab Demo（2022年7月）→ Hugging Face Space（2022年9月）→ Replicate API（2022年9月）→ OpenXLab（2023年7月）→ ComfyUI 自定义节点 → SD WebUI 集成。
第三方包装版本：由于 CodeFormer 核心项目长期未更新，社区出现了多个第三方包装版本。豌豆荚上出现了 codeformer v1.2、v1.3、v1.4 等版本号，但这些并非官方发布，而是第三方应用的版本迭代。
第二部分：各版本详细对比与拆解
一、核心权重与功能版本对比
维度 初始版本（2022.07） 增强版本（2022.09-10） 完整版本（2023.04）
核心能力 人脸修复（face restoration） 人脸修复 + 面部上采样 + 背景增强 人脸修复 + 上采样 + 背景增强 + 上色 + 修复
人脸检测器 RetinaFace（默认）、YOLOv5 同左 新增 dlib（更准确的 identity 保持）
背景增强 不支持 集成 Real-ESRGAN 同左
视频支持 不支持 支持（.mp4/.mov/.avi） 同左
上色功能 不支持 不支持 支持（彩色化黑白面部）
面部修复 不支持 不支持 支持（inpainting 修复遮挡/缺失区域）
训练代码 未公开 未公开 2023.04.19 公开
CodeFormer 的初始版本仅提供基础的人脸修复能力，输入一张低质量人脸图像，输出修复后的人脸。2022 年 9 月的更新是关键转折点——面部上采样（--face_upsample）的加入使其能够处理 AI 生成的高分辨率人脸增强场景，Real-ESRGAN 的集成则将处理范围从人脸扩展到了整个背景。
2023 年 4 月是功能最完整的一次更新。上色和修复功能的加入使 CodeFormer 从“人脸增强工具”升级为“人脸修复平台”——黑白老照片可以上色，被遮挡或损坏的面部区域可以修复填充。dlib 检测器的引入则提升了人脸身份保持的准确性，对于需要保留人物原始特征的场景尤为重要。
二、与同类模型的核心对比
维度 CodeFormer GFPGAN GPEN
技术路线 VQGAN 码本 + Transformer 生成先验 + 面部组件 生成先验 + 面部解析
核心优势 严重退化下鲁棒性最强 自然感和细节丰富 速度较快
PSNR（Mild） 24.66 26.29 25.52
SSIM（Mild） 0.7454 0.7795 0.7517
LPIPS（Mild） 0.2742 0.2482 0.2984
保真度控制 支持 w 参数调节 不支持 不支持
上色/修复 支持 不支持 不支持
推理速度 ~0.1秒/张 较快 较快
商用许可 非商业（CC BY-NC-SA 4.0） Apache 2.0 非商业
从客观指标看，CodeFormer 在 PSNR 和 SSIM 上并不总是优于 GFPGAN，这反映了两种技术路线的本质差异。GFPGAN 倾向于生成更“好看”但可能偏离原始身份的人脸，而 CodeFormer 更注重在严重退化条件下保持身份一致性和结构合理性。CodeFormer 的独特优势在于可控的保真度-质量权衡——通过 -w 参数（0 到 1 之间），用户可以在“更清晰但可能改变面部特征”和“更忠实于原始输入但可能不够清晰”之间自由调节。这一能力在需要保留人物身份的法律、档案、医疗等场景中具有不可替代的价值。
CodeFormer 还支持 GFPGAN 不具备的上色和修复功能，使其成为功能最全面的人脸修复开源工具。
三、部署方式版本对比
部署方式 适用场景 硬件要求 优势 限制
Hugging Face Space 快速体验 无（云端） 零门槛，作者维护 有使用限制，不适合批量
Replicate API 开发者集成 无（云端） API 调用，可编程 不可商用
本地 Conda 部署 批量处理/隐私场景 GPU 6GB+ VRAM 完全控制，无限制 安装复杂，有环境陷阱
ComfyUI 节点 工作流集成 GPU 6GB+ VRAM 可视化工作流，易用 需要已有 ComfyUI 环境
Docker 部署 生产环境 GPU 6GB+ VRAM 环境隔离，可复现 需要 Docker 知识
本地部署的最大陷阱是 basicsr 命名空间冲突，这会直接导致安装失败。另一个常见问题是静默的 CPU 回退——如果 CUDA 配置不正确，模型会悄悄使用 CPU 运行，使 3090 的运行速度变得像一台老旧笔记本。Python 版本也是关键变量，官方 README 锁定 Python 3.8，3.10 和 3.11 用户可能会遇到 3.8 上不会出现的导入错误。
第三部分：为什么分这么多版本？
一、从“论文复现”到“工具平台”的角色演进
CodeFormer 的版本分化与其他图像模型有本质区别。Stable Diffusion 通过扩大参数规模和重构架构来划分版本，而 CodeFormer 的核心架构从发布以来没有发生根本变化。其版本分化反映的是一个研究项目向工具平台演进的自然过程。
2022 年 7 月的初始版本是一个“论文复现”性质的代码库——能跑通人脸修复，但功能单一，部署门槛高。2022 年 9 月的功能扩展使其从“研究代码”变成了“可用工具”——视频支持、面部上采样、背景增强这些功能不是学术论文的核心贡献，但它们是实际使用中不可或缺的能力。2023 年 4 月的功能完善则将其升级为“平台”——上色、修复、训练代码的公开，使 CodeFormer 从一个“人脸增强工具”变成了一个“人脸修复的完整解决方案”。
这一演进路径的驱动力来自用户需求而非技术突破。当越来越多的用户开始用 CodeFormer 修复老照片时，“能不能给黑白照片上色”就成了刚需；当视频创作者开始用 CodeFormer 处理老视频时，“能不能处理视频”就成了必须支持的功能。版本分化的本质是从学术贡献到实际需求的响应。
二、架构稳定性带来的“长尾版本”现象
CodeFormer 的架构稳定性是其版本策略的核心特征。与其他模型每 6-12 个月就需要重新训练和发布新版本不同，CodeFormer 的核心模型权重在 2022 年发布后基本保持稳定。这带来一个独特的“长尾版本”现象——v0.1.0 是唯一的正式发布版本，但它持续获得新权重和新功能。
这一策略的优势在于：用户不需要担心“升级导致兼容性断裂”——今天能跑通的代码，明天还能跑通。劣势在于：版本号无法反映功能的实际演进，用户很难判断“哪个版本有什么功能”。社区不得不通过 changelog 和文档来追溯功能变化，而非通过版本号。
三、非商业许可下的生态扩散
CodeFormer 采用 CC BY-NC-SA 4.0 许可，禁止未经授权的商业使用。这一许可选择深刻影响了其版本生态。由于不能直接商用，CodeFormer 没有形成像 Stable Diffusion 那样庞大的商业微调生态，但它通过集成到其他工具的方式实现了广泛扩散。
ComfyUI 的 facerestore 自定义节点将 CodeFormer 作为面部修复的标准组件集成到 AI 绘画工作流中。SD WebUI 的插件生态将 CodeFormer 作为“面部修复”选项之一。fal.ai 和 Replicate 提供了 CodeFormer 的 API 服务，但明确标注“不可商用”。这种“不能直接卖，但可以被集成”的模式使 CodeFormer 在保持学术开源纯粹性的同时，获得了远超同类非商业项目的实际使用量。
第四部分：最著名版本——CodeFormer 完整版本地部署实战
CodeFormer v0.1.0 完整版（包含上色、修复、视频支持）是功能最全的版本，以下为完整的本地部署步骤。需要特别注意的是，CodeFormer 的安装过程存在两个常见陷阱——basicsr 命名空间冲突和静默 CPU 回退，步骤中已包含对应的解决方案。
步骤一：环境准备与硬件规划
硬件配置基准：
最低配置：CPU 可运行（极慢，不推荐）
推荐配置：NVIDIA GPU，显存 6GB 及以上，CUDA 11.7 或 11.8
内存：16GB DDR4 及以上
存储：约 5GB（模型权重 + 输出空间）
软件环境清单：
操作系统：Ubuntu 22.04（推荐）或 Windows 10
Python 3.8（官方锁定版本，不建议使用 3.10+）
PyTorch 1.13.1 或 2.1.0，匹配对应 CUDA 版本
conda 或 miniconda
步骤二：克隆仓库与创建环境
bash
git clone https://github.com/sczhou/CodeFormer
cd CodeFormer
conda create -n codeformer python=3.8 -y
conda activate codeformer
pip3 install -r requirements.txt
python basicsr/setup.py develop
关键陷阱处理——basicsr 命名空间冲突：如果 pip install -r requirements.txt 后出现 ModuleNotFoundError: No module named 'basicsr' 或 ImportError: cannot import name '...' from 'basicsr'，这是因为 pip 安装的 basicsr 与项目自带的 basicsr 冲突。解决方案是先卸载 pip 版本的 basicsr，再运行项目自带的 setup.py：
bash
pip uninstall basicsr -y
python basicsr/setup.py develop
步骤三：安装 dlib 人脸检测器（可选，推荐）
dlib 提供更准确的人脸身份保持，对于需要保留人物原始特征的场景尤为重要：
bash
conda install -c conda-forge dlib
步骤四：下载预训练模型
bash
# 下载 facelib 和 dlib 模型
python scripts/download_pretrained_models.py facelib
python scripts/download_pretrained_models.py dlib
# 下载 CodeFormer 主模型
python scripts/download_pretrained_models.py CodeFormer
模型权重会自动下载到 weights/ 目录下。如果下载缓慢，可从 Google Drive 或 OneDrive 手动下载后放入对应文件夹。
步骤五：基础人脸修复调用
bash
# 单张图片修复（默认参数）
python inference_codeformer.py \
--input_path inputs/old_photo.jpg \
--output_path results/
# 调节保真度（w 参数：0=更高清晰度，1=更高保真度）
python inference_codeformer.py \
--input_path inputs/old_photo.jpg \
--fidelity_weight 0.7 \
--output_path results/
--fidelity_weight 对应论文中的 w 参数。值越小，模型越倾向于生成“更清晰但可能改变面部特征”的结果；值越大，越忠实于原始输入但可能不够清晰。老照片修复通常建议使用 0.5-0.7 之间的值。
步骤六：视频修复与去码
bash
# 视频增强（需 ffmpeg）
python inference_codeformer.py \
--bg_upsampler realesrgan \
--face_upsample \
-w 1.0 \
--input_path inputs/old_video.mp4 \
--output_path results/
视频路径必须以 .mp4、.mov 或 .avi 结尾。--bg_upsampler realesrgan 启用背景增强，--face_upsample 启用面部上采样，-w 1.0 设置为最高保真度模式。
步骤七：上色与修复功能
bash
# 面部上色（黑白转彩色）
python inference_colorization.py \
--input_path inputs/bw_face.jpg \
--output_path results/
# 面部修复（遮挡/缺失区域填充）
python inference_inpainting.py \
--input_path inputs/masked_face.jpg \
--output_path results/
步骤八：关键陷阱处理——静默 CPU 回退
如果运行过程中发现速度极慢（单张图数分钟而非数秒），很可能是 CUDA 未正确配置导致的静默 CPU 回退。检查方式：
bash
# 确认 PyTorch 是否检测到 CUDA
python -c "import torch; print(torch.cuda.is_available())"
# 应输出 True。如果输出 False，需要重新安装匹配 CUDA 版本的 PyTorch
pip install torch==2.1.0+cu118 torchvision==0.16.0+cu118 \
--index-url https://download.pytorch.org/whl/cu118
步骤九：ComfyUI 集成（推荐工作流方案）
对于已有 ComfyUI 环境的用户，推荐通过 facerestore 自定义节点集成 CodeFormer：
bash
cd ComfyUI/custom_nodes
git clone https://github.com/facerestore/ComfyUI-Facerestore.git
# 重启 ComfyUI
在 ComfyUI 工作流中添加“Facerestore CF (Code Former)”节点，支持 CodeFormer Fidelity 参数调节，可在 AI 绘画工作流中自动修复生成图像的面部崩坏。
第五部分：不同版本的实践成果
案例一：第 5 届索尔维会议历史照片修复（基于 CodeFormer 完整版）
CodeFormer 论文中展示了一个标志性的修复案例——对 1927 年第 5 届索尔维会议（Solvay Conference）历史照片的修复。这张照片汇集了爱因斯坦、居里夫人、玻尔、普朗克等物理学史上的传奇人物，但原始照片存在严重的模糊和颗粒问题，面部细节几乎不可辨认。
实践成效：研究团队首先裁剪并对齐了照片中的所有面部，然后使用 CodeFormer 进行增强处理。修复后的图像中，爱因斯坦标志性的蓬松头发、居里夫人的面部轮廓、玻尔的坚毅神情都得到了清晰恢复，同时保留了每个人的身份特征而没有“美颜化”或“换脸”。这一案例的核心价值在于验证了 CodeFormer 在极端退化条件下的鲁棒性——1927 年的摄影技术、近百年的老化、多次翻拍导致的细节丢失，这些都是最严苛的修复挑战。CodeFormer 的码本先验机制使其能够在信息严重缺失的情况下，从离散码本中“查找”最合理的视觉原子来重建面部细节，而非依赖退化输入中的残余信息进行推测。
案例二：朱茵《大话西游》剧照修复与视频去码（基于 CodeFormer 完整版）
有用户使用 CodeFormer 修复了朱茵在《大话西游》中的经典剧照，效果显著。朱茵饰演的紫霞仙子是华语电影中最经典的角色形象之一，但受限于 1990 年代的胶片质量和后期 DVD 发行的压缩损失，原始画面的面部细节已经严重模糊。
实践成效：修复后的图像中，朱茵的面部轮廓、眼神和表情细节得到了清晰恢复，同时保留了角色的神态和气质，没有出现其他修复工具常见的“过度磨皮”或“面部特征偏移”问题。用户反馈“效果非常好”，但原图因审核原因被删除。这一案例在中文社区中引发了广泛关注，使 CodeFormer 被用户称为“地表最强 AI 马赛克去除神器”。除了静态图像，CodeFormer 还支持视频逐帧处理，能够有效提升老视频的清晰度、稳定性和色彩还原度。
案例三：亚运会老照片修复公益项目（基于 CodeFormer 完整版）
2023 年杭州亚运会期间，阿里云开发者社区发起了一项老照片修复公益项目，使用 CodeFormer 修复与亚运历史相关的珍贵影像资料。项目面向公众收集亚运主题的老照片，利用 CodeFormer 进行批量修复和增强。
实践成效：项目中发现了一个关键的参数调优经验——CodeFormer 的 w 参数（保真度权重）对最终效果影响显著。团队建议在修复老照片时使用 0.5-0.7 之间的值：值太高（如 1.0）会导致面部细节恢复不够充分，看起来仍然模糊；值太低（如 0.3）虽然视觉上更清晰，但面部像素被过度修改，局部放大后会发现部分面部特征已经失真，甚至分辨不出人脸。这一经验后来被广泛分享在中文技术社区中，成为 CodeFormer 老照片修复的标准实践指南。该项目的核心价值在于验证了 CodeFormer 在批量公益场景中的可用性——不是精修单张图片，而是以合理的质量和速度处理大量历史影像，让普通用户也能获得专业级的老照片修复服务。
案例四：InnoJoy 数字创享平台视频增强集成（基于 CodeFormer 完整版）
比利时 InnoJoy（数字创享）人工智能创新与应用平台将 CodeFormer 集成到其数字人视频制作流程中，与 wav2lip、sadtalker、chatglm、TTS 等技术配合，用于产品介绍、直播带货、品牌宣传等商业场景。
实践成效：在该平台的数字人工作流中，CodeFormer 承担“视频清晰度增强”的角色——数字人视频在生成和合成过程中难免出现面部模糊和细节损失，CodeFormer 被用于对最终视频进行超分和面部增强处理，提升数字人视频的观看质量。平台团队还对 CodeFormer 的超分算法进行了微调，以更好地适配数字人视频的特定场景。这一案例代表了 CodeFormer 在商业数字人应用中的落地路径——它不是一个独立的产品，而是作为视频制作流水线中的一个质量保障组件被集成使用，解决了 AI 生成视频中面部质量不稳定的问题。
版权声明：本平台仅提供信息存储空间服务，用户发布内容不代表本站观点，交易风险自担；侵权违法内容请立即举报（邮箱：37996619@qq.com），本站接通知后先行屏蔽，责任由发布者承担。