简介一套面向智能视频监控与行为分析场景的行人动作检测可运行工程整合了YOLOv8目标检测与MMAction2时序模型。内容涵盖环境配置、预训练模型选择如TSM在小数据集上的优势、数据预处理与划分、配置文件修改以及训练、测试、推理的完整流程适合有一定深度学习基础的开发者快速复现并迁移到自己的项目中无论是毕业设计还是工程预研都能得到闭环参考。压缩包共11个文件以Python脚本、mp4演示视频、配置与说明文档为主另含HTML展示页和模型权重文件整体大小仅14KB目录结构紧凑清晰。目前已吸引123人学习下载。通过源码中的行人提取、动作识别与结果融合步骤可以直观理解双阶段检测系统的搭建思路README文档与运行脚本则能帮助少走弯路在有限数据集上快速验证模型效果并为进一步调优提供起点。1. 行人动作检测为什么要拆成“YOLOv8MMAction2”两段来做前阵子接了一个智慧园区的需求摄像头拍到的画面里人不需要再“被看见”而是要被理解——这个人是在走路、在打电话、在攀爬围栏还是在倒地不起。直接拿一个端到端的动作识别模型去跑效果很玄学人一多、画面一杂模型根本分不清“谁在做什么”算力倒是烧得飞快。后来我把链路拆成两段前面用 YOLOv8 做行人检测锁定每个人的位置后面用 MMAction2 对每个目标做时序动作分类整个项目立刻变顺了。这套组合解决的问题很具体检测负责空间定位动作识别负责时间维度上的行为判断两者各干各的互不拖累。适合想在监控视频、行为分析、安防告警这类场景落地行人动作识别的工程师和学生。下面我把这套可运行方案的完整落地路径、关键参数和踩过的坑一次说清楚照着做基本能跑通。2. 两阶段架构先立住YOLOv8 负责“谁在哪”MMAction2 负责“在干嘛”2.1 YOLOv8 检测头的输出到底长什么样YOLOv8 的结构图在网上随便一搜就是一大把但真正决定你能不能跟 MMAction2 对接的不是 Backbone 或者 C2f 模块而是最后检测头吐出来的张量格式。以 COCO 预训练权重为例推理一张 640×640 的图模型输出的检测结果是一组 shape 为[N, 6]的数组N 是检测框数量6 是[x1, y1, x2, y2, conf, class_id]。这里的坐标是原图像素坐标不是归一化坐标这个细节后面裁剪行人区域时直接用得上。很多人第一次在这个环节翻车是因为把 YOLOv8 输出的class_id当成了动作类别。实际上 COCO 的 80 个类别里只有一个personclass_id 0YOLOv8 只能告诉你“这里有个人”不能告诉你“这个人在干嘛”。这就是为什么要再接 MMAction2 的原因检测解决空间维度动作分类解决时间维度。我一般会在检测环节做一次过滤只保留class_id 0的框同时用conf阈值滤掉低质量框。如果场景是固定摄像头机位还可以再加一个运动区域过滤——只在画面里的活动区域做检测这样能显著降低误检率。YOLOv8 在这里只需要输出框坐标不需要输出任何时序信息记住这一点就够用。2.2 MMAction2 的识别器吃的是什么输入MMAction2 是 OpenMMLab 系列的动作识别工具箱它内置了 TSN、TRN、SlowFast、C2D 这些常见动作识别模型。与图像分类不同动作识别模型的输入是一个短视频片段张量维度一般是[T, C, H, W]T 是采样帧数C 是通道数H/W 是空间尺寸。以 TSN 为例常用配置是 8 帧输入从一段视频里均匀采样 8 帧每帧 resize 到 224×224送入 Backbone 提取特征最后经过分类头输出动作类别概率。这里要理解一个关键点MMAction2 的输入不是“一帧图”而是“一串帧”。所以你从 YOLOv8 拿到的是每一帧的行人框你得按时间顺序把同一个人的连续帧裁剪出来拼成一个 clip再喂给 MMAction2。两阶段串联的核心就是这个“按人裁剪、按帧拼接”的过程。单个行人框的裁剪结果是一张图8 张连续帧的裁剪结果拼起来就是一个合格的 MMAction2 输入。这个数据流捋顺了整个管线就不会乱。很多人卡在维度对不上本质是没有理解 T 维度从哪来。2.3 为什么不选端到端方案而坚持两阶段端到端的动作识别模型比如 SlowFast 直接吃整段视频能同时建模空间和时间信息听起来更优雅。但实际落地时有一个很现实的问题画面里有多个行人时端到端模型默认是对整段视频做分类它不区分谁是谁。如果我需要的是“每个行人的动作”那我必须先用检测模型把每个人分离出来。另一个问题是显存和算力。端到端视频模型直接处理整帧画面输入张量动辄几十甚至上百帧显存占用极高。而两阶段方案只需要对检测框裁剪出的小图做时序推理单路视频的 MMAction2 推理成本远低于直接跑视频分类模型。对于园区监控这种多路并发的场景这个差别非常可观。两阶段也不是没有缺点最大的问题是“检测误差会传导”。如果 YOLOv8 在某一帧漏检了行人这一帧的裁剪结果就缺失clip 就不完整。后面我会说怎么缓解这个问题。3. 从零把两段管线跑起来环境配置、权重下载与最小推理代码3.1 YOLOv8 环境配置与行人检测最小命令YOLOv8 的环境配置比 MMAction2 简单太多它的核心依赖只有一个ultralytics包。注意它跟老版的yolov5不是一个仓库别下错包。配置完之后拉预训练权重就可以直接跑推理整个过程不需要自己写网络结构。# 新建虚拟环境Python 版本推荐 3.8 - 3.10 conda create -n action python3.10 -y conda activate action # 安装 ultralytics会自动带上 torch 和 torchvision pip install ultralytics # 测试一下能否正常加载模型 python -c from ultralytics import YOLO; model YOLO(yolov8n.pt); print(ok)这里有两个容易翻车的点。第一pip install ultralytics默认会给你装最新版 PyTorch如果你的显卡驱动较老或者说算力不支持可能跑不起来。常见做法是在装ultralytics之前先从 PyPI 装一个跟显卡匹配的 torch 版本再装 ultralytics。第二yolov8n.pt是 nano 版权重适合先跑通流程正式做项目建议下载yolov8s.pt或yolov8m.pt检测精度会高不少。下面这段是行人检测最小推理代码把框坐标输出成 JSON为后面裁剪做准备import json from ultralytics import YOLO # 加载模型s 版比 n 版精度高速度慢一点 model YOLO(yolov8s.pt) results model.predict( demo.mp4, conf0.5, # 置信度阈值低于此值的框丢弃 classes[0], # COCO 中 0 对应 person saveFalse, streamTrue, # 流式返回逐帧处理 ) detections [] for frame_idx, r in enumerate(results): boxes r.boxes.xyxy.cpu().numpy() # [x1, y1, x2, y2] scores r.boxes.conf.cpu().numpy() # 每个框的置信度 for box, score in zip(boxes, scores): detections.append({ frame: frame_idx, box: box.tolist(), score: float(score), }) with open(detections.json, w) as f: json.dump(detections, f)classes[0]是这一步最关键的参数它保证了模型只输出行人框不会把车、猫、狗都算进来。streamTrue对于长视频很重要它能逐帧迭代而不是一次性把全部帧加载进内存处理 2 小时以上的监控录像不会爆内存。3.2 MMAction2 环境配置与动作分类最小命令MMAction2 的环境配置是这条链路里最折腾的一步它依赖的mmcv和torch版本必须严格匹配。我的建议是直接看官方文档里的版本对应表安装不要自己猜版本。# 先安装 PyTorchCUDA 版本按你的显卡驱动来 pip install torch2.0.0 torchvision0.15.0 --index-url https://download.pytorch.org/whl/cu118 # 安装 mmcv版本号必须和 torch/cuda 对应 pip install mmcv2.1.0 -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html # 安装 mmaction2 本体 git clone https://github.com/open-mmlab/mmaction2.git cd mmaction2 git checkout v1.2.0 # 固定版本避免 master 分支的 breaking change pip install -v e .这里最关键的是mmcv的安装。它是 C 算子库如果版本不对后面模型推理时会直接报undefined symbol之类的错误而且这个错误非常像玄学不看版本根本想不到是这里出了问题。固定mmaction2版本也值得养成习惯OpenMMLab 项目的 master 分支改动很频繁今天能跑的代码下周可能就废了。验证环境是否装好去模型库下 TSN 的预训练权重跑一次最小推理import torch from mmaction.apis import init_recognizer, inference_recognizer # 配置文件和权重文件kinetics400 是通用动作识别数据集 config configs/recognition/tsn/tsn_r50_1x1x3_100e_kinetics400_rgb.py checkpoint https://download.openmmlab.com/mmaction/recognition/tsn/tsn_r50_1x1x3_100e_kinetics400_rgb_20200614-29e8f391.pth model init_recognizer(config, checkpoint, devicecuda:0) result inference_recognizer(model, demo.mp4) # 打印 Top3 动作类别和置信度 predictions result[pred_score].cpu().numpy() top3 predictions.argsort()[-3:][::-1] print(top3, predictions[top3])init_recognizer会把配置文件和权重加载成推理模型inference_recognizer接收一个视频路径或一组帧数组。这一步跑通了说明 MMAction2 的环境和权重链路没问题下一步就可以做真正的两段串联了。3.3 两段串联的最小可运行骨架串联逻辑不复杂读视频帧 → YOLOv8 检测行人 → 对每个行人裁剪出局部图 → 收集 8 帧裁剪图 → 拼成 clip 喂给 MMAction2 → 得到动作分类结果。下面是完整骨架代码把检测结果按帧存进缓存队列凑满 8 帧再送识别import cv2 import numpy as np from ultralytics import YOLO from mmaction.apis import init_recognizer, inference_recognizer detector YOLO(yolov8s.pt) recognizer init_recognizer(cfg, ckpt, devicecuda:0) # 每个目标维护自己的帧缓存key 是目标 id tracks {} CLIP_LEN 8 cap cv2.VideoCapture(demo.mp4) fps cap.get(cv2.CAP_PROP_FPS) for frame_idx in range(1000): ret, frame cap.read() if not ret: break # 1. 检测当前帧的所有行人框 results detector.predict(frame, conf0.5, classes[0], verboseFalse) boxes results[0].boxes.xyxy.cpu().numpy() # 2. 这里简化处理直接用 IOU 最近邻匹配上一帧的目标 # 真实项目建议接 DeepSort / ByteTrack后面会说原因 for i, box in enumerate(boxes): x1, y1, x2, y2 [int(v) for v in box] crop frame[y1:y2, x1:x2] # 在原图裁剪行人区域 # 3. 维持目标的 clip 缓存凑满 CLIP_LEN 帧就识别一次 if i not in tracks: tracks[i] [] tracks[i].append(crop) if len(tracks[i]) CLIP_LEN: clip [cv2.resize(f, (224, 224)) for f in tracks[i]] result inference_recognizer(recognizer, clip) action_id result[pred_score].argmax().item() label labels[action_id] print(fframe {frame_idx}: 行人 {i} 动作 {label}) tracks[i] [] # 清空缓冲开始下一段识别 cap.release()这段代码表达了整套方案的骨架但它有一个简化问题没有做目标关联。真实视频里行人会移动可能上一帧的0号目标和这一帧的0号目标是不同的人。解决这个问题要用多目标跟踪器把 YOLOv8 的检测框交给 ByteTrack 或 DeepSort 得到稳定的 track_id再用 track_id 做缓存 key。源码包里一般会集成 ByteTrack因为它不需要额外训练 RE-ID 模型默认参数在行人场景表现不错。4. 训练自己的数据集数据标注、目录组织与关键训练参数4.1 行人检测数据怎么组织成 YOLOv8 格式用 YOLOv8 训练自己的行人检测模型数据目录组织是固定的但很多人第一次都会搞错images和labels必须是两个平行目录每张图片对应一个同名.txt标签文件。标签文件里每一行是class_id x_center y_center width height注意都是归一化坐标且框坐标中心点加宽高不是x1 y1 x2 y2。dataset/ ├── images/ │ ├── train/ │ │ ├── img_001.jpg │ │ └── img_002.jpg │ └── val/ │ └── img_003.jpg ├── labels/ │ ├── train/ │ │ ├── img_001.txt │ │ └── img_002.txt │ └── val/ │ └── img_003.txt └── data.yamldata.yaml内容是数据集根路径、类别名和类别数。一行车辆数据集转换脚本往往在这里出问题拿到手的标注如果是 VOC 格式的 XML里面是xmin, ymin, xmax, ymax的绝对像素坐标需要转换成 YOLOv8 的归一化格式。下面是一个把一边转一边顺手校验的脚本import os import xml.etree.ElementTree as ET def voc_to_yolo(xml_path, out_path, img_w, img_h): tree ET.parse(xml_path) root tree.getroot() boxes [] for obj in root.findall(object): name obj.find(name).text if name ! person: # 只保留行人过滤其他类别 continue bnd obj.find(bndbox) x1 float(bnd.find(xmin).text) y1 float(bnd.find(ymin).text) x2 float(bnd.find(xmax).text) y2 float(bnd.find(ymax).text) # 归一化中心点坐标 宽高 cx (x1 x2) / 2 / img_w cy (y1 y2) / 2 / img_h w (x2 - x1) / img_w h (y2 - y1) / img_h boxes.append(f0 {cx:.6f} {cy:.6f} {w:.6f} {h:.6f}) with open(out_path, w) as f: f.write(\n.join(boxes)) # 遍历 VOC 目录对每张图调用 voc_to_yolo这里最值得留意的是坐标系归一化要在原图尺寸上进行。很多转换脚本里拿img_w和img_h时用了 resize 之后的尺寸结果标签全部错位训练出来的模型在验证集上 mAP 极高但真实场景一塌糊涂。转完务必随机抽几张图用cv2.rectangle把标签框画回原图上肉眼核对一遍再开训这一步能省下后面好几天排错时间。4.2 MMAction2 的 RawFrame 数据集怎么做MMAction2 支持直接读视频文件VideoDataset也支持读帧目录RawFrameDataset。我的经验是帧目录的方式虽然占磁盘但训练时速度快很多而且做时间维度裁剪更灵活生产项目首选它。目录结构是这样的每个动作类别一个子目录每个视频样本再按帧拆成图片mmaction_data/ ├── annotations/ │ ├── train.txt │ └── val.txt └── rawframes/ ├── walking/ │ ├── video_001/ │ │ ├── img_00001.jpg │ │ ├── img_00002.jpg │ │ └── ... │ └── video_002/ └── falling/标注文件train.txt里每行是空格分隔的三列视频帧目录相对路径 总帧数 类别索引。下面用 ffmpeg 按 25fps 抽帧# 抽帧把 walking/001.mp4 按 25fps 拆成图片 ffmpeg -i walking/001.mp4 -vf fps25 rawframes/walking/video_001/img_%05d.jpg # 统计每个文件夹的帧数 python -c import os for root, dirs, files in os.walk(rawframes): for d in dirs: path os.path.join(root, d) n len([f for f in os.listdir(path) if f.endswith(.jpg)]) print(f{os.path.relpath(path, \rawframes\)} {n}) 抽帧时帧率必须统一。如果一部分视频是 25fps一部分是 30fps那么同样时长的一个动作“总帧数”就不一样训练时采样位置会错乱模型学出来的时序特征会偏。常见做法是全部统一抽成 25fps并且动作片段前后多留 0.5 秒的余量不要卡得太紧否则采样时会采到动作开始前或结束后的无效帧。4.3 YOLOv8 与 MMAction2 训练参数的必调项训练参数决定了模型能不能收敛也决定了你烧多少显卡时间。YOLOv8 的关键参数是imgsz、epochs、batch、patienceyolo detect train \ data/path/to/data.yaml \ modelyolov8s.yaml \ imgsz640 \ epochs100 \ batch16 \ patience20 \ device0imgsz一般 640 就够行人本身是小目标设成 960 能提升小目标召回但显存和时间成本翻倍。patience是早停轮数超过这个轮数验证集 mAP 不再上涨就自动停止防止过拟合。batch受显存限制单卡 12G 用yolov8s跑 640 输入batch16 是安全值想跑更大先看显存和训练时间的对比再决定。MMAction2 用配置文件控制超参最常改的三项是clip_len、num_clips、batch_size。其中clip_len8表示每个训练样本采样 8 帧num_clips3表示测试时抽 3 段取平均分。测试多段投票能显著提高动作分类的稳定性这里是真实项目中常用的 trick# 在 TSN 配置文件中定位 train_dataloader 和 model 参数 train_dataloader dict( batch_size8, # 每卡 batch 大小8 帧输入下 12G 显存可以跑 16 num_workers4, samplerdict(typeDefaultSampler, shuffleTrue), ) model dict( typeRecognizer2D, backbonedict(typeResNet, depth50), cls_headdict( typeTSNHead, num_classes4, # 你的动作类别数 in_channels2048, spatial_typeavg, consensusdict(typeAvgConsensus, dim1), dropout_ratio0.5, ), )新手最容易踩的坑是把num_classes忘记改成自己的类别数直接沿用 kinetics400 的 400 类结果分类头输出维度不匹配训练直接报错。另一个常见问题是dropout_ratio设得太小比如 0.1行人动作数据量通常不大容易过拟合我一般设 0.5 或 0.6。训练命令一行就够了:cd mmaction2 python tools/train.py configs/recognition/tsn/tsn_r50_1x1x3_100e_kinetics400_rgb.py \ --work-dir work_dirs/tsn_custom训练完之后的评估别急着看精度先找几段验证集视频手动跑一遍推理看预测结果和标注是不是对得上。很多时候指标是好的但模型学到的是背景特征不是动作本身这时候手动看一眼结果比任何指标都管用。5. 避坑合集版本、显存与标注这三个老大难5.1 现象import mmaction报No module named mmcv但 mmcv 明明装过原因mmaction2用的是源码安装它的setup.py里面依赖的mmcv版本段位只认某个区间而你可能装的是mmcv-lite或版本不匹配的mmcv。mmcv和mmcv-lite是两个不同包前者包含编译好的 CUDA 算子后者是纯 Python 实现mmaction2要求完整版 mmcv。解决先卸载干净再重装卸载时要把两个名字都卸载掉。pip uninstall mmcv mmcv-lite -y pip install mmcv2.1.0 -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html装完之后立刻做一次完整导入测试不要等跑训练才暴露问题。顺手把mmcv.__version__和torch.__version__打印出来确认和官方推荐的对应表一致。5.2 现象MMAction2 训练或推理时 CUDA out of memory明明 batch 已经很小了原因显存爆炸往往不是 batch 太大而是clip_len、num_clips和输入分辨率同时堆叠。TSN 的输入是 8 帧 × 3 通道 × 224 × 224但 ResNet50 的中间 feature map 在 224 输入下占用相当可观。单卡 12G 跑 8 帧 TSNbatch32 可以但如果把crop_size从 224 改成 320显存占用会翻一倍以上。解决先看一眼自己的输入尺寸。crop_size保持 224 别动优先调节 batch 到 8 或 16确认显存余量后再往上加。还有一种情况是开了torch.backends.cudnn.benchmark,它会在前几个 iteration 做 auto-tune这时候显存会突然冲高等跑完第一个 step 会降回来不是真实占用不用慌。5.3 现象YOLOv8 检测框很小远距离行人送进 MMAction2 识别结果一团糟原因行人离摄像头远时裁剪出来的图可能只有 60×120 像素直接 resize 到 224×224 会严重拉伸变形而且原图本来就信息不足。MMAction2 在 kinetics400 上预训练时的输入分布是“全身动作占据画面主体”的短视频和你从检测框裁剪出来的小图分布差异很大模型按原训练集的统计量做推理结果自然离谱。解决限制检测框的最小宽高比如小于 80 像素的框直接丢弃不要送进动作识别。另外一个常见做法是把裁剪图做边缘填充再 resize 到 224而不是直接拉伸。下面这段是填充示例def crop_with_padding(frame, box, target_size224): x1, y1, x2, y2 [int(v) for v in box] # 限制框不能超出画面边界 x1, y1 max(0, x1), max(0, y1) x2, y2 min(frame.shape[1], x2), min(frame.shape[0], y2) crop frame[y1:y2, x1:x2] h, w crop.shape[:2] # 长边缩放到 target_size短边用边缘像素填充 scale target_size / max(h, w) new_w, new_h int(w * scale), int(h * scale) resized cv2.resize(crop, (new_w, new_h)) pad_w target_size - new_w pad_h target_size - new_h padded cv2.copyMakeBorder( resized, pad_h // 2, pad_h - pad_h // 2, pad_w // 2, pad_w - pad_w // 2, cv2.BORDER_REPLICATE ) return padded用BORDER_REPLICATE做边缘填充而不是BORDER_CONSTANT填充纯色是因为模型预训练时见过自然图像的纹理纯色填充会引入分布外的像素。这一步改完远距离行人的识别准确率能提好几个点。5.4 现象训练时 loss 不降val loss 一开始就很高原因标注文件里的类别索引和模型配置里的num_classes对不上或者标注的时间段没有对齐。MMAction2 的标注是按“帧号区间”标动作的如果你的视频抽帧是 25fps但标注工具用的是视频原始时间戳换算两边不一致模型看到的同一段动作有时在标签里是“走路”有时是“站立”它根本无法学。解决写一个脚本把标注区间重放回视频上逐帧检查。比如找 5 个标注样本按标注的起始帧和结束帧裁剪出实际片段人眼确认内容与标签一致。这一步在训练前做不要等 loss 不对了再回来查。还有一个小坑MMAction2 默认的采样方式是从 clip 长度均匀取clip_len帧如果动作发生时间很短比如跌倒只有 1 秒8 帧采样可能只采到 4 帧有效动作识别效果就差可以考虑把clip_len降到 4 或 6。5.5 现象训练和推理正常但实时视频里动作切换“抖”得厉害原因单次 clip 分类没有做时间平滑相邻 0.5 秒的两个 clip 可能一次预测“走路”一次预测“站立”。这在监控场景是最常见的观感问题。解决这类问题要把推理侧做结果聚合放最后一章详细讲。6. 把推理链路做稳的技巧帧级动作分数的时间聚合上面 5.4 提到动作切换抖动的问题实际项目里如果直接逐 clip 输出动作标签监控画面上标签会高频跳动没法看。我一般会在推理侧加一个时间状态机不直接输出每个 clip 的类别而是维护一个滑动窗口窗口内累积最近 N 次动作分类概率取平均最高的类别作为输出。from collections import deque class ActionSmoother: def __init__(self, window_size5, min_duration0.6): self.window deque(maxlenwindow_size) self.current_action None self.current_duration 0.0 self.min_duration min_duration def update(self, pred_score, frame_interval): self.window.append(pred_score) if len(self.window) self.window.maxlen: return self.current_action avg_score np.mean(self.window, axis0) action_id avg_score.argmax() # 状态机只有同一个动作累计超过阈值才切换 if action_id self.current_action: self.current_duration frame_interval elif self.current_duration self.min_duration: self.current_action action_id self.current_duration 0.0 return self.current_actionmin_duration0.6表示同一个动作必须连续保持 0.6 秒以上才允许切换标签。这样“走路”和“站立”之间即使偶尔有误判也不会导致画面上的标签反复跳变。这个状态机是我做过的项目里性价比最高的一段代码几乎零成本但体验提升非常明显。另外还习惯把检测失帧也纳入平滑考虑。YOLOv8 如果连续几帧没检测到某个行人就给这个 track 打一个丢失标记超过 30 帧没恢复就删除这个目标。这样系统不会把短暂遮挡当成“行人消失再出现”动作标签也不会断开后重连。这个只要你用 ByteTrack 这类跟踪器丢失帧数可以从跟踪器里直接拿到。这套方案做到最后稳定输出的是“第 3 个摄像头左侧第 2 个人正在攀爬围栏”这样具体的告警信息而不是一堆框和概率。每当有朋友抱怨动作识别跑起来效果差我第一句话都是先问你的检测结果有没有先过滤、后平滑、再输出把这三步补上大部分项目都能从“能跑”变成“能用”。希望帮到你。本文还有配套的精品资源点击获取