CodeFormer 预训练模型下载：三个 weight 目录各装什么

三个 weights 目录

CodeFormer 需要的预训练模型放在仓库根目录下的 weights/ 文件夹，结构如下：

weights/
├── CodeFormer/           # 核心模型
│   ├── codeformer.pth    # 最终版本（w=1）
│   └── codeformer_stage2.pth  # Stage II 预训练（w=0）
├── facelib/              # 人脸检测和对齐
│   ├── detection_ResNet50_FPN.pth
│   ├── detection_mobilenet0.25.pth
│   └── alignment_ResNet50.pth
└── realesrgan/           # 背景增强和上采样
    └── RealESRGAN_x4plus.pth

一键下载脚本

CodeFormer 提供了 scripts/download_pretrained_models.py，在仓库根目录执行：

# 下载人脸检测模型（必选）
python scripts/download_pretrained_models.py facelib

# 下载 CodeFormer 核心模型（必选）
python scripts/download_pretrained_models.py CodeFormer

# 下载 Real-ESRGAN（可选，只有用 --bg_upsampler realesrgan 时才需要）
python scripts/download_pretrained_models.py realesrgan

# 下载 dlib 模型（可选，用 dlib 做人脸检测时需要）
python scripts/download_pretrained_models.py dlib

脚本会自动从 GitHub Releases / Google Drive / OneDrive 下载并放到正确位置。

手动下载（脚本失败时）

如果网络问题导致脚本下载失败，可以手动从以下地址获取：

CodeFormer 核心模型

从 GitHub Releases v0.1.0 下载：

• codeformer.pth：完整训练的最终模型
• codeformer_stage2.pth：Stage II 预训练版本（w=0，纯 Codebook 重建）

Google Drive / OneDrive 链接在 GitHub README 里有列出。

人脸检测模型

从 XPixelGroup/BasicSR 的模型库下载，放到 weights/facelib/ 目录。

如果已经用 pip install facexlib 装好，facexlib 会自动管理这些模型，不需要手动下载。

Real-ESRGAN

从 xinntao/Real-ESRGAN 的 Releases 页面下载 RealESRGAN_x4plus.pth（~64MB），放到 weights/realesrgan/。

模型大小参考

总共约 1GB（必选部分 ~900MB）。

模型加载验证

下载完成后，快速验证模型能正常加载：

# verify_weights.py
import os

base = "weights"
for subdir in ["CodeFormer", "facelib"]:
    path = os.path.join(base, subdir)
    if os.path.exists(path) and os.listdir(path):
        print(f"✅ {subdir}: {os.listdir(path)}")
    else:
        print(f"❌ {subdir}: 未找到")

# 验证 CodeFormer 模型能否加载
from basicsr.utils import img2tensor, tensor2img
from facexlib.detection import init_detection_model
from basicsr.utils.download_util import load_file_from_url

print("✅ 依赖 import 正常")

常见下载问题

Google Drive 下载失败

Google Drive 有时会限速或强制登录。解决方案：

• 使用脚本自带的 OneDrive 链接（脚本会自动选最快的源）
• 直接用浏览器下载后手动放到对应目录
• 用国内镜像（如 AutoDL 社区、huggingface.co 的 mirror）

文件名大小写

Windows 不区分大小写，Linux 区分。手动下载时确保文件名和模型加载代码里的预期一致。如果跑推理时提示 FileNotFoundError，用 Grep 搜一下文件名在代码里怎么写的。

更新模型

CodeFormer 的模型文件稳定，通常不会频繁更新。GitHub Releases 上 v0.1.0 是目前的正式版。如果作者发了新版本，重跑下载脚本或手动覆盖即可。