Ditto-Talkinghead 保姆级部署教程：蚂蚁开源运动空间扩散，实时可控说话头像合成

Ditto（仓库 antgroup/ditto-talkinghead）是蚂蚁集团开源的实时说话头像合成模型，论文《Ditto: Motion-Space Diffusion for Controllable Realtime Talking Head Synthesis》，已被 ACM MM 2025 接收。它的核心思路是把面部运动和图像渲染解耦：在"运动空间"里做扩散，只生成运动信号，再由渲染网络贴回人脸，从而实现单张照片 + 音频 → 实时说话视频，而且官方 2025 年 11 月 12 日开源了训练代码（train 分支）。与 EchoMimic 那种离线扩散生成不同，Ditto 主打"实时"两个字，官方还提供了 PyTorch 版权重和 TensorRT 两种推理后端。

本文按官方 README 走通：conda 环境、从 HuggingFace 下载 checkpoints、TensorRT 版与 PyTorch 版两条推理命令，并解释 Ampere_Plus 硬件不匹配时如何用 ONNX 转 TRT。

一、项目介绍与适用场景

Ditto 把数字人拆成"外观提取器 + 运动扩散 + 缝合/渲染网络"：音频经 HuBERT 编码后送入运动扩散模型，只生成面部运动潜变量，再由 decoder/stitch/warp 网络把运动贴回原图，输出实时说话视频。官方提供两种部署形态：

• TensorRT 版：预编译好的 .engine 文件，Ampere_Plus 架构（RTX 30/40、A100 等）直接跑，速度最快；
• PyTorch 版：2025.07.11 新增，纯 .pth 权重，兼容性更好、方便二次开发。

适用场景：实时对话数字人（在线客服、虚拟主播）、直播口播、对延迟敏感的交互式形象应用。官方还挂了 Colab Demo 可在线试。

二、核心功能逐条拆解

1. 单图 + 音频实时说话：一张人像照片驱动成说话视频。
2. 运动空间扩散：解耦面部运动与渲染，运动可控性强。
3. TensorRT 加速：预编译 engine，Ampere_Plus 显卡直接推理。
4. PyTorch 后端：纯 pth 权重，跨平台易改。
5. ONNX 中转：官方提供 cvt_onnx_to_trt.py 把 ONNX 转自定义 TRT。
6. 在线 / 离线配置：v0.4_hubert_cfg_trt_online.pkl 与 v0.4_hubert_cfg_trt.pkl 两套配置。
7. 训练代码开源：train 分支 2025.11.12 开放，可自训。
8. 基于 LivePortrait 技术栈：官方致谢基于 S2G-MDDiffusion 与 LivePortrait，与本站已写的 LivePortrait 同生态但用途不同（Ditto 是音频驱动实时说话头）。

三、全套官方链接

四、硬件与环境前置要求

官方 README "Installation" 一节测试环境原文：

• 系统：Centos 7.2
• GPU：A100
• Python：3.10
• TensorRT：8.6.1
• TRT 预编译后端：checkpoints/ditto_trt_Ampere_Plus/，要求显卡支持 Ampere_Plus（RTX 30/40 系、A100）；不支持则需用 ONNX 自行转换。
• 权重：从 HuggingFace digital-avatar/ditto-talkinghead 克隆到 checkpoints/ 目录。

五、多平台部署步骤

官方只提供源码部署（conda 或 pip 两种装法），未提供 Docker，本文不展开 Docker 小节。

5.1 源码部署

第 1 步：克隆代码。

git clone https://github.com/antgroup/ditto-talkinghead
cd ditto-talkinghead

第 2 步：创建 conda 环境（官方推荐）。

conda env create -f environment.yaml
conda activate ditto

解释：官方 environment.yaml 已锁定依赖（含 tensorrt==8.6.1）。如果 conda 创建失败，官方给了 pip 备选方案：先自己装好 pytorch + cuda + cudnn，再执行：

pip install \
    tensorrt==8.6.1 \
    librosa \
    tqdm \
    filetype \
    imageio \
    opencv_python_headless \
    scikit-image \
    cython \
    cuda-python \
    imageio-ffmpeg \
    colored \
    polygraphy \
    numpy==2.0.1

不用 conda 时还需按 https://www.ffmpeg.org/download.html 自行安装 ffmpeg（官方原文）。

第 3 步：下载权重到 checkpoints。

git lfs install
git clone https://huggingface.co/digital-avatar/ditto-talkinghead checkpoints

下载后目录结构（官方原文）：

./checkpoints/
├── ditto_cfg
│   ├── v0.4_hubert_cfg_trt.pkl
│   └── v0.4_hubert_cfg_trt_online.pkl
├── ditto_onnx
│   ├── appearance_extractor.onnx
│   ├── blaze_face.onnx
│   ├── decoder.onnx
│   ├── face_mesh.onnx
│   ├── hubert.onnx
│   ├── insightface_det.onnx
│   ├── landmark106.onnx
│   ├── landmark203.onnx
│   ├── libgrid_sample_3d_plugin.so
│   ├── lmdm_v0.4_hubert.onnx
│   ├── motion_extractor.onnx
│   ├── stitch_network.onnx
│   └── warp_network.onnx
└── ditto_trt_Ampere_Plus
    ├── appearance_extractor_fp16.engine
    ├── blaze_face_fp16.engine
    ├── decoder_fp16.engine
    ├── face_mesh_fp16.engine
    ├── hubert_fp32.engine
    ├── insightface_det_fp16.engine
    ├── landmark106_fp16.engine
    ├── landmark203_fp16.engine
    ├── lmdm_v0.4_hubert_fp32.engine
    ├── motion_extractor_fp32.engine
    ├── stitch_network_fp16.engine
    └── warp_network_fp16.engine

