1. 环境配置搭建你的第一个骨骼动作识别“厨房”想自己动手训练一个能看懂视频里人在做什么的AI模型吗比如识别一段视频里是“打篮球”还是“游泳”听起来很酷但一想到要配置环境、安装各种依赖库是不是头都大了别担心我刚开始接触pyskl和poseC3D的时候也这么觉得踩了不少坑。今天我就把这一路走来的经验掰开揉碎了讲给你听保证你也能从零开始把环境搭起来。首先你得明白我们这套“厨房”的基石是什么。pyskl是一个基于OpenMMLab生态特别是MMDetection和MMPose的骨骼动作识别工具箱而poseC3D是它的核心“菜谱”——一种基于3D卷积的骨骼序列识别算法。所以搭建环境的第一步不是直接装pyskl而是先把它的“地基”打好也就是MMDetection和MMPose。我实测下来最稳的版本搭配是这样的PyTorch版本最好在1.5.0到1.11.0之间。太新的版本可能会有兼容性问题我试过1.12编译的时候就报了一堆错。MMCV和MMCV-Full这两个是关键版本要对应。我推荐用1.3.18。MMDetection用2.23.0这个版本。MMPose用0.24.0。为什么强调版本因为开源社区迭代快新版本API常有变动。我一开始图省事直接pip install mmdet装了最新版结果跑pyskl的demo时各种函数找不到折腾了半天才发现是版本不匹配。所以老老实实用我上面给的版本号能帮你省下至少半天的时间。安装命令很简单但顺序有讲究。我建议你打开终端按这个顺序来# 1. 创建并激活一个conda环境强烈推荐方便管理 conda create -n pyskl python3.8 conda activate pyskl # 2. 安装PyTorch请根据你的CUDA版本去官网获取对应命令这里以CUDA 11.3为例 pip install torch1.10.0cu113 torchvision0.11.1cu113 torchaudio0.10.0cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html # 3. 安装MMCV和MMDetection pip install mmcv-full1.3.18 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10.0/index.html pip install mmdet2.23.0 # 4. 安装MMPose pip install mmpose0.24.0这里有个小坑要注意MMCV-Full必须通过指定下载链接的方式安装直接pip install mmcv-full可能会装成不包含CUDA扩展的版本导致后续无法使用GPU加速。地基打好了我们再来安装“厨房”本身——pyskl。这个过程就顺畅多了git clone https://github.com/kennymckormick/pyskl.git cd pyskl pip install -r requirements.txt pip install -e .最后一步pip install -e .是以“可编辑”模式安装这样你修改项目里的任何代码都能立刻生效对于后续调试非常方便。环境装完怎么验证成功了呢跑一下官方提供的demo脚本是最快的办法python demo/demo_skeleton.py demo/ntu_sample.avi demo/demo.mp4如果一切顺利你会看到终端刷刷刷地跑日志最后在当前目录生成一个demo.mp4文件。用播放器打开它你会发现视频上的人被画上了骨骼点并且左上角显示了预测的动作类别。恭喜你你的“厨房”开火成功可以开始准备“食材”数据了1.1 避坑指南常见环境报错与解决我敢打赌90%的新手都会在这里遇到一两个问题。别慌我把最常见的几个坑和填坑方法列出来你大概率用得上。问题一ModuleNotFoundError: No module named ‘mmcv._ext‘这通常是因为MMCV-Full没有安装成功或者安装的版本不对。请务必使用上面提到的带CUDA版本和PyTorch版本号的完整安装命令。如果你不确定可以pip list查看已安装的mmcv-full版本。问题二编译Detectron2时卡住或报错pyskl的依赖里虽然没有明确要求Detectron2但MMDetection的某些后端可能会用到。如果你在安装或后续运行中遇到相关错误可以手动安装一下python -m pip install githttps://github.com/facebookresearch/detectron2.git如果网络不好clone不下来可以去GitHub下载zip包然后进入目录用pip install -e .安装。问题三CUDA out of memory跑demo时如果显存不够可以尝试在demo脚本里找到模型加载的地方把设备从‘cuda‘改成‘cpu‘。当然这样会慢很多但至少能验证流程是否通。正式训练时你还是需要一张足够显存的GPU至少8G推荐11G以上。记住环境配置是万里长征第一步也是最磨人的一步。一旦跨过去后面就是一马平川了。如果遇到上面没提到的问题别急着放弃把完整的错误信息复制下来去项目的GitHub Issues里搜一搜大概率已经有解决方案了。2. 数据准备给你的模型准备“定制食谱”环境好了模型架子搭起来了现在最关键的来了——数据。模型就像个小孩你喂它什么它就学什么。你想让它认识“太极拳”和“广场舞”的区别就得准备相应的视频数据。这一部分是整个过程里最需要耐心和细心的也是最容易出错的环节。pyskl官方支持的数据格式是一种特殊的.pkl文件里面包含了视频的骨骼关键点序列和标签。但我们的原始数据通常是一堆.mp4或.avi视频文件。所以核心任务就是把一堆视频文件转换成pyskl能吃的.pkl文件。整个流程可以拆解成三步整理视频和标签把视频文件按训练集、验证集放好并生成记录它们路径和标签的文本文件。提取骨骼关键点调用MMDetection和MMPose从每一帧视频里检测出人并提取出17个关键点鼻子、眼睛、肩膀、手肘、手腕、髋部、膝盖、脚踝。打包成pkl把所有的关键点序列和对应的标签打包成最终的.pkl数据集文件。2.1 第一步组织你的视频文件与标签列表我建议你按这样的目录结构来组织数据pyskl_data/ ├── train_label_list.txt ├── val_label_list.txt ├── videos/ │ ├── train/ │ │ ├── 打篮球_01.mp4 │ │ ├── 游泳_01.mp4 │ │ └── ... │ └── val/ │ ├── 打篮球_02.mp4 │ └── 游泳_02.mp4videos/train/和videos/val/下面直接放视频文件。这里有个超级实用的小技巧给视频文件命名时直接把标签作为文件名的一部分。比如打篮球_01.mp4游泳_03.mp4。这样后面生成标签列表时会非常简单。接下来生成两个关键的文本文件train_label_list.txt和val_label_list.txt。它们的格式是每一行代表一个样本视频文件的绝对路径 标签数字例如/home/yourname/pyskl_data/videos/train/打篮球_01.mp4 0 /home/yourname/pyskl_data/videos/train/游泳_01.mp4 1标签数字从0开始连续编号。你可以手动写但如果视频多最好写个Python脚本。我常用的脚本是这样的import os def generate_label_list(video_dir, output_file): video_dir: 存放视频的文件夹例如 ‘videos/train/‘ output_file: 输出的标签文件路径例如 ‘train_label_list.txt‘ video_files os.listdir(video_dir) with open(output_file, w) as f: for vf in video_files: # 假设文件名格式为类别名_编号.mp4 # 我们通过下划线分割取第一部分作为类别名 # 你需要根据自己文件名的实际情况修改这里的逻辑 class_name vf.split(_)[0] # 这里需要一个映射类别名 - 数字标签 # 例如{‘打篮球‘: 0, ‘游泳‘: 1} label_map {‘打篮球‘: 0, ‘游泳‘: 1} # 请根据你的类别修改 label label_map.get(class_name, -1) # 如果找不到给-1 if label ! -1: full_path os.path.join(os.path.abspath(video_dir), vf) f.write(f{full_path} {label}\n) else: print(f警告文件 {vf} 的类别无法识别已跳过。) # 使用示例 generate_label_list(‘pyskl_data/videos/train/‘, ‘pyskl_data/train_label_list.txt‘) generate_label_list(‘pyskl_data/videos/val/‘, ‘pyskl_data/val_label_list.txt‘)注意这个脚本只是个示例核心逻辑是根据你的文件名提取出类别名再映射成数字。你的文件名规则可能不同一定要修改class_name vf.split(‘_‘)[0]这一行来适应你的命名方式。2.2 第二步运行关键点提取脚本最易踩坑环节这是数据准备的核心也是我踩坑最多的地方。pyskl项目里提供了一个脚本tools/data/custom_2d_skeleton.py它就是用来干这个的。你需要准备好预训练的人体检测和关键点检测模型。首先下载模型权重。在pyskl项目根目录下mkdir -p weights cd weights # 下载Faster R-CNN检测模型 wget https://download.openmmlab.com/mmdetection/v2.0/faster_rcnn/faster_rcnn_r50_fpn_2x_coco/faster_rcnn_r50_fpn_2x_coco_bbox_mAP-0.384_20200504_210434-a5d8aa15.pth # 下载HRNet关键点检测模型 wget https://download.openmmlab.com/mmpose/top_down/hrnet/hrnet_w32_coco_256x192-c78dce93_20200708.pth cd ..然后运行提取脚本。命令看起来很简单python tools/data/custom_2d_skeleton.py \ --video-list pyskl_data/train_label_list.txt \ --out pyskl_data/train_annotations.pkl但就是这里我遇到了三个大坑。坑一分布式环境变量错误脚本默认是为分布式训练环境写的如果你只有一张显卡大多数个人开发者的情况直接运行会报KeyError: ‘RANK‘。你需要修改custom_2d_skeleton.py脚本。找到parse_args()函数后面main()函数开头附近有几行关于分布式初始化的代码把它们注释掉# 注释掉下面这几行 # if ‘RANK‘ not in os.environ: # os.environ[‘RANK‘] str(args.local_rank) # os.environ[‘WORLD_SIZE‘] str(1) # os.environ[‘MASTER_ADDR‘] ‘localhost‘ # os.environ[‘MASTER_PORT‘] ‘12345‘ # init_dist(‘pytorch‘, backend‘nccl‘) # rank, world_size get_dist_info() # ... # dist.barrier()同时把后面循环处理数据部分的my_part annos[rank::world_size]改成my_part annos确保处理全部数据。坑二数组维度错误这是最诡异的一个错误报错信息是IndexError: too many indices for array: array is 1-dimensional, but 2 were indexed。问题出在pose_inference函数里。当某一张图片里检测到多个人时检测框d的维度是(N, 5)但当只检测到一个人时它可能被处理成了(5,)的一维数组导致后续索引出错。解决方法是在pose_inference函数内部对d进行维度检查和处理。找到for i, (f, d) in enumerate(zip(frames, det_results)):这行在它下面添加# 确保d是二维数组形状为 [N, 5] if d.ndim 1: d d.reshape(1, -1) # 从 (5,) 变成 (1, 5)坑三路径和配置问题确保--det-config和--pose-config指向的配置文件路径是正确的。它们默认在demo/目录下。如果你的pyskl项目结构不同需要指定绝对路径或相对路径。同样模型权重路径--det-ckpt和--pose-ckpt也要确保正确。成功运行后你会得到train_annotations.pkl和val_annotations.pkl需要对验证集再运行一次。这两个文件包含了所有视频的骨骼序列是后续训练的“食材精华”。3. 模型训练启动你的“AI厨师”数据准备好了终于到了最激动人心的训练环节。你可以把训练想象成教一个厨师做菜我们已经有切配好的食材pkl数据现在需要告诉厨师用什么火候学习率、炒多久训练轮数。pyskl提供了很多预定义的配置文件在configs/目录下。对于自定义数据集一个不错的起点是configs/posec3d/slowonly_r50_ntu120_xsub/joint.py这个配置它是在NTU RGBD 120数据集上训练的一个比较通用的配置。但我们不能直接用需要根据我们的数据集进行修改。我建议你复制一份出来修改cp configs/posec3d/slowonly_r50_ntu120_xsub/joint.py configs/posec3d/my_custom_dataset.py然后用文本编辑器打开my_custom_dataset.py重点关注以下几个部分数据集路径和类别数找到data字典修改train和val的ann_file路径指向你生成的.pkl文件。同时修改num_classes为你的动作类别总数比如你只有“打篮球”和“游泳”那就是2。data dict( videos_per_gpu32, # 根据你的GPU显存调整越小越省显存 workers_per_gpu2, traindict( typedataset_type, ann_file‘你的路径/pyskl_data/train_annotations.pkl‘, # 修改这里 ... # 其他参数通常不用动 ), valdict( typedataset_type, ann_file‘你的路径/pyskl_data/val_annotations.pkl‘, # 修改这里 ... # 其他参数通常不用动 ), testdict(...) # 通常和val一样 ) # 在文件靠前的位置找到 num_classes 并修改 model dict( cls_headdict( num_classes2, # 修改为你的类别数 ...))训练策略可以调整total_epochs总训练轮数比如50、optimizer里的lr学习率新手建议从0.1开始。如果数据集很小要小心过拟合可以适当减少轮数或增加正则化。工作目录修改work_dir这是训练日志和模型权重保存的地方。配置文件改好后就可以启动训练了。如果你只有一张GPU使用以下命令python tools/train.py configs/posec3d/my_custom_dataset.py --work-dir work_dirs/my_first_training如果你有多张GPU可以使用分布式训练加速bash tools/dist_train.sh configs/posec3d/my_custom_dataset.py 2 --work-dir work_dirs/my_first_training这里的2表示使用2张GPU。训练开始后你会在终端看到类似这样的输出2023-xx-xx xx:xx:xx - pyskl - INFO - Epoch [1][20/100] lr: 1.000e-01, eta: 0:30:00, time: 0.500, data_time: 0.300, memory: 5120, top1_acc: 0.1500, top5_acc: 0.4500, loss_cls: 2.1234, loss: 2.1234重点关注top1_acc预测最准的准确率和loss损失值越低越好。一开始准确率可能很低比如0.1相当于乱猜损失值很高。随着训练进行准确率应该会慢慢上升损失值会慢慢下降。如果训练几十个epoch后准确率还在0.5以下徘徊可能就需要回头检查数据或调整模型参数了。3.1 训练监控与调试技巧训练不是设好命令就万事大吉你得学会“看火候”。看日志work_dirs/my_first_training/目录下会生成一个.log文件记录了所有训练细节。用tail -f xxx.log命令可以实时查看最新日志。看TensorBoard如果支持有些配置支持TensorBoard可视化能更直观地看到损失和准确率曲线。查看配置文件中是否有log_config里配置了TensorboardLoggerHook。理解输出lr当前学习率好的训练策略会让它逐渐变小。eta预计剩余训练时间。top1_acc/top5_acc对于分类任务这是最直接的性能指标。如果你的类别数少于5top5_acc可能意义不大。loss总损失。如果它剧烈震荡或变成NaN非数字说明训练不稳定可能是学习率太高或数据有问题。如果训练过程中遇到loss不下降、准确率不变的情况别急着否定模型。首先检查你的数据集标签是否正确是不是把“游泳”的视频标成了“打篮球”。其次尝试调小学习率比如从0.1调到0.01。最后可以尝试更简单的模型配置比如通道数更少的网络在小数据集上复杂模型反而容易学不好。4. 模型测试与应用尝尝“AI厨师”的手艺训练完成后模型权重会保存在work_dirs/my_first_training/下通常以epoch_x.pth命名x是轮数。我们需要用最好的那个权重通常是验证集上准确率最高的来做测试和推理。首先评估模型在验证集上的性能python tools/test.py \ configs/posec3d/my_custom_dataset.py \ work_dirs/my_first_training/epoch_50.pth \ --eval top_k_accuracy这个命令会输出模型在验证集上的top1_acc和top5_acc。这是衡量模型泛化能力的金标准。如果效果满意就可以用它来对新的、没见过的视频进行动作识别了pyskl提供了很方便的demo脚本。你需要准备一个配置文件告诉模型用哪个结构以及加载哪个权重。最简单的方法是复制一份训练用的配置文件然后只修改model部分指向训练好的权重并设置test_cfg。更直接的方法是使用他们提供的推理API。我写了一个简单的脚本示例import torch from pyskl.apis import init_recognizer, inference_recognizer # 1. 构建模型 config_file ‘configs/posec3d/my_custom_dataset.py‘ checkpoint_file ‘work_dirs/my_first_training/epoch_50.pth‘ model init_recognizer(config_file, checkpoint_file, device‘cuda:0‘) # 或用‘cpu‘ # 2. 准备待推理的视频骨骼数据 # 假设你已经有一个新视频并用之前的方法提取好了它的骨骼关键点序列 # 这里需要构建一个和训练数据格式一样的字典 # 关键点数组形状应为: (1, T, 17, 2)1代表1个人T代表帧数17个关键点2是坐标(x,y) # 关键点分数数组形状应为: (1, T, 17) import numpy as np keypoint np.random.randn(1, 300, 17, 2).astype(np.float32) # 示例随机数据请替换为真实数据 keypoint_score np.random.rand(1, 300, 17).astype(np.float32) input_data { ‘keypoint‘: keypoint, ‘keypoint_score‘: keypoint_score, ‘modality‘: ‘Pose‘, ‘total_frames‘: 300 } # 3. 进行推理 results inference_recognizer(model, input_data) # results 是一个列表每个元素是 (类别id, 得分) print(‘预测结果‘, results) # 4. 映射回类别名需要你有一个id到类名的映射字典 label_map {0: ‘打篮球‘, 1: ‘游泳‘} # 和训练时一致 pred_index results[0][0] # 取得分最高的类别id pred_label label_map[pred_index] print(f‘模型认为这个动作是{pred_label}‘)注意在实际应用中你需要先对新视频运行custom_2d_skeleton.py脚本或者集成其关键点提取功能得到骨骼数据才能喂给这个推理脚本。这构成了一个完整的 pipeline原始视频 - 骨骼关键点提取 - PoseC3D模型推理 - 动作标签。4.1 效果不佳试试这些优化思路如果你的模型在验证集上准确率不高别灰心这太正常了。机器学习项目大部分时间都在调优。你可以从以下几个方向尝试数据层面数据量这是最重要的因素。动作识别通常需要较多的数据每个类别至少准备几百个样本视频。数据质量检查关键点提取是否准确。有些视频背景复杂、人物遮挡严重会导致提取的骨骼点“飘忽”或错误。可以尝试换用更准的关键点检测模型如HRNet-W48。数据增强在配置文件中可以开启更多数据增强如随机旋转、缩放、时间上的裁剪等让模型看到更多样的数据增强泛化能力。模型层面更换主干网络PoseC3D默认使用SlowOnly-ResNet50。你可以尝试更深的网络如ResNet101或不同的3D CNN架构如X3D。调整输入长度骨骼序列的长度帧数很重要。太短可能信息不够太长则计算量大且可能包含无关信息。在配置文件中调整clip_len参数。使用骨骼“边”信息除了关节点的坐标Joint人体骨骼之间的连接Limb也包含重要信息。pyskl支持同时使用这两种模态在配置文件中设置modality‘both‘通常能提升效果。训练技巧学习率策略尝试不同的学习率衰减策略如余弦退火CosineAnnealing。标签平滑对于有噪声的标签使用标签平滑Label Smoothing可以防止模型过于自信可能提升泛化能力。更长的训练时间有时候只是训练轮数不够把total_epochs从50增加到100试试。记住调参是一个循环往复的过程修改 - 训练 - 评估 - 分析 - 再修改。每次最好只改动一个变量这样才能知道是哪个改动起了作用。做好实验记录这是你宝贵的经验财富。5. 进阶与扩展让你的模型更强大当你跑通了整个流程并且模型有了一个还不错的基础准确率后就可以考虑一些进阶操作让模型更贴合你的实际需求性能也更强。使用预训练模型进行微调这是提升小数据集性能的“大杀器”。pyskl在Model Zoo里提供了在大型数据集如NTU RGBD, Kinetics上预训练好的模型。你可以直接加载这些模型的权重然后只用自己的数据去微调fine-tune最后的分类层甚至微调整个网络。这能极大加快收敛速度并显著提升最终精度。具体做法很简单在配置文件的load_from参数里指定预训练权重的路径即可load_from ‘https://download.openmmlab.com/mmaction/pyskl/ckpt/posec3d/slowonly_r50_ntu120_xsub/joint.pth‘然后正常启动训练模型会加载这些权重作为初始值。处理多人场景我们之前的流程默认处理的是单人视频。如果你的视频里有多个人并且你想识别每个人的动作或者识别整体的交互动作比如“握手”、“拥抱”就需要更复杂的处理。这涉及到在关键点提取阶段保留检测到的多个人。在数据打包时keypoint数组的第一个维度就是人数N。在模型设计上可能需要引入注意力机制或图神经网络GNN来建模多人之间的关系。pyskl目前对多人场景的原生支持有限可能需要你自己修改数据加载和模型前处理部分。部署到实际应用训练好的模型最终要用来服务。你可以使用OpenMMLab的模型部署工具链MMDeploy将PyTorch模型转换成ONNX、TensorRT等格式从而在服务器、边缘设备甚至手机端高效运行。这涉及到模型简化、量化等一系列工程化步骤是另一个广阔的领域。尝试不同的骨骼表示PoseC3D论文里提到了几种骨骼表示法Joint关节点坐标、Bone骨骼向量即关节点间的向量、Limb肢体长度和方向。你可以尝试不同的组合比如同时输入Joint和Bone信息看看哪个对你的任务最有效。在pyskl的配置文件中可以通过modality和num_clips等参数进行设置。走到这一步你已经不再是一个简单的工具使用者了。你开始思考如何针对具体问题优化流程如何结合最新研究改进模型。这个过程可能会遇到更棘手的问题但解决问题的过程正是你从“会用”到“精通”的蜕变之路。我自己的项目就从最基础的版本开始通过引入预训练、调整数据增强、修改网络结构一步步把准确率从70%提到了90%以上。这其中的成就感远大于简单地跑通一个demo。