VideoPose3D 这个项目最近已经是第三回有人跑来问我环境怎么搭了。它本身是 Facebook Research 在 2019 年放出的 3D 人体姿态估计模型用时间卷积网络把 2D 关键点“提升”成 3D 坐标在 Human3.6M 数据集上刷了一波 SOTA。按理说一个 2019 年的老项目依赖不复杂才对但问题恰恰出在“老”字上——你现在机器上的 Python 版本太新PyTorch 版本太新ffmpeg 没装对detectron2 版本匹配不上随便一个环节都可能让环境卡死。这篇文章就把 VideoPose3D 的环境搭建从零到跑通完整讲一遍包括我实际踩过的坑以及每个选择背后的理由。1. 跑通 VideoPose3D 之前模型定位与软硬件底线1.1 这个项目到底解决什么问题很多人看完 README 会误以为 VideoPose3D 是一个“输入视频直接输出 3D 骨架”的端到端工具其实不是。它的核心是 2D 到 3D 的 lifting 模块输入是一系列二维人体关键点坐标输出是对应帧的 3D 关节坐标。换句话说2D 检测这一环需要你自己搞定可以用 Detectron2、OpenPose、MediaPipe或者任何你喜欢的检测器检测结果喂给 VideoPose3D 就行。作者原论文里强调的是“Temporal modeling and better supervision”也就是通过时间维度的建模来提升 3D 姿态估计的稳定性。模型本身是一系列残差连接的一维时间卷积网络接受长度为 243 帧的 2D 关键点序列生成中心帧的 3D 关键点。整个过程对显存要求不算高但对依赖链的要求比想象中敏感。1.2 硬件和系统的真实门槛先给结论只要你不是跑大批量训练一块 6GB 显存的 GPU 就够用。我最初是在一台 GTX 1660 Super 上跑的batch size 设置为 256序列长度设为 243 帧显存占用大概在 4GB 左右。显存不够时把 batch size 降到 128 甚至 64 都能正常训练但测试时 batch size 对结果影响不大。CPU 也不是完全不能跑推理速度会慢不少。我拿一台 8 核的机器测过单条序列前向推理大概需要 200 毫秒左右处理一段 3 分钟的视频会明显卡顿但至少能跑通。如果只是想验证环境没问题CPU 完全可以。系统方面强烈建议 LinuxUbuntu 18.04 到 22.04 都可以。Windows 上跑这个问题不大但 ffmpeg 的路径处理、数据集脚本里的斜杠分隔符会让你多花不少时间macOS 也能跑不过 M 系列芯片在安装某些旧版 PyTorch 时容易碰到编译问题。如果你是第一次配这个环境直接用 Linux 最省心。2. 环境安装的先后顺序conda、Python 与 PyTorch 版本取舍2.1 为什么必须用 conda 隔离环境我遇到过不止一个朋友图省事直接在系统 Python 里 pip install torch结果把系统环境搞得一塌糊涂。VideoPose3D 依赖的包版本比较固定尤其是 PyTorch 和 numpy 的版本兼容性很容易和你机器上其他项目冲突。用 conda 单独建一个虚拟环境是最稳妥的做法。conda create -n videopose python3.8 conda activate videoposePython 版本我建议固定在 3.8。作者仓库原始代码跑在 Python 3.6 上但 3.7 和 3.8 都能正常跑3.9 开始有个别的集合类型导入问题3.10 以上会更明显。下面会有专门一节说这个坑。如果你装了 Anaconda 或者 Miniconda直接执行上面两句即可。2.2 PyTorch 版本选择1.x 兼容性最好2.x 也能跑这应该是新老用户分歧最大的地方。项目原始代码发布时用的是 PyTorch 1.0 左右的 API代码本身很朴素主要就是 torch 的 nn 模块和优化器所以到了 PyTorch 2.x模型定义部分依然可以跑通。真正有影响的是模型加载时的torch.load行为以及个别 API 的默认参数变化。我更推荐用 PyTorch 1.10 到 1.13 这个区间兼容性最高几乎不会碰到 torch.load 相关问题。装法如下pip install torch1.13.1 torchvision0.14.1如果是新买的 40 系及以上显卡CUDA 版本要求会迫使你装 PyTorch 2.x。这时候也不用慌装最新稳定版然后模型加载时手动指定weights_onlyFalse新版本 PyTorch 的torch.load默认只加载权重张量。我后面会给出具体改法。安装时一定注意用官网给出的 CUDA 版本号匹配命令别用pip install torch默认的 CPU 版本否则后面跑起来慢到怀疑人生。可以用下面命令确认 GPU 是否可用python -c import torch; print(torch.cuda.is_available())输出True就说明环境没问题。2.3 ffmpeg、numpy 与可视化依赖的安装细节VideoPose3D 的数据预处理脚本会调用外部 ffmpeg 命令来切分视频帧所以这里有个很容易踩的坑需要装的是系统级 ffmpeg不是 Python 包。# Ubuntu/Debian sudo apt update sudo apt install ffmpeg # macOS brew install ffmpeg装完后用ffmpeg -version确认。我第一次就是在容器里只装了 Python 的 ffmpeg-python 包结果预处理脚本报“ffmpeg not found”那个报错信息比较迷惑容易让人走弯路。numpy 版本不要太新推荐 1.24.x 或者更低。原因在第五章会详细讲这里先打个预防针——新版本 numpy 对旧代码的默认行为改了数据读取时会报错。可视化部分需要 matplotlib 和 tqdm这些直接 pip 安装pip install matplotlib tqdm3. 源码目录、预训练权重和数据文件的落位3.1 克隆仓库与关键目录职责源码直接克隆官方仓库git clone https://github.com/facebookresearch/VideoPose3D.git cd VideoPose3D整个项目结构非常清晰核心就是三个目录common模型定义、数据集加载、损失函数、可视化工具所有的核心逻辑都在这里。data存放处理好的数据文件包括 2D/3D 关键点文件、metadata.xml。仓库里会保留 metadata.xml但真正的 .npz 数据需要单独下载或自己生成。scripts包含预处理脚本比如prepare_data_h36m.py用来从原始 Human3.6M 数据生成 3D 关键点文件。训练和测试的入口是根目录下的run.py自定义数据推理是inference.py。搞清楚这些文件的位置后面遇到问题才能快速定位。我的经验是拿到项目先别急着跑花十分钟把run.py的参数列表过一遍你会在里面看到大部分环境问题的答案。3.2 预训练模型和 2D 关键点文件放哪官方仓库提供了一个训练好的模型下载脚本也提供了一些预处理好的 2D 检测关键点文件这些文件的文件名大致长这样data_2d_h36m_cpn_ft_h36m_dnn.npz。下载后放进data目录即可。如果没有官方链接可以搜文件名找第三方的备份但下载后注意比对文件大小和哈希值确保完整性。预训练权重是.pt或.pth文件一般放在项目根目录或者单独的checkpoint/目录。下载完成后先用ls -lh看一下大小一个完整的权重文件应该在几十 MB 到几百 MB 之间如果只有几 KB大概率是下载页面返回的 HTML 错误文件。这里有一个很容易被忽略的问题如果你只想跑通环境而不训练至少需要一个处理好的 3D 数据集文件data_3d_h36m.npz和一个 2D 关键点文件。2D 关键点可以用现成的3D 文件则需要从 Human3.6M 原始数据处理而来。这就牵出第四章的内容。4. Human3.6M 数据集获取与预处理唯一没有捷径的环节4.1 申请下载的完整流程Human3.6M 是目前 3D 姿态估计领域最常用的数据集但它的获取方式比较传统——需要去官网填申请表用学校或机构邮箱说明用途然后等对方人工审核。审核通过后会收到一组 FTP 账号密码里面是按 subject 和 action 组织的视频文件和 3D 骨架数据。这个流程通常会耗掉几天时间。如果你想缩短等待可以看看实验室或公司是否已有下载好的副本如果没有就得尽早提交申请。审核时一定要写清楚是学术研究用途留真实姓名和联系方式这样通过率会高很多。下载完后的原始数据目录结构大概是按S1、S5、S6、S7、S8这样的编号组织每个 subject 下有多个 action每个 action 下有多个相机视角的视频。这些原始素材加一起非常占空间几百 GB 很正常下载前先检查磁盘空间。4.2 预处理脚本与输出格式拿到原始数据后运行预处理脚本python scripts/prepare_data_h36m.py --from-source这个脚本的工作流程是先用 ffmpeg 把每个视频抽帧再读取每帧的 3D 骨架坐标把不同相机的视角信息归一化最后生成一个data_3d_h36m.npz文件里面按 subject、action、camera 索引存放 3D 关键点坐标。这个格式是后面训练和测试的标准输入run.py里会通过--dataset h36m自动加载。整个预处理过程比较慢我当年在普通机器上跑了一个多小时。如果中途报错最常见的是某个视频文件缺失或损坏处理方式是先检查原始数据是否完整再确认 ffmpeg 是否正确安装。4.3 不想下载 Human3.6M 时的替代方案如果你只是想跑通环境、看模型效果其实不一定非要折腾完整数据集。官方仓库已经提供了处理好的 2D 关键点文件你只需要再拿到一个 3D 关键点文件就能把测试流程跑起来。有些研究者会把处理好的data_3d_h36m.npz传到网盘或开源镜像上文件名搜得到就可以直接下载。另外项目还有个自定义数据入口。你只要把自己的 2D 关键点数据转成项目要求的 npz 格式然后配合预训练模型直接做 3D 推理。这个方案最大的优势是绕开了 Human3.6M 的申请和预处理能让你在半小时内就跑到结果。第六章会给出具体做法。5. 高频报错排查ffmpeg、torch 加载、内存越界5.1 ffmpeg 相关报错我见过最多的报错就是预处理脚本里提示找不到 ffmpegRuntimeError: ffmpeg not found, install it.这个报错的根因前面说了——系统里面没有 ffmpeg 可执行文件。python 的 ffmpeg-python 包只是一个封装底层还是要调用系统命令。装了系统级 ffmpeg 之后还要确认它在 PATH 里。命令行直接输入ffmpeg -version如果能输出信息就没问题。还有一种情况是 ffmpeg 装了但版本太老某些编码器不兼容。这时候升级一下即可apt update apt install ffmpeg装的就是当前源里的最新版一般不出现这个问题。5.2 高版本 PyTorch 模型加载报错如果你装的是 PyTorch 2.6 或更高版本加载旧权重时大概率会遇到这个TypeError: weights_only should be a boolean或者UnpicklingError: Weights only load failed.原因是 PyTorch 在 2.6 版本开始把torch.load的默认行为改成了weights_onlyTrue而旧权重里通常包含自定义类对象或省略参数绑定加载会失败。解决方式很简单在run.py和common/generic.py里找到所有torch.load(...)调用加上参数weights_onlyFalsestate_dict torch.load(args.reload, map_locationcuda:0, weights_onlyFalse)这个改动只在本地有效不影响模型结构。还有一个更隐蔽的相似问题旧版本的 PyTorch 保存权重时用的张量存储方式不同新版本在加载时偶尔会提示 missing keys导致模型参数没加载全。遇到这种情况先看missing_keys和unexpected_keys分别是什么绝大多数是预训练模型与当前模型定义的分类数不匹配不是环境问题。5.3 内存、显存和数据路径问题VideoPose3D在加载数据时会一次性把 npz 文件读进内存data_3d_h36m.npz解压后可能占 10GB 左右。如果机器内存小于 16GB加载过程可能直接被系统杀掉。这时可以分批加载或增大 swap但最直接的办法是用 32GB 内存的机器跑或者把输入序列长度调小一点。显存溢出则表现为CUDA out of memory。这种情况优先把run.py训练参数里的 batch size 调小然后再把模型里的--architecture层级数调小。测试阶段如果还溢出检查一下是否同时加载了多个模型或者把输入序列长度从 243 降到 81效果差异不大但显存占用骤减。路径问题是 Windows 用户专属大坑——数据集脚本里大量使用os.path.join拼接路径但某些子路径写的是相对路径比如data/和checkpoint/。在 Linux 上没什么问题在 Windows 上如果路径分隔符不一致程序会找不到文件。解决办法是把数据集和模型权重全部放在项目根目录下的data/和checkpoint/目录里不要在系统盘的其他路径运行脚本我从不在 Windows 上折腾这个项目可以少掉不少头发。6. 环境跑通后的快速验证与后续扩展6.1 用预训练模型跑出第一组 3D 关键点环境全部配好后最快的验证方式是运行测试脚本。假设你已经把data_3d_h36m.npz、2D 关键点文件和预训练模型权重放到了正确位置执行python run.py --test --reload path/to/pretrained_model.bin这里的--reload参数指定权重文件路径。以 Human3.6M 的测试集为例模型会按协议 1 和协议 2 输出关节平均误差。看到类似Protocol 1 mean joint position error on the test set: 46.8 mm的输出就说明整个环境链路已经通了。这个数字是不是和论文数字一致不重要不同机器、不同 PyTorch 版本之间会有细微浮点误差只要在合理范围内50mm 上下就没问题。如果误差离谱比如几千毫米检查是不是 2D 关键点没做归一化或者模型权重加载时没对齐。6.2 可视化输出把 3D 骨骼画出来跑出数值还不直观建议下一步直接做一个可视化。项目里自带可视化工具但接口比较底层我一般用common/visualization.py里的函数配合 matplotlib 直接画 3D 骨架import matplotlib.pyplot as plt from common.visualization import render_animation最简单的做法是把测试集里某一帧的关键点提取出来用 matplotlib 的scatter和plot画散点和连线。骨架连接关系可以参照 Human3.6M 的.xml定义官方仓库的metadata.xml里也有。如果想让效果更像演示视频里那样可以把多帧结果连成动画流用 matplotlib 的FuncAnimation实现。这一步纯粹看你需求不跑也不影响环境验证。6.3 替换自己的 2D 检测器作为输入VideoPose3D 的推理环节支持从自定义 2D 关键点出发预测 3D。操作路径是先用你喜欢的 2D 检测器比如 OpenPose、MMPose、MediaPipe对视频逐帧检测关键点保存为每帧 17 个关键点的坐标数组然后转成项目的 npz 格式。inference.py里做了这个逻辑的适配。很多人在这一步会纠结detectron2的安装。实际上如果你不打算走官方自带的 2D 检测流程完全可以跳过 detectron2。inference.py确实需要它但你可以只调用模型的前向推理部分传入自定义的 2D 关键点即可不需要安装 detectron2。这一步能省掉大量编译时间——detectron2 从源码编译经常能把人卡到自闭。替换 2D 检测器后最重要的一件事关键点顺序必须和预训练模型训练时一致。官方模型用的是 Human3.6M 的 17 个关键点顺序COCO 也是 17 个但顺序不同直接喂进去结果必然错乱。解决办法是写一个关键点索引映射表把 COCO 顺序映射到 Human3.6M 顺序这一步踩过的人不在少数。最后的几个建议回想这几年帮别人排查 VideoPose3D 环境的经历大部分问题都集中在“版本新老冲突”上而不是模型本身。装环境的时候宁可多花几分钟把 Python、PyTorch、ffmpeg、数据文件的位置全部固定好也不要在跑起来之后来回试错。新版本不一定是坏事但跑老项目时“稳定”比“最新”更重要这是我在无数个坑里换来的经验。如果你用的是自己的数据建议第一次跑通前先只跑几分钟内的短片段确认整个流程没问题再处理完整视频。2D 检测的单帧误差会在 3D 提升时被放大所以尽量选检测质量高的模型作为输入。最后再补充一个小技巧项目根目录下的run.py里面默认参数非常多但大多数不需要动。建议把常用的参数组合整理成一个 shell 脚本或命令这样后续切换数据、切换模型权重时不用每次敲一串长命令。环境搭建是一次性的但调试和实验是长期的把自己的工作流固化下来收益远大于那几分钟的偷懒。