MDM实战：基于扩散模型的文本驱动3D人体动作生成全解析

简介：扩散模型在生成式AI领域正逐步取代GAN与VAE，成为文本驱动视觉内容生成的主流技术。其核心思想是通过逐步加噪与去噪的逆过程，从随机噪声中还原出符合语义的高质量数据，训练稳定且生成结果天然具备多样性。在3D人体动作生成任务中，扩散模型能够将自然语言描述映射为连续的运动序列，广泛应用于游戏动画、虚拟人交互和具身智能仿真等场景。本文以Motion Diffusion Model（MDM）的开源PyTorch实现为对象，系统讲解其基于CLIP文本编码器与Transformer去噪网络的三段式架构，覆盖HumanML3D数据集预处理、训练调参、DDIM采样加速、可视化渲染及常见工程问题排查，帮助读者从理论到实操完整掌握文本驱动动作生成的落地流程。 去年因为一个动画自动生成的内部项目，我在文本驱动的人体运动生成上折腾了不少时间。试过几套方案之后，最终在一个开源项目里扎了很久：由《Human Motion Diffusion Model》（MDM）论文第一作者 Guy Tevet 开源的 PyTorch 实现。这个仓库把“输入一句话，生成一段 3D 人体动作”这件事从论文落地成了可以直接实操的代码，在 HumanML3D 和 KIT-ML 两个主流数据集上训练和评测，生成结果还能渲染成视频看效果。

这篇文章不是论文复读机，而是从实际使用的角度，把整个项目的设计思路、环境搭建、数据管线、训练推理全流程以及踩过的坑一次性讲清楚。不论你是刚接触扩散模型的研究生，还是想把动作生成接入游戏或虚拟人项目中的工程师，都可以参考这套流程。看完你至少能跑通官方的训练和推理，并且知道每个环节为什么这么做。

1. 项目整体设计与核心思路拆解

1.1 为什么是扩散模型

在 MDM 出现之前，文本生成人体运动的主流方案是 GAN 和 VAE 两个流派。GAN 的思路是生成器直接输出动作序列，判别器判断动作是否真实、是否匹配文本。问题在于 GAN 训练非常不稳定，动不动就模式崩溃，生成的多样性也有限。VAE 相对稳定，但生成的 motion 质量偏糊，动作的细节和物理合理性都不够。

扩散模型的思路完全不同。它不直接“生成”一个动作，而是先给动作数据逐步加上高斯噪声，直到数据变成纯噪声；然后训练一个网络学习逆过程，从纯噪声中一步步恢复出动作。这个过程有两个关键优势：一是训练目标非常稳定，每一步只需要做回归任务，没有对抗博弈；二是生成时可以从噪声中采样，天然具备多样性。MDM 的论文里大量实验也证明了，在 FID、R-Precision 这些指标上，扩散模型明显压过当年的 GAN/VAE 方案。

不过，扩散模型也有代价——采样速度慢。原始 DDPM 需要上千步迭代才能从噪声还原出动作。好在实际用起来可以用 DDIM 等加速采样器，几十步也能得到不错的效果，后面我会讲到这个技巧。

1.2 整体架构：三段式流水线

MDM 的架构看起来不复杂，核心是一条三段式流水线。

第一段是文本编码器，用的是 CLIP 的 text encoder。CLIP 是在大规模图文对上训练出来的，它的文本语义空间对于动作描述也很友好。比如 “a person walks forward” 和 “the person walked forward and stopped” 这类描述，CLIP 能把它们映射到相近的语义向量，这对动作生成来说非常关键，因为自然语言表达动作的方式太灵活了。

第二段是扩散过程本体。前向过程往真实动作数据里逐步加噪，生成训练用的带噪样本；反向过程则用去噪网络逐步去掉噪声，从随机噪声中恢复出动作序列。这个去噪网络就是整个模型的骨干，MDM 用的是 Transformer Encoder。

第三段是条件注入。MDM 不是无条件生成，它要把文本语义向量和扩散过程的时间步信息一起送进 Transformer。具体做法是把运动序列切分成 token，和时间步 embedding、文本 embedding 拼成一个序列送入 Transformer Encoder，让 self-attention 在运动 token 和条件 token 之间建模关联。这样模型在每一步去噪时，都能看到“当前动作长什么样、在第几步、该匹配什么语义”这三个信息。

