# Day 6: LatentSync 1.6 升级

**日期**: 2026-01-20  
**目标**: 将唇形同步模型从 MuseTalk 迁移至 LatentSync 1.6

---

## 📋 任务概览

| 任务 | 状态 |
|------|------|
| 后端配置迁移 | ✅ 完成 |
| 服务层重写 | ✅ 完成 |
| 模型目录结构 | ✅ 完成 |
| 部署文档更新 | ✅ 完成 |
| 服务器部署验证 | ✅ 完成 |
| 性能优化 - 视频预压缩 | ✅ 完成 |
| 性能优化 - 进度更新 | ✅ 完成 |
| README.md 更新 | ✅ 完成 |

---

## 🔄 迁移原因

### MuseTalk vs LatentSync 对比

| 对比项 | MuseTalk v1.5 | LatentSync 1.6 |
|--------|---------------|----------------|
| 分辨率 | 256×256 | **512×512** |
| 架构 | GAN + 传统CV | **Latent Diffusion** |
| 质量 | 良好 | 更清晰、抗模糊 |
| VRAM 需求 | ~10GB | ~18GB |
| 维护 | 社区 | ByteDance 官方 |

### 主要优势

1. **更高分辨率**: 512×512 输出，视觉质量显著提升
2. **更先进架构**: 基于 Stable Diffusion 的 Latent 空间扩散
3. **更好的唇同步**: 集成 SyncNet 监督训练
4. **官方维护**: ByteDance 持续更新

---

## 📝 代码变更

### 1. `backend/app/core/config.py`

移除 MuseTalk 配置，添加 LatentSync 配置：

```python
# LatentSync 配置
LATENTSYNC_GPU_ID: int = 1                      # GPU ID (默认使用 GPU1)
LATENTSYNC_LOCAL: bool = True                   # 使用本地推理
LATENTSYNC_INFERENCE_STEPS: int = 20            # 推理步数 [20-50]
LATENTSYNC_GUIDANCE_SCALE: float = 1.5          # 引导系数 [1.0-3.0]
LATENTSYNC_ENABLE_DEEPCACHE: bool = True        # 启用 DeepCache 加速
LATENTSYNC_SEED: int = 1247                     # 随机种子
```

### 2. `backend/app/services/lipsync_service.py`

完全重写，适配 LatentSync 命令行接口：

```python
# 构建 LatentSync 推理命令
cmd = [
    str(self.conda_python),
    "-m", "scripts.inference",
    "--unet_config_path", "configs/unet/stage2_512.yaml",
    "--inference_ckpt_path", "checkpoints/latentsync_unet.pt",
    "--inference_steps", str(settings.LATENTSYNC_INFERENCE_STEPS),
    "--guidance_scale", str(settings.LATENTSYNC_GUIDANCE_SCALE),
    "--video_path", video_path,
    "--audio_path", audio_path,
    "--video_out_path", output_path,
]
```

### 3. 新增文件

- `models/LatentSync/DEPLOY.md` - 部署指南
- `models/LatentSync/requirements.txt` - Python 依赖

---

## 🖥️ 服务器部署步骤

### 步骤 1: 上传代码

```bash
# 同步本地代码到服务器
rsync -avz --exclude 'venv' --exclude 'node_modules' \
    ViGent2/ rongye@server:/home/rongye/ProgramFiles/ViGent2/
```

### 步骤 2: 创建 Conda 环境

```bash
ssh rongye@server
conda create -y -n latentsync python=3.10.13
conda activate latentsync
conda install -y -c conda-forge ffmpeg
```

### 步骤 3: 安装依赖

```bash
cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
```

### 步骤 4: 下载权重

```bash
huggingface-cli download ByteDance/LatentSync-1.6 whisper/tiny.pt --local-dir checkpoints
huggingface-cli download ByteDance/LatentSync-1.6 latentsync_unet.pt --local-dir checkpoints
```

### 步骤 5: 复制核心代码

```bash
cd /tmp
git clone https://github.com/bytedance/LatentSync.git
cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync
cp -r /tmp/LatentSync/latentsync ./
cp -r /tmp/LatentSync/scripts ./
cp -r /tmp/LatentSync/configs ./
rm -rf /tmp/LatentSync
```

### 步骤 6: 验证推理

