简介面向教育技术研究者、课堂管理者及深度学习开发者基于YOLOv8的学生课堂行为识别项目代码专注于在课堂视频流中实时检测、分类学生行为可用于课堂出勤分析、专注度评估、异常行为预警等教学场景也可迁移至其他目标检测任务。YOLOv8作为You Only Look Once系列的最新版本采用改进的卷积神经网络与端到端训练方式在人员密集、遮挡频繁的课堂环境中仍能保持较高准确率与实时性项目从环境配置、数据准备到模型推理提供了完整实现路径。压缩包共476个文件大小约23.7MB其中Markdown文档约230个、Python脚本约130个、YAML配置43个、预训练权重3个并有Dockerfile容器化配置、图片、文本等辅助文件Python脚本覆盖数据加载、训练与推理YAML文件配置模型结构预训练权重可直接加载测试同时包含中英文说明文档与许可证便于本地部署与二次开发。项目已有520人浏览学习适合具备Python与深度学习基础、希望掌握目标检测落地流程的学习者。除核心代码外还提供预训练模型、安装配置脚本及多类型辅助资源配套博文与数据集介绍链接可帮助深入理解项目背景、训练数据构建与算法调优思路目录结构清晰适合快速定位与二次开发是一份兼顾代码实践与理论说明的完整参考资料。1. 课堂行为识别选型YOLOv8 目标检测的工程化边界课堂场景的学生行为识别是目标检测在教育领域最常见的落地需求。YOLOv8 学生课堂行为识别项目把这件事拆成一条完整链路数据标注、模型微调、实时推理每一环都有对应的工程文件。一个普通教室里有几十名学生遮挡、逆光、后排目标过小、动作幅度低这些干扰叠加在一起直接拿 COCO 预训练权重去识别睡觉玩手机举手这类行为几乎不可用。这个项目的价值在于用 YOLOv8 算法做目标检测底座配合课堂行为数据集微调训练把视频流里的学生行为转成类别、置信度和边界框。这套项目代码覆盖了从环境配置到推理输出的全部环节。核心是基于 PyTorch 的 YOLOv8 深度学习训练框架预训练权重用 yolov8n.pt仓库里还带了 Dockerfile、setup.py、CITATION.cff 这些工程化文件——它不是实验脚本的一次性堆积而是按可复现、可分发、可部署的标准整理的。对做智慧课堂产品验证的工程师来说可以直接拿它当基线工程跑通再按硬件条件去调。适合两类人读一类是毕业设计或课题验证阶段的学生需要快速拿到一个能演示的目标检测系统把课堂行为识别做成可交互的 demo另一类是在做课堂行为分析产品的工程师想先验证类别划分和数据标注方案是否合理再决定要不要引入姿态估计、人脸识别这类更重的模块。下面按结构理解 → 环境配置 → 训练实战 → 优化部署的顺序拆开讲。2. YOLOv8 结构拆解C2f 特征提取与 Anchor-Free 解耦头的设计逻辑2.1 C2f 模块梯度流更平滑的 CSP 结构YOLOv8 的 backbone 沿用 CSPDarknet 的整体思路但把 YOLOv5 里的 C3 模块换成了 C2f。C3 的典型做法是输入进来后在两条分支上分别处理一条分支经过若干 Bottleneck另一条分支做恒等映射最后拼接再卷积。C2f 的区别在于每一层 Bottleneck 的输出都会被收集起来参与最后的 concat而不是只在末尾合并一次。这样改动带来的直接收益是梯度回传路径变多。对照 YOLOv8 网络结构图可以看到C2f 在 backbone 里出现了多次浅层负责边缘纹理深层负责语义信息。课堂场景里学生目标密集且相互遮挡特征图上的响应容易被周围目标干扰更丰富的梯度流能让浅层特征保留更多细节对区分低头写字和低头玩手机这类细粒度差异有帮助。C2f 的参数量和计算量相比 C3 没有明显增加属于典型的结构换信息密度。可以打印模型里的 C2f 模块确认当前权重文件的结构from ultralytics import YOLO model YOLO(yolov8n.pt) for idx, (name, module) in enumerate(model.model.named_modules()): if module.__class__.__name__ C2f: print(findex{idx}, name{name}, type{module.__class__.__name__})这段代码用named_modules()遍历模型的全部子模块过滤出类名为C2f的层。name字段能看出它在 backbone 还是 neck 的哪一段比如model.2.c2f是浅层特征提取model.8.c2f已经在输出较深的语义特征。想确认自己拿到的 pt 文件是否被改动过结构这是最直接的办法。2.2 Anchor-Free 解耦头与三路损失函数YOLOv8 的检测头是解耦的分类和回归分支分开走回归分支内部用 Distribution Focal Loss 预测边界框四条边的分布。相比 YOLOv5它彻底去掉了预设 anchor直接在特征图每个位置预测框的中心点与宽高这也是 YOLO 系列里比较激进的一次 head 改进。对课堂行为识别来说Anchor-Free 的意义在于省去了聚类 anchor 这一步。不同教室的摄像头安装高度和角度差别很大同一个班级里前排和后排的学生尺度能差 4 倍以上预聚类 anchor 在这种场景下很容易过拟合到某个固定机位。去掉 anchor 之后模型对尺度变化的适应性更好代价是对小目标的回归精度更依赖特征图分辨率这也是后面讲输入尺度时要重点讨论的原因。训练时三路损失并行回传box_loss用 CIoU 衡量预测框和真实框的重合程度cls_loss用 BCE 处理多标签分类dfl_loss负责边界框分布的建模。看到训练日志里这三项分别下降比只看 mAP 更能判断模型是否在正常收敛。如果box_loss降了而dfl_loss不动通常是边界框回归分支的学习率设置偏保守。2.3 模型规模取舍为什么项目默认 yolov8n.ptYOLOv8 官方提供 n/s/m/l/x 五个尺寸参数量和精度依次递增。这个项目默认带 yolov8n.pt不是因为它精度最好而是因为它能满足教室场景的实时性约束。模型参数量适用场景yolov8n3.2M实时视频流、边缘设备本项目默认yolov8s11.2M精度与速度均衡常用作对比基线yolov8m25.9M精度更好需要独立显卡支持yolov8l43.7M接近精度上限训练和推理成本明显升高yolov8x68.2M精度最高通常用于离线批量处理教室监控通常有多路视频流每路都要实时出框。yolov8n 在 GTX 1660 Ti 这类 6GB 显存的显卡上640 输入尺度下可以跑到 60 FPS 以上而 yolov8s 会掉到 35 FPS 左右。如果后续要部署到香橙派这类边缘设备n 尺寸几乎是唯一选择。我的建议是先用 n 跑通全流程确认数据标注质量之后再逐级往上换权重对比而不是一上来就上大模型。3. 环境配置与项目骨架requirements.txt 到 Dockerfile 的依赖闭环3.1 requirements.txt 依赖清单与 CUDA 版本匹配项目按 requirements.txt 配置环境即可运行。文件里核心依赖是 ultralytics、torch、torchvision以及 opencv-python、pandas、matplotlib、PyYAML、tqdm 这些配套库。最容易出问题的不是这些库本身而是 torch 和 CUDA 的版本匹配两者的组合不对训练时要么报 CUDA error要么直接静默退回 CPU 训练。PyTorch 版本推荐 CUDA 版本对应 cuDNN1.8 ~ 1.12CUDA 11.3 / 11.6cuDNN 8.22.0.xCUDA 11.7 / 11.8cuDNN 8.62.1CUDA 12.1 及以上cuDNN 8.9配置环境时用 conda 新建独立环境避免污染系统 Pythonconda create -n behavior python3.9 -y conda activate behavior pip install -r requirements.txt python -c import torch; print(torch.__version__, torch.cuda.is_available())最后一行命令用来验证 torch 是否真的能用 GPU。注意torch.cuda.is_available()返回 True 只代表驱动和 torch 匹配上了不代表算力充足。如果是在 GTX 1660 Ti 这类 6GB 显存的卡上跑推荐 torch 2.0.1 CUDA 11.7 的组合稳定性好显存占用也比 2.1 版本低一些。提示Windows 下pip install torch默认装的是 CPU 版本。先按照 CUDA 版本去官网复制对应的 torch 安装命令再回来装 requirements.txt 里其余的包。3.2 setup.py 安装方式与项目文件作用除了直接 pip install项目里的 setup.py 和 setup.cfg 还提供了可编辑安装方式pip install -e .-e参数会把项目以开发模式装进当前环境改了代码不用重新安装就能生效适合在调试模型逻辑时用。setup.cfg 在这个仓库里主要放 flake8 的 lint 配置真正的包元数据在 setup.py 里维护这两者的分工不要搞混。接手项目时几个看起来不起眼的文件各有用途先扫一眼能省不少时间文件作用requirements.txt环境依赖清单优先处理setup.py / setup.cfg包安装与代码风格检查配置Dockerfile推理环境固化一键构建镜像CITATION.cff学术引用标准格式写论文引用时用MANIFEST.in打包时额外包含的资源文件清单README.zh-CN.md中文使用说明建议先读这个results.csv训练过程指标汇总训练完自动生成style.css / CNAME演示页面的样式和域名配置方便结果可视化展示3.3 Dockerfile 固化推理环境如果有多台机器要部署同一套推理服务Docker 是最省心的方案。项目自带的 Dockerfile 一般基于 PyTorch 官方镜像把依赖和代码分层拷贝进去FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, main.py, --source, 0]--source 0表示读取本机摄像头实际部署时可以换成 RTSP 流地址或视频文件路径。构建命令是docker build -t behavior-detector .运行时加--gpus all才能让容器里看到 GPU。需要注意 PyTorch 官方镜像体积接近 8GB如果目标设备是边缘盒子不要用这个镜像构建第 5 章会讲更轻量的导出方案。4. 训练自己的课堂行为数据集标注格式、超参数与 results.csv 解析4.1 数据集目录与 YOLO txt 标注格式数据是课堂行为识别的命门深度学习的性能上限由训练数据的质量和多样性决定。YOLOv8 要求的数据集组织方式是图片和标注分目录放classroom/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── classroom.yaml图片和标注文件文件名要一一对应标注文件是 txt 格式每行表示一个目标0 0.512 0.344 0.128 0.186 1 0.712 0.618 0.095 0.142五个数字依次是类别 id、目标中心点 x、中心点 y、宽度、高度坐标值都归一化到 0~1 之间用图片宽高做分母。写脚本批量检查标注时最常见的错误是坐标没归一化训练时 loss 直接飞到 NaN。类别 id 的定义要和 classroom.yaml 里的 names 列表严格对齐顺序错一位整个训练就废了。4.2 训练命令与关键超参数数据准备好之后Ultralytics 一条命令拉起训练yolo detect train dataclassroom.yaml modelyolov8n.pt \ epochs150 imgsz640 batch16 device0 \ projectbehavior_runs nameexp1data指向数据集 yamlmodel指向预训练权重epochs是训练轮数imgsz是输入尺度batch受显存限制project和name决定结果输出目录。classroom.yaml 的内容大致如下path: /data/classroom train: images/train val: images/val nc: 6 names: 0: read 1: write 2: hand_raise 3: sleep 4: phone 5: look_around几个关键超参数的经验取值参数建议范围调参依据imgsz640 / 960 / 1280目标越小越要加大但显存和时间成本翻倍batch8 ~ 326GB 显存建议 16OOM 就降到 8epochs100 ~ 200课堂数据量不大150 基本收敛lr00.005 ~ 0.01迁移学习微调用 0.01 起步patience30 ~ 50验证集指标连续不提升时提前停止微调场景下预训练权重已经在 COCO 上学会了通用的目标语义学习率不用太低0.01 起步通常能较快收敛。数据量大或者类别特别多时再把 lr0 降到 0.005。4.3 从 results.csv 读训练状态训练过程中项目会在输出目录下生成 results.csv自动记录每一轮的损失和指标。用 pandas 画损失函数曲线比盯控制台日志直观得多import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(behavior_runs/exp1/results.csv) df.columns [c.strip() for c in df.columns] fig, axes plt.subplots(1, 3, figsize(15, 4)) for ax, col in zip(axes, [train/box_loss, val/box_loss, metrics/mAP50(B)]): ax.plot(df[epoch], df[col]) ax.set_title(col) ax.grid(True) plt.tight_layout() plt.savefig(loss_curves.png, dpi150)results.csv 里值得盯的列有三组。train/box_loss和val/box_loss成对看训练 loss 持续下降而验证 loss 在第 40 轮左右开始回升说明过拟合了这时应该减小 epochs 或加强数据增强。metrics/mAP50(B)是 IoU 阈值 0.5 下的平均精度课堂场景先看它因为它对目标位置误差不那么敏感。metrics/mAP50-95(B)更严格小目标表现差时这个值会明显低于 mAP50。如果 mAP50 已经到 0.9 而 mAP50-95 只有 0.5基本可以判断是后排小目标拖了后腿。4.4 视频推理与 inference.cpp 的部署衔接训练完用 best.pt 做视频推理yolo detect predict modelbehavior_runs/exp1/weights/best.pt \ sourceclassroom.mp4 conf0.35 iou0.5 device0conf0.35是置信度阈值低于它的预测框被过滤掉iou0.5是 NMS 的 IoU 阈值两个框重合度超过它时保留置信度高的那个。课堂监控建议 conf 设在 0.3~0.4 之间太低会出大量误检太高会把后排小目标的正确框一起滤掉。如果要把检测集成到现有系统Python 推理速度不够时项目里的 inference.cpp 和 main.cpp 提供了 C 部署的骨架。常见做法是先把 best.pt 导出成 ONNX再用 OpenCV DNN 或 ONNX Runtime 加载。C 主流程一般是读帧、letterbox 预处理、前向推理、NMS 后处理、画框并统计结果cv::Mat blob cv::dnn::blobFromImage(letterbox_img, 1.0 / 255.0, cv::Size(640, 640), cv::Scalar(), true, false); net.setInput(blob); cv::Mat output net.forward();blobFromImage的第一个参数是 letterbox 后的图像第二个参数 1/255 把像素归一化到 0~1第五个参数true表示交换 R/B 通道以符合 RGB 输入顺序。C 版相比 Python 能省掉解释器开销在 Jetson 或边缘盒子上跑同一个模型每帧能快几十毫秒多路视频流的差距会更明显。5. 进阶调优后排小目标识别与 ONNX 导出加速5.1 输入尺度与滑窗策略对后排识别的影响课堂视频里后排学生占的像素很少640×360 的画面中后排人脸可能只有 20×20 像素。最简单的提精度手段是加大imgsz从 640 提到 1280mAP50-95 通常能提升 3~8 个点但推理时间接近翻倍。按摄像头分辨率来定1080p 视频源把 imgsz 设在 960 左右720p 设在 640~800不要盲目上 1280。imgsz相对耗时小目标效果适用场景6401x一般实时监控CPU 也能跑9602.2x明显提升1080p 视频主流显卡12804x最好后排占比高的教室精度优先如果加大 imgsz 后小目标提升仍不明显可以试滑窗推理把原图切成四个 640×640 patch 分别检测再合并结果等价于用计算量换分辨率适合离线批量分析。5.2 ONNX 导出与 CPU 端加速训练完成后导出 ONNX是摆脱 PyTorch 运行时依赖的关键一步yolo export modelbehavior_runs/exp1/weights/best.pt formatonnx imgsz640 opset12导出的best.onnx可以交给 OpenCV DNN、ONNX Runtime 或 TensorRT 加载。CPU 机器上用 ONNX Runtime 比原版 PyTorch 快 1.5~2 倍设置线程数时按物理核数来别直接填逻辑核数。检查当前环境可用的推理后端python -c import onnxruntime as ort; print(ort.get_available_providers())如果列表里有TensorrtExecutionProvider说明环境具备 TensorRT 条件。边缘设备部署时优先试 FP16 精度的 ONNX显存和带宽占用减半精度损失通常可以接受。导出时如果报算子不支持先降 opset 到 11 或 12反过来要在 TensorRT 上跑就保持 opset 不低于 13。提示导出的 ONNX 文件最好用同一段视频在导出前后各跑一遍对比两边的类别和置信度分布确认数值一致性再进部署流程。5.3 类别不平衡的兜底操作课堂行为数据天然不平衡写字和看书的样本可能占 70%举手玩手机只占 5%少数类别 mAP 会明显偏低。兜底手段按成本从低到高先对少数类别做过采样再对少数类样本做 copy-paste 增强把目标抠出来随机贴到其他图上最后才考虑在训练配置里调整各类别损失权重。多数情况做过采样就能把举手的 mAP 从 0.6 拉到 0.8 以上。最后提醒一个排错细节换机位或换摄像头后必须回头检查验证集。课堂行为识别对拍摄角度非常敏感同一个模型在讲台视角表现好切到教室后方视角可能直接掉 20 个点。遇到这种情况别急着改网络结构先用新角度的几十张图跑一次 quick test确认是数据分布偏移再决定要不要补充训练数据。本文还有配套的精品资源点击获取 YOLOv8课堂行为识别实战：目标检测训练与工程化部署
简介面向教育技术研究者、课堂管理者及深度学习开发者基于YOLOv8的学生课堂行为识别项目代码专注于在课堂视频流中实时检测、分类学生行为可用于课堂出勤分析、专注度评估、异常行为预警等教学场景也可迁移至其他目标检测任务。YOLOv8作为You Only Look Once系列的最新版本采用改进的卷积神经网络与端到端训练方式在人员密集、遮挡频繁的课堂环境中仍能保持较高准确率与实时性项目从环境配置、数据准备到模型推理提供了完整实现路径。压缩包共476个文件大小约23.7MB其中Markdown文档约230个、Python脚本约130个、YAML配置43个、预训练权重3个并有Dockerfile容器化配置、图片、文本等辅助文件Python脚本覆盖数据加载、训练与推理YAML文件配置模型结构预训练权重可直接加载测试同时包含中英文说明文档与许可证便于本地部署与二次开发。项目已有520人浏览学习适合具备Python与深度学习基础、希望掌握目标检测落地流程的学习者。除核心代码外还提供预训练模型、安装配置脚本及多类型辅助资源配套博文与数据集介绍链接可帮助深入理解项目背景、训练数据构建与算法调优思路目录结构清晰适合快速定位与二次开发是一份兼顾代码实践与理论说明的完整参考资料。1. 课堂行为识别选型YOLOv8 目标检测的工程化边界课堂场景的学生行为识别是目标检测在教育领域最常见的落地需求。YOLOv8 学生课堂行为识别项目把这件事拆成一条完整链路数据标注、模型微调、实时推理每一环都有对应的工程文件。一个普通教室里有几十名学生遮挡、逆光、后排目标过小、动作幅度低这些干扰叠加在一起直接拿 COCO 预训练权重去识别睡觉玩手机举手这类行为几乎不可用。这个项目的价值在于用 YOLOv8 算法做目标检测底座配合课堂行为数据集微调训练把视频流里的学生行为转成类别、置信度和边界框。这套项目代码覆盖了从环境配置到推理输出的全部环节。核心是基于 PyTorch 的 YOLOv8 深度学习训练框架预训练权重用 yolov8n.pt仓库里还带了 Dockerfile、setup.py、CITATION.cff 这些工程化文件——它不是实验脚本的一次性堆积而是按可复现、可分发、可部署的标准整理的。对做智慧课堂产品验证的工程师来说可以直接拿它当基线工程跑通再按硬件条件去调。适合两类人读一类是毕业设计或课题验证阶段的学生需要快速拿到一个能演示的目标检测系统把课堂行为识别做成可交互的 demo另一类是在做课堂行为分析产品的工程师想先验证类别划分和数据标注方案是否合理再决定要不要引入姿态估计、人脸识别这类更重的模块。下面按结构理解 → 环境配置 → 训练实战 → 优化部署的顺序拆开讲。2. YOLOv8 结构拆解C2f 特征提取与 Anchor-Free 解耦头的设计逻辑2.1 C2f 模块梯度流更平滑的 CSP 结构YOLOv8 的 backbone 沿用 CSPDarknet 的整体思路但把 YOLOv5 里的 C3 模块换成了 C2f。C3 的典型做法是输入进来后在两条分支上分别处理一条分支经过若干 Bottleneck另一条分支做恒等映射最后拼接再卷积。C2f 的区别在于每一层 Bottleneck 的输出都会被收集起来参与最后的 concat而不是只在末尾合并一次。这样改动带来的直接收益是梯度回传路径变多。对照 YOLOv8 网络结构图可以看到C2f 在 backbone 里出现了多次浅层负责边缘纹理深层负责语义信息。课堂场景里学生目标密集且相互遮挡特征图上的响应容易被周围目标干扰更丰富的梯度流能让浅层特征保留更多细节对区分低头写字和低头玩手机这类细粒度差异有帮助。C2f 的参数量和计算量相比 C3 没有明显增加属于典型的结构换信息密度。可以打印模型里的 C2f 模块确认当前权重文件的结构from ultralytics import YOLO model YOLO(yolov8n.pt) for idx, (name, module) in enumerate(model.model.named_modules()): if module.__class__.__name__ C2f: print(findex{idx}, name{name}, type{module.__class__.__name__})这段代码用named_modules()遍历模型的全部子模块过滤出类名为C2f的层。name字段能看出它在 backbone 还是 neck 的哪一段比如model.2.c2f是浅层特征提取model.8.c2f已经在输出较深的语义特征。想确认自己拿到的 pt 文件是否被改动过结构这是最直接的办法。2.2 Anchor-Free 解耦头与三路损失函数YOLOv8 的检测头是解耦的分类和回归分支分开走回归分支内部用 Distribution Focal Loss 预测边界框四条边的分布。相比 YOLOv5它彻底去掉了预设 anchor直接在特征图每个位置预测框的中心点与宽高这也是 YOLO 系列里比较激进的一次 head 改进。对课堂行为识别来说Anchor-Free 的意义在于省去了聚类 anchor 这一步。不同教室的摄像头安装高度和角度差别很大同一个班级里前排和后排的学生尺度能差 4 倍以上预聚类 anchor 在这种场景下很容易过拟合到某个固定机位。去掉 anchor 之后模型对尺度变化的适应性更好代价是对小目标的回归精度更依赖特征图分辨率这也是后面讲输入尺度时要重点讨论的原因。训练时三路损失并行回传box_loss用 CIoU 衡量预测框和真实框的重合程度cls_loss用 BCE 处理多标签分类dfl_loss负责边界框分布的建模。看到训练日志里这三项分别下降比只看 mAP 更能判断模型是否在正常收敛。如果box_loss降了而dfl_loss不动通常是边界框回归分支的学习率设置偏保守。2.3 模型规模取舍为什么项目默认 yolov8n.ptYOLOv8 官方提供 n/s/m/l/x 五个尺寸参数量和精度依次递增。这个项目默认带 yolov8n.pt不是因为它精度最好而是因为它能满足教室场景的实时性约束。模型参数量适用场景yolov8n3.2M实时视频流、边缘设备本项目默认yolov8s11.2M精度与速度均衡常用作对比基线yolov8m25.9M精度更好需要独立显卡支持yolov8l43.7M接近精度上限训练和推理成本明显升高yolov8x68.2M精度最高通常用于离线批量处理教室监控通常有多路视频流每路都要实时出框。yolov8n 在 GTX 1660 Ti 这类 6GB 显存的显卡上640 输入尺度下可以跑到 60 FPS 以上而 yolov8s 会掉到 35 FPS 左右。如果后续要部署到香橙派这类边缘设备n 尺寸几乎是唯一选择。我的建议是先用 n 跑通全流程确认数据标注质量之后再逐级往上换权重对比而不是一上来就上大模型。3. 环境配置与项目骨架requirements.txt 到 Dockerfile 的依赖闭环3.1 requirements.txt 依赖清单与 CUDA 版本匹配项目按 requirements.txt 配置环境即可运行。文件里核心依赖是 ultralytics、torch、torchvision以及 opencv-python、pandas、matplotlib、PyYAML、tqdm 这些配套库。最容易出问题的不是这些库本身而是 torch 和 CUDA 的版本匹配两者的组合不对训练时要么报 CUDA error要么直接静默退回 CPU 训练。PyTorch 版本推荐 CUDA 版本对应 cuDNN1.8 ~ 1.12CUDA 11.3 / 11.6cuDNN 8.22.0.xCUDA 11.7 / 11.8cuDNN 8.62.1CUDA 12.1 及以上cuDNN 8.9配置环境时用 conda 新建独立环境避免污染系统 Pythonconda create -n behavior python3.9 -y conda activate behavior pip install -r requirements.txt python -c import torch; print(torch.__version__, torch.cuda.is_available())最后一行命令用来验证 torch 是否真的能用 GPU。注意torch.cuda.is_available()返回 True 只代表驱动和 torch 匹配上了不代表算力充足。如果是在 GTX 1660 Ti 这类 6GB 显存的卡上跑推荐 torch 2.0.1 CUDA 11.7 的组合稳定性好显存占用也比 2.1 版本低一些。提示Windows 下pip install torch默认装的是 CPU 版本。先按照 CUDA 版本去官网复制对应的 torch 安装命令再回来装 requirements.txt 里其余的包。3.2 setup.py 安装方式与项目文件作用除了直接 pip install项目里的 setup.py 和 setup.cfg 还提供了可编辑安装方式pip install -e .-e参数会把项目以开发模式装进当前环境改了代码不用重新安装就能生效适合在调试模型逻辑时用。setup.cfg 在这个仓库里主要放 flake8 的 lint 配置真正的包元数据在 setup.py 里维护这两者的分工不要搞混。接手项目时几个看起来不起眼的文件各有用途先扫一眼能省不少时间文件作用requirements.txt环境依赖清单优先处理setup.py / setup.cfg包安装与代码风格检查配置Dockerfile推理环境固化一键构建镜像CITATION.cff学术引用标准格式写论文引用时用MANIFEST.in打包时额外包含的资源文件清单README.zh-CN.md中文使用说明建议先读这个results.csv训练过程指标汇总训练完自动生成style.css / CNAME演示页面的样式和域名配置方便结果可视化展示3.3 Dockerfile 固化推理环境如果有多台机器要部署同一套推理服务Docker 是最省心的方案。项目自带的 Dockerfile 一般基于 PyTorch 官方镜像把依赖和代码分层拷贝进去FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, main.py, --source, 0]--source 0表示读取本机摄像头实际部署时可以换成 RTSP 流地址或视频文件路径。构建命令是docker build -t behavior-detector .运行时加--gpus all才能让容器里看到 GPU。需要注意 PyTorch 官方镜像体积接近 8GB如果目标设备是边缘盒子不要用这个镜像构建第 5 章会讲更轻量的导出方案。4. 训练自己的课堂行为数据集标注格式、超参数与 results.csv 解析4.1 数据集目录与 YOLO txt 标注格式数据是课堂行为识别的命门深度学习的性能上限由训练数据的质量和多样性决定。YOLOv8 要求的数据集组织方式是图片和标注分目录放classroom/ ├── images/ │ ├── train/ │ └── val/ ├── labels/ │ ├── train/ │ └── val/ └── classroom.yaml图片和标注文件文件名要一一对应标注文件是 txt 格式每行表示一个目标0 0.512 0.344 0.128 0.186 1 0.712 0.618 0.095 0.142五个数字依次是类别 id、目标中心点 x、中心点 y、宽度、高度坐标值都归一化到 0~1 之间用图片宽高做分母。写脚本批量检查标注时最常见的错误是坐标没归一化训练时 loss 直接飞到 NaN。类别 id 的定义要和 classroom.yaml 里的 names 列表严格对齐顺序错一位整个训练就废了。4.2 训练命令与关键超参数数据准备好之后Ultralytics 一条命令拉起训练yolo detect train dataclassroom.yaml modelyolov8n.pt \ epochs150 imgsz640 batch16 device0 \ projectbehavior_runs nameexp1data指向数据集 yamlmodel指向预训练权重epochs是训练轮数imgsz是输入尺度batch受显存限制project和name决定结果输出目录。classroom.yaml 的内容大致如下path: /data/classroom train: images/train val: images/val nc: 6 names: 0: read 1: write 2: hand_raise 3: sleep 4: phone 5: look_around几个关键超参数的经验取值参数建议范围调参依据imgsz640 / 960 / 1280目标越小越要加大但显存和时间成本翻倍batch8 ~ 326GB 显存建议 16OOM 就降到 8epochs100 ~ 200课堂数据量不大150 基本收敛lr00.005 ~ 0.01迁移学习微调用 0.01 起步patience30 ~ 50验证集指标连续不提升时提前停止微调场景下预训练权重已经在 COCO 上学会了通用的目标语义学习率不用太低0.01 起步通常能较快收敛。数据量大或者类别特别多时再把 lr0 降到 0.005。4.3 从 results.csv 读训练状态训练过程中项目会在输出目录下生成 results.csv自动记录每一轮的损失和指标。用 pandas 画损失函数曲线比盯控制台日志直观得多import pandas as pd import matplotlib.pyplot as plt df pd.read_csv(behavior_runs/exp1/results.csv) df.columns [c.strip() for c in df.columns] fig, axes plt.subplots(1, 3, figsize(15, 4)) for ax, col in zip(axes, [train/box_loss, val/box_loss, metrics/mAP50(B)]): ax.plot(df[epoch], df[col]) ax.set_title(col) ax.grid(True) plt.tight_layout() plt.savefig(loss_curves.png, dpi150)results.csv 里值得盯的列有三组。train/box_loss和val/box_loss成对看训练 loss 持续下降而验证 loss 在第 40 轮左右开始回升说明过拟合了这时应该减小 epochs 或加强数据增强。metrics/mAP50(B)是 IoU 阈值 0.5 下的平均精度课堂场景先看它因为它对目标位置误差不那么敏感。metrics/mAP50-95(B)更严格小目标表现差时这个值会明显低于 mAP50。如果 mAP50 已经到 0.9 而 mAP50-95 只有 0.5基本可以判断是后排小目标拖了后腿。4.4 视频推理与 inference.cpp 的部署衔接训练完用 best.pt 做视频推理yolo detect predict modelbehavior_runs/exp1/weights/best.pt \ sourceclassroom.mp4 conf0.35 iou0.5 device0conf0.35是置信度阈值低于它的预测框被过滤掉iou0.5是 NMS 的 IoU 阈值两个框重合度超过它时保留置信度高的那个。课堂监控建议 conf 设在 0.3~0.4 之间太低会出大量误检太高会把后排小目标的正确框一起滤掉。如果要把检测集成到现有系统Python 推理速度不够时项目里的 inference.cpp 和 main.cpp 提供了 C 部署的骨架。常见做法是先把 best.pt 导出成 ONNX再用 OpenCV DNN 或 ONNX Runtime 加载。C 主流程一般是读帧、letterbox 预处理、前向推理、NMS 后处理、画框并统计结果cv::Mat blob cv::dnn::blobFromImage(letterbox_img, 1.0 / 255.0, cv::Size(640, 640), cv::Scalar(), true, false); net.setInput(blob); cv::Mat output net.forward();blobFromImage的第一个参数是 letterbox 后的图像第二个参数 1/255 把像素归一化到 0~1第五个参数true表示交换 R/B 通道以符合 RGB 输入顺序。C 版相比 Python 能省掉解释器开销在 Jetson 或边缘盒子上跑同一个模型每帧能快几十毫秒多路视频流的差距会更明显。5. 进阶调优后排小目标识别与 ONNX 导出加速5.1 输入尺度与滑窗策略对后排识别的影响课堂视频里后排学生占的像素很少640×360 的画面中后排人脸可能只有 20×20 像素。最简单的提精度手段是加大imgsz从 640 提到 1280mAP50-95 通常能提升 3~8 个点但推理时间接近翻倍。按摄像头分辨率来定1080p 视频源把 imgsz 设在 960 左右720p 设在 640~800不要盲目上 1280。imgsz相对耗时小目标效果适用场景6401x一般实时监控CPU 也能跑9602.2x明显提升1080p 视频主流显卡12804x最好后排占比高的教室精度优先如果加大 imgsz 后小目标提升仍不明显可以试滑窗推理把原图切成四个 640×640 patch 分别检测再合并结果等价于用计算量换分辨率适合离线批量分析。5.2 ONNX 导出与 CPU 端加速训练完成后导出 ONNX是摆脱 PyTorch 运行时依赖的关键一步yolo export modelbehavior_runs/exp1/weights/best.pt formatonnx imgsz640 opset12导出的best.onnx可以交给 OpenCV DNN、ONNX Runtime 或 TensorRT 加载。CPU 机器上用 ONNX Runtime 比原版 PyTorch 快 1.5~2 倍设置线程数时按物理核数来别直接填逻辑核数。检查当前环境可用的推理后端python -c import onnxruntime as ort; print(ort.get_available_providers())如果列表里有TensorrtExecutionProvider说明环境具备 TensorRT 条件。边缘设备部署时优先试 FP16 精度的 ONNX显存和带宽占用减半精度损失通常可以接受。导出时如果报算子不支持先降 opset 到 11 或 12反过来要在 TensorRT 上跑就保持 opset 不低于 13。提示导出的 ONNX 文件最好用同一段视频在导出前后各跑一遍对比两边的类别和置信度分布确认数值一致性再进部署流程。5.3 类别不平衡的兜底操作课堂行为数据天然不平衡写字和看书的样本可能占 70%举手玩手机只占 5%少数类别 mAP 会明显偏低。兜底手段按成本从低到高先对少数类别做过采样再对少数类样本做 copy-paste 增强把目标抠出来随机贴到其他图上最后才考虑在训练配置里调整各类别损失权重。多数情况做过采样就能把举手的 mAP 从 0.6 拉到 0.8 以上。最后提醒一个排错细节换机位或换摄像头后必须回头检查验证集。课堂行为识别对拍摄角度非常敏感同一个模型在讲台视角表现好切到教室后方视角可能直接掉 20 个点。遇到这种情况别急着改网络结构先用新角度的几十张图跑一次 quick test确认是数据分布偏移再决定要不要补充训练数据。本文还有配套的精品资源点击获取