OpenPose模型文件全攻略：下载、路径配置与故障排查

简介：OpenPose模型压缩包是OpenPose开源姿态估计库的模型文件集合，面向需要快速搭建人体、面部、手部关键点检测环境的开发者与研究者。包内共有16个文件，包括caffemodel预训练权重、prototxt网络配置、模型下载脚本、人脸检测分类器及示例文件，压缩后总大小约727.86MB。目录按面部、手部、人体姿态等模块划分，方便按需取用。其中人体姿态模型提供Body_25、COCO、MPI三种选择：Body_25基于COCO数据训练，适合复杂场景；MPI模型在特定姿势下表现稳定；另有面部51点与手部21点检测模型，覆盖常见关键点识别需求。所有文件均为预训练权重，可直接放入OpenPose目录使用，省去从零训练的时间和算力，配合框架即可完成推理。目前已有916人学习下载。借助这些模型，读者能快速对比不同方案的精度与特点，为行为识别、人机交互、运动分析等应用提供现成基础，特别适合姿态估计入门和项目集成。

1. openpose-models 到底装的是什么：别把模型文件当成“AI 引擎”

第一次用 OpenPose 的人，几乎都会在openpose/models目录前愣一下：里面躺着一堆.caffemodel、.pth文件，大的有 200MB，小的只有几 MB，和源码放在一起看起来像“模型库”，但又不确定这些文件是不是就是“OpenPose 本身”。实际上 OpenPose 的可执行文件、Python API、网络定义全在源码里，models目录装的只是预训练权重——它们是让骨架检测真正出结果的“肌肉”，没有它们，程序能跑起来，但输出里全是乱线或空白的点。

这个下载模板openpose-models解决的正是这一层：把openpose/models下面所有官方需要的手部、脸部、身体姿态模型一次性规整好，放到程序默认会去加载的位置。适合两类人：一类是刚在服务器上编译完 OpenPose，正发愁“模型去哪下”的新手；另一类是国内网络环境下反复下载失败、想手动补齐模型的运维或算法工程师。下面从头拆：这些文件各自负责什么、放在哪、参数怎么设、坏了怎么查。

2. 打开 openpose/models 目录：三套身体模型加一套手、脸模型，各管什么活

2.1 模型文件清单：先知道桌上有哪些菜

OpenPose 官方在models/下维护了一套固定的文件布局，分为pose/、hand/、face/三个子目录。主程序启动时按网络类型去对应目录里找权重文件，文件名是硬编码在源码里的，不能随便改，也不能随意移动。下面是一份我本机常用的对照表，文件大小以官方发布为准，不同版本略有出入：

注意上面.pth是 PyTorch 格式的权重，.caffemodel是 Caffe 格式的。OpenPose 的 C++ 核心基于 Caffe 加载身体模型，手和脸的模型则通过内嵌的 PyTorch 推理器加载。这意味着你的 OpenPose 编译时必须同时开启了 Caffe 和 PyTorch 支持，否则即使模型文件放对了位置，程序也会报“找不到对应后端”的错误。

2.2 三套身体模型怎么选：参数model_pose的取值逻辑

在openpose.bin或 Python API 里，--model_pose参数决定加载哪一套身体模型。常见做法是：

./build/examples/openpose/openpose.bin \ --model_pose BODY_25 \ --model_folder /path/to/openpose/models/ \ --image_dir /path/to/test_images/

逻辑说明：--model_pose的可选值有BODY_25、COCO、MPI和BODY_25B。程序拿到这个值后，会在--model_folder指向的目录下拼接出pose/<model_pose>/pose_iter_xxxxxx.caffemodel的完整路径。选型的经验法则：

参数上，BODY_25的--net_resolution我一般设置656x368（输入分辨率），COCO常用656x368也可以；如果显存吃紧，把--net_resolution降到320x240会牺牲一些精度，但模型加载逻辑不受影响。改完--model_pose后第一次运行，程序会重新加载对应的.caffemodel，耗时比换图片大得多，这不是卡死，是正常预热。

2.3 手脸模型不是自动加载的：参数开关和模型的依赖关系

手部模型和面部模型不会因为身体模型加载了就自动启用。OpenPose 的流程是先跑身体姿态估计，在检测到人的区域上再做手部和脸部关键点回归。实际使用中，我通常会在命令里显式打开两个开关：

