# 高清超分管线 · 完整参考

> 本文档记录了本机图片高清化/超分/2K/4K 的完整管线。
> 用途： Apple iPhone 人像图 → 高清商品图 (电商/AI视频素材)
> 作者： 2026-06-19 测试定型，存入知识库防止走弯路

---

## 一、⚠️ 核心铁律（必须先看）

| # | 铁律 | 原因 |
|:--|:-----|:------|
| 1 | **人脸永远从原图裁** | HYPIR 扩散模型会彻底破坏人脸，五官变形，不能恢复 |
| 2 | **头发不过 HYPIR** | HYPIR 会把头发变成一坨一坨的，失去发丝细节 |
| 3 | **先做人脸 → 再做衣服** | 顺序错了，原图被 HYPIR 污染后，人脸无法补救 |
| 4 | **CodeFormer 输出固定 512×512** | 不能直接贴回，必须 LANCZOS 放大到匹配尺寸再 warp |
| 5 | **检测不到人脸就跳过** | 铺在地面上的衣服没有人脸，不需要处理 |

> **上一次犯的错**: 先跑 HYPIR 全图，再想从 HYPIR 输出上做人脸。结果人脸已经被 HYPIR 污染变形，CodeFormer 也救不回来。**正确顺序: 原图→CF人脸→HYPIR衣服→合成**

---

## 二、管线全景

### 当前生产管线（简单有效，已批量化）

```
输入: 原图 54 张 (多种尺寸)
  ↓
  ├─ ① 原图 → 检测人脸 → CodeFormer w=0.7 → 512×512 修复脸
  │     ↓
  │    LANCZOS 2x → 1024×1024
  │
  ├─ ② HYPIR_2x (已有54张) — 衣服纹理锐利处理
  │
  └─ ③ warpAffine + 椭圆羽毛蒙版 σ=30 → 合成
       ↓
  输出: JPG 85% (按原图尺寸分目录存放)
```

每张耗时: ~2.2s (含CF推理+warp+合成)

### 未来三模型分区管线（暂不启用）

```
SAM分割 → HYPIR(衣服) + CF(人脸头发) + PureVision(背景) → 羽化合成
```

原因: SAM 8GB VRAM 跑不动全分辨率，等硬件升级或需要更精细分区时再开。

---

## 三、模型资产清单

### 3.1 HYPIR（衣物纹理超分）

| 组件 | 路径 | 大小 |
|:-----|:------|:------|
| 代码 | `/home/zhengjie/HYPIR/` | 16MB |
| SD2.1 base | `/home/zhengjie/models/hypir/sd2-base/` | 3.5GB |
| LoRA权重 | `/home/zhengjie/models/hypir/HYPIR_sd2.pth` | 991MB |
| Python环境 | `/home/zhengjie/hypir_env/` (python2) | — |
| **参数** | `--model_t 200 --coeff_t 200 --scale 2 --patch_size 512 --stride 256` | |

使用方式:
```bash
HF_HOME=/tmp/cache XDG_CACHE_HOME=/tmp/cache python /home/zhengjie/HYPIR/test.py \
  --base_model_type sd2 \
  --base_model_path /home/zhengjie/models/hypir/sd2-base \
  --model_t 200 --coeff_t 200 \
  --lora_rank 128 \
  --lora_modules down_blocks,up_blocks \
  --weight_path /home/zhengjie/models/hypir/HYPIR_sd2.pth \
  --lq_dir INPUT_DIR \
  --output_dir OUTPUT_DIR \
  --upscale 2 --scale_by factor --patch_size 512 --stride 256 \
  --captioner empty --device cuda
```

### 3.2 CodeFormer（人脸+头发修复）

| 组件 | 路径 | 大小 |
|:-----|:------|:------|
| 代码 | `/home/zhengjie/CodeFormer/` | — |
| 主权重 | `/home/zhengjie/codeformer.pth` | 360MB |
| 检测模型 | `/home/zhengjie/CodeFormer/weights/facelib/detection_Resnet50_Final.pth` | 105MB |
| 解析模型 | `/home/zhengjie/CodeFormer/weights/facelib/parsing_parsenet.pth` | 82MB |

依赖安装位置（系统 python3）：
- **facexlib v0.3.0** → `/home/zhengjie/.local/lib/python3.12/site-packages/facexlib/`
- **lpips v0.1.4** → `/home/zhengjie/.local/lib/python3.12/site-packages/lpips/`
- **basicsr v1.4.2** → `/home/zhengjie/.local/lib/python3.12/site-packages/basicsr/`

facexlib 权重（检测+解析模型）：
- `/home/zhengjie/.local/lib/python3.12/site-packages/facexlib/weights/detection_Resnet50_Final.pth`
- `/home/zhengjie/.local/lib/python3.12/site-packages/facexlib/weights/parsing_parsenet.pth`

### 3.3 PureVision 2x（备选超分）

| 模型 | 路径 | 大小 | 说明 |
|:-----|:------|:------|:------|
| 2x_PureVision | `/home/zhengjie/2x_PureVision.pth` | 65.5MB | ESRGAN架构，通用超分 |
| 推理引擎 | `spandrel` (pip) | — | 自动识别模型架构 |

使用方式：
```python
import spandrel, cv2, torch, numpy as np
pv = spandrel.ModelLoader().load_from_file('/home/zhengjie/2x_PureVision.pth').cuda().eval()
# 输入BGR → 输出2x BGR
```