这套设计的巧妙之处在于，它把“文本生成动作”拆成“理解文本”和“生成动作”两个相对独立的模块，而不是像端到端模型那样把所有知识都塞进一个黑盒。复现和调试时思路很清晰：生成效果不好，要么是文本理解不到位，要么是动作去噪能力不行，可以分别排查。

1.3 运动表示与数据集

MDM 默认使用 HumanML3D 数据集。训练前，动作数据会被预处理成固定维度的特征向量，这也是扩散模型能直接处理的空间。

HumanML3D 的数据每条 motion 以 20fps 的帧率保存，每帧由 263 维特征构成。这 263 维不是随便拼出来的，而是从 SMPL 参数和关节位置里提取的，包含 22 个关节点在局部坐标系下的位置、旋转、根节点的线速度和角速度、脚部接触标记等。为什么不用原始 SMPL 姿态参数直接做扩散？因为旋转矩阵或轴角这类参数并不在欧氏空间上，扩散模型里的加噪去噪操作默认假设数据是欧氏空间里的向量，直接对姿态参数做线性插值会产生不合理的姿态。把动作转换到关节位置、速度这种特征空间之后，加噪过程才符合直觉，训练也稳定得多。

还有一个细节值得注意：HumanML3D 对动作做了对齐和长度处理，还提供了 44,970 条文本描述对应 14,616 个动作序列，文本和动作的配对质量非常高。MDM 的仓库里同时支持 HumanML3D 和 KIT-ML 两个数据集，如果你是想快速验证想法，KIT-ML 更小，训练速度更快。

2. 环境搭建与依赖准备

2.1 PyTorch 环境配置

这个项目是基于 PyTorch 的，第一步是准备一个可用的 PyTorch 环境。官方给了environment.yml，里面列出了 Python 3.8、PyTorch 1.12 等版本。如果你按官方文件装，基本一条命令能搞定：

conda env create -f environment.yml conda activate mdm

但这里有个现实问题：现在新装的显卡驱动和 CUDA 版本，很可能已经不适配 PyTorch 1.12 了。我的建议是直接用 PyTorch 2.x，代码本身兼容性还不错，只需要稍微注意后面提到的 API 变化。

安装 PyTorch 时最关键的是 CUDA 版本。不要直接pip install torch装 CPU 版，否则后面跑训练直接绝望。正确的做法是先查自己的显卡驱动支持的 CUDA 版本：

nvidia-smi

然后在 PyTorch 官网选择对应的安装命令。比如 CUDA 12.1 可以这样：

pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121

装完之后用这段代码验证 GPU 是否可用：

import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))

如果cuda.is_available()返回 False，多半是 CUDA 驱动版本太低或者 PyTorch 和驱动的 CUDA 版本不匹配，要先把驱动升级到合适版本。

2.2 关键依赖与仓库结构

除了 PyTorch，项目还依赖几个重要库：einops（做张量维度变换很方便）、numpy、matplotlib、smplx（处理 SMPL 人体模型）、clip（文本编码）、tensorboard（训练日志）。官方environment.yml里这些都有，但如果你是自己手动建环境，记得一起装。

pip install einops numpy matplotlib smplx ftfy regex tensorbboard

然后是克隆仓库和准备数据。仓库结构比较清晰，核心代码分布在几个目录：

• train/：训练入口和训练逻辑
• models/：扩散模型和去噪网络的定义
• data_loaders/：数据加载和预处理
• sample/：生成入口
• evaluate/：指标评测
• visualize/：结果可视化渲染
• prepare/：数据准备脚本

先克隆下来：

git clone https://github.com/GuyTevet/motion-diffusion-model.git cd motion-diffusion-model

2.3 数据集与预训练模型准备

这一步是最容易卡住的。HumanML3D 数据集需要从官方仓库下载，文件放在 Google Drive 上，如果你网络环境不方便，下载会非常痛苦。我的经验是不要傻等，直接用支持断点续传的下载工具，或者找数据集镜像。