./build/examples/openpose/openpose.bin \ --model_pose BODY_25 \ --hand \ --face \ --model_folder /path/to/openpose/models/

逻辑说明：--hand和--face是布尔开关，不传默认关闭。一旦开启，OpenPose 需要能在models/hand/和models/face/下找到hand_pose_model.pth和face_pose_model.pth。这两个文件不在getModels.sh的默认下载列表里，需要单独确认。我的习惯是跑手脸需求前先ls -lh models/hand models/face看一眼文件大小，手部模型约 14MB，面部约 2MB，如果只有几 KB 那一定是下载占位文件或者下载失败，后面所有手脸结果都会是空白。

另外要注意.pth文件的加载对 OpenPose 的 PyTorch 版本敏感。某开发者在某公司服务器上遇到过一种情况：模型文件完整，但运行时提示pytorch相关错误，最后发现是编译 OpenPose 时用的 PyTorch 和当前系统的 CUDA 库版本错位。这种情况重新编译一次 OpenPose 比换模型文件更有效。

3. 模型文件放哪、怎么放：getModels.sh 到手动下载的完整路径

3.1 快速版：用官方脚本一键补齐但可能卡在半路

OpenPose 源码的models/目录下自带getModels.sh，它是一系列wget命令的集合，逐个下载官方发布在服务器上的权重文件。常规操作是：

cd /opt/openpose sudo chmod +x models/getModels.sh ./models/getModels.sh

命令运行的逻辑：脚本依次进入models/pose/body_25、models/pose/coco等目录，用wget拉取对应模型，下载完成后留在原地。脚本本身不带断点续传逻辑，一旦某个文件下载到一半连接断开，脚本会继续执行下一个，导致最后目录里出现一个体积不完整的.caffemodel，程序加载时才会报错。

这个脚本适合两条路：一是网络环境良好的海外服务器，几分钟就能全部拉完；二是你愿意反复执行脚本，断了的文件重新跑一遍会覆盖补全。但如果你在国内服务器上跑它，大概率会在某个大文件上反复失败，等待时间成本很高。我一般不建议新手直接在生产环境上跑这个脚本，因为脚本没有校验逻辑，下载失败和下载成功混在一起时，很难一眼看出哪个文件是坏的。

3.2 手动下载版：绕开脚本，自己控制文件名和路径

手动下载的本质是利用 OpenPose 官方发布页上的固定 URL。文件名和路径在getModels.sh里都能看到，照着写就行。以下是我经常用的手动方案，把三套身体模型和手、脸模型按官方路径放好：

mkdir -p /opt/openpose/models/pose/body_25 mkdir -p /opt/openpose/models/pose/coco mkdir -p /opt/openpose/models/pose/mpi mkdir -p /opt/openpose/models/hand mkdir -p /opt/openpose/models/face cd /opt/openpose/models/pose/body_25 wget -c -O pose_iter_584000.caffemodel \ https://example.com/pose/body_25/pose_iter_584000.caffemodel wget -c -O pose.prototxt \ https://example.com/pose/body_25/pose.prototxt cd /opt/openpose/models/pose/coco wget -c -O pose_iter_440000.caffemodel \ https://example.com/pose/coco/pose_iter_440000.caffemodel wget -c -O pose.prototxt \ https://example.com/pose/coco/pose.prototxt cd /opt/openpose/models/hand wget -c -O hand_pose_model.pth \ https://example.com/hand/hand_pose_model.pth cd /opt/openpose/models/face wget -c -O face_pose_model.pth \ https://example.com/face/face_pose_model.pth

逻辑说明：wget -c支持断点续传，网络中断后重新执行同一条命令会从断点位置继续，而不是从头开始。-O参数强制指定输出文件名，避免服务器上文件名带版本号或时间戳导致 OpenPose 找不到。mkdir -p是递归创建目录，放在最前面保证后续命令不会因为目录不存在而失败。

这里的https://example.com/...是占位 URL，实际使用时要把官方getModels.sh里对应行的地址整段复制过来。为什么一定要按这个目录结构放？因为 OpenPose 源码里的加载器是硬编码拼接路径的，具体在src/openpose/pose/poseParameters.cpp和src/openpose/hand/handParameters.cpp里，它会用model_folder + "pose/" + model_pose + "/" + model_filename的方式拼路径。model_folder就是命令里的--model_folder，默认值是编译时指定的路径。你如果改了子目录名，即使文件都在，程序也会提示找不到pose_iter_xxxxxx.caffemodel，直接拒绝启动。

