企业官网建设流程全解析

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 完全可以。

系统方面强烈建议 Linux，Ubuntu 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 python=3.8 conda activate videopose

Python 版本我建议固定在 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 torch==1.13.1 torchvision==0.14.1

如果是新买的 40 系及以上显卡，CUDA 版本要求会迫使你装 PyTorch 2.x。这时候也不用慌，装最新稳定版，然后模型加载时手动指定weights_only=False（新版本 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 tqdm

3. 源码目录、预训练权重和数据文件的落位

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 相关报错

我见过最多的报错就是预处理脚本里提示找不到 ffmpeg：

RuntimeError: 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_only=True，而旧权重里通常包含自定义类对象或省略参数绑定，加载会失败。解决方式很简单，在run.py和common/generic.py里找到所有torch.load(...)调用，加上参数weights_only=False：

state_dict = torch.load(args.reload, map_location='cuda:0', weights_only=False)

这个改动只在本地有效，不影响模型结构。还有一个更隐蔽的相似问题：旧版本的 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 脚本或命令，这样后续切换数据、切换模型权重时不用每次敲一串长命令。环境搭建是一次性的，但调试和实验是长期的，把自己的工作流固化下来，收益远大于那几分钟的偷懒。