# MuseTalk 部署指南

> **更新时间**：2026-03-02
> **适用版本**：MuseTalk v1.5 (常驻服务模式)
> **架构**：FastAPI 常驻服务 + PM2 进程管理

---

## 架构概览

MuseTalk 作为 **混合唇形同步方案** 的长视频引擎：

- **短视频 (<100s，按当前 `.env` 示例)** → LatentSync 1.6 (GPU1, 端口 8007)
- **长视频 (>=100s，按当前 `.env` 示例)** → MuseTalk 1.5 (GPU0, 端口 8011)
- 路由阈值由 `LIPSYNC_DURATION_THRESHOLD` 控制
- MuseTalk 不可用时自动回退到 LatentSync

---

## 硬件要求

| 配置 | 最低要求 | 推荐配置 |
|------|----------|----------|
| GPU | 8GB VRAM (RTX 3060) | 24GB VRAM (RTX 3090) |
| 内存 | 32GB | 64GB |
| CUDA | 11.7+ | 11.8 |

> MuseTalk fp16 推理约需 4-8GB 显存，可与 CosyVoice 共享 GPU0。

---

## 安装步骤

### 1. Conda 环境

```bash
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk
conda create -n musetalk python=3.10 -y
conda activate musetalk
```

### 2. PyTorch 2.0.1 + CUDA 11.8

> 必须使用此版本，mmcv 预编译包依赖。

```bash
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
```

### 3. 依赖安装

```bash
pip install -r requirements.txt

# MMLab 系列
pip install --no-cache-dir -U openmim
mim install mmengine
mim install "mmcv==2.0.1"
mim install "mmdet==3.1.0"
pip install chumpy --no-build-isolation
pip install "mmpose==1.1.0" --no-deps

# FastAPI 服务依赖
pip install fastapi uvicorn httpx
```

---

## 模型权重

### 目录结构

```
models/MuseTalk/models/
├── musetalk/                   ← v1 基础模型
│   ├── config.json -> musetalk.json    (软链接)
│   ├── musetalk.json
│   ├── musetalkV15 -> ../musetalkV15   (软链接, 关键!)
│   └── pytorch_model.bin       (~3.2GB)
├── musetalkV15/                ← v1.5 UNet 模型
│   ├── musetalk.json
│   └── unet.pth                (~3.2GB)
├── sd-vae/                     ← Stable Diffusion VAE
│   ├── config.json
│   └── diffusion_pytorch_model.bin
├── whisper/                    ← OpenAI Whisper Tiny
│   ├── config.json
│   ├── pytorch_model.bin       (~151MB)
│   └── preprocessor_config.json
├── dwpose/                     ← DWPose 人体姿态检测
│   └── dw-ll_ucoco_384.pth     (~387MB)
├── syncnet/                    ← SyncNet 唇形同步评估
│   └── latentsync_syncnet.pt
└── face-parse-bisent/          ← 人脸解析模型
    ├── 79999_iter.pth          (~53MB)
    └── resnet18-5c106cde.pth   (~45MB)
```

### 下载方式

使用项目自带脚本：

```bash
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk
conda activate musetalk
bash download_weights.sh
```

或手动 Python API 下载：

```bash
conda activate musetalk
export HF_ENDPOINT=https://hf-mirror.com
python -c "
from huggingface_hub import snapshot_download
snapshot_download('TMElyralab/MuseTalk', local_dir='models',
    allow_patterns=['musetalk/*', 'musetalkV15/*'])
snapshot_download('stabilityai/sd-vae-ft-mse', local_dir='models/sd-vae',
    allow_patterns=['config.json', 'diffusion_pytorch_model.bin'])
snapshot_download('openai/whisper-tiny', local_dir='models/whisper',
    allow_patterns=['config.json', 'pytorch_model.bin', 'preprocessor_config.json'])
snapshot_download('yzd-v/DWPose', local_dir='models/dwpose',
    allow_patterns=['dw-ll_ucoco_384.pth'])
"
```

### 创建必要的软链接

```bash
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk/models/musetalk
ln -sf musetalk.json config.json
ln -sf ../musetalkV15 musetalkV15
```

> **关键**：`musetalk/musetalkV15` 软链接缺失会导致权重检测失败 (`weights: False`)。

---

## 服务启动

### PM2 进程管理（推荐）

```bash
# 首次注册
cd /home/rongye/ProgramFiles/ViGent2
pm2 start run_musetalk.sh --name vigent2-musetalk
pm2 save

# 日常管理
pm2 restart vigent2-musetalk
pm2 logs vigent2-musetalk
pm2 stop vigent2-musetalk
```

### 手动启动

```bash
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk
/home/rongye/ProgramFiles/miniconda3/envs/musetalk/bin/python scripts/server.py
```

### 健康检查

```bash
curl http://localhost:8011/health
# {"status":"ok","model_loaded":true}
```

---

## 后端配置

`backend/.env` 中的相关变量：

