1. 先搞清楚 HumanML3D 到底是什么1.1 它解决的是哪个环节的痛点做过文本驱动动作生成的朋友应该都经历过一个尴尬阶段模型搭好了文本编码器写完了可一到数据从哪来就卡住。Motion-Language 这个方向的公开数据本来就少KIT Motion-Language 是经典但只有约 6300 条动作种类也偏实验室场景跑出来的模型泛化性很一般。HumanML3D 出现的意义就在这——它把 AMASS 这一批动捕数据重新整理、切片、重新配文本做成了一个规模足够、语义足够丰富、格式统一到可以直接喂进网络的文本-动作配对数据集。一句话概括HumanML3D 是目前文本驱动人体动作生成领域最主流的公开数据集包含约 14616 段动作序列配上 44970 条英文文本描述覆盖行走、跳跃、踢腿、舞蹈、坐下、挥手等大量日常动作。它同时提供了统一的 263 维向量表示把姿态、速度、脚部接触状态全部打包成定长向量省去了每个模型自己处理 SMPL 参数的麻烦。它适合谁做文本生成动作text-to-motion、动作到文本motion-to-text、动作检索、动作插值、动作预测的研究者和工程同学也适合刚入门这个方向、想找个能直接跑起来的数据集练手的学生。如果你只是想看看人体动捕数据长什么样它也完全够用。1.2 数据集的组成和规模HumanML3D 不是凭空采集的它的动作来自 AMASS 的子集然后经过人工分段、清洗、重新标注文本。几个关键数字你需要记住后面选模型、算显存都用得上指标数值动作序列数约 14616 段去重后的原始动作约 4490 个序列文本描述条数约 44970 条平均每段动作文本数约 3 条总时长约 28.6 小时骨架关节数22 个SMPL-H 骨架单帧向量维度263 维帧率20 FPS这里有个容易误会的点为什么动作序列数和去重后原始动作差了这么多因为 HumanML3D 对同一段原始动作做了多段切分。比如一段 20 秒的走路片段会被切成若干 2 到 10 秒的子片段每个子片段都有自己的文本这样既增加了数据量也让动作和文本的对齐粒度更细模型学起来更稳。切分长度通常控制在 2 到 10 秒之间太短的片段语义不完整太长的片段又不好配一句精准的文本。1.3 为什么它成了这个方向的事实标准我个人的观察是HumanML3D 能被广泛采用主要靠三点。第一是格式统一263 维向量屏蔽了底层 SMPL 参数的各种坑大家拿到手就能用。第二是评测协议统一它给出了 train/val/test 的标准划分后来几乎所有文本驱动动作生成的论文都在这套划分上报 FID、R-Precision、Diversity 这些指标横向对比才有意义。第三是文本质量它的描述是重新人工标注的不是机器生成的像a person walks forward and then turns left这种句子语义和动作的对应关系比较干净模型不容易学到噪声。所以如果你在复现别人的模型第一步几乎一定是先把 HumanML3D 跑通。而下载和处理这个数据集恰恰是新手最容易卡住的地方——它不是点一下就能下的涉及到 AMASS 申请、SMPL 模型权限、脚本链处理几个环节。下面我把整个流程拆开讲。2. 下载之前必须理清的三份原料2.1 HumanML3D 本体可以直接拿处理好的包很多人不知道HumanML3D 官方仓库其实提供了一份已经处理好的数据压缩包大约 1.3 GB里面包含了最终训练要用的所有东西263 维动作向量、文本标注、划分文件、均值方差文件。也就是说如果你只是想训练和评测不打算改预处理逻辑完全可以跳过 AMASS 那一大堆申请流程直接用这份成品。这份成品数据的目录核心是这几个new_joints22 个关节的 3D 坐标序列人脸友好适合做可视化或某些不做归一化的任务。new_joint_vecs263 维向量这是训练主力。texts每段动作对应的文本描述文件。Mean.npy/Std.npy全局均值和标准差用于归一化。train.txt/val.txt/test.txt标准划分。我的建议是第一次上手直接用官方成品包。等模型跑通了、你确实想改切分策略或者加自己的数据再回头走完整的 AMASS 处理流程。这个顺序能帮你省掉至少一整天在权限申请和脚本报错上的折腾。2.2 AMASS仅在你要从原始数据重做时才需要AMASS 是一个把多个动捕数据库统一到 SMPL 格式的大集合体量非常大完整下载是几百 GB 级别而且需要去官网注册账号、接受许可协议才能拿到下载链接。HumanML3D 用到的只是它的一个子集但即使只要子集你也得先把 AMASS 下下来再按 HumanML3D 的脚本去筛。这里要提醒一个现实问题AMASS 网站需要邮箱注册并同意学术使用条款下载链接是分数据集给的你不可能一次性全下完。实际做法是只下 HumanML3D 用到的那几个子集。官方仓库里有个文件列出了它依赖的 AMASS 子集清单你照着这个清单去挑能省下大量磁盘空间和时间。注意AMASS 和 SMPL 模型的许可协议都限制在非商业学术用途。商用前务必确认授权这不是技术问题但踩了会很麻烦。2.3 SMPL-H 模型没有它脚本跑不动SMPL-H 是带手部关节的人体参数化模型22 个关节的骨架定义就来自它。HumanML3D 的预处理脚本在把原始 SMPL 参数转成 263 维向量时需要读取 SMPL-H 的模型文件来做前向运动学计算。所以即使你只处理少量数据也必须去 SMPL 官网注册、下载 SMPL-H 的模型文件放到脚本指定的目录。这一步最常见的坑是文件名和路径。脚本里对 SMPL-H 文件的命名和放置位置是有预期的通常是body_models/smplh/下面按性别分文件夹。如果你下载后随手一放脚本找不到文件就会报FileNotFoundError。我建议下载完先看一眼官方 README 里对目录结构的要求照着摆别自己发挥。3. 从零开始的完整下载与处理流程3.1 环境准备依赖其实不多HumanML3D 的预处理对环境的依赖不算重但有几个库是硬性的。我列一下我实际用到的# 建议 Python 3.8 及以上 pip install numpy pip install torch # 生成 6D 旋转表示时可能会用到 pip install smplx # 读取 SMPL-H 模型 pip install spacy pip install moviepy # 文本到 GloVe 词向量的处理 python -m spacy download en_core_web_sm这里spacy和moviepy容易被忽略。text_processing.py会用到 spaCy 做分词和一些文本规整如果你没装对应的语言模型脚本会在处理文本那一步直接崩。moviepy是早期版本遗留下来的依赖某些文本向量化流程会用到装上不亏。我的经验是先建一个干净的 conda 环境专门给这个数据集处理用。因为脚本里对 numpy、torch 的版本比较敏感混在你平时的环境里很容易冲突。踩过一次坑——本机 numpy 版本太新脚本里的某些老 API 直接报错换环境才解决。3.2 获取仓库与原始数据先把官方仓库克隆下来git clone https://github.com/EricGuo5513/HumanML3D.git cd HumanML3D仓库结构大致是这样的raw_pose_processing.py、motion_representation.py、text_processing.py、preprocess.py是四个核心处理脚本data/下面放数据body_models/放人体模型。你需要在data/下建好amass和humanml3d两个目录把 AMASS 原始数据放进data/amass。如果你的目标是直接用成品包这一步就简单了从官方给的备份渠道仓库 README 里通常会指向 Google Drive 或国内网盘下载处理好的压缩包解压到data/humanml3d下然后跳到 3.4 验收目录。整个过程十分钟内能搞定。3.3 运行四步脚本链如果你要走完整流程处理顺序不能乱四个脚本是有依赖关系的。我按实际执行顺序说第一步raw_pose_processing.py。它的作用是遍历data/amass下的原始 npz 文件做初步清洗把姿态数据整理成统一格式输出中间结果。这一步最耗时因为 AMASS 文件多且大。我实测在普通机器上跑全量几个小时是正常现象建议挂后台跑别盯着终端。第二步motion_representation.py。这一步把清洗后的姿态转成最终表示——也就是new_joints关节坐标和new_joint_vecs263 维向量。核心逻辑是把绝对姿态转成相对表示再做归一化。这一步是技术含量最高的地方后面我会专门拆解。第三步text_processing.py。处理文本描述做分词、规整并把文本对齐到动作片段。如果你的动作切片变了这一步必须重跑否则文本和动作会对不上。第四步preprocess.py。生成最终的训练文件划分文件、均值方差、以及一些统计量。跑完这一步data/humanml3d下就会出现前面说的那几个标准文件。跑之前有个检查习惯值得养成先拿一两个 AMASS 小文件跑通全流程确认没报错再放大批量。不然你挂后台跑了三小时最后一步崩了得从头再来。3.4 目录验收确认你能开始训练跑完之后或者解压成品包之后第一件事是验收目录。你要确认data/humanml3d下至少有这些new_joint_vecs/里面是一堆.npy文件每个对应一段动作形状是(帧数, 263)。new_joints/形状(帧数, 22, 3)。texts/每段动作的文本。Mean.npy、Std.npy。train.txt、val.txt、test.txt。我习惯写一小段脚本抽查import numpy as np vec np.load(data/humanml3d/new_joint_vecs/000000.npy) print(vec.shape) # 期望 (T, 263) print(vec.dtype) # 期望 float32 或 float64如果维度不是 263或者 dtype 是 object说明文件坏了或者下错版本了。这一步看着简单但能帮你尽早发现解压不完整这类隐蔽问题。4. 数据格式深度解析263 维向量是怎么来的4.1 分块拆解这 263 个数字很多人拿到 263 维向量就懵了不知道每一段算什么。其实它是有清晰规律的我可以把它拆成七块数据块维度含义root rotation velocity1根节点绕竖直轴的角速度root linear velocity2根节点在水平面的线速度X、Zroot height1根节点高度Ylocal joint positions6321 个关节相对骨盆的局部坐标21×3local joint rotations12621 个关节的 6D 旋转表示21×6local velocities6622 个关节的局部速度22×3foot contact4双脚的接触状态4 个标记位加起来正好 4 63 126 66 4 263。理解这个拆分对你调试模型非常关键——比如模型脚部滑步严重你就知道要去看 foot contact 那 4 维比如模型转身奇怪问题多半出在根节点的旋转速度上。4.2 为什么要用 6D 旋转而不是四元数这里有个细节值得展开。局部关节旋转用的是 6D 表示也就是把一个旋转矩阵的前两列拉平变成 6 个数。为什么不直接用欧拉角或者四元数欧拉角有万向节死锁问题训练时数值不稳定四元数虽然没死锁但它是双覆盖的q 和 -q 表示同一个旋转直接让网络回归四元数会导致符号翻转的跳变。6D 表示的好处是连续、无奇异、适合网络直接回归而且从 6D 恢复旋转矩阵有闭式解。这是 HumanML3D 表示里一个很讲究的设计很多新手直接忽略结果训练时 loss 震荡还以为是学习率的问题。4.3 文本标注和划分的那些事文本方面每段动作平均配 3 条描述描述有长有短有的偏动作分解walk forward, then sit down有的偏整体语义a person is exercising。这种多描述的设置其实是有意的评测时用多条文本减去单条文本的偏差得到的指标更稳健。划分文件是标准的三段式train、val、test 是互斥的。这里要提醒一句千万不要自己随便重划。因为整个社区都是在官方划分上报数的你重划了结果就没法跟别人比。我见过有人为了提升自己模型的数字偷偷把测试集样本挪进训练集这种操作短期好看长期害的是自己——模型泛化能力根本没提升。归一化用Mean.npy和Std.npy处理方式是(x - mean) / std。训练时归一化推理时再反归一化还原成真实尺度。这两个文件一定要和你的动作数据配套使用用错了归一化参数生成出来的动作幅度会完全失控。5. 常见问题与排查速查5.1 下载与权限类问题这类问题基本集中在前任几步我整理了一张速查表现象可能原因解决方向AMASS 链接打不开未注册或未接受协议重新登录官网确认协议状态压缩包解压报错下载不完整重新下载核对文件大小SMPL-H 文件找不到路径或命名不符按 README 目录结构摆放脚本报权限错误文件权限或路径含空格换纯英文无空格路径我最常遇到的是国内网络下大文件下载中断下载下来的包看着有大小其实内容不全解压到一半才报错。解决办法是用支持断点续传的工具下下完对比一下官方给的文件大小或校验值。5.2 脚本运行报错脚本报错里最典型的是 spaCy 模型缺失和 numpy 版本冲突。前者报错信息通常带Cant find model en_core_web_sm装上对应模型即可后者报错五花八门常见的是np.float这类老 API 在新版 numpy 里被移除。我的处理办法是装一个稍旧一点、和脚本作者开发时接近的 numpy 版本。还有一个坑是内存。motion_representation.py处理大文件时会占不少内存机器内存小的同学建议分批处理或者临时增加 swap。挂后台时用nohup加日志重定向方便事后查错nohup python motion_representation.py log.txt 21 5.3 训练加载数据时的坑数据处理好、目录也对了可训练时还是可能出问题。最常见的是 DataLoader 里长度不一致不同动作帧数不同如果 batch 里直接 stack 会报 shape 不匹配。标准做法是 padding 加 mask或者按长度分桶采样。HumanML3D 的官方代码里有对应的 collate 逻辑别自己重造轮子。另一个坑是文本向量的维度。如果你用预训练文本编码器比如 CLIP要确认文本特征维度和模型输入对得上。我见过有人换了文本编码器却没改模型的输入层结果一开始训练就维度不匹配。实操心得处理完数据先别急着训练写个小脚本随机抽 10 段动作把归一化后的向量反归一化画出根节点轨迹看看动作是不是合理的。这一步能提前发现归一化参数用错这类隐蔽问题。6. 加载、可视化与接入训练6.1 训练时到底该用哪份文件训练用new_joint_vecs这是主流做法因为 263 维向量自带了速度、旋转、接触信息网络不用自己算差分。new_joints主要拿来做可视化或者某些需要显式关节坐标的任务。如果你是做动作渲染、要看骨架动画就用new_joints如果是训练生成模型就用new_joint_vecs配合Mean.npy、Std.npy。加载的时候注意一个细节263 维向量的不同块物理意义不同、量纲也不同所以归一化是全局做的但你在解读时要知道哪几维是位置、哪几维是速度。我建议把 4.1 那张拆分表存下来调试时随时对照。6.2 快速可视化验证数据是否正确想肉眼确认数据没坏最快的办法是画根节点轨迹。下面这段是我常用的import numpy as np import matplotlib.pyplot as plt vec np.load(data/humanml3d/new_joint_vecs/000000.npy) mean np.load(data/humanml3d/Mean.npy) std np.load(data/humanml3d/Std.npy) # 反归一化 raw vec * std mean # 根节点高度在第 3 维0 索引为 3 plt.plot(raw[:, 3]) plt.title(root height over time) plt.show()如果这条曲线是一条合理的人体高度波动曲线比如在 0.9 到 1.0 附近小幅波动说明数据基本正常如果是一条斜线或者数值离谱那多半是归一化参数配错或者你用错了版本的文件。这个检查只要两分钟但能帮你避开后面几小时的无效训练。6.3 想接入自己的任务该怎么改如果你不满足于跑公开基准想加自己的数据思路是这样的先把你的动作对齐到 SMPL-H 骨架算出 SMPL 参数再走motion_representation.py那套转换逻辑生成 263 维向量最后把文本也按同样的格式标注好重新生成划分。整个过程中最麻烦的是动作和文本的对齐——你的描述必须精确对应动作的时间区间不能笼统地写一句一个人在运动那样模型学不到细粒度对应关系。我自己做过一个小实验把同一段动作切成更细的片段、配更精确的文本模型在细粒度指令上的响应确实更好但代价是数据量膨胀、训练变慢。所以切分粒度这事要权衡不是越细越好。HumanML3D 选 2 到 10 秒这个区间是经过验证的平衡点个人建议先沿用。最后分享一个我在实际使用中的体会这个数据集最值钱的地方其实不是那 263 维向量本身而是它把动作和语言这两套本来毫不相干的表达对齐到了一起。你处理数据时多花点时间理解每一维、每条文本背后的物理含义比急着调模型参数有用得多。数据理解到位了模型出问题你一眼就能看出是哪一环不对理解不到位就只能对着 loss 曲线瞎猜。
HumanML3D 数据集下载与263维向量处理：文本驱动动作生成实战
1. 先搞清楚 HumanML3D 到底是什么1.1 它解决的是哪个环节的痛点做过文本驱动动作生成的朋友应该都经历过一个尴尬阶段模型搭好了文本编码器写完了可一到数据从哪来就卡住。Motion-Language 这个方向的公开数据本来就少KIT Motion-Language 是经典但只有约 6300 条动作种类也偏实验室场景跑出来的模型泛化性很一般。HumanML3D 出现的意义就在这——它把 AMASS 这一批动捕数据重新整理、切片、重新配文本做成了一个规模足够、语义足够丰富、格式统一到可以直接喂进网络的文本-动作配对数据集。一句话概括HumanML3D 是目前文本驱动人体动作生成领域最主流的公开数据集包含约 14616 段动作序列配上 44970 条英文文本描述覆盖行走、跳跃、踢腿、舞蹈、坐下、挥手等大量日常动作。它同时提供了统一的 263 维向量表示把姿态、速度、脚部接触状态全部打包成定长向量省去了每个模型自己处理 SMPL 参数的麻烦。它适合谁做文本生成动作text-to-motion、动作到文本motion-to-text、动作检索、动作插值、动作预测的研究者和工程同学也适合刚入门这个方向、想找个能直接跑起来的数据集练手的学生。如果你只是想看看人体动捕数据长什么样它也完全够用。1.2 数据集的组成和规模HumanML3D 不是凭空采集的它的动作来自 AMASS 的子集然后经过人工分段、清洗、重新标注文本。几个关键数字你需要记住后面选模型、算显存都用得上指标数值动作序列数约 14616 段去重后的原始动作约 4490 个序列文本描述条数约 44970 条平均每段动作文本数约 3 条总时长约 28.6 小时骨架关节数22 个SMPL-H 骨架单帧向量维度263 维帧率20 FPS这里有个容易误会的点为什么动作序列数和去重后原始动作差了这么多因为 HumanML3D 对同一段原始动作做了多段切分。比如一段 20 秒的走路片段会被切成若干 2 到 10 秒的子片段每个子片段都有自己的文本这样既增加了数据量也让动作和文本的对齐粒度更细模型学起来更稳。切分长度通常控制在 2 到 10 秒之间太短的片段语义不完整太长的片段又不好配一句精准的文本。1.3 为什么它成了这个方向的事实标准我个人的观察是HumanML3D 能被广泛采用主要靠三点。第一是格式统一263 维向量屏蔽了底层 SMPL 参数的各种坑大家拿到手就能用。第二是评测协议统一它给出了 train/val/test 的标准划分后来几乎所有文本驱动动作生成的论文都在这套划分上报 FID、R-Precision、Diversity 这些指标横向对比才有意义。第三是文本质量它的描述是重新人工标注的不是机器生成的像a person walks forward and then turns left这种句子语义和动作的对应关系比较干净模型不容易学到噪声。所以如果你在复现别人的模型第一步几乎一定是先把 HumanML3D 跑通。而下载和处理这个数据集恰恰是新手最容易卡住的地方——它不是点一下就能下的涉及到 AMASS 申请、SMPL 模型权限、脚本链处理几个环节。下面我把整个流程拆开讲。2. 下载之前必须理清的三份原料2.1 HumanML3D 本体可以直接拿处理好的包很多人不知道HumanML3D 官方仓库其实提供了一份已经处理好的数据压缩包大约 1.3 GB里面包含了最终训练要用的所有东西263 维动作向量、文本标注、划分文件、均值方差文件。也就是说如果你只是想训练和评测不打算改预处理逻辑完全可以跳过 AMASS 那一大堆申请流程直接用这份成品。这份成品数据的目录核心是这几个new_joints22 个关节的 3D 坐标序列人脸友好适合做可视化或某些不做归一化的任务。new_joint_vecs263 维向量这是训练主力。texts每段动作对应的文本描述文件。Mean.npy/Std.npy全局均值和标准差用于归一化。train.txt/val.txt/test.txt标准划分。我的建议是第一次上手直接用官方成品包。等模型跑通了、你确实想改切分策略或者加自己的数据再回头走完整的 AMASS 处理流程。这个顺序能帮你省掉至少一整天在权限申请和脚本报错上的折腾。2.2 AMASS仅在你要从原始数据重做时才需要AMASS 是一个把多个动捕数据库统一到 SMPL 格式的大集合体量非常大完整下载是几百 GB 级别而且需要去官网注册账号、接受许可协议才能拿到下载链接。HumanML3D 用到的只是它的一个子集但即使只要子集你也得先把 AMASS 下下来再按 HumanML3D 的脚本去筛。这里要提醒一个现实问题AMASS 网站需要邮箱注册并同意学术使用条款下载链接是分数据集给的你不可能一次性全下完。实际做法是只下 HumanML3D 用到的那几个子集。官方仓库里有个文件列出了它依赖的 AMASS 子集清单你照着这个清单去挑能省下大量磁盘空间和时间。注意AMASS 和 SMPL 模型的许可协议都限制在非商业学术用途。商用前务必确认授权这不是技术问题但踩了会很麻烦。2.3 SMPL-H 模型没有它脚本跑不动SMPL-H 是带手部关节的人体参数化模型22 个关节的骨架定义就来自它。HumanML3D 的预处理脚本在把原始 SMPL 参数转成 263 维向量时需要读取 SMPL-H 的模型文件来做前向运动学计算。所以即使你只处理少量数据也必须去 SMPL 官网注册、下载 SMPL-H 的模型文件放到脚本指定的目录。这一步最常见的坑是文件名和路径。脚本里对 SMPL-H 文件的命名和放置位置是有预期的通常是body_models/smplh/下面按性别分文件夹。如果你下载后随手一放脚本找不到文件就会报FileNotFoundError。我建议下载完先看一眼官方 README 里对目录结构的要求照着摆别自己发挥。3. 从零开始的完整下载与处理流程3.1 环境准备依赖其实不多HumanML3D 的预处理对环境的依赖不算重但有几个库是硬性的。我列一下我实际用到的# 建议 Python 3.8 及以上 pip install numpy pip install torch # 生成 6D 旋转表示时可能会用到 pip install smplx # 读取 SMPL-H 模型 pip install spacy pip install moviepy # 文本到 GloVe 词向量的处理 python -m spacy download en_core_web_sm这里spacy和moviepy容易被忽略。text_processing.py会用到 spaCy 做分词和一些文本规整如果你没装对应的语言模型脚本会在处理文本那一步直接崩。moviepy是早期版本遗留下来的依赖某些文本向量化流程会用到装上不亏。我的经验是先建一个干净的 conda 环境专门给这个数据集处理用。因为脚本里对 numpy、torch 的版本比较敏感混在你平时的环境里很容易冲突。踩过一次坑——本机 numpy 版本太新脚本里的某些老 API 直接报错换环境才解决。3.2 获取仓库与原始数据先把官方仓库克隆下来git clone https://github.com/EricGuo5513/HumanML3D.git cd HumanML3D仓库结构大致是这样的raw_pose_processing.py、motion_representation.py、text_processing.py、preprocess.py是四个核心处理脚本data/下面放数据body_models/放人体模型。你需要在data/下建好amass和humanml3d两个目录把 AMASS 原始数据放进data/amass。如果你的目标是直接用成品包这一步就简单了从官方给的备份渠道仓库 README 里通常会指向 Google Drive 或国内网盘下载处理好的压缩包解压到data/humanml3d下然后跳到 3.4 验收目录。整个过程十分钟内能搞定。3.3 运行四步脚本链如果你要走完整流程处理顺序不能乱四个脚本是有依赖关系的。我按实际执行顺序说第一步raw_pose_processing.py。它的作用是遍历data/amass下的原始 npz 文件做初步清洗把姿态数据整理成统一格式输出中间结果。这一步最耗时因为 AMASS 文件多且大。我实测在普通机器上跑全量几个小时是正常现象建议挂后台跑别盯着终端。第二步motion_representation.py。这一步把清洗后的姿态转成最终表示——也就是new_joints关节坐标和new_joint_vecs263 维向量。核心逻辑是把绝对姿态转成相对表示再做归一化。这一步是技术含量最高的地方后面我会专门拆解。第三步text_processing.py。处理文本描述做分词、规整并把文本对齐到动作片段。如果你的动作切片变了这一步必须重跑否则文本和动作会对不上。第四步preprocess.py。生成最终的训练文件划分文件、均值方差、以及一些统计量。跑完这一步data/humanml3d下就会出现前面说的那几个标准文件。跑之前有个检查习惯值得养成先拿一两个 AMASS 小文件跑通全流程确认没报错再放大批量。不然你挂后台跑了三小时最后一步崩了得从头再来。3.4 目录验收确认你能开始训练跑完之后或者解压成品包之后第一件事是验收目录。你要确认data/humanml3d下至少有这些new_joint_vecs/里面是一堆.npy文件每个对应一段动作形状是(帧数, 263)。new_joints/形状(帧数, 22, 3)。texts/每段动作的文本。Mean.npy、Std.npy。train.txt、val.txt、test.txt。我习惯写一小段脚本抽查import numpy as np vec np.load(data/humanml3d/new_joint_vecs/000000.npy) print(vec.shape) # 期望 (T, 263) print(vec.dtype) # 期望 float32 或 float64如果维度不是 263或者 dtype 是 object说明文件坏了或者下错版本了。这一步看着简单但能帮你尽早发现解压不完整这类隐蔽问题。4. 数据格式深度解析263 维向量是怎么来的4.1 分块拆解这 263 个数字很多人拿到 263 维向量就懵了不知道每一段算什么。其实它是有清晰规律的我可以把它拆成七块数据块维度含义root rotation velocity1根节点绕竖直轴的角速度root linear velocity2根节点在水平面的线速度X、Zroot height1根节点高度Ylocal joint positions6321 个关节相对骨盆的局部坐标21×3local joint rotations12621 个关节的 6D 旋转表示21×6local velocities6622 个关节的局部速度22×3foot contact4双脚的接触状态4 个标记位加起来正好 4 63 126 66 4 263。理解这个拆分对你调试模型非常关键——比如模型脚部滑步严重你就知道要去看 foot contact 那 4 维比如模型转身奇怪问题多半出在根节点的旋转速度上。4.2 为什么要用 6D 旋转而不是四元数这里有个细节值得展开。局部关节旋转用的是 6D 表示也就是把一个旋转矩阵的前两列拉平变成 6 个数。为什么不直接用欧拉角或者四元数欧拉角有万向节死锁问题训练时数值不稳定四元数虽然没死锁但它是双覆盖的q 和 -q 表示同一个旋转直接让网络回归四元数会导致符号翻转的跳变。6D 表示的好处是连续、无奇异、适合网络直接回归而且从 6D 恢复旋转矩阵有闭式解。这是 HumanML3D 表示里一个很讲究的设计很多新手直接忽略结果训练时 loss 震荡还以为是学习率的问题。4.3 文本标注和划分的那些事文本方面每段动作平均配 3 条描述描述有长有短有的偏动作分解walk forward, then sit down有的偏整体语义a person is exercising。这种多描述的设置其实是有意的评测时用多条文本减去单条文本的偏差得到的指标更稳健。划分文件是标准的三段式train、val、test 是互斥的。这里要提醒一句千万不要自己随便重划。因为整个社区都是在官方划分上报数的你重划了结果就没法跟别人比。我见过有人为了提升自己模型的数字偷偷把测试集样本挪进训练集这种操作短期好看长期害的是自己——模型泛化能力根本没提升。归一化用Mean.npy和Std.npy处理方式是(x - mean) / std。训练时归一化推理时再反归一化还原成真实尺度。这两个文件一定要和你的动作数据配套使用用错了归一化参数生成出来的动作幅度会完全失控。5. 常见问题与排查速查5.1 下载与权限类问题这类问题基本集中在前任几步我整理了一张速查表现象可能原因解决方向AMASS 链接打不开未注册或未接受协议重新登录官网确认协议状态压缩包解压报错下载不完整重新下载核对文件大小SMPL-H 文件找不到路径或命名不符按 README 目录结构摆放脚本报权限错误文件权限或路径含空格换纯英文无空格路径我最常遇到的是国内网络下大文件下载中断下载下来的包看着有大小其实内容不全解压到一半才报错。解决办法是用支持断点续传的工具下下完对比一下官方给的文件大小或校验值。5.2 脚本运行报错脚本报错里最典型的是 spaCy 模型缺失和 numpy 版本冲突。前者报错信息通常带Cant find model en_core_web_sm装上对应模型即可后者报错五花八门常见的是np.float这类老 API 在新版 numpy 里被移除。我的处理办法是装一个稍旧一点、和脚本作者开发时接近的 numpy 版本。还有一个坑是内存。motion_representation.py处理大文件时会占不少内存机器内存小的同学建议分批处理或者临时增加 swap。挂后台时用nohup加日志重定向方便事后查错nohup python motion_representation.py log.txt 21 5.3 训练加载数据时的坑数据处理好、目录也对了可训练时还是可能出问题。最常见的是 DataLoader 里长度不一致不同动作帧数不同如果 batch 里直接 stack 会报 shape 不匹配。标准做法是 padding 加 mask或者按长度分桶采样。HumanML3D 的官方代码里有对应的 collate 逻辑别自己重造轮子。另一个坑是文本向量的维度。如果你用预训练文本编码器比如 CLIP要确认文本特征维度和模型输入对得上。我见过有人换了文本编码器却没改模型的输入层结果一开始训练就维度不匹配。实操心得处理完数据先别急着训练写个小脚本随机抽 10 段动作把归一化后的向量反归一化画出根节点轨迹看看动作是不是合理的。这一步能提前发现归一化参数用错这类隐蔽问题。6. 加载、可视化与接入训练6.1 训练时到底该用哪份文件训练用new_joint_vecs这是主流做法因为 263 维向量自带了速度、旋转、接触信息网络不用自己算差分。new_joints主要拿来做可视化或者某些需要显式关节坐标的任务。如果你是做动作渲染、要看骨架动画就用new_joints如果是训练生成模型就用new_joint_vecs配合Mean.npy、Std.npy。加载的时候注意一个细节263 维向量的不同块物理意义不同、量纲也不同所以归一化是全局做的但你在解读时要知道哪几维是位置、哪几维是速度。我建议把 4.1 那张拆分表存下来调试时随时对照。6.2 快速可视化验证数据是否正确想肉眼确认数据没坏最快的办法是画根节点轨迹。下面这段是我常用的import numpy as np import matplotlib.pyplot as plt vec np.load(data/humanml3d/new_joint_vecs/000000.npy) mean np.load(data/humanml3d/Mean.npy) std np.load(data/humanml3d/Std.npy) # 反归一化 raw vec * std mean # 根节点高度在第 3 维0 索引为 3 plt.plot(raw[:, 3]) plt.title(root height over time) plt.show()如果这条曲线是一条合理的人体高度波动曲线比如在 0.9 到 1.0 附近小幅波动说明数据基本正常如果是一条斜线或者数值离谱那多半是归一化参数配错或者你用错了版本的文件。这个检查只要两分钟但能帮你避开后面几小时的无效训练。6.3 想接入自己的任务该怎么改如果你不满足于跑公开基准想加自己的数据思路是这样的先把你的动作对齐到 SMPL-H 骨架算出 SMPL 参数再走motion_representation.py那套转换逻辑生成 263 维向量最后把文本也按同样的格式标注好重新生成划分。整个过程中最麻烦的是动作和文本的对齐——你的描述必须精确对应动作的时间区间不能笼统地写一句一个人在运动那样模型学不到细粒度对应关系。我自己做过一个小实验把同一段动作切成更细的片段、配更精确的文本模型在细粒度指令上的响应确实更好但代价是数据量膨胀、训练变慢。所以切分粒度这事要权衡不是越细越好。HumanML3D 选 2 到 10 秒这个区间是经过验证的平衡点个人建议先沿用。最后分享一个我在实际使用中的体会这个数据集最值钱的地方其实不是那 263 维向量本身而是它把动作和语言这两套本来毫不相干的表达对齐到了一起。你处理数据时多花点时间理解每一维、每条文本背后的物理含义比急着调模型参数有用得多。数据理解到位了模型出问题你一眼就能看出是哪一环不对理解不到位就只能对着 loss 曲线瞎猜。