**注意**: PureVision 2x 适合背景超分 ✔️，**不适合做人脸超分 ❌**（皮肤会太亮像塑料）

### 3.4 SAM（未来分区用）

| 版本 | 路径 | 大小 |
|:-----|:------|:------|
| HF transformers | `/home/zhengjie/.local/lib/sam_models/models--facebook--sam-vit-base/` | 1.1GB |
| 原生 .pth | `/home/zhengjie/ComfyUI/models/sam/sam_vit_b_01ec64.pth` | 358MB |

---

## 四、脚本位置

| 脚本 | 路径 | 说明 |
|:-----|:------|:------|
| 批量人脸替换 | `/home/zhengjie/images/batch_face_replace.py` | **生产脚本**，处理 HYPIR_2x/ 全部图片 |
| 三模型测试 | `/home/zhengjie/images/test_triple_pipeline.py` | 未来管线的测试脚本 |

### batch_face_replace.py 运行方式

```bash
cd /home/zhengjie && python3 images/batch_face_replace.py
```

逻辑：
1. 读 `HYPIR_2x/*.png`（54张）
2. 在5个尺寸目录找同名原图
3. 检测人脸 → CodeFormer → LANCZOS 1024 → warp贴回 → 椭圆蒙版 → JPG 85%
4. 输出到 `HYPIR_2x+CF/` + 同时复制回各尺寸目录替换原图
5. 检测不到人脸的直接跳过（铺地上的衣服）

---

## 五、目录结构

```
/home/zhengjie/图片/可灵素材/
├── 1024x1536/          23张 JPG  ← HYPIR+CF 增强结果
├── 1055x1491/           8张 JPG  ← HYPIR+CF 增强结果
├── 1122x1402/           4张 JPG  ← HYPIR+CF 增强结果
├── 941x1672/           12张 JPG  ← HYPIR+CF 增强结果
├── 971x1619/            2张 JPG  ← HYPIR+CF 增强结果
├── 1279x1706/           5张 PNG  ← 原始输入（未处理）
├── HYPIR_2x/           54张 PNG  ← HYPIR 2x 超分（439MB）
├── HYPIR_2x+CF/        49张 JPG  ← 合成结果（23MB）
└── 2K输出/             49张 JPG  ← 之前2K输出
```

---

## 六、关键参数速查

| 参数 | 建议值 | 说明 |
|:-----|:-------|:------|
| CodeFormer w | 0.7 | 平衡保真+补纹理，通用最优 |
| | 0.85-0.9 | 高保真，几乎不改原脸 |
| HYPIR model_t | 200 | 扩散步数，越高纹理越锐 |
| HYPIR coeff_t | 200 | 条件控制强度 |
| HYPIR scale | 2 | 2x超分 |
| LANCZOS | — | 最锐利插值缩放，不用AI |
| 椭圆蒙版 σ | 30 | 人脸过渡宽度 |
| JPG quality | 85 | 省90%空间，画质损失极小 |

---

## 七、踩坑记录（必读）

### 坑1: HYPIR 不能做人脸（重复多次）
- **问题**: HYPIR 扩散模型把衣服纹理锐化得极好，但处理人脸时会彻底变形
- **后果**: 眼睛不圆、五官移位、皮肤变塑料
- **解决**: 人脸永远从原图裁取，只用 CodeFormer 处理

### 坑2: 先跑 HYPIR 再做人脸
- **问题**: 顺序错了，原图被 HYPIR 污染后无法恢复
- **解决**: HYPIR 只做衣服区域，人脸在 HYPIR 之前就处理

### 坑3: PureVision 做人脸
- **问题**: PureVision 2x 把人脸皮肤变亮像塑料，改变原图色调
- **对比**: 用 LANCZOS 放大人脸比 PureVision 更真实
- **解决**: PureVision 只做背景/全图，人脸用 LANCZOS 缩放

### 坑4: CF 脸直接贴回错位
- **问题**: 用检测框直接贴回不用仿射逆变换，导致人脸位置偏移
- **解决**: 用 FaceRestoreHelper 的 affine_matrices 计算逆仿射，warpAffine 贴回

### 坑5: 512×512 强行贴回
- **问题**: 512×512 的脸直接 warp 到大图上会模糊（压缩到 198×198）
- **解决**: 先 LANCZOS 2x 到 1024×1024，再 warp 到目标位置

### 坑6: 正方形边界明显
- **问题**: warpAffine 贴回整个 512×512 矩形，角上黑色区域可见
- **解决**: 椭圆羽毛蒙版（σ=30），只替换人脸区域

---

## 八、模型原理简述

| 模型 | 架构 | 特点 |
|:-----|:------|:------|
| **HYPIR** | SD2.1 扩散 + LoRA | 脑补细节（添加皮肤纹理/衣物细节），衣服顶尖，人脸不行 |
| **CodeFormer** | VQGAN + Transformer | 用预训练人脸码本做修复，固定 512×512，头发真实，五官保真 |
| **PureVision 2x** | ESRGAN (RRDB) | 纯 CNN 超分，16.7M 参数，不改色调，"啥都能做啥都不精" |
| **SAM** | Transformer | Meta 通用分割，ViT-B 358MB，需要 2GB+ VRAM |
| **LANCZOS** | 数学插值 (8×8) | 最锐利缩放，不添加 AI 内容，保持原图色调 |