解释：ditto_cfg/v0.4_hubert_cfg_trt.pkl 是离线配置，v0.4_hubert_cfg_trt_online.pkl 是在线配置。

5.2 Docker 部署

官方未提供 Docker 部署方式，本文不展开。

六、配置文件全部参数解释

官方 README 明确两个配置文件用途：

推理脚本参数（inference.py，官方原文）：

七、启动、后台常驻与开机自启

7.1 TensorRT 版推理（官方示例命令）

python inference.py \
    --data_root "./checkpoints/ditto_trt_Ampere_Plus" \
    --cfg_pkl "./checkpoints/ditto_cfg/v0.4_hubert_cfg_trt.pkl" \
    --audio_path "./example/audio.wav" \
    --source_path "./example/image.png" \
    --output_path "./tmp/result.mp4"

7.2 PyTorch 版推理

先把 PyTorch 权重目录放好（官方 ditto_pytorch/models/*.pth + aux_models/*.onnx），然后：

python inference.py \
    --data_root "./checkpoints/ditto_pytorch" \
    --cfg_pkl "./checkpoints/ditto_cfg/v0.4_hubert_cfg_pytorch.pkl" \
    --audio_path "./example/audio.wav" \
    --source_path "./example/image.png" \
    --output_path "./tmp/result.mp4"

7.3 后台常驻

Ditto 是单次推理脚本，跑完即退出；如需做成常驻 API，可自行用 FastAPI 包一层，官方未提供常驻服务，本文不展开 systemd 细节。

八、功能实操教程

第 1 步：conda env create -f environment.yaml 成功后 conda activate ditto。

第 2 步：git lfs install && git clone https://huggingface.co/digital-avatar/ditto-talkinghead checkpoints，确认目录树与官方一致。

第 3 步：用官方示例 ./example/audio.wav 和 ./example/image.png 跑 7.1 的 TensorRT 命令，输出到 ./tmp/result.mp4。

第 4 步：如果显卡不支持 Ampere_Plus，先做 ONNX→TRT 转换：

python scripts/cvt_onnx_to_trt.py --onnx_dir "./checkpoints/ditto_onnx" --trt_dir "./checkpoints/ditto_trt_custom"

然后推理时把 --data_root 指向 ./checkpoints/ditto_trt_custom（官方原文）。

第 5 步：换自己的图和音频：把 --source_path 换成正面人像、--audio_path 换成自己的 wav，重新跑命令，得到自己的数字人说话视频。

九、全套报错故障排查

1. TRT engine 加载失败 / 架构不兼容 原因：官方预编译的 ditto_trt_Ampere_Plus 只支持 Ampere_Plus 架构显卡。 解决：用 ONNX 自行转换（本文第 4 步命令），--data_root 改 ./checkpoints/ditto_trt_custom。

2. tensorrt 版本报错 / import 失败 原因：官方锁定 tensorrt==8.6.1。 解决：pip install tensorrt==8.6.1；系统还需装对应版本的 TensorRT runtime（NVIDIA 官网）。

3. ffmpeg not found 原因：非 conda 安装时缺 ffmpeg。 解决：按 https://www.ffmpeg.org/download.html 安装并加入 PATH。

4. HuggingFace 克隆超时 原因：网络问题。 解决：export HF_ENDPOINT=https://hf-mirror.com 后再 git clone，或手动下载。

5. conda env create 失败 原因：environment.yaml 依赖冲突。 解决：官方给出 pip 备选方案——先装好 pytorch/cuda/cudnn，再按本文第五节的 pip 列表安装。

十、升级、回滚与卸载

• 升级：git pull；推理用 main 分支、训练切 train 分支（2025.11.12 训练代码开源）；权重更新后重新克隆 checkpoints。
• 回滚：git checkout <旧tag>；checkpoints 目录建议备份。
• 卸载：删除仓库、conda env remove -n ditto。

十一、商用许可与合规风险提示

• 代码为 Apache-2.0，允许商用、修改、分发。
• 官方实现基于 S2G-MDDiffusion 与 LivePortrait，需同时遵守上游许可。
• 说话头像合成涉及真人肖像与声音权，实时交互场景下更要防范 deepfake 滥用，使用真实人物形象必须取得本人授权。

参考链接

• 官方 README：https://github.com/antgroup/ditto-talkinghead/blob/main/README.md
• 权重（HF）：https://huggingface.co/digital-avatar/ditto-talkinghead
• 论文：https://arxiv.org/abs/2411.19509
• 项目页：https://digital-avatar.github.io/ai/Ditto/