下载好的数据需要放置到指定目录。以 HumanML3D 为例，目录结构应该是：

datasets/humanml3d/ ├── new_joint_vecs/ ├── texts/ ├── train.txt ├── val.txt ├── test.txt └── ...

其中new_joint_vecs/存放预处理后的运动特征（npy 文件），texts/存放对应的文本描述文件，三个 txt 文件划分了训练、验证、测试集。

预训练模型也需要从仓库指定的链接下载。文件名通常是model000200000.pt，对应训练 200,000 步后的 checkpoint。下载后放在save/humanml_trans_enc_512/目录下，也可以放在任意位置，推理时用--model_path指定即可。

如果你还要渲染 mesh 视频，需要额外下载 SMPL 模型文件，放到bodies/smpl/目录。不要跳过这步，视觉化输出能让调试效率提升很多。

3. 训练流程与核心机制解析

3.1 数据加载管线

MDM 的数据加载逻辑在data_loaders/下，核心是HumanML3D数据集类。它的工作流程是：加载运动文件（npy）和对应的文本描述文件（txt），按 train/val/test 划分，然后对文本和运动做配对。

一个关键细节是文本的负采样。训练时并不是每条文本都会进入模型，有一定概率会丢弃文本条件，让模型学会无条件生成。这个比例由--cond_drop_prob控制，默认设成 0.1 左右。为什么要这么做？这其实是在为采样时的 classifier-free guidance 做准备：如果模型在训练时见过“没有条件”的情况，推理时就可以在“有条件输出”和“无条件输出”之间插值，让生成结果更贴合文本，同时保持多样性。

数据加载还有一个多长处理的机制。HumanML3D 里的动作长度不一，MDM 通过采样固定长度的窗口来对齐，在--motion_length参数里控制。默认的生成长度是 6 秒左右，对应 120 帧（20fps）。

3.2 扩散模型核心：加噪与去噪

扩散模型的核心代码在models/diffusion.py，如果你看过 DDPM 的实现，会发现大框架非常相似。

前向过程（加噪）在给定真实动作 x0 时，随机选一个时间步 t，按照预设的噪声调度表生成噪声 epsilon，然后得到带噪样本：

xt = sqrt(alpha_bar_t) * x0 + sqrt(1 - alpha_bar_t) * epsilon

这里 alpha_bar_t 是累积噪声调度的乘积，控制前 t 步之后信号和噪声的比例。训练时，MDM 让网络从 xt 出发预测原始 x0（或者预测噪声 epsilon），用 L2 距离计算 loss。

反向过程（去噪）是推理时的核心。从标准高斯噪声 xT 出发，循环 T 次，每次用模型预测噪声，然后根据 DDPM 推导的更新公式算出前一步的 x_{t-1}。MDM 默认循环 1000 步，这也是采样慢的主要原因。

在实际使用中，我强烈建议改一下采样参数，用 DDIM 加速。你在sample/generate.py里把采样器切到 DDIM，步数减到 50~100，效果损失很小，速度能快 10 倍以上。这个改动在models/diffusion.py里已经内置了支持，不需要大改代码。

3.3 训练命令与关键参数

训练入口是train/train_mdm.py，启动命令很简单：

python -m train.train_mdm --save_dir save/my_first_model --dataset humanml

训练过程中，checkpoint 会定期保存到save_dir下，默认每 50,000 步保存一次。日志会写到 TensorBoard，你可以实时监控 loss 曲线和生成的样例。

最关键的超参数是这几个：

如果你显存比较紧张，我建议先调小 batch size 和 motion 窗口长度，而不是直接换更小的模型。因为 Transformer Encoder 对 motion token 长度的显存消耗是平方级的，缩短序列长度立竿见影。

训练到什么时候可以停？我的经验是看验证集上的 FID 和 R-Precision。官方 checkpoint 是 200,000 步，但在自己的数据上，如果 loss 不再下降，而且生成样例肉眼可见合理，就可以提前停。200,000 步在单卡 RTX 3090 上大约需要一到两天时间。

3.4 文本条件如何进入模型

