学霸同款9个AI论文写作软件，MBA论文轻松搞定！
2026/1/13 17:43:11
MediaPipe Pose部署教程：Windows/Linux双平台适配说明
1. 引言
1.1 学习目标
本文将带你从零开始部署基于 Google MediaPipe 的人体骨骼关键点检测系统，支持 Windows 与 Linux 双平台运行。通过本教程，你将掌握：
- 如何在本地环境快速搭建 MediaPipe Pose 推理服务
- WebUI 的配置与访问方式
- 跨平台兼容性处理的关键技巧
- 实际图像输入的处理流程与结果可视化方法
最终实现一个无需联网、不依赖外部 API、纯 CPU 运行、毫秒级响应的人体姿态估计系统。
1.2 前置知识
为顺利跟随本教程，请确保具备以下基础：
- 基础 Python 编程能力（熟悉
pip安装） - 熟悉命令行操作（CMD / Terminal）
- 了解基本的 HTTP 概念（如端口、URL 访问）
无需深度学习背景或 GPU 环境，本方案专为轻量级 CPU 部署设计。
1.3 教程价值
与市面上多数依赖 ModelScope 或云 API 的“伪本地”方案不同，本文提供的部署方式：
- ✅完全离线运行：模型已内嵌于 MediaPipe 包中，启动即用
- ✅跨平台通用：Windows 10+/Linux 均可一键部署
- ✅免编译安装：所有依赖可通过 pip 直接安装
- ✅自带 WebUI：无需前端开发经验即可使用图形界面上传图片并查看结果
适合用于健身动作识别、舞蹈教学分析、人机交互原型开发等场景。
2. 环境准备
2.1 系统要求
| 平台 | 操作系统 | Python 版本 | 最低配置 |
|---|---|---|---|
| Windows | Windows 10 / 11 (64位) | 3.8 - 3.11 | 4GB RAM, i5 处理器 |
| Linux | Ubuntu 20.04+ / CentOS 7+ | 3.8 - 3.11 | 4GB RAM, x86_64 架构 |
⚠️ 注意：不支持 Python 3.12 及以上版本（MediaPipe 尚未完全兼容）。
2.2 安装 Python 与 pip
Windows 用户
前往 https://www.python.org/downloads/ 下载 Python 3.11.x 安装包，勾选"Add Python to PATH"后完成安装。
验证安装：
python --version pip --versionLinux 用户（以 Ubuntu 为例）
sudo apt update sudo apt install python3 python3-pip -y创建软链接（可选）：
sudo ln -s /usr/bin/python3 /usr/local/bin/python sudo ln -s /usr/bin/pip3 /usr/local/bin/pip验证：
python --version pip --version2.3 创建虚拟环境（推荐）
避免污染全局包环境，建议使用venv创建隔离环境：
python -m venv mediapipe_pose_env source mediapipe_pose_env/bin/activate # Linux # 或 mediapipe_pose_env\Scripts\activate # Windows激活后提示符前应出现(mediapipe_pose_env)标识。
3. 核心模块解析与部署实践
3.1 技术栈概览
本项目基于以下核心技术构建：
- MediaPipe Pose：Google 开源的姿态估计框架，提供 BlazePose 模型
- Flask：轻量级 Web 框架，用于构建图像上传接口
- OpenCV：图像处理库，负责读取、绘制和编码图像
- Jinja2：模板引擎，渲染 HTML 页面展示结果
整体架构如下：
[用户浏览器] ↓ (HTTP POST) [Flask Web Server] ↓ (调用模型) [MediaPipe Pose Inference] ↓ (返回33个关键点) [OpenCV 绘制骨架] ↓ (编码为 JPEG) [返回带骨骼图的图像]3.2 安装核心依赖
执行以下命令安装所需库：
pip install mediapipe opencv-python flask numpy pillow✅ 所有包均支持 CPU 推理，无需 CUDA 或 GPU 驱动。
验证 MediaPipe 是否正常工作：
import mediapipe as mp print(mp.__version__)输出类似0.10.9即表示安装成功。
3.3 实现 WebUI 服务
创建项目目录结构：
mediapipe_pose/ ├── app.py ├── templates/ │ └── index.html ├── static/ │ └── style.css └── uploads/1. 编写 Flask 主程序 (app.py)
# app.py import os from flask import Flask, request, render_template, send_from_directory import cv2 import numpy as np import mediapipe as mp app = Flask(__name__) UPLOAD_FOLDER = 'uploads' os.makedirs(UPLOAD_FOLDER, exist_ok=True) app.config['UPLOAD_FOLDER'] = UPLOAD_FOLDER mp_pose = mp.solutions.pose mp_drawing = mp.solutions.drawing_utils pose = mp_pose.Pose(static_image_mode=True, model_complexity=1) @app.route('/', methods=['GET', 'POST']) def index(): if request.method == 'POST': file = request.files.get('image') if not file: return '请上传一张图片', 400 # 读取图像 img_stream = np.frombuffer(file.read(), np.uint8) image = cv2.imdecode(img_stream, cv2.IMREAD_COLOR) # 转换为 RGB rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results = pose.process(rgb_image) # 绘制骨架 annotated_image = image.copy() if results.pose_landmarks: mp_drawing.draw_landmarks( annotated_image, results.pose_landmarks, mp_pose.POSE_CONNECTIONS, landmark_drawing_spec=mp_drawing.DrawingSpec(color=(0, 0, 255), thickness=2, circle_radius=3), # 红点 connection_drawing_spec=mp_drawing.DrawingSpec(color=(255, 255, 255), thickness=2) # 白线 ) # 保存结果 output_path = os.path.join(app.config['UPLOAD_FOLDER'], 'result.jpg') cv2.imwrite(output_path, annotated_image) return send_from_directory(os.getcwd(), 'uploads/result.jpg', mimetype='image/jpeg') return render_template('index.html') if __name__ == '__main__': app.run(host='0.0.0.0', port=5000, debug=False)2. 创建前端页面 (templates/index.html)
<!-- templates/index.html --> <!DOCTYPE html> <html> <head> <title>MediaPipe 姿态检测</title> <style> body { font-family: Arial; text-align: center; margin: 40px; } .upload-box { border: 2px dashed #ccc; padding: 20px; margin: 20px auto; width: 400px; } img { max-width: 100%; margin: 10px 0; } </style> </head> <body> <h1>🤸♂️ AI 人体骨骼关键点检测</h1> <div class="upload-box"> <form method="POST" enctype="multipart/form-data"> <input type="file" name="image" accept="image/*" required><br><br> <button type="submit">上传并分析</button> </form> </div> {% if result %} <h3>检测结果：</h3> <img src="{{ result }}" alt="Skeleton"> {% endif %} </body> </html>3.4 启动服务
在项目根目录运行：
python app.py服务将在http://localhost:5000启动。
点击平台提供的 HTTP 按钮（如 CSDN 星图镜像环境），即可打开 WebUI。
4. 使用说明与结果解析
4.1 操作步骤详解
- 启动服务后，浏览器自动跳转至 WebUI 页面；
- 点击“选择文件”，上传一张包含人物的 JPG/PNG 图像；
- 点击“上传并分析”，等待 1~2 秒；
- 页面将返回一张新图像，显示：
- 红点：33 个关键点位置（如肩、肘、膝、踝等）
- 白线：骨骼连接关系（依据人体解剖结构）
4.2 关键点说明（共 33 个）
| 区域 | 包含关键点示例 |
|---|---|
| 面部 | 左右眼、鼻尖、嘴 |
| 上肢 | 肩、肘、腕、手部关键点 |
| 躯干 | 髋、脊柱、胸骨 |
| 下肢 | 膝、踝、脚跟、脚尖 |
完整列表参考：MediaPipe 官方文档 - Pose Landmarks
4.3 输出图像格式
- 保存路径：
uploads/result.jpg - 格式：JPEG，与原图分辨率一致
- 可直接下载或集成到其他系统中进行后续分析（如角度计算、动作分类）
5. 跨平台适配要点
5.1 Windows 与 Linux 兼容性处理
虽然代码本身是跨平台的，但在实际部署中需注意以下差异：
| 问题点 | Windows 解决方案 | Linux 解决方案 |
|---|---|---|
| 路径分隔符 | 使用os.path.join()自动适配 | 同左 |
| 权限问题 | 无特殊限制 | 确保uploads/目录可写：chmod -R 755 uploads |
| OpenCV GUI 问题 | 若报错cv2.imshow()，改用matplotlib | 服务器环境通常禁用 GUI，仅做图像保存 |
| 端口占用 | 检查防火墙设置 | 使用netstat -tuln \| grep 5000查看占用 |
5.2 Docker 化建议（可选进阶）
若需进一步提升稳定性与可移植性，可封装为 Docker 镜像：
# Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 5000 CMD ["python", "app.py"]构建并运行：
docker build -t mediapipe-pose . docker run -p 5000:5000 -v ./uploads:/app/uploads mediapipe-pose6. 总结
6.1 核心收获回顾
通过本文，我们完成了：
- ✅ 在 Windows 与 Linux 平台上成功部署 MediaPipe Pose 服务
- ✅ 实现了基于 Flask 的 WebUI 图像上传与结果展示
- ✅ 掌握了 33 个关键点的检测与可视化绘制方法
- ✅ 理解了跨平台部署中的常见问题及解决方案
该系统具备高精度、低延迟、零依赖、易扩展四大优势，非常适合教育、健身、安防等领域的小型化 AI 应用开发。
6.2 下一步学习建议
- 📌进阶方向 1：结合
angle calculation实现健身动作标准度评分 - 📌进阶方向 2：接入摄像头实现实时视频流姿态追踪
- 📌进阶方向 3：导出关键点坐标为 JSON 或 CSV，用于数据分析
💡获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。