```bash
conda activate latentsync
cd /home/rongye/ProgramFiles/ViGent2/models/LatentSync

CUDA_VISIBLE_DEVICES=1 python -m scripts.inference \
    --unet_config_path "configs/unet/stage2_512.yaml" \
    --inference_ckpt_path "checkpoints/latentsync_unet.pt" \
    --inference_steps 20 \
    --guidance_scale 1.5 \
    --enable_deepcache \
    --video_path "test.mp4" \
    --audio_path "test.wav" \
    --video_out_path "output.mp4"
```

---

## 📊 预期效果

- **分辨率提升**: 256×256 → 512×512
- **质量提升**: 基于 Diffusion 的更细腻唇形
- **推理时间**: 约 2-5 分钟/视频 (取决于长度和参数)

---

## ⚠️ 注意事项

1. LatentSync 1.6 需要 **18GB VRAM**，确保使用 RTX 3090
2. 首次推理会下载 SD VAE (~335MB)，需要网络连接
3. `guidance_scale` 过高 (>2.5) 可能导致画面抖动
4. 推理超时已调整为 15 分钟 (MuseTalk 为 10 分钟)

---

## 🚀 性能优化 (16:30)

### 耗时分析

| 阶段 | 耗时 | 占比 |
|------|------|------|
| TTS 生成 | 2秒 | 1% |
| 健康检查 | 2秒 | 1% |
| **LatentSync 推理** | 3分30秒 | **97%** |
| FFmpeg 合成 | <1秒 | <1% |

### 已实施优化

1. **视频预压缩** (`lipsync_service.py`)
   - 高分辨率视频自动压缩到 720p
   - 加速人脸检测和仿射变换
   - 验证结果: `14.9MB → 1.1MB`，LipSync 耗时 `235s → 217s`

2. **进度更新优化** (`videos.py`)
   - 细化进度: 5% → 10% → 25% → 30% → 35% → 85% → 90% → 100%
   - 添加耗时日志
   - LipSync 服务单例缓存
   - 健康检查缓存 (5分钟)

3. **异步子进程修复** (`lipsync_service.py` 17:03)
   - `subprocess.run()` → `asyncio.create_subprocess_exec()`
   - 解决推理期间事件循环阻塞问题
   - 前端进度轮询可正常响应

### 待实施优化

| 优化项 | 难度 | 预期收益 |
|--------|------|----------|
| 预加载模型服务 | 高 | 节省 30秒/次 |
| 批量队列处理 | 中 | 提高吞吐量 |

---

## 📚 相关文档

- [LatentSync GitHub](https://github.com/bytedance/LatentSync)
- [HuggingFace 模型](https://huggingface.co/ByteDance/LatentSync-1.6)
- [论文](https://arxiv.org/abs/2412.09262)

---

## 🐛 修复：视频分辨率降低问题 (17:30)

**问题**：generated video is not resolution of original video (原视频预压缩导致输出为 720p)
**原因**：之前的性能优化中强制将视频压缩至 720p 以提高推理速度，导致 1080p 视频输出被降采样。
**修复**：在 `lipsync_service.py` 中禁用了 `_preprocess_video` 调用，直接使用原始视频进行推理。此时 `LatentSync` 将输出与输入视频一致的分辨率。
**结果**：
- ✅ 输出视频将保持原始分辨率 (1080p)。
- ⚠️ 推理时间将相应增加 (约需多花费 20-30% 时间)。

---

## ⚡ 性能优化补全 (18:00)

### 1. 常驻模型服务 (Persistent Server)
**目标**: 消除每次生成视频时 30-40秒 的模型加载时间。
**实现**: 
- 新增 `models/LatentSync/scripts/server.py` (FastAPI 服务)
- 自动加载后端 `.env` 配置
- 服务常驻显存，支持热调用
**效果**: 
- 首次请求：正常加载 (~40s)
- 后续请求：**0s 加载**，直接推理

### 2. GPU 并发控制 (队列)
**目标**: 防止多用户同时请求导致 OOM (显存溢出)。
**实现**: 
- 在 `lipsync_service.py` 引入 `asyncio.Lock`
- 建立全局串行队列，无论远程还是本地调用，强制排队
**效果**: 
- 即使前端触发多次生成，后端也会逐个处理，保证系统稳定性。