从零构建课堂行为分析系统：基于YOLO与MediaPipe的AI实践

在实际教育技术项目中，课堂行为分析正从传统的视频人工观察，转向结合计算机视觉与人工智能的自动化、量化评估。这项技术旨在通过分析课堂录像，识别教师与学生的行为模式、互动频率、专注度等指标，为教学评估、教研改进和个性化学习提供数据支持。对于开发者、教育技术产品经理以及对AI应用落地方案感兴趣的技术人员而言，理解如何构建一个基础的课堂行为分析系统，是进入AI+教育领域一个非常具体的切入点。

本文将以一个工程实践的角度，探讨如何从零开始构建一个简易的课堂行为分析原型系统。我们将不依赖特定商业平台，而是聚焦于技术选型、核心流程实现、常见问题排查以及生产环境考量。通过本文，你将了解从视频输入到行为数据输出的完整技术链路，掌握关键组件的集成方法，并能够规避初期开发中的典型陷阱。

1. 理解课堂行为分析的技术栈与核心流程

课堂行为分析并非单一算法，而是一个融合了多个AI子领域的系统工程。在动手编码前，必须理清其技术栈和数据流。

1.1 核心分析目标与对应技术

课堂行为分析通常关注以下几类目标，每类目标对应不同的AI技术：

• 人员检测与跟踪：识别视频中所有人员（教师、学生）的位置并持续跟踪。这是所有后续分析的基础，通常使用目标检测（如YOLO系列）和多目标跟踪（MOT）算法。
• 姿态估计：识别个体的关键身体关节点（如头、肩、手肘）。用于分析举手、站立、坐姿、趴桌等行为。常用OpenPose、MediaPipe或基于深度学习的2D/3D姿态估计模型。
• 人脸识别与表情分析：区分教师与学生，并分析基本的面部表情（如专注、疑惑、高兴）。这涉及人脸检测、人脸识别和表情分类模型。
• 行为分类：基于检测框、姿态、轨迹等特征，对特定行为进行分类，例如“教师板书”、“学生举手”、“学生交头接耳”、“学生离开座位”等。这通常需要训练一个时序行为分类模型，或基于规则进行判断。
• 语音与文本分析：结合音频流，进行语音识别（ASR）得到文字，再对文本进行情感、关键词分析。这属于另一个模态，本文主要聚焦视觉分析。

1.2 系统架构与数据流

一个典型的离线分析系统（非实时）的数据流如下：

1. 输入：课堂录制视频文件（如MP4格式）。
2. 视频解码与抽帧：使用OpenCV或FFmpeg库读取视频，并按固定频率（如每秒1-5帧）抽取图像帧。
3. 预处理：对图像帧进行缩放、归一化等操作，以适应模型输入要求。
4. AI模型推理流水线：
   • 阶段一：人员检测。对每一帧图像，运行目标检测模型，得到所有人的边界框（Bounding Box）。
   • 阶段二：人员重识别与跟踪。跨帧关联同一个人的检测框，形成每个人的运动轨迹（Track ID）。
   • 阶段三：姿态估计与特征提取。对每个检测到的人，裁剪出区域，运行姿态估计模型，得到关节点坐标。同时，可以提取人脸区域进行识别。
   • 阶段四：行为分类。结合当前帧的检测框、姿态、以及过去数帧的历史轨迹，判断该对象当前的行为类别。
5. 后处理与聚合：将每一帧的识别结果（如：{frame_id: 100, track_id: 1, person_type: 'teacher', action: 'writing', bbox: [x,y,w,h]}）进行整理。按时间维度聚合，生成课堂报告，如教师移动轨迹热力图、学生举手次数统计、各行为时间占比等。
6. 输出：结构化的JSON/CSV数据报告，以及可选的可视化视频（将识别结果画在原视频上）。

2. 环境准备与依赖配置

我们将使用Python作为开发语言，因为它拥有最丰富的AI开源库生态。以下环境配置以Linux/Ubuntu系统为例，Windows/macOS需注意部分库的安装差异。

2.1 基础环境与Python环境