3.3 路径检查三步法：确保文件真正落在加载器的视野里

模型放完后，建议在启动 demo 前先跑三个检查命令，把“文件不在”“文件坏了”“文件放错架构目录”三种情况一次性排除：

find /opt/openpose/models -type f | sort file /opt/openpose/models/pose/body_25/pose_iter_584000.caffemodel du -h /opt/openpose/models/pose/body_25/pose_iter_584000.caffemodel

逻辑说明：find列出目录下所有文件，确认文件名和子目录跟上一节表格里完全一致；file查看文件真实格式，.caffemodel应该反馈为data或caffemodel相关字样，如果反馈HTML document或者ASCII text，说明下载到的其实是错误页面或占位内容；du -h查文件大小，BODY_25 模型应该有约 200MB，COCO 约 200MB，MPI 约 100MB 上下，大小明显偏小，例如几 MB，基本可以判断是下载中断。

这三步做完，再进 demo 验证就不会出现“玄学失灵”了。一个真实经历：A同学在某高校服务器上部署时，file一看发现所有模型都是 0 字节，原因是getModels.sh执行时磁盘写满了，wget 生成了空文件，后面所有问题都源于此。所以他后来养成了每次下载完先du -sh看一眼总量的习惯。

4. 版本和路径的暗坑：为什么文件名一样，程序还是报找不到模型

4.1 加载器的搜索顺序：model_folder参数的默认值到底指向哪

很多新手会把模型下载到openpose-models单独解压出来的目录里，然后直接运行 demo，结果报错找不到模型。原因要从 OpenPose 编译期说起：CMake 配置时如果设置了OPENPOSE_MODEL_FOLDER，这个路径会被编译进二进制文件作为默认的model_folder。也就是说，你运行openpose.bin时不加--model_folder参数，它会去编译时指定的路径找模型，而不是去当前目录找。

cmake -D OPENPOSE_MODEL_FOLDER=/opt/openpose/models ..

逻辑说明：这个参数在源码CMakeLists.txt里定义，不传时默认是models相对目录。在项目根目录下运行有时碰巧能找到，但如果你的可执行文件在build/examples/openpose/下，相对路径就变成build/examples/openpose/models，自然找不到。我在装机器时固定用绝对路径，这样无论从哪个目录启动 demo 都不会踩这个坑。查看当前二进制内置的默认路径，可以用strings搜索：

strings ./build/examples/openpose/openpose.bin | grep -i "models"

如果输出里有models/pose之类的字样，就说明编译时确实写死了一个相对路径，运行时最好还是显式加--model_folder。还有一种情况是 Docker 镜像里，模型放在/opt/openpose/models，但容器工作目录被改了，这时不带参数基本必挂。

4.2.prototxt和.caffemodel的配对校验：换模型不换网络定义直接崩溃

每套模型都有配套的.prototxt文件，它描述网络每层的输入输出尺寸和连接关系。.caffemodel里的权重必须严格匹配.prototxt里的层结构。最常见的翻车现场是：为了用 BODY_25 模型，只下载了pose_iter_584000.caffemodel，却忘了下载对应pose.prototxt，或者从其他项目里拷了一份 COCO 的.prototxt过来。运行时 OpenPose 会加载出错，提示layer "loss"之类的维度不匹配，程序直接退出。

ls -l /opt/openpose/models/pose/body_25/

检查这个目录时，必须看到pose_iter_584000.caffemodel和pose.prototxt两个文件同时存在。.prototxt很小，不到 50KB，但缺了它整个模型都起不来。有些用户把getModels.sh里.prototxt那一行漏掉，手动下载时只记得大文件，所以我在前面手动下载命令里特别强调两个都需要。如果你确实丢了.prototxt，去 OpenPose 源码的models/pose/body_25/下复制一份即可，它的内容在代码仓库里，不需要单独下载。

4.3 多个 OpenPose 版本共存时的模型目录隔离问题

同一台机器上装了不同版本的 OpenPose（常见于算法同学先装了旧版，后来又拉新代码编译），两个版本可能共用同一个models/目录。OpenPose 的老版本不支持 BODY_25 网络，你如果用旧版二进制去加载新版模型目录里的 BODY_25 权重，会提示未知层类型或者直接段错误。反过来新版本去加载老模型一般没问题，因为向前兼容。

