解决MediaPipe在Python 3.12上的兼容性问题：从依赖冲突到平滑运行

Python 3.12的性能提升和新特性吸引众多开发者升级，但MediaPipe项目在该版本下常出现依赖解析失败、模块导入错误等问题。本文将系统分析兼容性障碍，提供可落地的解决方案，并配套完整测试流程，帮助开发者快速适配Python 3.12环境。

兼容性问题诊断

核心依赖冲突表现

MediaPipe的Python 3.12专用依赖文件requirements_lock_3_12.txt显示，NumPy 1.26.4与Protobuf 4.25.5存在版本绑定关系。当使用pip install mediapipe时，若环境中已存在更高版本的这些库，会触发以下错误：

ERROR: Cannot install mediapipe because these package versions have conflicting dependencies.

关键冲突库及其兼容范围：

依赖库	兼容版本	冲突版本
NumPy	1.26.x	≥1.27.0
Protobuf	4.25.x	≥4.26.0
OpenCV	4.10.0.84	其他次要版本

框架层兼容性验证

通过对mediapipe/python目录的源码扫描，未发现直接针对Python 3.12的条件判断或异常捕获代码。这表明当前版本未对3.12的语法变化（如typing模块重构）做适配。典型问题场景包括：

• from typing import Collection 在3.12中需改为 from collections.abc import Collection
• distutils模块移除导致的ModuleNotFoundError

分步解决方案

1. 环境隔离与依赖安装

使用venv创建纯净环境，强制安装锁定版本依赖：

python3.12 -m venv mp_env && source mp_env/bin/activate
pip install -r requirements_lock_3_12.txt
pip install mediapipe

该方案利用项目预生成的requirements_lock_3_12.txt文件，确保所有依赖库版本与Python 3.12兼容。

2. 源码级兼容性修复

针对框架层问题，需修改以下文件：

• mediapipe/python/packet_creator.py： 将from typing import Sequence替换为from collections.abc import Sequence
• mediapipe/python/solution_base.py： 添加import sys及版本检查逻辑：

  if sys.version_info >= (3, 12):
      from collections.abc import MutableMapping
  else:
      from typing import MutableMapping
  

3. 替代安装方案

若源码修改不可行，可使用Docker构建兼容环境：

FROM python:3.12-slim
COPY requirements_lock_3_12.txt .
RUN pip install -r requirements_lock_3_12.txt && pip install mediapipe

项目提供的Dockerfile已包含基础构建环境，可在此基础上添加上述依赖安装步骤。

验证与测试流程

基础功能验证

执行官方Python示例验证核心功能：

git clone https://gitcode.com/gh_mirrors/me/mediapipe
cd mediapipe
python3.12 -m mediapipe.examples.desktop.hand_tracking

预期输出：摄像头启动并显示手部关键点识别结果。

兼容性测试矩阵

测试项	测试方法	通过标准
依赖解析	pip check	无冲突提示
模型加载	运行face_detection.py	成功加载BlazeFace模型
实时推理	处理30fps视频流	帧率稳定>25fps

长期适配建议

开发者指南更新

项目文档docs/getting_started/python.md尚未提及Python 3.12支持。建议添加以下内容：

• 在"安装步骤"章节明确推荐使用requirements_lock_3_12.txt
• 添加版本兼容性表格，标注支持的Python版本及对应依赖文件

自动化测试集成

在CI流程中添加Python 3.12测试任务，使用以下命令：

bazel test --python_version=3.12 mediapipe/python/...

该命令需配合修改WORKSPACE文件中的Python版本配置。

通过以上步骤，MediaPipe可在Python 3.12环境中稳定运行。建议定期检查requirements_lock_3_12.txt的更新，及时同步官方兼容性修复。