首先确保系统已安装Python（推荐3.8-3.10版本）和pip。建议使用虚拟环境隔离项目依赖。

# 创建并激活虚拟环境 python -m venv venv_classroom_analysis source venv_classroom_analysis/bin/activate # Linux/macOS # venv_classroom_analysis\Scripts\activate # Windows # 升级pip pip install --upgrade pip

2.2 核心依赖库安装

我们需要计算机视觉库、深度学习框架以及一些工具库。

# 1. 核心计算机视觉与深度学习框架 pip install opencv-python-headless # 用于视频处理，headless版本无需GUI pip install opencv-contrib-python # 包含更多功能，如跟踪器 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu # PyTorch (CPU版本，GPU版本需根据CUDA版本调整) pip install ultralytics # 用于YOLOv8，一个简单强大的目标检测库 # 2. 姿态估计与AI工具库 pip install mediapipe # Google的轻量级姿态、人脸、手势识别库 # 注意：MediaPipe可能对系统有额外要求，如Linux上可能需要安装libgl1-mesa-glx # 3. 数据处理与工具 pip install numpy pandas # 数值计算与数据处理 pip install scikit-learn # 可选，用于简单的行为分类模型 pip install matplotlib seaborn # 数据可视化 pip install tqdm # 进度条 pip install jupyter # 可选，用于交互式开发

注意：torch的安装命令会根据你的操作系统、Python版本以及是否有GPU而不同。上述命令安装的是CPU版本。如果你有NVIDIA GPU并已安装CUDA，请访问PyTorch官网获取对应的安装命令。mediapipe在部分Windows环境安装可能遇到问题，可查阅其官方文档解决。

2.3 模型文件准备

一些预训练模型需要单独下载。我们将使用YOLOv8进行人员检测，使用MediaPipe进行姿态估计。

• YOLOv8模型：ultralytics库会在首次使用时自动从网络下载模型（如yolov8n.pt,yolov8s.pt）。确保运行时网络通畅。
• MediaPipe模型：其模型权重已内置于库中，无需额外下载。

环境检查清单：

• [ ] Python版本为3.8+
• [ ] 虚拟环境已激活
• [ ]opencv-python和torch成功安装
• [ ] 运行python -c “import cv2; import torch; print(cv2.__version__, torch.__version__)”无报错

3. 构建最小化课堂行为分析原型

我们将分步骤实现一个最简分析流程：读取视频，检测人员，进行简单的行为推断（如是否举手），并输出统计结果。

3.1 项目结构设计

创建一个清晰的项目目录，便于管理代码、数据和结果。

classroom_behavior_analysis/ ├── configs/ # 配置文件 │ └── default.yaml ├── data/ │ ├── input_videos/ # 存放待分析的课堂视频 │ └── output/ # 存放分析结果和可视化视频 ├── models/ # 存放本地模型文件（如果需要） ├── src/ │ ├── __init__.py │ ├── video_processor.py # 视频处理与帧抽取 │ ├── detector.py # 目标检测模块 │ ├── pose_estimator.py # 姿态估计模块 │ ├── action_analyzer.py # 行为分析逻辑 │ └── utils.py # 工具函数 ├── requirements.txt # 依赖列表 ├── run_analysis.py # 主运行脚本 └── README.md

3.2 实现视频处理与人员检测

首先，我们实现视频读取和基于YOLOv8的人员检测。

src/video_processor.py：负责视频的IO操作。

import cv2 from tqdm import tqdm import os class VideoProcessor: def __init__(self, video_path): self.video_path = video_path self.cap = cv2.VideoCapture(video_path) if not self.cap.isOpened(): raise ValueError(f"无法打开视频文件: {video_path}") self.fps = int(self.cap.get(cv2.CAP_PROP_FPS)) self.total_frames = int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT)) self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH)) self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) print(f"视频信息: {self.width}x{self.height}, {self.fps} FPS, 总帧数: {self.total_frames}") def get_frames(self, interval=1): """按间隔抽取视频帧""" frame_count = 0 while True: ret, frame = self.cap.read() if not ret: break if frame_count % interval == 0: # 将BGR转换为RGB，因为大多数AI模型使用RGB frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) yield frame_count, frame_rgb frame_count += 1 self.cap.release() def release(self): if self.cap.isOpened(): self.cap.release()

