cat-shark
121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# 后端适配指南
|
||
|
||
## 1. 后端必须满足的条件
|
||
|
||
无论接入哪个模型，最终都要满足：
|
||
|
||
- 输入：一个音频文件路径、一个视频文件路径。
|
||
- 输出：一个 mp4 文件路径。
|
||
- 失败：抛出异常或返回非零退出码，错误信息要能定位原因。
|
||
|
||
## 2. `command` 后端接入方式
|
||
|
||
`command` 后端是最推荐的第一步，因为它不要求立刻改 Python 代码。只要你的模型有命令行推理脚本，就可以接入。
|
||
|
||
示例：
|
||
|
||
```powershell
|
||
$env:LIPSYNC_BACKEND = "command"
|
||
$env:LIPSYNC_COMMAND_CWD = "D:\models\Wav2Lip"
|
||
$env:LIPSYNC_COMMAND_TIMEOUT_SECONDS = "1800"
|
||
$env:LIPSYNC_COMMAND_TEMPLATE = 'python inference.py --checkpoint_path D:\models\Wav2Lip\checkpoints\wav2lip_gan.pth --face {video_q} --audio {audio_q} --outfile {output_q}'
|
||
.\scripts\start.ps1 -Backend command
|
||
```
|
||
|
||
模板变量：
|
||
|
||
- `{audio}`：音频路径
|
||
- `{video}`：视频路径
|
||
- `{output}`：输出路径，模型必须写到这里
|
||
- `{workdir}`：临时工作目录
|
||
- `{cwd}`：命令执行目录，来自 `LIPSYNC_COMMAND_CWD`
|
||
- `{audio_q}` / `{video_q}` / `{output_q}` / `{workdir_q}` / `{cwd_q}`：已按当前系统 shell 转义的路径，推荐在命令模板中使用
|
||
|
||
## 3. Wav2Lip 接入提示
|
||
|
||
适合快速验证，生态资料多。
|
||
|
||
典型命令形态：
|
||
|
||
```powershell
|
||
python D:\models\Wav2Lip\inference.py `
|
||
--checkpoint_path D:\models\Wav2Lip\checkpoints\wav2lip_gan.pth `
|
||
--face {video_q} `
|
||
--audio {audio_q} `
|
||
--outfile {output_q}
|
||
```
|
||
|
||
注意点：
|
||
|
||
- 原始 Wav2Lip 对高清视频和复杂脸部姿态效果有限。
|
||
- 需要确认 ffmpeg 可用。
|
||
- 输出路径必须是 `{output}`，否则服务会认为失败。
|
||
- 如果模型脚本依赖相对路径资源，把 `LIPSYNC_COMMAND_CWD` 设为模型仓库根目录。
|
||
- 真实推理耗时较长时，设置 `LIPSYNC_COMMAND_TIMEOUT_SECONDS`；`0` 表示不限时。
|
||
|
||
## 3.1 命令后端失败诊断
|
||
|
||
`command` 后端会检查：
|
||
|
||
- 模板变量是否存在。
|
||
- `LIPSYNC_COMMAND_CWD` 是否是有效目录。
|
||
- 命令退出码是否为 0。
|
||
- `{output}` 指向的 mp4 是否存在且非空。
|
||
|
||
失败时会返回命令、退出码、耗时、stdout 尾部和 stderr 尾部。错误信息会隐藏常见 token、secret、password 字段，但不要把密钥写进命令模板；需要密钥时优先让模型脚本自己从环境变量读取。
|
||
|
||
## 4. MuseTalk 接入提示
|
||
|
||
效果通常比传统 Wav2Lip 更好，但环境更重。
|
||
|
||
你需要先在模型仓库中跑通官方 demo，再把官方命令改造成模板。重点确认：
|
||
|
||
- 是否支持直接传入任意视频。
|
||
- 是否需要预处理 avatar。
|
||
- 输出是否能指定到 `{output}`。
|
||
- 是否需要长驻服务或预热。
|
||
|
||
## 5. LstmSync 接入提示
|
||
|
||
主项目已有 `resources/lstmsync` 配置，说明它是项目期望的本地数字人口型同步方案之一。可选路线：
|
||
|
||
- 直接复用主项目 LstmSync 资源包作为独立服务后端。
|
||
- 或把 LstmSync 封成命令行脚本，再通过 `command` 后端调用。
|
||
|
||
需要确认：
|
||
|
||
- 模型权重位置。
|
||
- Python/CUDA/PyTorch 版本。
|
||
- 输入参数名和输出路径参数。
|
||
- 是否支持 `256m`、`256o`、`384m` 等权重选择。
|
||
|
||
## 6. 新增专用后端建议
|
||
|
||
当 `command` 后端跑通后，可以把逻辑固化成专用后端：
|
||
|
||
```python
|
||
class Backend:
|
||
name = "wav2lip"
|
||
|
||
def process(self, audio_path, video_path, output_path, settings):
|
||
...
|
||
return output_path
|
||
```
|
||
|
||
专用后端需要补充：
|
||
|
||
- 环境变量配置。
|
||
- 模型路径检查。
|
||
- 预热逻辑。
|
||
- 明确的异常类型。
|
||
- 最小单元测试。
|
||
|
||
## 7. 常见失败原因
|
||
|
||
- CUDA / PyTorch 版本不匹配。
|
||
- ffmpeg 不在 PATH。
|
||
- 视频里没有可检测的人脸。
|
||
- 输入视频分辨率过高导致显存不足。
|
||
- 模型脚本输出到了其它路径，没有写入 `{output}`。
|
||
- Gradio 端口被占用。
|