做前端或者做交互的朋友应该都遇到过这种需求：想在浏览器里直接捕捉人的动作，不装插件、不用高性能显卡，打开网页就能实时跟踪人体姿态。过去这几乎是不可想象的，但 MediaPipe 的 BlazePose 模型加上 TensorFlow.js 这套组合，确实把这条路给走通了，而且这次还能拿到 3D 坐标而不是简单的 2D 点。
这篇文章我想从自己的实践角度，把“MediaPipe BlazePose + GHUM + TensorFlow.js 做 3D 姿态检测”这条链路完整拆一遍。你会看到为什么选 BlazePose 而不是 OpenPose 或者 MoveNet，33 个关键点背后的 z 轴深度是怎么来的，以及如何在前端项目里真正把它跑起来。我尽量按实际踩坑的顺序来写，涉及代码的部分也会直接给出能跑的例子，适合那些想在 Web 端做姿态识别、动作打分、健身计数、体感交互的朋友参考。
1. 先搞清楚这套技术组合到底在做什么
1.1 三个关键词各是什么
先说 MediaPipe。它是 Google 开源的一套跨平台多媒体处理框架，内置了大量现成的 AI 解决方案，比如人脸检测、手势识别、人体分割、姿态检测等等。它的价值在于把模型和前后处理都打包好了，你不用自己写图像预处理、推理调度、关键点后处理这些脏活，调用封装好的 API 就能拿到结果。而且它不只是跑在服务器上，移动端、浏览器、嵌入式设备都有对应的方案。
然后是 BlazePose。它是 MediaPipe 里的一个人体姿态检测模型，特点是轻量且支持 3D 输出。传统姿态检测模型比如 OpenPose 走的是“先检测人体区域、再逐关节回归”的重型路线，在 CPU 上很难实时。BlazePose 则沿用了 BlazeFace 那种“先检测、再对齐”的两阶段思路：先用一个 detector 找到人体 bounding box，再在框内用 regressor 回归出 33 个关键点的坐标。模型做了高度精简，所以能在手机浏览器这种环境里也能保持实时帧率。
GHUM 是这组技术里容易被忽略但其实非常关键的一环。它是 Google 提出的一个可微分的参数化 3D 人体模型，简单理解就是一个“数字人”的骨架和形体模板，包含形状参数、姿态参数和表情参数。BlazePose 训练时不是直接在一个普通数据集上标注 3D 点，而是基于 GHUM 模型生成海量带有精确 3D 标注的训练样本，让神经网络学会从单张 2D 图像推测出人体在三维空间中的姿态。换句话说，GHUM 是 BlazePose 的“老师”，BlazePose 在推理时虽然不直接输出 GHUM 的模型参数，但它输出的 33 个关键点的 z 轴深度，本质上是通过 GHUM 的监督信号学到的“伪深度”，这也是这套方案能输出 3D 姿态的关键。
最后是 TensorFlow.js。它把 TensorFlow 模型搬到了 JavaScript 环境，让模型推理直接在浏览器里完成，不需要把视频帧传到服务器，既省了带宽也保护了用户隐私。MediaPipe 官方在 Web 端的解决方案底层也支持 TF.js 的 runtime，同时提供了一系列高层的 JavaScript API，开发体验会比直接裸用 TF.js 好很多。
1.2 这套方案的独特价值
拿 MoveNet 对比就明白了。MoveNet 是 TF.js 官方主推的姿态检测模型，但输出的是 17 个 2D 关键点，只有 x、y 坐标。BlazePose 输出的是 33 个关键点，每个点除了 x、y，还带一个 z 坐标。z 坐标表示的深度信息可以让很多应用上一个台阶：比如健身动作的幅度判断、人机交互中的手势方向、虚拟形象驱动，甚至是简单的动作三维回放。虽然这个 z 不是真实尺度上的绝对深度，但在同一帧内各个关节的相对深度关系是合理的，这就足够支撑很多应用了。
而且 BlazePose 的模型尺寸和计算量都控制得不错。Lite 版本只有几 MB，在 CPU 上也能跑出 30 FPS 上下，叠加上 WebGL 或者 WebGPU 加速后效果更好。这意味着你不一定需要一台高配电脑，普通笔记本、中端手机浏览器都能玩起来。
这套组合里还有一个值得说的点是数据和隐私。因为整个推理过程都在浏览器本地完成，视频帧不会离开用户的设备，这在做远程康复、在线健身这类产品时是一个非常大的卖点，省掉了大量的合规成本。
2. 搭建开发环境与基础工程结构
2.1 传统浏览器项目也能快速接入
我一开始以为要在 React 或 Vue 这种工程化项目里才能用好 MediaPipe，后来发现其实一个普通的 HTML 页面就够了。MediaPipe 官方提供了 CDN 引入的方式，把 JavaScript 包和 WASM 文件加载进来，就能直接调用里面的 API。这意味着你不用配 webpack、不用装 Node.js 环境，一个静态文件服务器就能跑起来。对快速原型验证来说，这种方式非常舒服。
如果你是在一个已有的现代前端项目里集成，那也不冲突。官方 npm 包是 @mediapipe/tasks-vision，你可以直接用 npm 安装，然后在代码里 import。这两种方式本质上对应的是同一套底层能力，只是入口不同。
2.2 两种依赖加载方式对比
我建议先走 CDN 方式做验证，原因有两条：
- 省去构建配置的麻烦，模型加载的逻辑也更透明，报错容易排查。
- MediaPipe 的 WASM 文件和模型文件体积不小，如果项目本身没有做静态资源托管方案的规划，一上来就引入 npm 包容易把构建产物撑大。
等确认了功能流程可行，再迁移到工程化项目里也不迟。迁移时主要注意两点：一是 WASM 文件路径需要正确配置，二是模型文件建议下载到本地而不是直接依赖远程 URL，否则 CDN 出了问题你的功能就跟着挂了。
2.3 一个能跑起来的基础 HTML 结构
先放一个最基础的页面骨架，包含视频元素、画布元素和一个状态展示区域，后面我们要用的核心能力都是在这个骨架上叠加的。
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>MediaPipe BlazePose 3D 姿态检测</title> <style> body { margin: 0; background: #1a1a2e; color: #eee; font-family: system-ui, sans-serif; } #container { position: relative; max-width: 720px; margin: 0 auto; } video { width: 100%; display: block; transform: scaleX(-1); } canvas { position: absolute; top: 0; left: 0; width: 100%; height: 100%; transform: scaleX(-1); } #status { padding: 12px; text-align: center; background: rgba(0,0,0,0.5); font-size: 14px; } </style> </head> <body> <div id="container"> <video id="video" autoplay playsinline></video> <canvas id="canvas"></canvas> </div> <div id="status">正在初始化...</div> <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.3/vision_bundle.js"></script> <script src="app.js"></script> </body> </html>这里有几个细节想提醒你：
transform: scaleX(-1)是为了做镜像显示，跟照镜子的感觉一致，避免用户抬手时方向错乱。但这个镜像只是 CSS 层面的，canvas 的绘制逻辑也要对应做镜像处理，否则会出现画布定位不对的问题。playsinline属性在移动端必须加，否则 iOS Safari 会强制全屏播放视频。@mediapipe/tasks-vision的版本号建议锁定一个固定版本，不要用latest，否则将来 API 一变你的代码可能就无声无息地坏了。
3. 核心代码实现：从摄像头到 3D 关键点
3.1 初始化 PoseLandmarker 实例
MediaPipe Tasks Vision 里负责姿态检测的类是PoseLandmarker。初始化时需要一个FilesetResolver来加载 WASM 和基础资源，然后通过createFromOptions创建检测器实例。
const vision = await FilesetResolver.forVisionTasks( "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.3/wasm" ); const poseLandmarker = await PoseLandmarker.createFromOptions(vision, { baseOptions: { modelAssetPath: "https://storage.googleapis.com/mediapipe-models/pose_landmarker/pose_landmarker_lite/float16/1/pose_landmarker_lite.task", delegate: "GPU" }, runningMode: "VIDEO", numPoses: 1, minPoseDetectionConfidence: 0.5, minPosePresenceConfidence: 0.5, minTrackingConfidence: 0.5 });模型文件这里用的是官方托管在 Google 存储桶上的 Lite 版本。还有另外两个版本：Full 和 Heavy，前者精度更高但速度更慢，适合 PC 端；后者精度最高，主要给离线高精度场景用。我在实际项目中一般默认选 Lite，然后根据用户的设备性能再动态切换。
delegate: "GPU"表示优先用 WebGL 做推理加速，如果浏览器不支持，会自动回退到 CPU。你可以在代码里先检测一下navigator.gpu或者 WebGL 的支持情况，再决定是否强制指定 GPU 代理。
numPoses默认是 1，如果设成 2 以上就可以同时追踪多人，但对性能的消耗是线性增长的。除非业务确实需要多人同时检测，否则保持 1 就够了。多人追踪的稳定性也比单人差不少，容易出现 ID 互换的问题。
3.2 启动摄像头并进入检测循环
摄像头部分用getUserMedia获取视频流，然后通过requestVideoFrameCallback来做帧同步的循环检测。这个方法比传统的setInterval好用的地方在于它是和视频帧率同步的，不会出现掉帧或重复处理同一帧的情况。
const video = document.getElementById("video"); const canvas = document.getElementById("canvas"); const ctx = canvas.getContext("2d"); async function startCamera() { const stream = await navigator.mediaDevices.getUserMedia({ video: { width: 640, height: 480, facingMode: "user" } }); video.srcObject = stream; await video.play(); canvas.width = video.videoWidth; canvas.height = video.videoHeight; requestVideoFrameCallback(loop); } function loop(timestamp) { if (poseLandmarker && video.readyState >= 2) { const results = poseLandmarker.detectForVideo(video, timestamp); drawResults(results); } requestVideoFrameCallback(loop); } startCamera();detectForVideo第二个参数传的是performance.now()的时间戳，在requestVideoFrameCallback里直接拿到的回调参数就是这个时间，可以直接透传。如果你同时在页面上跑了多个检测器，注意每个检测器的时间戳要是递增的，否则 MediaPipe 内部会认为你传入了乱序帧，直接抛异常。
video.readyState >= 2这个判断很重要，防止视频还没准备好就开始检测，导致拿到的是黑帧或空帧。
3.3 33 个关键点的含义与 3D 可视化思路
拿到结果后，results.landmarks是一个数组，每个元素代表一个人，里面有 33 个关键点。每个关键点有x、y、z和visibility四个属性。
x、y是归一化到 [0, 1] 的图像坐标，分别对应宽度和高度的比例。z是以臀部中心点为原点的相对深度坐标，数值越大代表离相机越远。因为不同人的身高体型不同，z值不具备跨人的可比性。visibility表示这个点被遮挡的概率，越接近 1 表示模型对这个点的位置越确信。在自拍场景下，当一个人侧身时，被挡住的那只手的关键点 visibility 会明显下降，这时如果你在做动作分析，就要考虑是否信任这个坐标。
33 个关键点的编号和对应关系大致是：0 是鼻子，1-4 是眼睛和耳朵，5-8 是脸部轮廓点，9-10 是嘴巴区域，11-12 是肩膀，13-14 是手肘，15-16 是手腕，17-18 是髋部，19-20 是膝盖，21-22 是脚踝，23-24 是脚后跟，25-26 是脚趾，27-28 是髋部中心，29-32 是额外的手指/脚趾点。
const POSE_CONNECTIONS = [ [0, 1], [1, 2], [2, 3], [3, 4], [0, 5], [5, 6], [6, 7], [7, 8], [5, 9], [9, 10], [10, 11], [11, 12], [12, 13], [13, 14], [14, 15], [0, 16], [16, 17], [17, 18], [18, 19], [19, 20], [20, 21], [16, 22], [22, 23], [23, 24], [24, 25], [25, 26], [11, 27], [27, 28], [28, 29], [11, 30], [29, 30], [30, 31], [31, 32] ];在 canvas 上绘制时，可以把x、y乘以画布的宽高得到像素坐标，然后用beginPath、moveTo、lineTo把对应的关键点连起来。
3D 可视化的部分，推荐在拿到关键点后直接用 Three.js 渲染。你可以创建一个三维坐标轴空间，把x、y映射到水平面和垂直面，z映射到纵深方向，再用THREE.BufferGeometry把关节点的连线构成一个线框骨骼。要注意的是归一化坐标和 Three.js 世界坐标之间需要做一个缩放系数，否则整个人体会小得看不清。
function drawResults(results) { ctx.clearRect(0, 0, canvas.width, canvas.height); const landmarks = results.landmarks[0]; if (!landmarks) return; ctx.save(); ctx.scale(-1, 1); ctx.translate(-canvas.width, 0); // 绘制连线 ctx.strokeStyle = "#00e5ff"; ctx.lineWidth = 2; POSE_CONNECTIONS.forEach(([a, b]) => { const pa = landmarks[a]; const pb = landmarks[b]; if (pa.visibility > 0.3 && pb.visibility > 0.3) { ctx.beginPath(); ctx.moveTo(pa.x * canvas.width, pa.y * canvas.height); ctx.lineTo(pb.x * canvas.width, pb.y * canvas.height); ctx.stroke(); } }); // 绘制关节点 landmarks.forEach((p) => { if (p.visibility > 0.3) { ctx.beginPath(); ctx.arc(p.x * canvas.width, p.y * canvas.height, 3, 0, Math.PI * 2); ctx.fillStyle = "#ffcc00"; ctx.fill(); } }); ctx.restore(); }你注意我在绘制前先做了镜像变换，这样 CSS 和 canvas 的方向一致，视觉上不会出现左右错位。visibility过滤条件的作用是避免画出那些模型都不确定的位置，不然会出现一些很奇怪的飘浮线段。
4. 关键参数调优与性能优化
4.1 模型选型：Lite vs Full vs Heavy
MediaPipe 官方提供了三个版本的.task模型文件，它们在精度、速度和体积上各有取舍：
| 模型版本 | 体积（约） | 适合设备 | 适用场景 |
|---|---|---|---|
| pose_landmarker_lite | 5.5 MB | 移动端 CPU | 实时预览、低功耗场景 |
| pose_landmarker_full | 9.6 MB | PC 端 GPU | 精度和速度均衡 |
| pose_landmarker_heavy | 13.3 MB | PC 端性能强 | 离线高精度分析 |
我在实际项目里的经验是：如果只是做实时互动类的应用，比如动作游戏、摄像头滤镜，Lite 完全够用；如果是做动作评分、康复训练记录，Full 精度会好一些，特别是手肘、膝盖这些容易混淆的关键点。Heavy 在浏览器端性价比不高，推理耗时明显增加，但精度提升有限。
还有个折中方案：在页面加载时先检测设备，如果是手机访问就加载 Lite，PC 再加载 Full。这个判断可以基于navigator.userAgent里是否有Mobile字段，简单但有效。
4.2 置信度阈值怎么调
minPoseDetectionConfidence控制人体检测阶段的最低置信度，低于这个值就认为画面里没有人。minPosePresenceConfidence控制关键点跟踪阶段人物存在的最低置信度。minTrackingConfidence控制关键点跟踪的质量。
这三个阈值同时作用，调低任何一个都可能导致误检，调高了又会漏检。我的建议是先从 0.5 起步，然后在你的目标场景下滑动调整。关键是看两个极端场景：一个人完全面对镜头时不能丢检测；一个人快速转身时不能出现混乱的关键点跳跃。
实际项目中如果在做动作教学类应用，我会把阈值设高一点（0.6-0.7），因为误检比漏检更影响体验，毕竟用户手里的动作不对还可以提醒，模型识别出来的动作完全错了就很尴尬。
4.3 前端性能优化的几个实招
第一个建议是降低输入分辨率。getUserMedia不一定要请求 1080p，640x480 在绝大多数情况下姿态检测的效果和 1080p 没有肉眼可见的差别。分辨率越高，后续的缩放和纹理上传耗时就越长，对整体 FPS 影响很大。
第二个建议是并行不要贪多。如果你同时跑姿态检测、人脸检测、手势识别，每增加一个模型，PoseLandmarker 的帧率都会明显下降。MediaPipe 底层虽然是共享 WASM 资源，但每个模型的推理计算是独立的，不能靠多线程缓存省掉。
第三个建议是用requestVideoFrameCallback而不是requestAnimationFrame。前者的回调频率和视频的真实出帧频率绑定，不会做无意义的重复计算。如果你的摄像头只有 30 FPS，requestAnimationFrame在 60Hz 显示器上会每秒触发 60 次，有 30 次是重复计算。
第四个建议是把清理工作放到 Web Worker 里。MediaPipe 的推理本身是异步的，不会阻塞 UI 线程，但如果你在拿到结果后马上做大量的 canvas 绘制、骨骼数据处理，还是可能让 UI 卡顿。把结果数据扔给 Worker 做计算，主线程只负责绘图，是一个性价比很高的优化方案。
5. 高频问题的排查经验
5.1 z 轴深度到底准不准
这是被问得最多的问题。BlazePose 输出的 z 值不是真实物理距离，它的单位不是米，而是归一化到了以髋部中心为原点的相对空间。同一帧里，左手在身体前面 20 厘米，右手在身后 20 厘米，z 值的差异能体现出来，但你没法从 z 值直接反推出真实的厘米数。
所以如果你要做“测量两个关节之间的真实距离”这类功能，不能直接用 z 值。替代方案是用图像中已知尺寸的参照物做单目测距，或者结合深度摄像头（比如 RealSense）把 MediaPipe 的关键点映射到深度图上去取深度值。这些方案在工程上复杂度会高一截，但原理并不复杂。
5.2 GPU 加速失效
我在一些老的安卓 WebView 里遇到过delegate: "GPU"导致初始化失败的情况。表现是createFromOptions抛异常，或者初始化后检测结果全为空。排查思路是先去掉delegate字段，让 MediaPipe 自动选择计算后端。如果在 CPU 模式下一切正常，那基本可以确定是 GPU 路径的问题。
原因通常是 WebGL 上下文创建失败，或者设备支持的是 WebGL 1 而 MediaPipe 某些算子需要 WebGL 2。你可以用document.createElement('canvas').getContext('webgl2')先做个环境检测，不支持时就明确切换到 CPU 模式，而不是让用户在数据崩溃和空白页面之间二选一。
5.3 WASM 文件加载失败
FilesetResolver.forVisionTasks加载的是一个.wasm文件集合，如果 CDN 不稳或者浏览器缓存策略有问题，会出现TypeError: Failed to fetch dynamically imported module这类报错。解决方案：把wasm目录下载到本地，路径改成相对路径。这样部署之后不依赖外部网络，离线环境下也能用。
模型文件也是同理。modelAssetPath如果指向远程 URL，首次加载会比较慢，而且有时会因为跨域限制被浏览器拦截。建议在后端存一份模型文件，前端通过同域 URL 加载，这样还能配合 Service Worker 做缓存，二次访问几乎无感加载。
5.4 多人追踪时关键点“串人”
设置numPoses: 2或更高后，偶尔会出现两个人的手臂关键点互相交叉、跳变的情况。这本质上是 tracking 阶段对帧与帧之间人的关联判断错误。目前 MediaPipe 的可配置项里没有直接的满意度开关，我能给的建议是：
- 尽量保持画面中两个人不要有太多身体重叠；
- 控制追踪人数，不要超过 3 人；
- 如果只是单人应用，严格保持
numPoses: 1，避免无谓的成本和串扰。
6. 扩展玩法：结合 MediaPipe Model Maker 做自定义动作识别
6.1 为什么还要自己训练分类器
BlazePose 本身只输出关键点坐标，它不知道你是在做深蹲、举铁还是瑜伽。要想实现“识别出用户在做哪个动作”，一个简单可靠的做法是：先用 BlazePose 提取 33 个关键点的坐标，再把坐标当作特征输入到一个分类模型里，让模型学会区分不同动作。
MediaPipe Model Maker 正好提供了这样一个工具链。它内置了一个姿态分类器的训练流程，输入是一批不同动作的关键点数据，输出是一个自定义的.task文件。这个文件可以直接交给 PoseLandmarker 加载，在拿到关键点的同时输出动作分类结果。
6.2 数据准备与训练脚本
训练需要 Python 环境，核心步骤是装mediapipe-model-maker这个库，然后组织好训练数据。数据目录结构是每个动作一个子文件夹，里面放对应动作的图片或者视频，然后写一个简单的训练脚本：
import mediapipe_model_maker as mpmm data = mpmm.ExternalFiles("path/to/dataset") model = mpmm.PoseClassifierOptions( data=data, model_path="pose_classifier.task" ) model.train() model.export("pose_classifier.task")训练过程并不复杂，但数据质量直接决定模型效果。每个动作最好收集 200 段以上不同人、不同角度、不同距离的样本。如果数据都是同一个人拍的，模型会“记住”这个人，换个人就失灵。
6.3 在浏览器中加载自定义分类器
训练好的.task文件可以和原来的姿态检测模型合并使用。在PoseLandmarker.createFromOptions里，把modelAssetPath指向自定义分类器文件即可。MediaPipe 会先跑 BlazePose 得到关键点，再跑你已经训练好的分类器得到动作标签和置信度。
这样做的好处非常明显：你不需要自己处理关键点的归一化、分类器的输入输出格式，MediaPipe 已经把它们封装好了。如果你想把整套流程做大，还可以在拿到关键点后，自己用 TensorFlow.js 再叠一个 LSTM 模型，对连续帧的动作序列做时序建模，从而判断动作的完成质量，这就是另一个进阶话题了。
结尾
跑了几轮之后我最大的感受是：MediaPipe BlazePose 这套方案真正把“3D 姿态检测”从学术 demo 拉到了可落地的产品层面。它对硬件的要求比想象中低很多，一台普通笔记本的浏览器就能跑出平滑的骨骼动画，而且 z 轴深度信息确实能让动作判断的维度丰富很多。如果你要在 Web 端做任何跟人体动作相关的功能，这套组合绝对值得花一个下午跑通。它就像一个打磨得很顺手的工具箱，框架替你挡住了绝大多数底层复杂度，你只需要专注在上层业务逻辑上。不过也别把所有依赖都寄托在官方 CDN 上，模型文件、WASM 资源该自托管就自托管，这是产品化之后必须做的功课。
