init

2026-03-27 10:49:34 +08:00
commit 22a5f31847
56 changed files with 5145 additions and 0 deletions
@@ -0,0 +1,517 @@
+# 数字人视频生成 — 研究与验证记录
+
+> 本文档记录了从零开始探索「单图 + 音频 → 说话视频」的完整过程，
+> 包括工具选型、环境踩坑、最终跑通的完整流程，以及对产品化的建议。
+>
+> 日期：2026-03-25
+> 硬件：RTX 5090 (Blackwell, sm_120), CUDA 12.9, WSL2
+
+---
+
+## 一、目标
+
+给定一张人物图片和一段音频，生成该人物"说话"的视频：
+- 嘴型与音频内容同步
+- 头部有自然动作（非僵硬的照片）
+- 可扩展至实时/直播场景
+
+---
+
+## 二、工具选型过程
+
+### 2.1 最初方向：LivePortrait
+
+- **项目**：https://github.com/KlingTeam/LivePortrait（快手）
+- **本质**：视频驱动的人脸动画，需要一个"驱动视频"来控制人物表情和头部运动
+- **误区澄清**：网上有描述称 LivePortrait 支持"音频驱动"，这是**不准确的**。它只能从驱动视频中提取音频附加到输出，无法用音频生成嘴型
+- **结论**：LivePortrait 适合生成头部动作底片，不能单独完成任务
+
+### 2.2 调研其他工具
+
+| 工具 | 厂商 | 核心能力 | 实时性 | 结论 |
+|------|------|---------|--------|------|
+| LatentSync 1.6 | 字节跳动 | 扩散模型唇形同步，512x512 | ❌ 约4fps | 质量好，但太慢 |
+| MuseTalk 1.5 | 腾讯 | 单步推理唇形同步 | ⚠️ 约7fps | 速度可接受，质量好 |
+| Live Avatar | 阿里 | 140B 扩散模型 | ❌ 需集群 | 单卡不可行 |
+| SadTalker | 开源 | 音频驱动全脸动画 | ❌ | 未测试 |
+| Sonic | 腾讯 | 音频驱动 | 未知 | 项目在 `/home/xsl/work/Sonic`，未测试 |
+
+### 2.3 最终方案
+
+**两阶段流水线：**
+
+```
+hairstyle-result.jpg
+        ↓
+  [LivePortrait]  ←  驱动视频 (d3.mp4, 自然头部动作)
+        ↓
+  头动底片视频 (hairstyle-result--d3.mp4, 11.8s)
+        ↓
+   [MuseTalk]  ←  音频 (test_speech_10s.wav)
+        ↓
+  最终视频 (嘴型同步 + 头部运动)
+```
+
+---
+
+## 三、环境配置（重要踩坑记录）
+
+### 3.1 RTX 5090 的核心问题
+
+RTX 5090 是 Blackwell 架构（sm_120），**PyTorch 稳定版（2.6 及以下）不支持**。
+所有项目都必须使用 PyTorch nightly cu128：
+
+```bash
+pip install --pre torch torchvision torchaudio \
+  --index-url https://download.pytorch.org/whl/nightly/cu128
+# 已验证版本：torch-2.12.0.dev20260324+cu128
+```
+
+**这是最先要做的事，否则所有 CUDA 推理都会报错：**
+```
+CUDA error: no kernel image is available for execution on the device
+```
+
+### 3.2 HuggingFace CLI 命令名
+
+在某些 conda 环境中，命令名是 `hf` 而不是 `huggingface-cli`：
+
+```bash
+which hf          # /home/xsl/miniconda3/envs/MuseTalk/bin/hf
+hf --version      # 1.7.2
+```
+
+下载需要 Token：
+```bash
+export HF_TOKEN=<your_token>
+hf download <repo> <file> --local-dir <dir>
+```
+
+---
+
+## 四、LivePortrait 部署
+
+### 4.1 环境
+
+```bash
+conda create -n LivePortrait python=3.10 -y
+conda activate LivePortrait
+pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128
+cd /home/xsl/work/LivePortrait
+pip install -r requirements.txt
+```
+
+### 4.2 权重
+
+```bash
+# 约 1.1GB
+huggingface-cli download KlingTeam/LivePortrait \
+  --local-dir pretrained_weights \
+  --exclude "*.git*" "README.md" "docs"
+```
+
+目录结构：
+```
+pretrained_weights/
+├── insightface/        (~21MB)
+├── liveportrait/       (~608MB)
+└── liveportrait_animals/ (~500MB)
+```
+
+### 4.3 生成头动底片
+
+```bash
+conda activate LivePortrait
+cd /home/xsl/work/LivePortrait
+
+python inference.py \
+  -s /path/to/portrait.jpg \
+  -d assets/examples/driving/d3.mp4 \
+  --flag_crop_driving_video \
+  -o /home/xsl/work/head_motion_base
+```
+
+**驱动视频参考**（位于 `assets/examples/driving/`）：
+
+| 文件 | 时长 | 特点 |
+|------|------|------|
+| d3.mp4 | 11.8s | 自然说话动作，与10s音频匹配 |
+| d6.mp4 | 33.6s | 长片段，适合循环 |
+| d10.mp4 | 15.0s | 较长 |
+
+**技巧**：选择时长接近音频时长的驱动视频；`--flag_crop_driving_video` 会自动裁剪驱动视频。
+
+### 4.4 已知警告（可忽略）
+
+```
+[E:onnxruntime] Failed to load library libonnxruntime_providers_cuda.so
+```
+onnxruntime-gpu 依赖 CUDA 11.x，与系统 CUDA 12.9 不兼容，人脸检测自动回退 CPU，不影响结果。
+
+---
+
+## 五、LatentSync 部署（已验证，非推荐方案）
+
+> **结论**：质量好，但速度太慢（4fps），不适合产品化。作为备选方案保留。
+
+### 5.1 环境
+
+```bash
+conda create -y -n latentsync python=3.10.13
+conda activate latentsync
+conda install -y -c conda-forge ffmpeg
+
+pip install -r /home/xsl/work/LatentSync/requirements.txt
+
+# RTX 5090 必须卸载稳定版再装 nightly
+pip uninstall torch torchvision torchaudio -y
+pip install --pre torch torchvision torchaudio \
+  --index-url https://download.pytorch.org/whl/nightly/cu128
+```
+
+### 5.2 权重（约 4.9GB）
+
+```bash
+cd /home/xsl/work/LatentSync
+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.3 输入准备
+
+LatentSync 需要**视频**（非图片）+ **WAV 音频**：
+
+```bash
+# 图片 → 视频
+ffmpeg -loop 1 -i portrait.jpg \
+  -t <duration> \
+  -vf "scale=512:512:force_original_aspect_ratio=decrease,pad=512:512:(ow-iw)/2:(oh-ih)/2" \
+  -r 25 -c:v libx264 -pix_fmt yuv420p input_video.mp4 -y
+
+# mp3 → wav
+ffmpeg -i audio.mp3 -ar 16000 -ac 1 input_audio.wav -y
+```
+
+### 5.4 推理
+
+```bash
+conda activate latentsync
+cd /home/xsl/work/LatentSync
+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 "assets/input_video.mp4" \
+    --audio_path "assets/input_audio.wav" \
+    --video_out_path "video_out.mp4"
+```
+
+---
+
+## 六、MuseTalk 部署（推荐方案）
+
+### 6.1 项目路径
+
+```
+/home/xsl/work/MuseTalk
+```
+
+### 6.2 环境搭建（完整步骤，含所有踩坑修复）
+
+```bash
+conda create -y -n MuseTalk python=3.10
+conda activate MuseTalk
+conda install -y -c conda-forge ffmpeg
+
+# 1. PyTorch nightly（RTX 5090 必须）
+pip install --pre torch torchvision torchaudio \
+  --index-url https://download.pytorch.org/whl/nightly/cu128
+
+# 2. 项目依赖
+cd /home/xsl/work/MuseTalk
+pip install -r requirements.txt
+
+# 3. 修复 chumpy 构建问题
+pip install --no-build-isolation chumpy
+
+# 4. MMLab（版本必须严格匹配，不可随意升降）
+pip install mmengine
+MMCV_WITH_OPS=1 pip install mmcv==2.1.0 --no-build-isolation  # 需要系统 nvcc
+pip install "mmdet>=3.3.0"        # ≥3.3.0 才兼容 mmcv 2.1.0
+pip install "mmpose>=1.3.0"       # ≥1.3.0 才兼容 mmcv 2.1.0
+pip install xtcocotools json-tricks munkres
+
+# 5. 更新 transformers（旧版与 huggingface-hub 1.x 冲突）
+pip install "transformers>=4.45.0"
+```
+
+### 6.3 MMLab 版本兼容矩阵（关键）
+
+```
+mmcv 2.1.0  ←→  mmdet ≥3.3.0  ←→  mmpose ≥1.3.0
+```
+
+| 踩坑 | 原因 | 修复 |
+|------|------|------|
+| mmcv 构建失败 | nightly PyTorch 没有预编译轮子 | `MMCV_WITH_OPS=1 pip install mmcv==2.1.0 --no-build-isolation`（需系统 nvcc） |
+| `MMCV==2.1.0 is used but incompatible` | mmdet 3.1.0 要求 mmcv < 2.1.0 | 升级到 mmdet ≥3.3.0 |
+| `mmpose 1.1.0 incompatible` | 同上 | 升级到 mmpose ≥1.3.0 |
+| `transformers ImportError` | huggingface-hub 1.x 与旧 transformers 冲突 | 升级 transformers ≥4.45.0 |
+
+### 6.4 权重下载
+
+```bash
+cd /home/xsl/work/MuseTalk
+export HF_TOKEN=<your_token>
+
+# 注意：此环境中命令是 hf，不是 huggingface-cli
+hf download TMElyralab/MuseTalk \
+  "musetalkV15/musetalk.json" "musetalkV15/unet.pth" \
+  --local-dir models
+
+hf download stabilityai/sd-vae-ft-mse \
+  config.json diffusion_pytorch_model.bin \
+  --local-dir models/sd-vae
+
+hf download yzd-v/DWPose \
+  dw-ll_ucoco_384.pth \
+  --local-dir models/dwpose
+
+hf download openai/whisper-tiny \
+  config.json pytorch_model.bin preprocessor_config.json \
+  --local-dir models/whisper
+
+hf download ByteDance/LatentSync \
+  latentsync_syncnet.pt \
+  --local-dir models/syncnet
+
+# face-parse 权重（不在 HuggingFace）
+pip install gdown
+gdown --id 154JgKpzCPW82qINcVieuPH3fZ2e0P812 -O models/face-parse-bisent/79999_iter.pth
+curl -L https://download.pytorch.org/models/resnet18-5c106cde.pth \
+  -o models/face-parse-bisent/resnet18-5c106cde.pth
+```
+
+权重总大小约 **5GB**：
+```
+models/
+├── musetalkV15/
+│   ├── unet.pth         (3.2GB)
+│   └── musetalk.json
+├── sd-vae/
+│   ├── diffusion_pytorch_model.bin  (320MB)
+│   └── config.json
+├── dwpose/
+│   └── dw-ll_ucoco_384.pth  (389MB)
+├── whisper/
+│   └── pytorch_model.bin    (145MB)
+├── syncnet/
+│   └── latentsync_syncnet.pt  (1.4GB)
+└── face-parse-bisent/
+    ├── 79999_iter.pth     (51MB)
+    └── resnet18-5c106cde.pth  (45MB)
+```
+
+### 6.5 PyTorch 2.6+ 兼容性补丁（必须）
+
+PyTorch 2.6+ 将 `torch.load` 的 `weights_only` 默认值改为 `True`，导致 MuseTalk 加载旧格式权重失败。
+已在 `scripts/inference.py` 中加入 monkey-patch：
+
+```python
+# 在 inference.py 开头的 import torch 后面加入：
+_orig_torch_load = torch.load
+def _patched_torch_load(f, *args, **kwargs):
+    kwargs.setdefault('weights_only', False)
+    return _orig_torch_load(f, *args, **kwargs)
+torch.load = _patched_torch_load
+```
+
+同样的补丁也需要加到 `scripts/realtime_inference.py`（如果使用实时模式）。
+
+### 6.6 推理配置文件
+
+创建 YAML 配置文件（`configs/inference/my_task.yaml`）：
+
+```yaml
+task_0:
+ video_path: "/path/to/head_motion_video.mp4"
+ audio_path: "/path/to/audio.wav"
+ bbox_shift: 0   # 可选：调整嘴部区域位置，负值下移，正值上移
+```
+
+### 6.7 运行推理
+
+```bash
+conda activate MuseTalk
+cd /home/xsl/work/MuseTalk
+
+python -m scripts.inference \
+  --inference_config configs/inference/my_task.yaml \
+  --result_dir results/output \
+  --unet_model_path models/musetalkV15/unet.pth \
+  --unet_config models/musetalkV15/musetalk.json \
+  --version v15
+```
+
+输出路径：`results/output/v15/<video_name>.mp4`
+
+---
+
+## 七、完整流水线（已验证示例）
+
+### 输入
+
+- 图片：`/home/xsl/work/LivePortrait/hairstyle-result.jpg`（1080x1920，正面人像）
+- 音频：`/home/xsl/work/LivePortrait/test_speech_10s.mp3`（11.8秒，中文语音）
+
+### Step 1：生成头动底片
+
+```bash
+conda activate LivePortrait
+cd /home/xsl/work/LivePortrait
+
+python inference.py \
+  -s /home/xsl/work/LivePortrait/hairstyle-result.jpg \
+  -d assets/examples/driving/d3.mp4 \
+  --flag_crop_driving_video \
+  -o /home/xsl/work/head_motion_base
+```
+
+输出：`/home/xsl/work/head_motion_base/hairstyle-result--d3.mp4`（11.8s, 2.1MB）
+
+### Step 2：音频转 WAV
+
+```bash
+ffmpeg -i /home/xsl/work/LivePortrait/test_speech_10s.mp3 \
+  -ar 16000 -ac 1 /tmp/input_audio.wav -y
+```
+
+### Step 3：MuseTalk 嘴型同步
+
+```bash
+conda activate MuseTalk
+cd /home/xsl/work/MuseTalk
+
+cat > configs/inference/hairstyle.yaml << 'EOF'
+task_0:
+ video_path: "/home/xsl/work/head_motion_base/hairstyle-result--d3.mp4"
+ audio_path: "/tmp/input_audio.wav"
+EOF
+
+python -m scripts.inference \
+  --inference_config configs/inference/hairstyle.yaml \
+  --result_dir results/hairstyle \
+  --unet_model_path models/musetalkV15/unet.pth \
+  --unet_config models/musetalkV15/musetalk.json \
+  --version v15
+```
+
+输出：`/home/xsl/work/MuseTalk/results/hairstyle/v15/hairstyle-result--d3_input_audio.mp4`
+
+### 性能数据
+
+| 阶段 | 耗时 | 帧数 | 等效速度 |
+|------|------|------|---------|
+| LivePortrait 头动生成 | ~30s | 295帧 | ~10fps |
+| MuseTalk 嘴型合成 | ~50s | 354帧 | ~7fps |
+| 总计 | ~80s | — | 生成12s视频 |
+
+---
+
+## 八、产品化建议
+
+### 8.1 当前方案的局限
+
+1. **非实时**：总体约 7fps 生成速度，12秒视频需要 80 秒处理
+2. **两套环境**：LivePortrait 和 MuseTalk 分别用不同 conda 环境，pipeline 不够整洁
+3. **头动单调**：驱动视频固定，长时间使用会重复
+4. **图片分辨率**：MuseTalk 处理区域限定在 256x256 嘴部区域
+
+### 8.2 提速方向
+
+- **MuseTalk 实时模式**：`scripts/realtime_inference.py` 支持流式处理，延迟更低
+- **头动循环库**：预先用 LivePortrait 生成多种头动视频（点头、摇头、思考等），运行时随机选取
+- **TensorRT 量化**：对 MuseTalk UNet 做 TRT 优化，预计可提速 2-3x
+
+### 8.3 架构建议（产品级）
+
+```
+音频输入
+   ↓
+[ASR/VAD]  →  静音检测、分段
+   ↓
+[MuseTalk 实时流]  ←  头动视频循环
+   ↓
+[后处理：美颜/超分]（可选）
+   ↓
+视频输出流
+```
+
+### 8.4 替代方案调研建议
+
+在正式产品开发前，建议调研以下工具：
+- **Sonic**（`/home/xsl/work/Sonic`）：已有项目，未测试，可能支持更好的实时性
+- **EchoMimic**：阿里的音频驱动方案，支持半身动作
+- **AniPortrait**：同时驱动头部和嘴型
+
+---
+
+## 九、目录结构总览
+
+```
+/home/xsl/work/
+├── LivePortrait/          # 头部动作驱动
+│   ├── pretrained_weights/  (~1.1GB)
+│   ├── hairstyle-result.jpg # 测试图片
+│   ├── test_speech_10s.mp3  # 测试音频
+│   └── DEPLOYMENT.md        # 详细部署笔记
+│
+├── LatentSync/            # 扩散模型唇形同步（备用）
+│   ├── checkpoints/         (~4.9GB)
+│   └── video_out.mp4        # 测试输出
+│
+├── MuseTalk/              # 单步推理唇形同步（推荐）
+│   ├── models/              (~5GB)
+│   └── results/hairstyle/v15/hairstyle-result--d3_input_audio.mp4
+│
+├── head_motion_base/      # LivePortrait 生成的头动底片
+│   └── hairstyle-result--d3.mp4
+│
+└── Sonic/                 # 待调研
+```
+
+### Conda 环境
+
+```bash
+conda env list
+# LivePortrait   /home/xsl/miniconda3/envs/LivePortrait
+# latentsync     /home/xsl/miniconda3/envs/latentsync
+# MuseTalk       /home/xsl/miniconda3/envs/MuseTalk
+```
+
+---
+
+## 十、快速复现命令（Cheat Sheet）
+
+```bash
+# === 生成一个说话视频（完整流程）===
+
+# 1. 生成头动底片
+conda activate LivePortrait && cd /home/xsl/work/LivePortrait
+python inference.py -s portrait.jpg -d assets/examples/driving/d3.mp4 \
+  --flag_crop_driving_video -o /tmp/head_motion
+
+# 2. 音频转 WAV
+ffmpeg -i input.mp3 -ar 16000 -ac 1 /tmp/audio.wav -y
+
+# 3. 嘴型同步
+conda activate MuseTalk && cd /home/xsl/work/MuseTalk
+python -m scripts.inference \
+  --inference_config <(echo "task_0:\n video_path: /tmp/head_motion/*.mp4\n audio_path: /tmp/audio.wav") \
+  --result_dir /tmp/output \
+  --unet_model_path models/musetalkV15/unet.pth \
+  --unet_config models/musetalkV15/musetalk.json \
+  --version v15
+```