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 步：拉代码 + 装依赖
```bash
git clone https://www.modelscope.cn/studios/guobc2026/stable-makeup.git
cd stable-makeup && pip install -r requirements.txt
```
预计 3-5 分钟。依赖已锁版本，AutoDL 干净环境不会冲突。

### 第 2 步：启动
```bash
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 秒/张