简介OpenPose 1.7.0全模型压缩包专为需要部署人体、面部与手部关键点检测的开发者准备。内含姿态、人脸、手部三类预训练模型姿态模型覆盖全身十八个关键点人脸模型能定位眼睛、鼻子、嘴巴等特征区域手部模型则精确到指关节适用于动作捕捉、虚拟现实交互、运动分析等实时推理场景。压缩包共十五个文件以Caffe框架的prototxt网络结构与caffemodel预训练权重为主另附getModels下载脚本和示例配置整体大小约七百二十七兆。模型按官方models目录组织放入OpenPose源码根目录即可被自动调用无需手动指定路径可避免逐个下载权重文件的繁琐有效提升编译和调试效率显著降低配置门槛。已有1010人学习下载适合正在搭建OpenPose环境或希望快速完成关键点检测任务的中初级开发者。1. OpenPose 1.7.0 全套模型文件为什么单独收集它是值得的跑过 OpenPose 的人都知道最耗耐心的不是编译而是模型文件。官方项目在 GitHub 上开源但模型存放在自己的服务器上网络稍差就反复断点下回来一个 0 字节的 caffemodelCMake 配置时还会在 Downloading 阶段卡半小时最后直接报错。你问我要 openpose 1.7.0 模型文件去哪弄我通常直接回一句别在线下了先把整套模型文件一次性拿到本地后面所有坑都能绕开。这套资源覆盖 BODY_25、COCO、MPI 三套人体姿态模型外加手部和脸部模型外加配套的 prototxt 与 yml 归一化文件装好 OpenPose 1.7.0 之后把模型目录替换进去就能跑通单人、多人、手势、人脸关键点检测。适合两类人一类是刚把 OpenPose 编译出来、卡在模型下载这一步的新手另一类是需要在离线环境部署姿态识别服务的从业者内网没法访问外网模型文件必须先打包好。2. 模型文件构成与选型BODY_25、COCO、MPI、手部、脸部五套模型的取舍2.1 五套模型的适用场景先想清楚你要检测谁OpenPose 1.7.0 的模型文件不是一套而是按数据集和关键点数量分成好几套。人体姿态这边有三套主流选择BODY_25、COCO、MPI。BODY_25 是 OpenPose 自家提出的 25 关键点标注体系除了常规的关节还多了脚部关键点和背景分割用的颈部、髋部中间点在多人遮挡场景下鲁棒性最好也是 1.7.0 的默认推荐模型。COCO 是 18 关键点社区生态好很多下游任务比如动作识别、异常行为检测的标签体系就是按 COCO 设计的输出结果可以直接对接。MPI 是 15 关键点模型体积最小、速度最快但精度和关键点覆盖都不如前两者适合嵌入式设备或者对关键点数量要求不高的场景。我在实际项目里的选择逻辑是先看输出要不要接下游算法。要接 COCO 标注的公开数据集就用 COCO 模型要自己训练或者需要脚部关键点做步态分析就用 BODY_25设备算力有限、只要躯干大致姿态用 MPI 顶一版原型。手部模型和脸部模型是独立的两套不在人体模型里需要单独开启对应的--hand和--face参数才会加载。手部检测是 22 个关键点每只手 21 个点加一个背景分类脸部是 70 个关键点不包含眼球中心点。如果你的需求是手势识别或人脸关键点对齐这两套模型文件必须和人体模型放在一起缺一个就只能在日志里看到模型加载失败的红字。2.2 模型文件格式与对应关系caffemodel、prototxt、yml 各自负责什么OpenPose 1.7.0 的模型文件不是单一文件而是每组模型包含多个文件缺一不可。以 BODY_25 为例模型目录下有pose_iter_440000.caffemodel存放训练好的权重参数有pose_deploy.prototxt描述网络结构还有pose_deploy_linevec.prototxt和pose_deploy_mulvec.prototxt用于 PAF 向量场解析以及一个 yml 文件存放关键点归一化参数。COCO 模型是pose_iter_440000.caffemodelMPI 是pose_iter_160000.caffemodel手部是pose_iter_102000.caffemodel脸部是pose_iter_116000.caffemodel。后缀名不一样不要慌.caffemodel是权重.prototxt是结构.yml是归一化系数三者在加载时会同时被读入。这里有个容易混淆的点prototxt 虽然看起来像配置文件但它决定的是网络层结构和输入输出尺寸不能随便改。你如果把pose_deploy.prototxt里的输入尺寸改掉而不改 caffemodel 对应的层加载必挂。yml 文件更隐蔽它只被部分代码路径读取默认例子跑起来没问题但如果你用自己的数据做归一化或关键点映射yml 缺失会导致输出坐标整体偏移。所以拿到这套模型文件合集之后建议不要只拷贝 caffemodel而是把整个模型目录按原结构放好。下表是 OpenPose 1.7.0 各模型的关键参数一览模型关键点数权重文件名适用硬件建议典型延迟GPUBODY_2525pose_iter_440000.caffemodel中高端 GPU约 20ms/帧COCO18pose_iter_440000.caffemodel中端 GPU约 15ms/帧MPI15pose_iter_160000.caffemodelCPU 或低端 GPU约 8ms/帧手部21×2pose_iter_102000.caffemodel需开启 --hand约 10ms/帧脸部70pose_iter_116000.caffemodel需开启 --face约 5ms/帧3. 目录结构与文件校验把 800MB 模型放对位置前先做的事3.1 官方目录结构按约定摆放模型目录省去 CMake 反复报错OpenPose 1.7.0 对模型目录是有固定预期的。默认情况下程序会在可执行文件所在目录的上级目录里找models文件夹CMake 配置阶段还会检查这个目录下是否存在对应模型不存在就触发联网下载。我收到这套模型文件合集后做的第一件事不是急着替换而是先在项目根目录下重建标准的models结构。下面是 BODY_25 和 COCO 的目录树示例和官方工程保持一致openpose/ ├── models/ │ ├── pose/ │ │ ├── body_25/ │ │ │ ├── pose_iter_440000.caffemodel │ │ │ ├── pose_deploy.prototxt │ │ │ ├── pose_deploy_linevec.prototxt │ │ │ ├── pose_deploy_mulvec.prototxt │ │ │ └── pose_iter_440000.yml │ │ ├── coco/ │ │ │ ├── pose_iter_440000.caffemodel │ │ │ └── pose_deploy.prototxt │ │ └── mpi/ │ │ ├── pose_iter_160000.caffemodel │ │ └── pose_deploy.prototxt │ ├── hand/ │ │ └── pose_iter_102000.caffemodel │ └── face/ │ └── pose_iter_116000.caffemodel按这个结构放置的原因有两个。第一OpenPose 在运行时会根据--model_pose拼接出模型文件的绝对路径比如--model_pose BODY_25就对应models/pose/body_25/这个目录第二--model_folder参数默认值是models/如果你把模型散落在别处每个命令都要额外指定这个参数批处理脚本里很容易漏掉。这个目录树看起来简单但实际上下载回来的模型文件经常被改名、被单独抽出来发导致目录结构对不上。我最开始在服务器上部署时图省事把 caffemodel 全部丢进一个平铺目录运行时光报错找不到pose_deploy.prototxt后来才意识到 prototxt 和 caffemodel 必须同在一个子目录里。3.2 文件校验用 sha256 和 prototxt 头检查三分钟排除坏文件模型文件体积加起来超过 800MB下载过程容易出问题最常见的是 0 字节文件、截断文件和文件名错乱。我一般不会用肉眼判断文件大小因为截断文件的大小可能看起来正常但加载到一半就报缓冲区错误。拿到这套模型文件后先在 Linux 服务器上做一轮快速校验看文件头和大小是否在合理范围。# 列出所有模型文件及大小重点观察疑似 0 字节或异常小的文件 find models -type f \( -name *.caffemodel -o -name *.prototxt -o -name *.yml \) -exec ls -lh {} \; # 用 sha256 做完整性校验官方未提供全网统一校验值时至少记录一份本地基准值 sha256sum models/pose/body_25/pose_iter_440000.caffemodel body25.sha256 # 检查 prototxt 文件有没有因为断点下载变成 0 字节 find models -name *.prototxt -size -1k -exec echo bad file: {} \;第一行命令的作用是快速扫描模型目录里所有文件的大小重点看有没有体积异常的文件。.caffemodel权重文件动辄几百 MB如果看到pose_iter_440000.caffemodel只有几百字节基本可以判断是下载失败了。第二行命令用 sha256 生成校验值虽然 OpenPose 官方没有统一公布每个模型的哈希值但本地保存一份基准值之后下次再拿到同套模型文件可以直接比对两台机器之间同步时也方便确认没有传输损坏。第三行命令针对 prototxt 这种小文件它们通常只有几十 KB如果小于 1KB 基本就是空文件或断点残留。做完这轮检查再跑一次模型加载测试是最稳妥的做法。我见过有人跳过校验直接把模型放进项目里然后编译 OpenPose 时报错花了两小时排查最后发现是 caffemodel 少了几个字节。如果你想更保险可以在校验之后顺手把所有文件的 md5 记录到一个文本文件里保存后续迁移服务器时直接用md5sum -c验证。4. 让 OpenPose 1.7.0 跑起来CMake 配置、模型路径与首个 demo4.1 编译选项与模型路径把模型目录告诉 OpenPose 的三种方式OpenPose 1.7.0 编译时CMake 会检查模型目录。如果你把模型文件已经放在了项目根目录下的models文件夹里CMake 会自动跳过下载步骤这是最省心的方式。但如果你的模型文件放在了别的位置或者你用的不是源码编译而是包管理器安装的版本就需要在运行阶段显式指定路径。这里有三种常见做法我按优先级排一下。第一种是编译前就把models目录放到 CMake 配置时的源码根目录下。CMake 检测到models/pose/body_25/pose_iter_440000.caffemodel存在就不会触发下载逻辑。注意 CMake 在configure阶段只会检查文件是否存在不会校验文件完好性所以第 3 章的文件校验要在编译前做。第二种是运行时指定--model_folder参数指向你的模型目录适合模型文件放在共享存储或多项目共用的情况。第三种是修改源码里的默认路径这在src/openpose/flags.cpp里能找到DEFINE_string(model_folder, models/, ...)改完后重新编译。这个方式我不推荐因为升级版本或换机器后容易忘了自己改过。从 1.7.0 的源码结构看模型路径逻辑在模型加载器里会拼接model_folder加上pose/body_25/这样的子路径所以无论你用什么方式指定根目录子目录结构必须保持官方约定。有一点需要特别提醒路径中不要带中文和空格。我见过有人把模型放在D:\我的模型\下面OpenPose 启动后加载模型时直接崩溃日志里没有任何有效报错换成纯英文路径就好了。这个问题在 Windows 上尤其明显Caffe 对窄字符路径处理得很脆弱。4.2 跑第一个 demo单张图、视频、网络摄像头的完整命令模型放好后用源码编译出的二进制文件直接跑样例即可。Windows 下可执行文件在build/x64/Release/openpose.exeLinux 下是build/examples/openpose/openpose.bin。我一般先跑单张图片因为定位问题最快。下面以 Linux 为例# 单张图片推理指定模型目录、模型类型和输入图片 ./build/examples/openpose/openpose.bin \ --model_folder ./models \ --model_pose BODY_25 \ --image_file ./examples/media/COCO_val2014_000000000192.jpg # 视频推理自动逐帧读取并实时显示结果 ./build/examples/openpose/openpose.bin \ --model_folder ./models \ --model_pose COCO \ --video ./examples/media/video.avi \ --net_resolution 656x368 \ --write_video ./output.avi # 网络摄像头实时推理开启手势和脸部检测 ./build/examples/openpose/openpose.bin \ --model_folder ./models \ --model_pose BODY_25 \ --hand \ --face \ --camera 0第一行命令是最简配置只给--model_folder和--model_pose其余参数走默认值。BODY_25 模型下默认输入分辨率是656x368如果图片太大程序会自动做缩放和内边距填充。第二行命令里--net_resolution参数需要解释一下它控制的是神经网络输入尺寸不是输出尺寸。改成656x368之后宽高比会强制拉伸如果你对关键点坐标精度有要求建议保持宽高比比如-1x368表示宽度按 368 高度等比缩放。第三行命令开了--hand和--face这意味着程序会先检测人体框再在每个人体框内裁出区域分别跑手部和脸部模型帧率会明显下降。运行之后默认会弹出一个 GUI 窗口显示带关键点叠加结果的图像。如果你在服务器上跑、没有显示器需要加--display 0关闭 GUI再用--write_images或--write_json保存结果。我的习惯是第一次跑单张图时加--display 0 --write_json output/这样既能在终端看到运行日志又能拿到 JSON 格式的关键点数据来验证坐标是否正确。5. 避坑与排查下载损坏、prototxt 不匹配、显存不足的五个实操记录5.1 现象caffemodel 加载失败报 Unable to load第一次从网上下载模型跑 OpenPose 时启动后日志显示Unable to load model程序直接退出连图像都不读。最开始怀疑是编译选项有问题反复重编了三次没用。原因caffemodel 文件在传输过程中损坏文件大小看起来正常但内部结构被破坏。Caffe 加载模型时对文件格式要求严格任何字节错位都会导致反序列化失败。有些下载工具开了多线程分段下载合并时出错也会造成同样问题。解决重新用单线程下载或直接换成已经校验好的完整模型文件合集。替换后重新跑单张图片测试注意观察日志里有没有Loading BODY_25 model这行之后紧跟成功标志。从那以后我每次拿到模型文件都会先执行第 3 章的 sha256 命令生成基准值并把校验结果保存在 release 目录下换机器部署时不踩第二次。5.2 现象BODY_25 出图但坐标全部错乱模型加载成功画面里也画出了骨架但关键点位置完全不对有的点飞到画面边缘有的点重叠在一起。原因模型文件和 prototxt 不匹配。我遇到过有人把 BODY_25 的 caffemodel 配上 COCO 的 prototxt或者反过来。两者关键点数量不同网络输出层的 channel 数对不上推理出的坐标自然失控。此外还有一种隐蔽情况同一版本的 caffemodel 配了不同迭代次数的 prototxt虽然能加载但结果语义错位。解决确认--model_pose参数对应的目录里caffemodel 和 prototxt 是同一套来源。打开 prototxt 看一眼关键的输出层名称BODY_25 的最后输出层通常包含concat_stage1或类似字段COCO 的关键点通道数是 18 的倍数BODY_25 是 25 的倍数。如果你用的这套模型文件合集目录结构完整一般不会出现这个问题但自己混搭过模型的人需要专门检查。5.3 现象手部/脸部模型不生效只跑出人体骨架加了--hand参数程序不报错但输出结果里没有手部关键点。原因手部模型和脸部模型是独立加载的OpenPose 只有检测到足够大的人体框才会触发手部区域裁剪。如果画面里人物太远裁出的手区域太小低于内部阈值就会被过滤掉。另一个常见原因是模型文件放错位置程序在models/hand/下找不到pose_iter_102000.caffemodel时不会报错而是直接跳过手部检测。解决先确认模型目录里有 hand 和 face 两个子目录且文件完整再拿一张人物靠近镜头的照片测试。如果画面里手部区域大于 100×100 像素仍检测不到检查日志中的User feedback内容一般会提示No hands found。OpenPose 的手部检测阈值没有简单参数可以调低最有效的方法就是确保模型文件在位同时把输入分辨率调大比如--net_resolution 656x368。5.4 现象Windows 下运行崩溃日志停在模型加载之后模型文件校验过没问题Linux 上跑得好好的拿到 Windows 上编译后运行就崩溃。原因最常见的元凶是路径包含中文、空格或特殊字符。OpenPose 在 Windows 下使用 Caffe 加载模型时对路径编码处理不完善带空格的路径在拼接时会导致文件句柄异常。另一个可能原因是显存不足Windows 图形桌面会占用一部分显存可用容量比 Linux 下小。解决把项目迁到无中文、无空格的纯英文路径比如C:\openpose。同时用nvidia-smi查看显存占用如果可用显存小于模型需求减少批处理数量不要一次喂入多张图片。网络分辨率也可以从656x368降到368x368来缓解显存压力。5.5 现象多人检测时帧率骤降GPU 利用率不到一半处理单人画面时帧率能到 20 FPS换成多人画面后帧率掉到 5 FPS 以下且 GPU 利用率没有跑满。原因OpenPose 的多人检测瓶颈在 PAF 解析阶段也就是对关键点候选进行组合匹配。这部分逻辑跑在 CPU 上GPU 推理完成得再快CPU 端解析不过来整体帧率就被拖住。模型文件本身没有问题这是 OpenPose 1.7.0 的架构特性。解决没有直接参数能把这个过程并行化常见的绕法有两个。一是用--number_people_max限制最大检测人数官方默认是无限制手动设成 4 或者 8 可以减轻解析压力。二是把小图输入分辨率调低比如--net_resolution 320x240GPU 推理和 PAF 解析的耗时都会下降适合不需要高精度关键点的计数类场景。6. 进阶用法模型加载验证脚本与批量处理时显存控制的三个技巧模型文件放好、demo 能跑通之后我建议你花十分钟做一个模型加载验证脚本把五套模型全部过一遍。这个脚本的价值在于以后任何一次升级系统、迁移服务器、更换模型文件先跑脚本确认所有模型都能正常加载再进入业务逻辑省掉大量无效排查时间。脚本不需要复杂逻辑一个简单的 bash 循环就能做到#!/bin/bash # 逐个测试五套模型是否可被 OpenPose 正常加载 MODELS(BODY_25 COCO MPI) for model in ${MODELS[]}; do echo Testing $model ... ./build/examples/openpose/openpose.bin \ --model_folder ./models \ --model_pose $model \ --image_file ./test.jpg \ --display 0 \ --write_json ./test_output_$model \ 21 | grep -E error|Error|failed|Failed || echo $model OK done--display 0关闭 GUI 窗口--write_json让每个模型都输出关键点文件脚本里用 grep 抓报错关键字只要没有 error、failed 字样就认为模型加载成功。这套验证方式有个细节它只检测模型能不能加载并完成一次前向推理不验证关键点精度所以 test.jpg 用一张有清晰人体轮廓的图就行不需要标准标注。脚本跑一遍大约一分钟比每次启动时报错再去翻日志快得多。批量处理视频时我额外会用到一个显存控制技巧。OpenPose 1.7.0 对每帧图像的显存占用是固定的批处理模式下默认一次处理一帧但如果视频分辨率太高显存占用依然可能爆掉。常见做法是不改--net_resolution而是先用 ffmpeg 把视频分辨率压到 1280×720 以下再送进 OpenPose。这比在 OpenPose 内部调参数更可控因为输入视频分辨率直接影响原始图像缓冲区大小压到 1280 宽以内可以让显存占用稳定在较低水位。最后记录一个踩过的教训我把模型文件单独放一个目录、用--model_folder指定路径后有一天路径前的环境变量被误改整个推理服务静默失败。从那以后我强制要求每次部署都把models目录放在项目根目录里、用相对路径并且跑一遍上面的验证脚本再交付。这套习惯帮我省下了大量线上排查时间。希望这些细节能帮到你尤其是刚把 OpenPose 1.7.0 编译出来、正卡在模型文件这一步的人。本文还有配套的精品资源点击获取