src/detector.py：封装YOLOv8检测逻辑。

from ultralytics import YOLO import numpy as np class PersonDetector: def __init__(self, model_name='yolov8n.pt', conf_threshold=0.5): """ 初始化人员检测器 Args: model_name: YOLO模型名称或路径 conf_threshold: 置信度阈值 """ # 加载模型，首次运行会自动下载 self.model = YOLO(model_name) self.conf_threshold = conf_threshold # YOLO COCO数据集中，‘person’类的ID是0 self.person_class_id = 0 def detect(self, image): """ 检测图像中的人员 Args: image: RGB格式的numpy数组 Returns: list: 每个元素为 [x1, y1, x2, y2, confidence] """ # YOLO模型推理 results = self.model(image, verbose=False) # verbose=False关闭日志 boxes = [] for result in results: for box in result.boxes: cls_id = int(box.cls[0]) conf = float(box.conf[0]) # 只保留‘person’类别且置信度高于阈值的框 if cls_id == self.person_class_id and conf >= self.conf_threshold: x1, y1, x2, y2 = map(int, box.xyxy[0].tolist()) boxes.append([x1, y1, x2, y2, conf]) return boxes

3.3 集成姿态估计与简单行为判断

接下来，使用MediaPipe进行姿态估计，并基于姿态定义一个简单的“举手”行为判断规则。

src/pose_estimator.py：

import mediapipe as mp import cv2 class PoseAnalyzer: def __init__(self): # 初始化MediaPipe姿态估计模型 self.mp_pose = mp.solutions.pose self.pose = self.mp_pose.Pose( static_image_mode=False, # 设置为False用于视频流 model_complexity=1, # 复杂度：0,1,2。越高越准越慢 smooth_landmarks=True, min_detection_confidence=0.5, min_tracking_confidence=0.5 ) self.mp_drawing = mp.solutions.drawing_utils def estimate(self, image): """ 估计图像中单人的姿态 Args: image: RGB格式的numpy数组 Returns: landmarks: 33个关节点坐标列表，每个为[x, y, visibility] """ results = self.pose.process(image) if results.pose_landmarks: # 转换为列表格式 h, w, _ = image.shape landmarks = [] for lm in results.pose_landmarks.landmark: landmarks.append([lm.x * w, lm.y * h, lm.visibility]) return landmarks return None def is_hand_raised(self, landmarks): """ 一个非常简单的举手判断规则：左手或右手腕的y坐标低于肩膀的y坐标。 这是一个启发式规则，实际应用需要更复杂的逻辑。 Args: landmarks: 从estimate()返回的关节点列表 Returns: bool: 是否举手 """ if landmarks is None or len(landmarks) < 16: # 确保有足够的关节点 return False # MediaPipe Pose关节点索引 LEFT_SHOULDER = 11 RIGHT_SHOULDER = 12 LEFT_WRIST = 15 RIGHT_WRIST = 16 ls = landmarks[LEFT_SHOULDER] rs = landmarks[RIGHT_SHOULDER] lw = landmarks[LEFT_WRIST] rw = landmarks[RIGHT_WRIST] # 如果手腕的y坐标比同侧肩膀的y坐标高（图像坐标系原点在左上角），则认为手在肩膀上方 left_raised = lw[1] < ls[1] and lw[2] > 0.5 # y坐标更小，且可见性高 right_raised = rw[1] < rs[1] and rw[2] > 0.5 return left_raised or right_raised def draw_landmarks(self, image, landmarks): """在图像上绘制姿态关节点和连线（用于可视化）""" # 需要将RGB图像转回BGR供OpenCV显示 img_bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR) if landmarks is not None: # 这里简化绘制，实际应使用MediaPipe的绘图工具 for lm in landmarks: x, y, vis = int(lm[0]), int(lm[1]), lm[2] if vis > 0.5: cv2.circle(img_bgr, (x, y), 3, (0, 255, 0), -1) return cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)