这是 MDM 容易被忽略的细节。文本不是简单拼一个向量进去，而是经过几步变换。

首先，文本描述经过 CLIP 的 text encoder，得到句子的 embedding，通常是一个 512 维向量。然后这个向量会经过一个 MLP 投影层，转成和 motion token 相同的维度。同时，时间步 t 也会被编码成 embedding，和文本 embedding 一起作为序列的一部分。

在训练时，模型输入包括三个部分：带噪的 motion token、时间步 embedding、文本 embedding。这些输入在 Transformer Encoder 里拼接成一个大序列，Self-Attention 能同时看到动作信息和文本信息，从而学会“把动作往文本描述的方向去噪”。

这里有一个值得注意的地方：CLIP 的文本 encoder 在训练时是冻结的，不参与梯度更新。这样做的理由很简单：CLIP 已经在大规模图文数据上学到了很好的语义表示，微调反而可能让文本语义空间发生偏移，破坏它和图像/动作空间之间的对齐关系。如果你要复用这个项目做二次开发，也建议保持 CLIP 冻结，主要去调投影层和 Transformer。

4. 推理实操：从文本到 3D 运动

4.1 加载预训练模型生成单条动作

官方预训练模型下载好之后，生成一条动作非常简单：

python -m sample.generate \ --model_path save/humanml_trans_enc_512/model000200000.pt \ --text "a person walks forward"

这条命令会生成符合文本描述的 3D 运动序列，默认是一段 6 秒左右的动作。生成的 motion 会以 npy 格式保存到save/sample/目录，同时还可能保存一个文本文件记录对应的文本描述。

如果你想一次生成多条不同的动作，可以加--num_samples参数：

python -m sample.generate \ --model_path save/humanml_trans_enc_512/model000200000.pt \ --text "a person walks forward" \ --num_samples 10

这会把初始随机噪声采样 10 次，得到 10 条不同的动作，全部跳同一个语义。

生成结果的质量和文本描述有直接关系。HumanML3D 的训练文本都比较保守，基本是 “a person walks forward” “a person sits down” “the person jumps up” 这类句式。如果输入特别复杂的描述，比如 “一个人先向左走，然后转身，最后蹲下来”，模型很容易糊，原因是训练数据里这种复杂组合本身就少。经验是：生成阶段尽量用训练集常见的短语结构，效果更稳。

4.2 控制运动长度与采样多样性

生成时还有一个关键参数是--motion_length，控制输出动作的时长（秒）。默认是 6 秒，实际可以按需求调整，比如生成 3 秒的简短动作，或者 10 秒的连续动作。

注意，运动长度不能无限拉长。Transformer 的位置编码和训练数据的长度分布是有边界的，拉太长会看到动作重复或者漂浮。短一些反而质量更有保证。

如果你想在贴近文本的同时增加多样性，可以调--guidance_param。这个参数控制 classifier-free guidance 的强度。数值越大，生成结果越贴近文本，但多样性会下降，动作可能变得僵硬；数值太小，动作和文本的对齐度会变差。我实测下来，1.0 到 2.0 之间是一个比较合理的区间，具体要在你的数据集上试。

多样性和文本保真度本质上是一对矛盾，这也是 diffusion 模型在条件生成里最需要调的地方。没有万能参数，只能多看生成结果来感觉。

4.3 可视化和结果导出

生成的是 263 维的运动特征，直接看数字没意义，必须可视化。MDM 仓库提供了两个渲染脚本：

• visualize/render_motion.py：渲染骨架动画，速度快，适合调试
• visualize/render_mesh.py：渲染 SMPL 网格模型，效果更接近最终产品

渲染 mesh 前需要确保 SMPL 模型文件已经放到bodies/smpl/目录。运行：

python -m visualize.render_mesh --model_path save/humanml_trans_enc_512/model000200000.pt --text "a person walks forward"

渲染结果会以 mp4 视频形式输出。这一步对调试太有用了，肉眼比任何指标都直观。

