# Day 3: MuseTalk 推理环境修复与验证

---

## 🔧 MuseTalk 推理环境修复

### 问题描述
MuseTalk 口型同步功能失效。后端日志显示任务完成，但生成的视频与原视频大小完全一致（28MB），说明执行了 fallback 逻辑（直接复制原视频），MuseTalk 推理过程静默失败。

### 根本原因分析
1.  **PyTorch 版本不兼容**：服务器安装了 PyTorch 2.5.1+cu121，但 mmcv 没有以此版本预编译的 CUDA 扩展，导致 `import mmcv` 失败。
2.  **MMLab 依赖缺失**：conda 环境中缺少 `mmcv`, `mmdet`, `mmengine` 等必要依赖。
3.  **模型路径错误**：HuggingFace 下载的模型结构包含嵌套目录（如 `models/musetalk/musetalk/`），且部分文件夹名称不符合代码预期（如服务器上为 `sd-vae-ft-mse`，代码期望 `sd-vae`）。
4.  **模型权重缺失**：缺少 `dwpose`, `syncnet`, `face-parse-bisent` 等辅助模型权重。

### 解决方案

#### 1. 环境重建
降级 PyTorch 并安装官方推荐的 MMLab 版本：
```bash
# 降级 PyTorch (配合 CUDA 11.8)
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118

# 安装 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
```

#### 2. 模型目录修复
重组目录结构并创建符号链接以匹配代码预期：
```bash
cd models/MuseTalk/models
# 修复 sd-vae 路径
ln -s sd-vae-ft-mse sd-vae
# 修复 config.json 命名
cd musetalk && ln -s musetalk.json config.json
```

#### 3. 补全缺失模型
下载 `dwpose`, `syncnet`, `face-parse-bisent` 模型到对应目录。

### 结果
- ✅ **推理脚本成功运行**：测试脚本成功加载所有模型并处理视频帧。
- ✅ **帧生成确认**：在输出目录中验证生成了 593 帧 PNG 图片。

### ⚠️ 遗留问题
- **视频合成未完成**：虽然推理生成了帧图片，但最终的 MP4 视频文件尚未生成。可能是 `inference.py` 中调用 ffmpeg 进行视频合成的步骤有问题，或者 ffmpeg 调用参数需要调整。需要进一步排查视频合成逻辑。

---

## 🛠️ 视频合成问题修复

### 问题分析
经排查 `inference.py` 代码，发现以下问题：
1.  **FFmpeg 调用静默失败**：原代码使用 `os.system()` 调用 ffmpeg，无法捕获错误输出，且忽略了返回值。
2.  **API 参数不匹配**：`musetalk_api.py` 传递 `--video_path` 等命令行参数，但 `inference.py` 仅支持 YAML 配置文件，导致 API 调用时参数解析错误。
3.  **临时文件清理过早**：发生错误时立即删除了临时帧，导致无法排查问题。
4.  **路径兼容性**：FFmpeg 命令中对路径的处理可能在某些 shell 环境下存在问题。

### 修复方案
已重写 `scripts/inference.py`：
1.  **增强 FFmpeg 调用**：替换 `os.system` 为 `subprocess.run(..., check=True, capture_output=True)`，即使失败也能打印完整的 stdout/stderr 错误日志。
2.  **支持命令行参数**：添加 `--video_path`、`--audio_path` 和 `--output_path` 参数支持，使其能直接被 API 调用（通过构建临时任务配置）。
3.  **优化错误处理**：增加 try-except 块，并在失败时保留临时文件以便调试，添加了详细的 Traceback 打印。
4.  **完善参数映射**：自动处理 `output_path` 到 `output_vid_name` 的映射。

### 下一步
1. 将本地更新的 `models/MuseTalk/scripts/inference.py` 同步到服务器。
2. 在服务器上运行测试，观察 FFmpeg 是否成功合成 MP4。
3. 验证 API 端到端调用是否成功。

---

## 🐛 前端端口配置修复 (17:03)

**问题**：后端日志或文档指引访问 3002 端口，但 Next.js 默认启动在 3000，导致无法访问。
**修复**：
1. 修改 `frontend/package.json` 默认启动命令为 `next dev -p 3002`。
2. 更新 `DEPLOY_MANUAL.md` 明确端口参数 `--port 3002`。
**状态**：✅ 已修复