简介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/三个子目录。主程序启动时按网络类型去对应目录里找权重文件文件名是硬编码在源码里的不能随便改也不能随意移动。下面是一份我本机常用的对照表文件大小以官方发布为准不同版本略有出入子目录文件名对应网络/数据集关节点数量典型用途pose/cocopose_iter_440000.caffemodelCOCO 18 关键点18日常人体姿态估计兼顾速度与精度pose/cocopose.prototxtCOCO 网络结构描述-主程序加载网络的拓扑说明pose/mpipose_iter_160000.caffemodelMPI 16 关键点16旧版数据集关键点较少但兼容老模型pose/mpipose.prototxtMPI 网络结构描述-配合上面权重使用pose/body_25pose_iter_584000.caffemodelBODY_2525包含脚部关键点官方推荐默认选项pose/body_25pose.prototxtBODY_25 网络结构描述-手势/步态分析常用handhand_pose_model.pth手部 21 关键点21/每只手单人或多人手部关键点检测faceface_pose_model.pth面部 70 关键点70人脸关键点检测需配合手部模型加载注意上面.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_2525 个关键点含双脚官方长期维护精度均衡追求速度COCO18 个点网络更轻推理耗时明显下降老项目延续MPI16 个点兼容旧的标注格式和既有项目参数上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 模型应该有约 200MBCOCO 约 200MBMPI 约 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 约 200MBCOCO 约 200MBMPI 约 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 or /opt/openpose/models find /opt/openpose/models -type d -exec chmod ox {} \;第一条给所有文件加只读第二条给所有子目录加执行权限因为只有先对目录有执行权限才能访问里面的文件。改完后用非 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 少走几步弯路模型这种东西放对了是提效工具放错了就是拦路石。本文还有配套的精品资源点击获取