3.4 组装主流程并输出结果

最后，我们创建一个主脚本，串联整个流程，并生成简单的统计报告。

run_analysis.py：

import os import json from src.video_processor import VideoProcessor from src.detector import PersonDetector from src.pose_estimator import PoseAnalyzer import cv2 from tqdm import tqdm def main(video_path, output_dir, frame_interval=5): os.makedirs(output_dir, exist_ok=True) # 初始化组件 processor = VideoProcessor(video_path) detector = PersonDetector(conf_threshold=0.6) pose_analyzer = PoseAnalyzer() # 准备输出视频（可选） output_video_path = os.path.join(output_dir, 'annotated_video.mp4') fourcc = cv2.VideoWriter_fourcc(*'mp4v') out_video = cv2.VideoWriter(output_video_path, fourcc, processor.fps//frame_interval, (processor.width, processor.height)) analysis_results = [] hand_raise_count = 0 print("开始分析视频...") for frame_idx, frame_rgb in tqdm(processor.get_frames(interval=frame_interval), total=processor.total_frames//frame_interval): # 1. 人员检测 person_boxes = detector.detect(frame_rgb) frame_result = {'frame_idx': frame_idx, 'persons': []} # 2. 对每个检测到的人进行姿态估计和行为分析 for i, box in enumerate(person_boxes): x1, y1, x2, y2, conf = box # 裁剪出人员区域（可适当扩大区域以包含完整身体） padding = 20 h, w, _ = frame_rgb.shape crop_x1 = max(0, x1 - padding) crop_y1 = max(0, y1 - padding) crop_x2 = min(w, x2 + padding) crop_y2 = min(h, y2 + padding) person_crop = frame_rgb[crop_y1:crop_y2, crop_x1:crop_x2] if person_crop.size == 0: continue # 姿态估计 landmarks = pose_analyzer.estimate(person_crop) # 简单行为判断：是否举手 is_raising_hand = pose_analyzer.is_hand_raised(landmarks) if landmarks else False person_info = { 'id': i, 'bbox': [x1, y1, x2, y2], 'confidence': conf, 'hand_raised': is_raising_hand } frame_result['persons'].append(person_info) if is_raising_hand: hand_raise_count += 1 # 在原始帧上绘制检测框和举手状态 label = f"Person {i}: HandRaised" if is_raising_hand else f"Person {i}" color = (0, 0, 255) if is_raising_hand else (0, 255, 0) # 红色表示举手，绿色表示未举手 cv2.rectangle(frame_rgb, (x1, y1), (x2, y2), color, 2) cv2.putText(frame_rgb, label, (x1, y1 - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 2) analysis_results.append(frame_result) # 将RGB帧转回BGR并写入输出视频 frame_bgr = cv2.cvtColor(frame_rgb, cv2.COLOR_RGB2BGR) out_video.write(frame_bgr) # 释放资源 out_video.release() processor.release() # 3. 生成汇总报告 total_analyzed_frames = len(analysis_results) total_persons_detected = sum(len(frame['persons']) for frame in analysis_results) avg_persons_per_frame = total_persons_detected / total_analyzed_frames if total_analyzed_frames > 0 else 0 summary = { 'video_info': { 'path': video_path, 'resolution': f'{processor.width}x{processor.height}', 'fps': processor.fps, 'total_frames': processor.total_frames, 'analyzed_frames': total_analyzed_frames }, 'statistics': { 'total_hand_raise_events': hand_raise_count, 'average_persons_per_frame': round(avg_persons_per_frame, 2), 'total_persons_detected': total_persons_detected } } # 保存详细结果和摘要 with open(os.path.join(output_dir, 'detailed_results.json'), 'w') as f: json.dump(analysis_results, f, indent=2) with open(os.path.join(output_dir, 'summary_report.json'), 'w') as f: json.dump(summary, f, indent=2) print(f"\n分析完成！") print(f"输出目录: {output_dir}") print(f"检测到举手总次数: {hand_raise_count}") print(f"平均每帧人数: {avg_persons_per_frame:.2f}") print(f"可视化视频已保存至: {output_video_path}") if __name__ == '__main__': # 使用示例 input_video = './data/input_videos/sample_classroom.mp4' # 请替换为你的视频路径 output_dir = './data/output/run_1' main(input_video, output_dir, frame_interval=10) # 每10帧分析一帧以加快速度

