功能与原理速览
CodeFormer 属于基于 Transformer 的人脸复原模型，它的定位不是“把整张图变清晰”，而是针对人脸区域做结构重建，再配合人脸检测与分割把修复结果贴回原图。理解这一点，后面的参数取舍就顺了。
它到底修什么
模型内部有两套特征：一套负责从低质量输入里提取编码，一套通过码本（codebook）查表重建高质量人脸。低清马赛克本质上丢失的是高频纹理，模型不是“还原真相”，而是依据学到的先验把缺失的结构补成一个可信的样子。所以它对人脸五官、皮肤过渡这类有大量训练样本的区域效果明显，对文字、车牌一类没有先验的内容基本无能为力。
保真度权重的作用
推理时有一个保真度系数，通常写作 w 或 fidelity weight。数值越低，模型越依赖码本先验，画面越干净、越“复原”，但也更容易和本人不像；数值越高，越贴近原图信息，细节保留多，马赛克边缘的碎块也会一起留下。实战里的经验区间是 0.5 到 0.8，先从这个范围试，再根据素材老化程度微调。
什么素材适合它
老照片扫描件、早期数码相机的低像素人像、被压缩过一次的视频截图，这几类收益最大。多次二次压缩、面部只占几十像素的素材，收益会明显下降，此时先做放大和降噪预处理，再送入模型，结果会更稳。
一句话判断标准：如果原图人脸还有可辨认的五官轮廓，CodeFormer 就有发挥空间；如果人脸已经是纯色方块，任何本地模型都补不回来。
下载与获取渠道
关于 codeformer去除马赛克下载，最先要明确的是：下载对象分两部分——仓库代码和模型权重。只下代码不拿权重，跑起来会直接报找不到文件。
- 官方仓库代码：在 GitHub 搜索项目名，认准作者本人的主仓库和 README 里给出的分支说明，不要用来路不明的“整合包”。
- 模型权重：README 会给出权重下载链接与存放目录，通常是
weights/CodeFormer与weights/facelib两处。 - 可信镜像：国内直连慢时，可用维护活跃的镜像站或学术模型托管平台，下载后对照 README 中给出的文件大小或校验值。
- 避坑：凡是要求填写手机号、先装额外“加速器”的下载页，一律不要用。见 合规与风险提示。
下载后的自检清单
- 权重文件大小与官方 README 标注一致，没有被截断成几 KB。
- 文件名大小写完全一致，Linux 下大小写敏感，改名就找不到。
- 解压后没有多套一层同名文件夹，目录层级要和代码里的路径对得上。
安装与部署步骤
环境依赖是最容易劝退的一段，用独立虚拟环境能省掉大半麻烦。下面五步按顺序做，做完一步验证一步，别一口气全装完再排查。
- 准备显卡驱动与运行环境先确认显卡驱动可用，再创建 Python 3.10 的虚拟环境。版本过新时部分依赖没有预编译轮子，会在本地编译阶段卡很久甚至失败。
- 获取官方仓库代码克隆仓库后切到稳定分支，记下当前提交号。日后想回滚或复现问题，这个号很有用。相关命令细节见 常见问题。
- 放置模型权重文件把复原权重放进
weights/CodeFormer，人脸检测与解析相关权重放进weights/facelib。路径写错是最常见的“跑不起来”原因。 - 安装依赖并首次推理安装依赖清单后，用仓库自带的示例图片跑一次推理，输出文件正常生成、显卡被占用，就说明链路通了。
- 调整保真度参数对比效果用同一张图跑 0.3、0.5、0.7 三组，放大同一块区域对照，选出细节和自然度平衡最好的一组，再去批处理自己的素材。
首次跑通后再做批量处理，先拿 3 到 5 张图试，确认显存峰值和耗时，再开长任务。想直接看参数说明可以跳到 效果实测与参数。
效果实测与参数
下面这张对照表是我在一台 8GB 显存机器上跑老照片的实际观感记录，供你选参时参考，具体结果会因素材而异。
| 保真度 | 清晰度 | 相似度 | 适用情况 |
|---|---|---|---|
| 0.3 | 最高 | 偏低 | 人脸极小、只求能看清 |
| 0.5 | 较高 | 较自然 | 多数老照片的默认选择 |
| 0.7 | 中等 | 高 | 需要保留本人真实特征 |
| 0.9 | 较低 | 很高 | 仅做轻微降噪提亮 |
几个实用的取舍习惯
- 先跑低值看上限，再往回调，比从高值往低调更容易找到合适点。
- 视频素材逐帧跑成本高，可只对含人脸的关键帧修复，再对齐时间轴。
- 输出后做一次轻微锐化与色阶校正，观感通常比原样输出更好。
常见问题
codeformer去除马赛克下载失败，文件总是下到一半断掉怎么办？
先分清是代码没下来还是权重没下来。权重文件通常有几百 MB，网络抖动时容易断在 80% 左右，表现是文件存在但大小不对。判断方法是逐个核对文件体积，并和 README 里给出的数值比对。
处理顺序建议这样：一是换网络环境或用支持断点续传的下载方式重试；二是优先选维护活跃、说明清晰的镜像源；三是下载完成后计算校验值，和官方给出的值一致再解压。如果解压时报错，多半是压缩包不完整，不要硬解，重下更省时间。
还有一种情况是把权重放错了目录。此时程序不报下载错误，而是在启动时提示找不到某个 .pth 文件。回到 安装与部署步骤 对照目录结构检查一遍即可。
装好以后程序跑不起来，报错一大堆，怎么快速定位？
绝大多数“跑不起来”落在三类原因上：显卡驱动与 CUDA 版本不匹配、Python 版本过新导致依赖编译失败、显存不足。
定位方法很直接：先看报错最后几行提到的关键词，出现 CUDA、cuDNN 字样就查驱动版本；出现编译错误、找不到头文件，基本是 Python 版本问题，退回 3.10 的独立环境重装依赖；如果报显存溢出，就把输入分辨率调小、批次设为 1，或先只处理人脸裁剪区域。
另外，路径里有中文或空格有时也会出问题，把项目放在纯英文路径下能排除一类玄学故障。
修复效果不理想，脸看着很“假”，还有办法改善吗？
先把保真度权重调高一点，让结果更贴近原图，很多“假”来自模型过度依赖先验补全。然后检查源素材：如果它已经被多次压缩，先做降噪和轻度放大预处理，再送入修复，效果通常能提升一档。
还要确认人脸检测是否真的命中。部分侧脸、大角度俯仰的照片检测框会偏，此时可以手动指定人脸区域再修复。最后就是预期管理：马赛克是不可逆的信息丢失，模型是在“补一个合理的样子”，不是还原真实细节，效果因人而异、因素材而异。
本地跑和在线工具比，值得折腾吗？
值得，前提是你有可用的独立显卡。本地跑的好处是素材不出本机、可以批量处理、参数完全可控；代价是要花一两个小时配环境，且显存不足时大图会跑不动。若只是偶尔修一两张图，用现成工具也无妨；如果你要处理一整批家庭影像，本地部署一次配好会省下大量重复操作。
合规与风险提示
修复技术本身是中性的，边界在于你处理的是什么素材、拿去做什么。
- 只处理自己有权处理的素材：翻拍、扫描家人照片没问题，未经许可处理他人肖像并公开传播则存在法律风险。
- 不外传原始文件：本地部署的优势正是数据不出本机，别为图省事把私人影像传到陌生的在线接口。
- 不用于伪造与误导：用复原模型生成不实的人脸内容，可能触及肖像权、名誉权乃至更严重的法律责任。
- 尊重版权：修复影视截图、商业摄影作品前，先确认使用范围是否被授权。
另外提醒一句：请遵守当地法律法规，理性使用工具，修复结果仅供参考，不作为任何身份识别或证据用途。下载渠道也尽量走官方与可信来源，避免夹带恶意程序。