HANDOFF.md

🤝 AI 交接文档 · Stable-Makeup 妆容迁移部署

写给下一位 AI：请从 AutoDL 终端开始，跑通推理流程。

---

项目目标

部署 Stable-Makeup（妆容迁移 AI）：用户上传素颜照 + 妆容参考图 → AI 输出迁移后的照片。

当前状态

用户在 AutoDL 租了一台 GPU 实例：

• 显卡: RTX 2080Ti 11GB
• 环境: PyTorch 2.x + CUDA 12.1 + Python 3.12 + Ubuntu 22.04
• 状态: 实例已创建，JupyterLab 已打开，还没开始操作

代码仓库：https://www.modelscope.cn/studios/guobc2026/stable-makeup.git

---

下一步（在 AutoDL JupyterLab Terminal 里执行）

第 1 步：拉代码 + 装依赖

git clone https://www.modelscope.cn/studios/guobc2026/stable-makeup.git
cd stable-makeup && pip install -r requirements.txt

预计 3-5 分钟。依赖已锁版本，AutoDL 干净环境不会冲突。

第 2 步：启动

python app.py

模型加载（下载 + 加载到 GPU）预计 5-10 分钟。成功标志：打印 ✅ 模型加载完成 (float16 GPU + DDIM)。

第 3 步：测试

Gradio 会打印公网链接（https://xxx.gradio.live），打开后上传素颜照和妆容图，点「开始试妆」测试。

---

技术架构（关键信息）

推理链路

素颜照 → batch_face.RetinaFace(人脸检测) → SPIGA(98点关键点) → 骨架图 → ControlNet
参考图 → CLIP ViT-L/14 → SSR Attention → cross-attention注入
→ SD1.5 UNet(DDIM 30步) → 输出

文件说明

文件	作用
app.py	主入口，Gradio UI + 推理函数
spiga_draw.py	人脸关键点检测 + 骨架图生成
pipeline_sd15.py	自定义 StableDiffusionControlNetPipeline（支持双路 ControlNet + SSR attention）
detail_encoder/	妆容编码器（CLIP + SSR cross-attention）
requirements.txt	完整依赖，版本已锁定

依赖版本链（不可单拆）

diffusers==0.29.2 + transformers==4.42.4 + peft==0.10.0

这三个版本互相依赖，改任何一个会导致 import 报错。pipeline_sd15.py 专为 diffusers 0.29.2 编写。

模型下载源

• SD1.5 / CLIP / SPIGA: 从 ModelScope 下载（_ms_download 函数）
• Stable-Makeup 预训练权重: 从 HuggingFace Hub 下载（Xiaojiu-z/Stable-Makeup）
• 人脸检测: batch_face 包（pip 安装，不依赖 GitHub）

精度

• GPU: float16
• CPU: float32
• app.py 第 18 行自动判断：DTYPE = torch.float16 if DEVICE == "cuda" else torch.float32

---

已知坑（已踩过）

坑	症状	原因	解决
peft/transformers 版本冲突	ImportError: cannot import name 'EncoderDecoderCache'	peft 新版本要求 transformers ≥ 4.45	锁死 peft==0.10.0
GitHub 不可达	facelib 安装超时	ModelScope/AutoDL 可能无法访问 GitHub	用 batch_face 替代
.gitignore 误伤 vendor	ModuleNotFoundError: _vendor.facelib	models/ 递归匹配	已删除 vendor 方案
float16 在 CPU 报错	推理崩溃	CPU 不支持 float16 运算	自适应精度
调度器不匹配	推理结果不对	默认 DPMSolver 不是论文原版	改用 DDIMScheduler

---

成功标准

1. app.py 启动无报错
2. 模型加载打印 ✅ 模型加载完成
3. 上传两张照片后返回一张 512×512 的妆容迁移结果
4. 推理时间：GPU 上约 10-20 秒/张