4. 运行验证与结果分析

4.1 准备测试数据与运行

1. 将一段课堂录像（时长1-5分钟为宜）放入./data/input_videos/，并命名为sample_classroom.mp4，或修改脚本中的路径。
2. 在项目根目录下运行命令：

   python run_analysis.py

3. 观察控制台输出。首次运行会下载YOLOv8n模型（约6MB），需要网络连接。

4.2 预期输出与验证

运行成功后，你应在./data/output/run_1/目录下看到以下文件：

• annotated_video.mp4：可视化视频，其中用绿色框标出检测到的人，用红色框标出被判断为“举手”的人。
• detailed_results.json：每一帧的详细分析数据。
• summary_report.json：汇总统计报告。

打开summary_report.json，内容应类似：

{ "video_info": { "path": "./data/input_videos/sample_classroom.mp4", "resolution": "1280x720", "fps": 30, "total_frames": 5400, "analyzed_frames": 540 }, "statistics": { "total_hand_raise_events": 23, "average_persons_per_frame": 15.67, "total_persons_detected": 8462 } }

播放annotated_video.mp4，检查检测框是否准确，举手判断是否符合预期。这个简单的规则（手腕高于肩膀）在正面、侧面视角下可能不准，但足以验证流程。

4.3 关键参数调优说明

原型系统中几个关键参数直接影响效果和性能：

5. 常见问题排查与优化

在实际部署中，你会遇到各种问题。以下是基于此原型系统的典型排查路径。

5.1 模型加载或推理失败

• 现象：运行脚本时卡在下载模型，或报错OSError: [Errno 8] Exec format error（可能与MediaPipe相关）。
• 排查：
  1. 网络问题：首次运行YOLO需要下载模型，确保网络通畅。可以手动下载yolov8n.pt并指定本地路径。
  2. 环境冲突：检查PyTorch、OpenCV、MediaPipe版本是否兼容。建议严格按照requirements.txt或前述命令安装。
  3. 系统依赖：在Linux上，MediaPipe可能需要libgl1-mesa-glx。安装命令：sudo apt-get update && sudo apt-get install -y libgl1-mesa-glx。
• 解决：创建纯净虚拟环境，按顺序安装依赖。对于MediaPipe问题，查阅其GitHub Issues。

5.2 检测或姿态估计精度低

• 现象：视频中的人检测不到，或者姿态关节点乱飞，举手判断完全错误。
• 排查：
  1. 视频质量：检查输入视频分辨率、光照、模糊程度。过于模糊或侧脸/背面过多会影响精度。
  2. 参数阈值：检查conf_threshold是否设得过高，导致漏检。尝试降低到0.3。
  3. 模型能力：YOLOv8n是轻量模型，在拥挤、小目标场景可能效果不佳。可尝试更大的模型，如yolov8s.pt或yolov8m.pt。
  4. 姿态估计视角：MediaPipe Pose在人体严重遮挡或非正面/侧面视角时效果会下降。我们的举手规则过于简单。
• 解决：
  • 确保视频清晰，人物大小适中。
  • 调整检测和姿态估计的置信度阈值。
  • 升级检测模型。
  • 设计更鲁棒的行为判断逻辑，例如结合多帧信息、使用更复杂的特征（如手腕与耳朵的相对位置）。

5.3 处理速度慢，无法实时

• 现象：分析一段1分钟的视频需要好几分钟。
• 排查：
  1. 抽帧频率：检查frame_interval。分析所有帧（interval=1）会非常慢。
  2. 模型复杂度：检查使用的YOLO模型和MediaPipe复杂度。yolov8x和model_complexity=2会慢很多。
  3. 硬件：是否在使用CPU运行？GPU可以极大加速。
