后端适配指南

1. 后端必须满足的条件

无论接入哪个模型，最终都要满足：

输入：一个音频文件路径、一个视频文件路径。
输出：一个 mp4 文件路径。
失败：抛出异常或返回非零退出码，错误信息要能定位原因。

2. `command` 后端接入方式

command 后端是最推荐的第一步，因为它不要求立刻改 Python 代码。只要你的模型有命令行推理脚本，就可以接入。

示例：

$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 接入提示

适合快速验证，生态资料多。

典型命令形态：

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 后端跑通后，可以把逻辑固化成专用后端：

class Backend:
    name = "wav2lip"

    def process(self, audio_path, video_path, output_path, settings):
        ...
        return output_path

专用后端需要补充：

环境变量配置。
模型路径检查。
预热逻辑。
明确的异常类型。
最小单元测试。

7. 常见失败原因

CUDA / PyTorch 版本不匹配。
ffmpeg 不在 PATH。
视频里没有可检测的人脸。
输入视频分辨率过高导致显存不足。
模型脚本输出到了其它路径，没有写入 {output}。
Gradio 端口被占用。

3.8 KiB Raw Blame History Unescape Escape