解决思路有两个。第一，每个版本的源码目录下单独维护一个models/，不做软链；第二，启动时明确指定各自的--model_folder，而不是依赖默认值。某公司生产环境里出现过一次事故：新版本上线时，启动脚本沿用旧版的--model_folder路径，结果加载了旧版模型，关键点数量对不上，推断结果全偏。排查方式很简单，看启动日志里的模型加载路径：

./build/examples/openpose/openpose.bin \ --model_folder /opt/openpose/v2/models \ --logging_level 3

日志级别--logging_level 3会打印每个模型文件的完整加载路径，一眼就能确认是否指向了正确目录。我在多版本环境中的习惯是给每个版本建独立目录，models-v2、models-v3，启动脚本里把路径写成变量，彻底避免两个版本抢同一个文件。

4.4 找不到肩部或脚部关键点？先查模型和关节点索引是否匹配

BODY_25 有 25 个关键点，其中包含 4 个脚部关键点（脚踝、脚跟、大脚趾、小脚趾），COCO 只有 18 个点，MPI 只有 16 个点。如果你用 COCO 模型但代码里按 BODY_25 的索引取脚部数据，拿到的会是大腿或空白。这类问题不算模型文件放错，而是模型选型和应用代码的匹配问题。

一个稳妥做法是先用官方 demo 跑一张标准姿势图，把可视化结果打开，确认所有点都画在人体上：

./build/examples/openpose/openpose.bin \ --model_pose COCO \ --image_dir /opt/openpose/examples/media/ \ --write_json /tmp/output_json/ \ --write_images /tmp/output_vis/

--write_json会输出每个人每个关键点的坐标和置信度，方便脚本检查关键点数量；--write_images保存带骨架叠加的图片，肉眼直接判断。如果 JSON 里关键点数量是 18，而你代码里写死 25 维数组，预处理逻辑就会失控。做这类二次开发前，先跑一遍这个命令确认模型和代码的索引映射是同一套，能省下大量调试时间。

5. openpose-models 避坑指南：下载、路径、显存三个高频故障排查

5.1 模型下载到一半失败：.caffemodel只有几 MB，程序报“file does not exist”

现象：getModels.sh执行后没有报错，但启动 demo 时提示找不到pose_iter_584000.caffemodel，或者提示加载模型失败。实际查看模型目录，文件确实存在，只不过体积只有 5MB 左右。

原因：wget默认遇到网络中断不会重试，脚本继续下载下一个文件。getModels.sh没有对单个文件断点续传，也没有在校验失败后退出，最终留下一个残缺文件。程序加载时打开文件成功，但读取权重解析失败，报错信息可能误导你去检查路径，而不是文件完整性。

解决：删除对应文件重新下载，并强制使用断点续传方式。我一般先跑rm清掉不完整的文件，再执行wget -c，确认du -h显示体积接近官方大小后才算完成。如果你不想保留脚本，就直接从我第 3 章的手动下载方案里挑对应行执行，注意-c参数是关键。下载完成的模型文件体积：BODY_25 约 200MB，COCO 约 200MB，MPI 约 100MB。明显偏小的一律删掉重下。

5.2 模型文件全在，但提示 “Check failed: ... caffemodel ... No such file”

现象：用find查文件都在，路径也对着，但程序就是报找不到文件。--model_folder传的目录是/opt/openpose/models，子目录结构也和官方一致。

原因：这不是文件的锅，是权限。OpenPose 从 Caffe 加载模型时用OpenCV的fstream打开文件，如果运行用户对目录没有读权限，或者文件权限是 600、只属于 root，程序打开失败，报错却叫“No such file”，因为它是按打开失败统一处理的。服务器上常见于用curl或sudo wget下载后文件归属 root，当前用户是普通用户。

解决：给整个 models 目录加读和执行权限，让运行用户能穿透目录：

chmod -R o+r /opt/openpose/models find /opt/openpose/models -type d -exec chmod o+x {} \;

第一条给所有文件加只读，第二条给所有子目录加执行权限，因为只有先对目录有执行权限才能访问里面的文件。改完后用非 root 用户跑一次 demo，如果还报同样错误，再检查mount是否有noexec或nodev限制。某开发者在某公司容器环境里就是被read_only_root_filesystem卡住了整个目录，最后把模型放到挂载卷里才解决。

5.3 显存频繁不够：--net_resolution参数和解码分辨率的关系

现象：模型加载正常，推理启动后跑一两张图就报cudaErrorMemoryAllocation，有时直接Segmentation fault。