如果你想把生成的运动数据导出成其他格式（比如 FBX 用于游戏引擎，或者 BVH 用于动画软件），MDM 原生不直接支持，但你可以拿到 263 维特征之后，通过 SMPL 参数逆映射把关节位置转换回 SMPL 姿态，再接一个 FBX/BVH 导出管线。这个环节在商业化项目里往往比训练模型还费时间。

5. 常见问题与排查技巧实录

5.1 环境与依赖问题

最典型的问题还是 PyTorch 和 CUDA 的版本匹配。这个项目官方是基于 PyTorch 1.12 开发的，但新环境里很容易遇到两种情况：一是 PyTorch 版本太低，装不上新版 CUDA 驱动对应的包；二是 PyTorch 2.x 里某些旧 API 被移除或改了行为，导致代码报错。

我遇到的比较有代表性的一个就是 PyTorch 2.6 之后，torch.load的weights_only参数默认值变成了 True，加载官方 checkpoint 时如果里面包含自定义 class 或函数，会直接报错。解决办法是在加载模型的地方显式传weights_only=False，或者干脆用torch.load(model_path, map_location='cpu', weights_only=False)。这个问题在网络上有大量讨论，排查思路就是先看报错堆栈，定位到加载权重那一行，再检查是版本差异还是文件损坏。

另一个常见问题是 CLIP 依赖的ftfy和regex库版本不够新，加载 CLIP 模型时报 Unicode 相关错误。直接pip install -U ftfy regex即可。

5.2 数据下载与加载问题

HumanML3D 数据集的下载经常让人头大。文件在 Google Drive 上，网速不稳定时容易下载到一半失败，导致某个 npy 文件损坏。加载数据时如果报EOFError或者numpy.load失败，先用python -c单独 load 一次损坏文件确认。

另外一个容易被忽视的问题是目录结构。MDM 的数据加载器对目录路径很敏感，datasets/humanml3d/下必须有train.txt、val.txt、test.txt三个文件，而且每个文件里是一行一个 motion 文件名。如果你从别的渠道拿到数据集，先对照官方目录结构检查一遍，不要想当然地放，否则在推理时会出现“某些文本找不到对应动作”的诡异问题。

5.3 生成效果问题

跑通之后最打击人的是生成效果不行。最常见的几种表现：

• 动作和文本完全不匹配。优先检查 pre-trained model 是否下载正确，以及文本是否用英文。MDM 的文本 encoder 是 CLIP，对中文支持很差，直接用中文描述基本是随机动作。
• 动作漂移、人物在滑动。这是运动生成里的通病，除非做物理约束或 foot contact 约束，否则很难完全避免。MDM 的 263 维特征里带了脚部接触信息，能缓解但没法根治。
• 动作太平淡，多样性不足。尝试调低--guidance_param，或者在采样时代入更大的随机噪声，早期步数里加一点噪声扰动有助于提升多样性。
• 生成的人体姿态严重扭曲。这通常是 motion 长度和训练数据长度不匹配导致的，检查--motion_length是否在训练分布范围内。

5.4 显存和性能问题

如果你是单卡 8GB 显存跑训练，会很痛苦。MDM 的 Transformer 对显存要求不低，我的建议是：

1. 先把--batch_size降到 16 甚至 8。
2. 减少 motion 序列的有效长度，比如从 120 帧减到 60 帧。
3. 如果还是爆显存，考虑用梯度累积来模拟更大的 batch。

推理时显存问题不大，但采样 1000 步很慢。用 DDIM 把步数砍到 100，速度能提升一个量级，这是最值得做的一个优化。

把我自己的使用体会放在最后：MDM 这个项目真正的价值不只是跑通 demo，而是把“文本生成动作”这件事拆成了清晰可复用的模块。你要做二次开发，大概率会替换数据、微调骨干网络、换文本 encoder，这时候理解每个模块的接口和数据流比背诵命令重要得多。

一个我自己踩过坑之后的建议：不管你是做研究还是做产品，拿到项目的第一步不是急着训练，而是先手工构造一批文本和动作的对应关系，用官方 checkpoint 跑一遍可视化，彻底搞清楚输入输出的数据格式。这能帮你避免后面大量无效调试。哪怕最后你换了自己的数据，这套思路也完全通用。

本文还有配套的精品资源，点击获取