• 解决：
  • 增大frame_interval。
  • 使用更轻量的模型（YOLOv8n, MediaPipe复杂度0）。
  • 启用GPU：安装CUDA版本的PyTorch，并确保代码在GPU上运行。修改detector.py，将模型加载到GPU：

    self.model = YOLO(model_name).to(‘cuda’ if torch.cuda.is_available() else ‘cpu’)

  • 考虑使用多进程或异步处理，将视频分块分析。

5.4 无法区分教师与学生

• 现象：原型系统只检测“人”，无法区分角色。
• 解决：这是一个更高级的功能。常见思路：
  1. 基于位置：假设讲台区域的人是教师。需要预先定义讲台区域（ROI）。
  2. 基于轨迹：教师通常移动范围小且在讲台附近，学生相对静止在座位。可通过跟踪轨迹的统计特征（如移动轨迹的中心点、方差）进行简单聚类。
  3. 基于外观：使用重识别（Re-ID）模型或人脸识别模型，预先录入教师人脸或服装特征。这需要额外的训练或注册流程。
  4. 多模态：结合音频，声源定位（谁在说话）有助于识别教师。

6. 从原型到生产：最佳实践与扩展方向

上述原型仅用于演示技术流程。要构建一个可用的课堂行为分析系统，还需要考虑以下方面。

6.1 工程化最佳实践

1. 配置化管理：将所有参数（模型路径、阈值、抽帧间隔、ROI坐标）放入配置文件（如YAML），避免硬编码。
2. 日志与监控：在关键步骤添加日志（如每处理100帧打印一次进度、记录异常帧），便于追踪问题。
3. 异常处理：视频读取失败、模型推理异常、文件写入错误等都需要被捕获并妥善处理，避免整个任务崩溃。
4. 资源管理：使用with语句或try...finally确保视频流、模型等资源被正确释放。
5. 结果存储：考虑使用数据库（如SQLite、MySQL）存储分析结果，而不是单一的JSON文件，便于查询和聚合。
6. 异步处理：对于长视频，采用任务队列（如Celery + Redis）进行异步处理，并提供任务状态查询接口。

6.2 算法与模型优化

1. 更鲁棒的行为识别：
   • 时序模型：使用LSTM、3D CNN或Transformer对连续帧的特征序列进行建模，识别“举手”、“走动”、“低头”等时序行为。
   • 集成多特征：结合姿态、人脸朝向、光流（运动信息）进行综合判断。
   • 定制化训练：在课堂场景数据上微调行为分类模型，以适应特定的教室布局、摄像头角度。
2. 稳定的多目标跟踪：使用更先进的跟踪算法（如DeepSORT, ByteTrack）替代简单的跨帧ID匹配，解决人员遮挡、进出画面导致的ID切换问题。
3. 情感与专注度分析：基于面部表情（通过表情识别模型）和头部姿态（通过姿态估计得到的头部欧拉角）来估计学生的课堂专注度。这是一个更复杂但更有价值的方向。

6.3 生产环境部署清单

在将系统部署到真实环境前，请检查以下清单：

• [ ]性能：在目标硬件（服务器/NVIDIA Jetson等边缘设备）上测试，确保处理速度满足要求（实时或准实时）。
• [ ]精度：在真实课堂数据上进行评估，计算行为识别的准确率、召回率，确保算法可用。
• [ ]鲁棒性：测试不同光照（白天/晚上开灯）、不同摄像头角度、不同教室布局下的效果。
• [ ]数据隐私：这是教育场景的重中之重。确保视频数据在传输、存储、处理过程中加密，分析结果脱敏，并遵守相关法律法规。
• [ ]系统集成：如何与现有的录播系统、教务系统对接？定义清晰的输入输出API。
• [ ]可解释性：分析结果（如“学生A专注度低”）应能提供依据（如“在20分钟内有15分钟面部未朝向讲台”），增加可信度。

课堂行为分析是一个典型的AI工程应用，它要求开发者不仅理解计算机视觉算法，更要深刻理解教育场景的业务逻辑、约束条件（如隐私、性能）和评价标准。从本文的原型出发，你可以沿着算法优化、工程健壮性、业务适配任何一个方向深入，构建出真正解决实际问题的产品。