简介OpenPose 作为实时多人姿态估计的常用开源库其模型权重与网络配置是跑通行为识别流程的关键依赖。这份模型包按 openpose/models 原有目录整理覆盖人体、面部和手部关键点检测任务面向需要直接部署 OpenPose 的开发者或研究者。压缩包共16个文件包含5个 caffemodel 预训练权重、6个 prototxt 网络结构定义以及 getModels 脚本、xml 参数、日志文件等整体约727.86MB。模型覆盖 Body_25、COCO、MPI 三套人体姿态方案并附带人脸关键点与手部21点检测模型用户可依照项目场景放入指定目录自动加载省去从零训练的时间。已有918人学习下载适合行为识别、人机交互、运动分析等方向也能帮助使用者理解 OpenPose 文件结构与推理配置逻辑。1. openpose 骨架行为识别卡住的往往不是编译而是模型做 openpose 骨架行为识别的人十有八九都经历过同一个场景源码编译用了大半天环境依赖装了一堆终于等到openpose.bin能跑起来结果程序一启动就提示找不到模型文件或者模型加载到一半直接崩溃。问题十有八九出在openpose/models目录下那几个.caffemodel文件——官方下载脚本连的是国外服务器文件又是几百 MB 级别的大文件网络稍有不稳就下载失败断点续传又不完善最后得到的是一堆残缺文件。这个坑让不少人在骨架行为识别项目上栽跟头甚至误以为是显卡驱动或 CUDA 版本不对把环境重装了好几遍。这套openpose-models资源要解决的就是这个问题把openpose/models目录下缺的文件一次补齐覆盖进去就能跑。适合已经装好 OpenPose 但模型文件不齐的开发者也适合准备从零搭建骨架识别环境、想先把模型备好的新手。文章后面会按环境准备、模型覆盖、参数配置、故障排查的顺序拆开讲最后用一张图和一段 JSON 输出验证跑通。2. 环境与版本选型先把 OpenPose 1.7.0 的性能边界摸清2.1 系统依赖与编译环境一档能长期跑的组合在动手下载模型之前建议先确认 OpenPose 本体处于什么状态。openpose-models只是模型的补全资源不是 OpenPose 主程序它要求你的机器上已经存在可运行的 OpenPose 环境。如果连主程序都没编译过先把源码和环境装好再回来覆盖模型顺序不能反。我经手的项目中OpenPose 1.7.0 是使用最广的版本它的依赖项不算少但也没到劝退的程度。下面这张表是我整理的一套长期跑过的组合供参考依赖项推荐版本区间说明操作系统Linux 系Ubuntu 类发行版Windows 也能跑但模型覆盖路径写法不同下文以 Linux 示例CMake3.12 以上低于这个版本部分 CUDA 检测模块会失效C 编译器GCC 7 以上编译 Caffe 后端时必须支持 C11CUDA11.x 系列不需要最新版稳定比新功能重要cuDNN与 CUDA 11 对应的 8.x 版本版本不匹配时模型加载会报错OpenCV4.x 系列3.4 也能用但 4.x 对视频流处理更稳Python3.8 或 3.9主要给后续关键点解析脚本用提示CUDA 和 cuDNN 的版本匹配关系建议通过显卡驱动的说明文档确认不同驱动分支支持的 CUDA 版本不一样。装错版本最常见的报错是“driver version is insufficient”跟模型文件本身无关。OpenPose 自带一份 Caffe 源码编译时用内部的BUILD_CAFFE选项即可不用额外装系统级 Caffe。这算是省心的地方——只要 CMake 配置正确Caffe 会跟着 OpenPose 一起编译不需要单独折腾依赖。2.2 models 目录里到底缺了什么一份官方标准结构清单编译完成、程序能启动之后模型文件是最后一道门槛。OpenPose 默认会在源码根目录下的models文件夹里找权重文件。正常的models目录应该长成这样models/ ├── pose/ │ ├── body_25/ │ │ ├── pose_deploy.prototxt │ │ └── pose_iter_584000.caffemodel │ ├── coco/ │ │ ├── pose_deploy_linevec.prototxt │ │ └── pose_iter_440000.caffemodel │ └── mpi/ │ ├── pose_deploy_linevec_faster_4_stages.prototxt │ └── pose_iter_160000.caffemodel ├── face/ │ └── pose_iter_116000.caffemodel └── hand/ └── pose_iter_102000.caffemodel结构不复杂每个子目录对应一种人体姿态模型body_25是 OpenPose 自研的 25 点骨架模型精度和速度比较均衡也是默认选项coco是 COCO 数据集的 18 点模型在早些年比较流行mpi是 15 点模型速度最快但精度一般适合对实时性要求高的场景。face目录是 70 点人脸关键点模型hand目录是 21 点手部关键点模型都是可选项——不跑人脸或手部识别时可以不放但缺失文件时程序会在初始化阶段报错所以我的习惯是全部放齐。.prototxt是 Caffe 的网络结构描述文件.caffemodel是训练好的权重文件。两者必须配套缺一个都不行。特别需要注意的是很多人在下载时只关注了体积大的.caffemodel忽略了体积很小的.prototxt结果运行时提示“网络结构不匹配”一脸懵。2.3 模型文件与 OpenPose 版本为什么不能随便混搭模型文件不是通用的。OpenPose 1.7.0 使用的 BODY_25 权重文件名是pose_iter_584000.caffemodelCOCO 权重是pose_iter_440000.caffemodelMPI 权重是pose_iter_160000.caffemodel。这些文件名在特定版本范围内是固定的OpenPose 源码里写死了默认的加载路径不会自动去目录里“发现”新模型。openpose-models这套资源的价值就在这里它覆盖的正是openpose/models下面缺的这些文件。拿到离线包之后不需要再跑官方下载脚本去慢慢拉取直接把文件覆盖到对应目录就能完成模型补齐。版本上建议匹配 OpenPose 1.7.0 使用如果用老版本或新版本的 OpenPose建议先确认一下源码里对应的proto版本文件是否和模型一致。这块我吃过一次亏在某个项目中COCO 模型用了新版本打包的 caffemodel但pose_deploy_linevec.prototxt还是旧版程序加载时直接报维度不匹配。从那以后我再也不混搭不同来源的模型文件坚持整套覆盖。3. 下载与覆盖安装把 openpose/models 目录一次补齐3.1 官方脚本下载失败的三种情况别在这上面硬耗OpenPose 官方提供了自动下载模型的脚本正常情况下一行命令就能把所有模型拉回来。但实际使用中这个脚本的成功率并不高我见过的主要有三种情况。第一种是网络中断。模型文件大脚本本身没有做可靠的断点续传下载到一半连接断开脚本直接就退出了留下一个不完整的.caffemodel文件——文件大小看起来有几 MB但远小于正常体积运行时程序不会提示下载不完整只会报加载失败。第二种是 SSL 证书校验失败。脚本内部用的是curl下载在部分网络环境下证书链不完整curl会报SSL certificate problem错误。这不是代码问题是网络设备拦截或证书源更新的问题硬改curl -k跳过校验也是一种办法但不少人折腾半天发现改了也没用。第三种是磁盘路径问题。脚本默认把模型写到当前目录下的models文件夹如果在 OpenPose 源码根目录之外执行脚本下载下来的文件会被丢到别处程序自然找不到。我的态度是别在官方脚本上钻牛角尖。环境网络不理想就别硬刚直接用openpose-models离线包一次性补齐更省心。3.2 覆盖 models 目录先备份再解压再替换拿到openpose-models离线包之后覆盖安装的步骤并不多但顺序有讲究。先把 OpenPose 源码目录下的原有 models 目录备份一份防止新文件不兼容时还能退回去。这在部署中属于后悔药级别的操作我做模型这类大文件替换时从来不敢跳过备份。# 进入 OpenPose 源码根目录 cd /opt/openpose # 备份原有 models 目录 mv models models.bak # 解压 openpose-models 离线包 unzip openpose-models.zip -d /tmp/openpose-models # 查看解压后的目录结构确认顶层是 models 目录 ls /tmp/openpose-models这段操作里备份和验证解压结构是关键。unzip -d后面指定的路径决定了文件解压到哪里如果解压出来顶层目录不叫models直接覆盖会让路径错位。常见的打包情况有两种压缩包内直接是models目录或者压缩包内是openpose-models之类的父目录里面再套一层models。先ls看一眼再动手能省掉后续一大半排查时间。确认结构没问题之后再做覆盖# 把离线包里的 models 内容复制到 OpenPose 源码目录 cp -rf /tmp/openpose-models/models /opt/openpose/ # 修正文件权限防止运行账户读不了 chmod -R 755 /opt/openpose/models # 检查关键权重文件是否就位 find /opt/openpose/models -name *.caffemodel -type fcp -rf会把整个 models 目录复制过去-r是递归复制子目录-f表示强制覆盖同名文件。chmod -R 755设置了目录和文件的读权限——OpenPose 运行只需要读取模型文件不需要写权限755 足够。最后一条find命令打印出所有.caffemodel文件路径能直观看到文件是否都在。如果解压后的目录结构不一样比如文件名不是上面的标准结构注意检查一下是不是拿到了不同平台的模型包。openpose-models的资源最好和 OpenPose 主程序版本匹配混用容易出现 prototxt 与 caffemodel 不配套的问题。3.3 目录验收文件齐全不等于路径正确覆盖完成之后别急着运行程序。先花两分钟把目录验收做一遍比启动时报错再回头排查快得多。# 逐个检查模型文件大小确认不是 0 字节或异常小 du -sh /opt/openpose/models/pose/*/ # 更细粒度地查看 caffemodel 和 prototxt 文件的体积 find /opt/openpose/models -name *.caffemodel -exec ls -lh {} \;du -sh会列出每个模型子目录的总大小。正常情况下body_25目录至少有 200 MB 以上的空间占用coco目录在 200 MB 左右mpi目录相对小一些。如果某个目录只有几十 KB那基本可以确定里面的权重文件是残缺的程序加载它必然失败。ls -lh命令更直接它会以人类可读的格式显示每个文件的体积。caffemodel 文件正常应该在几十 MB 到 200 MB 这个量级prototxt 文件通常只有几 KB。看到体积异常小的 caffemodel不用犹豫直接重新解压覆盖一遍。这一步在经验里就是黑匣子分层的过程把文件层面的问题先清零后面程序运行时再报错就能确定问题出在配置或参数上而不是模型缺失。4. 运行参数与模型路径配置让 OpenPose 认准你的模型4.1 运行时模型路径--model_folder 与默认值的坑模型文件放好了接下来是告诉 OpenPose 去哪里找。OpenPose 的 C 可执行文件在编译产物的build/examples/openpose/目录下运行时它会按编译时的默认路径搜索模型文件夹。问题在于如果你把models目录放在了 OpenPose 源码根目录下而你的工作目录在别处程序可能找错位置。# 进入构建输出目录 cd /opt/openpose/build/examples/openpose # 显式指定模型目录运行 ./openpose.bin --image /opt/test.jpg \ --model_folder /opt/openpose/models \ --write_json /opt/output \ --write_images /opt/output--model_folder参数的作用是指定模型文件所在目录的绝对路径。我一般会把它写成绝对路径尽量避免用相对路径——因为相对路径受工作目录影响执行位置一变就找不到模型。--write_json和--write_images是验证阶段要用的输出参数前者把检测到的关键点坐标和置信度写入 JSON 文件后者把带骨架线条的标注图保存下来这两个后面验证跑通时都会用到。运行后如果终端输出类似Cannot find models或Failed to load的字样第一反应不是重新编译而是先用ls /opt/openpose/models确认文件还在。这个检查 10 秒钟的事比去翻 CMakeCache 快得多。4.2 模型切换BODY_25 / COCO / MPI 怎么选OpenPose 支持三种人体骨架模型运行时用--model_pose参数切换。默认值是BODY_25也是我项目里最常用的。三种模型的差异主要在关键点数量和推理速度上模型关键点数量主要特点适用场景BODY_2525 点准确度最高包含脚部和脸部关键点通用骨架行为识别COCO18 点关键点较少速度略快追求更小输出量MPI15 点速度最快精度弱一些实时演示或低算力设备# 切换为 COCO 模型 ./openpose.bin --image /opt/test.jpg \ --model_folder /opt/openpose/models \ --model_pose COCO--model_pose参数值大小写敏感取值是BODY_25、COCO、MPI三者之一。切换模型时要注意OpenPose 不会自动去比对 models 目录里的文件是否匹配如果你指定了COCO但它找不到对应的pose_iter_440000.caffemodel程序会直接报错退出。所以切换模型的前提是 models 目录里对应文件齐全。我一般会同时维护好所有三套模型文件这样切换时只需改参数不用重新覆盖目录。如果磁盘空间紧张只留 BODY_25 也完全够用毕竟它才是新版 OpenPose 的主打模型。4.3 显存与推理速度参数net_resolution 和 number_people_max模型文件就位之后影响骨架行为识别能否流畅跑起来的关键在显存。多数开发者遇到的“程序能启动但一处理图片就崩”其实是显存不够而不是模型坏了。OpenPose 有两个参数直接影响显存占用。# 降低网络输入分辨率减少显存占用 ./openpose.bin --image /opt/test.jpg \ --model_folder /opt/openpose/models \ --net_resolution 368x368 \ --number_people_max 5--net_resolution指定神经网络输入图像的尺寸默认是656x368显存不够时改成368x368能明显降低占用。注意这个参数的单位是像素宽 x 高字母是小写 x写错成*或汉字会直接解析失败。--number_people_max限制单帧最多检测的人数默认在显存允许的情况下是 16 人左右。做单人骨架行为识别时把它调成 1 或 2 能省下不少显存换来的速度提升在 CPU 环境下尤其明显。这两个参数是调优时的万能钥匙先是调小number_people_max不够再降net_resolution一步步压到程序稳定运行。如果降到320x256仍然显存溢出那基本可以确定是显卡本身容量太小跟模型文件无关需要换硬件或者用 CPU 模式跑了。5. 避坑与常见问题排查模型文件相关的五个经典故障5.1 程序启动直接报 Models not found目录明明存在现象执行openpose.bin后终端打印Models not found或类似的路径错误程序立刻退出。用ls检查模型目录文件都在一切看起来正常。原因最常见的是--model_folder参数没有生效或者 OpenPose 内部分辨模型路径时把参数拼错了。另一种情况是编译时 OpenPose 把默认模型路径固化在了 CMakeCache 里运行时相对路径解析失败。解决改用绝对路径传参同时检查参数写法。正确写法是--model_folder /opt/openpose/models不要带结尾的models/和多余空格。另外确认运行命令的工作目录不影响路径解析必要时在命令前加cd /opt/openpose/build/examples/openpose。5.2 报 prototxt 和 caffemodel 维度不匹配加载崩溃现象程序能找到模型但加载时抛出维度不匹配的异常或者日志中提示 layer 的输入输出维度与权重不一致。这个报错隐含信息少第一次遇到很容易懵。原因.prototxt网络结构文件和.caffemodel权重文件来自不同版本。比如模型权重是 OpenPose 1.7.0 的prototxt 却来自 1.5.0 版本层数对不上。解决把模型目录下对应的整套文件删掉重新用同一份打包资源覆盖。我的习惯是每次覆盖都整个 models 目录一起替换不单独换某个文件。模型文件混搭是高风险操作绝不能图省事。5.3 官方下载脚本卡在 SSL 错误curl 报 60现象执行下载脚本时终端输出curl: (60) SSL certificate problem文件下不动。原因系统 CA 证书不完整或者网络环境对 HTTPS 连接做了拦截。这在部分办公网和运营商网络下比较常见跟 OpenPose 本身无关。解决不去调整系统证书坐等直接放弃官方脚本改用手头的 openpose-models 离线包本地覆盖。这也是这套资源的核心价值把网络下载环节整个绕开。手头资源缺失时找能连通的环境下载完整包再拷贝过来比在报错环境里硬刚证书快得多。5.4 覆盖模型目录后提示 Permission denied现象模型文件确认存在程序启动却报权限不足无法打开文件。原因解压工具或拷贝操作导致文件权限被重置常见于跨文件系统拷贝后属主变化。OpenPose 运行账户对 models 目录没有读权限。解决chmod -R 755 /opt/openpose/models统一放开读权限。如果 OpenPose 以特定服务账户运行还要确认该账户对目录有x执行权限否则目录能看不能进照样报错。5.5 加载模型时内存不足进程直接被杀现象程序启动后加载模型阶段内存飙升进程被系统 OOM killer 杀掉。用dmesg能看到进程被杀的记录。原因net_resolution设置的网络输入尺寸偏大加上同时加载人脸和手部模型内存占用超出可用范围。解决先只跑人体骨架模型不加载人脸和手部加上--hand false --face false参数然后调低分辨率。这两个参数关闭后内存占用能下降一大截。如果只是验证模型文件是否正常用最小配置跑通一张图就足够得出结论。6. 装完怎么验证跑通一张图跑出关键点 JSON6.1 用 openpose.bin 跑单张图片验证模型加载验证模型是否覆盖成功最直接的方式是跑一张单人站立图片生成带骨架的标注图和关键点 JSON。别一上来就跑视频视频流调试时问题定位成本更高。图片验证通过后再上视频顺序不能乱。# 单张图片验证输出关键点 JSON 和标注图 cd /opt/openpose/build/examples/openpose ./openpose.bin \ --image /opt/sample_stand.jpg \ --model_folder /opt/openpose/models \ --model_pose BODY_25 \ --net_resolution 368x368 \ --number_people_max 1 \ --write_json /opt/verify \ --write_images /opt/verify \ --hand false --face false运行时看到终端滚动输出层信息最后打印出关键点数量和推理耗时的统计就说明模型加载正常。如果输出 JSON 里people数组里有关键点数据这已经是成功跑通的信号。验证用的图片建议选一张背景干净、人物站姿完整的全身照复杂场景会对中间结果产生干扰不利于判断。6.2 用一段 Python 脚本校验关键点输出标注图能直观看到骨架线但机器可读的 JSON 才是骨架行为识别项目真正要用的数据。输出目录下会生成一个以输入图片名命名的 JSON 文件结构包含people数组每个人体对象里有pose_keypoints_2d数组。下面这段脚本可以快速统计关键点数量。import json import glob json_file sorted(glob.glob(/opt/verify/*.json))[0] with open(json_file, r) as f: data json.load(f) people data.get(people, []) print(检测到人数:, len(people)) if people: keypoints people[0][pose_keypoints_2d] valid sum(1 for i in range(2, len(keypoints), 3) if keypoints[i] 0.4) print(置信度大于0.4的关键点数量:, valid)脚本里用了glob自动找到验证目录下的第一个 JSON 文件避免手输文件名。pose_keypoints_2d数组每三个值是一组x, y, confidence第三步keypoints[i] 0.4计算置信度超过 0.4 的关键点数。BODY_25 模型正常单人检测时这个数值应该在 20 以上如果只有几个点说明模型加载虽然成功但推理效果异常需要回头检查图片质量和分辨率。6.3 一个容易忽略的习惯模型预热模型的第一次推理通常比后续推理慢不少。原因在于 OpenPose 第一次加载模型时会做权重初始化、显存分配、Caffe 的线程池预热这些工作都会计算在第一次推理耗时里。如果在验证时把第一次推理时间当作真实性能容易得出“机器很慢”的错误结论。我的习惯是验证时故意先跑一张无关紧要的图片做预热预热结果直接丢弃再跑正式的测试图片并把其耗时当作参考值。这个习惯在做骨架行为识别的性能评估时非常重要否则每次实验的基准数据都包含一次不稳定的预热耗时前后对比没有意义。从那以后我每搭好一套 OpenPose 环境都会强制先跑一张单人站立图确认 JSON 输出正常再做正式项目这个流程帮我挡下了不少以为环境坏了、其实只是没验证的返工。希望帮到你。本文还有配套的精品资源点击获取