8.7 KiB
8.7 KiB
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 环境
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 预编译包依赖。
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
3. 依赖安装
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)
下载方式
使用项目自带脚本：
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk
conda activate musetalk
bash download_weights.sh
或手动 Python API 下载：
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'])
"
创建必要的软链接
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk/models/musetalk
ln -sf musetalk.json config.json
ln -sf ../musetalkV15 musetalkV15
关键：
musetalk/musetalkV15软链接缺失会导致权重检测失败 (weights: False)。
服务启动
PM2 进程管理（推荐）
# 首次注册
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
手动启动
cd /home/rongye/ProgramFiles/ViGent2/models/MuseTalk
/home/rongye/ProgramFiles/miniconda3/envs/musetalk/bin/python scripts/server.py
健康检查
curl http://localhost:8011/health
# {"status":"ok","model_loaded":true}
后端配置
backend/.env 中的相关变量：
# 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 服务生效）：
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
pip install "huggingface-hub>=0.19.3,<1.0"
mmcv 导入失败
pip uninstall mmcv mmcv-full -y
mim install "mmcv==2.0.1"
音视频长度不匹配
已在 musetalk/utils/audio_processor.py 中修复（零填充逻辑），无需额外处理。