```ini
# MuseTalk 基础配置
MUSETALK_GPU_ID=0                        # GPU 编号 (与 CosyVoice 共存)
MUSETALK_API_URL=http://localhost:8011    # 常驻服务地址
MUSETALK_BATCH_SIZE=32                   # 推理批大小
MUSETALK_VERSION=v15                     # 模型版本
MUSETALK_USE_FLOAT16=true                # 半精度加速

# 推理质量参数
MUSETALK_DETECT_EVERY=2                  # 人脸检测降频间隔 (帧，越小越准但更慢)
MUSETALK_BLEND_CACHE_EVERY=2             # BiSeNet mask 缓存更新间隔 (帧)
MUSETALK_AUDIO_PADDING_LEFT=2            # Whisper 时序上下文 (左)
MUSETALK_AUDIO_PADDING_RIGHT=2           # Whisper 时序上下文 (右)
MUSETALK_EXTRA_MARGIN=14                 # v1.5 下巴区域扩展像素
MUSETALK_DELAY_FRAME=0                   # 音频-口型对齐偏移 (帧)
MUSETALK_BLEND_MODE=jaw                  # 融合模式: auto / jaw / raw
MUSETALK_FACEPARSING_LEFT_CHEEK_WIDTH=90   # 面颊宽度 (仅 v1.5)
MUSETALK_FACEPARSING_RIGHT_CHEEK_WIDTH=90

# 编码质量参数
MUSETALK_ENCODE_CRF=14                   # CRF 越小越清晰 (14≈接近视觉无损)
MUSETALK_ENCODE_PRESET=slow              # x264 preset (slow=高压缩效率)

# 混合唇形同步路由
LIPSYNC_DURATION_THRESHOLD=100           # 秒, >=此值用 MuseTalk
```

> **参数档位参考**：
> - 速度优先：`DETECT_EVERY=5, BLEND_CACHE_EVERY=5, ENCODE_CRF=18, ENCODE_PRESET=medium`
> - 质量优先（当前）：`DETECT_EVERY=2, BLEND_CACHE_EVERY=2, ENCODE_CRF=14, ENCODE_PRESET=slow`

---

## 相关文件

| 文件 | 说明 |
|------|------|
| `models/MuseTalk/scripts/server.py` | FastAPI 常驻服务 (端口 8011) |
| `run_musetalk.sh` | PM2 启动脚本 |
| `backend/app/services/lipsync_service.py` | 混合路由 + `_call_musetalk_server()` |
| `backend/app/core/config.py` | `MUSETALK_*` 配置项 |

---

## 性能优化 (server.py v2)

首次长视频测试 (136s, 3404 帧) 耗时 30 分钟。分析发现瓶颈在人脸检测 (28%)、BiSeNet 合成 (22%)、I/O (17%)，而非 UNet 推理 (17%)。

### 已实施优化

| 优化项 | 说明 |
|--------|------|
| `MUSETALK_BATCH_SIZE` 8→32 | RTX 3090 显存充裕，UNet 推理加速 ~3x |
| cv2.VideoCapture 直读帧 | 跳过 ffmpeg→PNG→imread 链路 |
| 人脸检测降频 (每N帧) | DWPose + FaceAlignment 只在采样帧运行，中间帧线性插值 bbox |
| BiSeNet mask 缓存 (每N帧) | `get_image_prepare_material` 每 N 帧运行，中间帧复用 |
| FFmpeg rawvideo 管道直编码 | 原 `cv2.VideoWriter(mp4v)` 中间有损文件改为 stdin 管道直写，消除一次冗余有损编码 |
| 参数环境变量化 | 所有推理/编码参数从 `.env` 读取，支持速度优先/质量优先快速切换 |
| 每阶段计时 | 7 个阶段精确计时，方便后续调优 |

### 编码链路

```
UNet 推理帧 (raw BGR24)
  → FFmpeg rawvideo stdin 管道
    → 一次 libx264 编码 (CRF 14, preset slow) + 音频 mux
      → 最终输出 .mp4
```

与旧流程对比：消除了 `cv2.VideoWriter(mp4v)` 中间有损文件，编码次数从 2 次减至 1 次。

### 调优参数

所有参数通过 `backend/.env` 配置（修改后需重启 MuseTalk 服务生效）：

```ini
MUSETALK_DETECT_EVERY=2        # 人脸检测降频间隔 (帧)，质量优先用 2，速度优先用 5
MUSETALK_BLEND_CACHE_EVERY=2   # BiSeNet mask 缓存间隔 (帧)
MUSETALK_ENCODE_CRF=14         # 编码质量 (14≈接近视觉无损，18=高质量)
MUSETALK_ENCODE_PRESET=slow    # 编码速度 (slow=高压缩效率，medium=平衡)
```

> 对于口播视频 (人脸几乎不动)，detect_every=5 的插值误差可忽略。
> 如人脸运动剧烈或追求最佳质量，使用 detect_every=2。

---

## 常见问题

### huggingface-hub 版本冲突

```
ImportError: huggingface-hub>=0.19.3,<1.0 is required
```

**解决**：降级 huggingface-hub

```bash
pip install "huggingface-hub>=0.19.3,<1.0"
```

### mmcv 导入失败

```bash
pip uninstall mmcv mmcv-full -y
mim install "mmcv==2.0.1"
```

### 音视频长度不匹配

已在 `musetalk/utils/audio_processor.py` 中修复（零填充逻辑），无需额外处理。
