4、环境搭建与工具准备：Python、PyTorch/TensorFlow、OpenCV、MediaPipe等安装与配置

运动姿态评估模型的开发，本质上是一条从“图像采集”到“关键点提取”再到“动作逻辑判断”的工程链路。在动手编写任何一行算法代码之前，必须先构建一个稳定、版本可控、可复现的软件环境。本章将围绕Python环境管理、深度学习框架选型与安装、OpenCV图像处理库配置、MediaPipe姿态估计库部署，以及GPU加速与常见排障展开，帮助你搭建一套能够支撑后续30章实战内容的完整开发环境。

4.1 核心原理：为什么环境搭建是姿态评估项目的“地基”

运动姿态评估模型并非单一算法，而是由多个开源库协同工作的系统工程。Python负责业务逻辑编排，PyTorch/TensorFlow提供神经网络训练与推理能力，OpenCV处理视频流与图像预处理，MediaPipe则负责从单目摄像头画面中实时提取人体33个关键点的三维坐标。这四个组件各自独立演进，版本兼容性问题非常突出。例如，MediaPipe 0.10.x版本要求Python 3.8-3.11，而PyTorch 2.1以上版本对CUDA 11.8或12.1有硬性要求。如果直接使用系统全局Python环境，极易出现“装A库时破坏了B库依赖”的恶性循环。

因此，环境搭建的核心原则是隔离与锁定。通过虚拟环境（如Anaconda或Python venv）为每个项目创建独立的依赖空间，再通过requirements.txt或environment.yml文件精确记录每个库的版本号，确保团队协作或服务器部署时能复现完全一致的运行环境。对于运动姿态评估项目，还需要特别关注推理性能：MediaPipe的CPU推理在普通笔记本上可达到30FPS，但若同时运行PyTorch模型进行动作分类，CPU资源将严重不足，此时必须考虑GPU加速或模型轻量化。

4.2 操作流程：从零搭建完整开发环境

下面以Windows 11 + NVIDIA GPU（可选）为例，给出标准安装流程。若使用macOS或Linux，命令略有差异，但核心逻辑一致。

步骤一：安装Python与虚拟环境

# 推荐使用Anaconda（自带Python和包管理）
# 下载地址：https://www.anaconda.com/products/individual
# 安装完成后，打开Anaconda Prompt，创建独立虚拟环境
conda create -n pose_env python=3.9 -y
conda activate pose_env

# 若使用原生Python，可执行：
# python -m venv pose_env
# pose_env\Scripts\activate  (Windows)
# source pose_env/bin/activate  (Linux/macOS)

选择Python 3.9而非最新版，是因为MediaPipe和部分旧版PyTorch对3.10以上版本支持不完善。创建虚拟环境后，所有后续安装均在该环境内进行，不会污染系统Python。

步骤二：安装深度学习框架

# 方式一：CPU版本（适合无GPU或仅做算法验证）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# 方式二：GPU版本（需先安装NVIDIA驱动和CUDA）
# 先检查显卡驱动支持的最高CUDA版本：nvidia-smi
# 以CUDA 11.8为例：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 验证安装
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

TensorFlow作为备选方案，安装命令为pip install tensorflow。但本课程后续实战以PyTorch为主，因为其动态图机制更适合姿态序列的灵活建模。若需同时安装TensorFlow，建议在另一个虚拟环境中操作，避免protobuf版本冲突。

步骤三：安装OpenCV与MediaPipe

# OpenCV：图像处理核心库
pip install opencv-python opencv-contrib-python

# MediaPipe：姿态关键点提取
pip install mediapipe

# 验证MediaPipe是否正常工作
python -c "import mediapipe as mp; print(mp.__version__)"

MediaPipe安装后会自动下载部分模型文件（约5MB），首次运行时会加载到内存。若网络受限，可手动下载pose_landmark_lite.tflite等模型文件并放置到指定缓存目录。

步骤四：安装辅助工具

# Jupyter Notebook（交互式调试）
pip install jupyter notebook

# 数据处理与可视化
pip install numpy pandas matplotlib scikit-learn

# 导出环境配置（便于复现）
pip freeze > requirements.txt
# 或使用conda导出
conda env export > environment.yml

4.3 案例拆解：一次真实的“环境地狱”排障过程

某健身APP开发团队在搭建姿态评估服务时，遇到了一个典型问题：开发机（Windows + RTX 3060）上代码运行正常，但部署到测试服务器（Ubuntu + 无GPU）后，MediaPipe报错RuntimeError: Failed to parse the model。经过排查，发现原因如下：

解决过程分为三步：首先，在服务器上创建Python 3.9虚拟环境；其次，将requirements.txt中的MediaPipe版本锁定为0.10.3；最后，重新安装OpenCV 4.8.1。整个排障耗时2小时，根本原因在于未使用虚拟环境锁定版本。这个案例说明，环境搭建不是“一次性工作”，而是需要纳入版本管理的持续过程。

4.4 常见误区与总结复盘

import sys, torch, cv2, mediapipe
assert sys.version_info >= (3, 9), "Python版本过低"
assert torch.__version__.startswith("2."), "PyTorch版本异常"
print(f"环境就绪：Python {sys.version.split()[0]}, PyTorch {torch.__version__}, OpenCV {cv2.__version__}, MediaPipe {mediapipe.__version__}")