一、前置准备
1. 安装依赖
首先确保你的 Python 环境（建议 3.8-3.11 版本）安装了 MediaPipe 库，执行以下命令：
bash
运行
# 核心安装命令
pip install mediapipe# 可选：若需处理图片/视频，安装opencv-python（推荐）
pip install opencv-python2. 下载预训练模型
MediaPipe Tasks 依赖预训练的
tflite模型文件，可从官方仓库下载：- 官方模型库：https://developers.google.com/mediapipe/solutions/guide#model_downloads
- 推荐先下载轻量模型（如
efficientnet_lite0.tflite用于图像分类、ssd_mobilenet_v2.tflite用于目标检测），下载后保存到本地目录（如models/文件夹）。
二、实战示例 1：图像分类（识别图片中的物体）
这是最基础的场景，实现对单张图片的内容识别，步骤如下：
完整代码
python
运行
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision# 1. 配置模型路径和分类器参数
MODEL_PATH = "models/efficientnet_lite0.tflite" # 替换为你的模型路径
IMAGE_PATH = "test.jpg" # 替换为你的测试图片路径# 基础配置：指定模型文件
base_options = python.BaseOptions(model_asset_path=MODEL_PATH)
# 分类器配置：返回Top3结果，置信度阈值0.5
options = vision.ImageClassifierOptions(base_options=base_options,max_results=3,score_threshold=0.5
)# 2. 初始化分类器并执行推理
with vision.ImageClassifier.create_from_options(options) as classifier:# 加载本地图片（MediaPipe专用Image格式）image = mp.Image.create_from_file(IMAGE_PATH)# 执行分类推理result = classifier.classify(image)# 3. 解析并输出结果print("图像分类结果（Top3）：")for idx, category in enumerate(result.classifications[0].categories):print(f"{idx+1}. 类别：{category.category_name}，置信度：{category.score:.2f}")代码关键说明
BaseOptions：核心配置类，指定预训练模型的本地路径；ImageClassifierOptions：图像分类专属配置，max_results控制返回结果数量，score_threshold过滤低置信度结果；mp.Image.create_from_file()：将本地图片转为 MediaPipe 可处理的格式，也支持cv2读取的图像（需转换格式）；- 推理结果
result中，classifications[0]对应单张图片的分类结果，categories包含类别名称和置信度。
运行效果示例
plaintext
图像分类结果（Top3）：
1. 类别：golden retriever，置信度：0.92
2. 类别：Labrador retriever，置信度：0.05
3. 类别：cocker spaniel，置信度：0.01三、实战示例 2：目标检测（识别图片中的多个物体并定位）
目标检测比分类更进阶，能识别物体位置（坐标），适合监控、巡检等场景：
完整代码
python
运行
import cv2
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision# 1. 配置参数
MODEL_PATH = "models/ssd_mobilenet_v2.tflite"
IMAGE_PATH = "test_scene.jpg"# 目标检测配置
base_options = python.BaseOptions(model_asset_path=MODEL_PATH)
options = vision.ObjectDetectorOptions(base_options=base_options,score_threshold=0.5, # 只显示置信度≥0.5的物体max_results=5 # 最多识别5个物体
)# 2. 执行检测
with vision.ObjectDetector.create_from_options(options) as detector:# 加载图片image = mp.Image.create_from_file(IMAGE_PATH)# 推理detection_result = detector.detect(image)# 3. 可视化结果（用OpenCV标注物体框和名称）
image_original = cv2.imread(IMAGE_PATH)
height, width = image_original.shape[:2]# 遍历检测结果，绘制边框和文字
for detection in detection_result.detections:# 获取物体边框坐标（归一化值，需转换为像素）bbox = detection.bounding_boxx_start = int(bbox.origin_x)y_start = int(bbox.origin_y)x_end = int(bbox.origin_x + bbox.width)y_end = int(bbox.origin_y + bbox.height)# 获取物体名称和置信度category = detection.categories[0]label = f"{category.category_name} ({category.score:.2f})"# 绘制矩形框和文字cv2.rectangle(image_original, (x_start, y_start), (x_end, y_end), (0, 255, 0), 2)cv2.putText(image_original, label, (x_start, y_start-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)# 显示结果图片
cv2.imshow("Object Detection Result", image_original)
cv2.waitKey(0)
cv2.destroyAllWindows()# 保存标注后的图片
cv2.imwrite("detection_result.jpg", image_original)代码关键说明
ObjectDetectorOptions：目标检测配置类，核心参数和分类器一致；bounding_box：返回物体的归一化坐标（0-1），需结合图片像素尺寸转换为实际坐标；- OpenCV 可视化：通过
cv2.rectangle绘制边框，cv2.putText标注物体名称和置信度，直观展示检测结果。
四、常见问题与注意事项
- 模型路径错误：确保
model_asset_path是本地绝对 / 相对路径，模型文件未损坏； - Python 版本兼容：MediaPipe 对 Python 3.12 + 支持尚不完美，建议用 3.8-3.11；
- 性能优化：若处理视频 / 实时流，优先用
lite版模型，减少推理耗时； - 其他任务扩展：手势识别、姿态估计的使用逻辑和上述示例一致，仅需替换模型和对应的 Task 类（如
HandLandmarker、PoseLandmarker）。
总结
- Python 中使用 MediaPipe Tasks 的核心步骤：安装依赖→下载预训练模型→配置 Task 参数→初始化 Task 实例→执行推理→解析结果；
- 不同 AI 任务（分类、检测、手势等）的代码结构一致，仅需替换模型文件和对应的 Task 类（如
ImageClassifier/ObjectDetector）； - 结合 OpenCV 可快速实现结果可视化，降低调试和落地成本。