原因：OpenPose 的计算量跟输入图像解码分辨率和网络分辨率两个因素有关。--net_resolution控制神经网络输入尺寸，--camera_resolution或输入图像分辨率影响预处理，开 Cascade 后每个检测框还会单独跑手部或脸部网络。显存占用大户是网络输入特征图，不是模型文件大小，所以模型体积 200MB 不代表推理时只占 200MB。

解决：显存有限时先降--net_resolution，同时把--num_gpu和--num_gpu_start显式指定为 1，避免自动检测多卡导致把模型重复载入每块 GPU：

./build/examples/openpose/openpose.bin \ --model_pose BODY_25 \ --net_resolution 320x240 \ --num_gpu 1 \ --num_gpu_start 0 \ --model_folder /opt/openpose/models/

逻辑说明：320x240是宽度 x 高度，注意字符串里宽在前、高在后，不要写反。如果你想要更高质量的骨架，可以调回656x368，但如果显存是 4GB 以下，同时开了--hand和--face就很容易溢出，建议优先关掉手脸：去掉--hand--face参数即可。另一个经验是把输入图片先缩放，例如原图 1920x1080 先缩到 960x540 再喂给 OpenPose，能显著减少预处理阶段的显存峰值。CONFIG 文件里net_resolution写错的案例很多，320x240和240x320性能差不少，前者是横屏常用，后者在竖屏视频里更合适，你要按实际输入源的比例来选，不匹配时会拉伸变形，关键点坐标也跟着偏移。

5.4 模型加载时间极长：每次都重新加载，没有缓存

现象：程序启动后要等待十几秒甚至半分钟才出现画面，换一次--model_pose又要等一轮。如果是在循环里反复调用 OpenPose 的 C++ API，每次都感觉卡在初始化。

原因：OpenPose 的OP::configure每次调用都会重新加载模型文件。Caffe 加载一个大模型需要读 200MB 文件并初始化网络层，这是纯 IO 和 CPU 开销。模型文件放置在网络位置例如 NFS 挂载盘上时，加载时间特别长。

解决：不要频繁销毁和重建 OpenPose 实例，进程内只初始化一次，后续直接调用。如果服务端程序需要支持多路请求，每路过一个独立进程，模型会各自加载一次，这是正常的。模型文件尽量放在本地 SSD 目录，不要放到网络盘。一个实际优化案例：某图像处理 Demo 项目把模型从 NFS 移到本地 SSD 后，首次加载从 25 秒降到 3 秒。如果你每次启动跑单张图就退出，考虑改成写个常驻进程，加载一次模型，循环处理多张图片，收益非常明显。

6. 验证 openpose-models 是否真的被用上：日志、demo 输出与裁剪提速技巧

模型放没放对、加载没加载成功，不能只靠“能跑起来”判断，因为 OpenPose 有时会静默降级。我常用的验证顺序：第一步看启动日志，--logging_level 3下会打印Loading model from ...和实际路径，确认指向你的模型目录；第二步用官方 demo 跑一张单人站立图，观察 JSON 输出里关键点数量是否匹配模型类型；第三步手脸模型单独验证，跑一张握拳或伸掌图片，确认手部 21 个点是否完整。

最后一个值得落地的技巧是“按需裁剪模型文件”，不需要手脸功能时，可以把hand_pose_model.pth和face_pose_model.pth从 models 目录里移走，只保留身体模型。很多生产环境里这一移，进程内存占用和启动时间立刻下降。有需要时再放回来，不影响任何全局配置。同理，如果你确定只用 BODY_25，可以直接删掉pose/coco和pose/mpi两个目录，节省几百 MB 磁盘空间，程序不会管多余文件。另外，模型文件可以放到只读卷里并用--model_folder指向它，OpenPose 不会写模型目录，只读挂载不会导致运行失败，还能防误删。

我自己的习惯是每次装完 OpenPose 第一件事就是跑一遍上面的日志验证，然后写一个两行的启动脚本：一行导出MODEL_FOLDER环境变量，一行跑 demo。这样后续换机器、换版本时，模型路径永远跟着脚本走，而不是靠记忆里的默认值。这个习惯帮我避开过至少三次“换了机器就找不到模型”的尴尬。希望这篇能帮你的 OpenPose 少走几步弯路，模型这种东西，放对了是提效工具，放错了就是拦路石。

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