学生课堂专注度分析系统光听名字就知道这活儿不轻松你得把摄像头拍到的课堂画面实时变成每个学生的专注状态。人脸朝向、眼睛睁开闭上、身体姿态、头部角度这些信息要从一帧一帧的画面里提出来再交给时序模型去判断“这人是在记笔记还是在发呆”。我接到这个项目的第一件事不是写模型结构而是把环境搭明白——因为后面所有的训练、推理、调试全部压在环境上。这篇就完整记录我用YOLOv8PyTorch做专注度分析时在Windows下通过WSL2搭建整套开发环境的过程包括每个命令、每个版本的选型理由以及我踩过的坑。给正在做类似视觉分析项目、卡在环境搭建这一步的同学一个可以照抄的作业。1. 先想清楚技术路线专注度分析为什么选了YOLOv8PyTorch这套组合环境搭建不是上来就敲命令你得先知道自己在给什么项目搭环境。学生课堂专注度分析系统的完整链路是这样的摄像头采集高清画面经过目标检测模型把人脸和上半身定位出来再用姿态估计或人脸关键点模型提取细粒度特征眼睛开合度、头部欧拉角、手部动作频率最后把这些特征序列喂给一个时序分类器输出“专注/走神/瞌睡/举手”之类的状态标签。这条链路里检测和后处理部分是算力消耗的大头也是环境搭建首先要服务的对象。1.1 YOLOv8在课堂场景下到底好在哪选YOLOv8不是跟风。课堂场景有几个硬指标人多、遮挡多、姿态变化大、需要实时性。学生坐在课桌前互相遮挡非常严重后排学生人脸只有很小一块区域这对小目标检测能力要求很高。YOLOv8相比之前v5/v7系列在COCO数据集上的小目标AP值提升明显C2f模块替换了C3模块之后模型对细粒度特征的提取能力更强检测头也换成了解耦头Decoupled Head分类和回归分支互不干扰。实测下来在同样分辨率下YOLOv8s比YOLOv5s的mAP50-95高出大概3到5个点课堂密集场景下差距会更明显。另一个很实际的原因是模型文件统一。后来我们要同时训检测模型和姿态模型YOLOv8官方仓库直接内置了pose模型分支一套环境装完检测和姿态两个任务都能跑不需要再单独装OpenPose那套又老又重的依赖。这对环境搭建来说省了大事。1.2 PyTorch生态才是真正决定成败的环节检测模型其实用什么框架都行但整个系统要串联的东西太多了人脸关键点要用到OpenCV和dlib或者mediapipe时序分类要上LSTM或者Transformer数据预处理要接albumentations可视化要接matplotlib——PyTorch在这些库的兼容性上做得最平滑。TensorFlow也可以跑但版本升级带来的API断裂问题在长周期项目里面非常要命我前一个项目就吃过TF2.0到2.4大版本接口不兼容的亏。而且PyTorch的生态有一块比较隐蔽的优势和ONNX、TensorRT的转换工具链配合成熟。后期我们要把模型部署到边缘盒子或者用TensorRT做推理加速PyTorch导出的模型在兼容性上踩坑最少。这一点在做环境选型时很少有人提但在实际项目周期里非常重要。1.3 Windows开发、Linux训练WSL2是唯一的解做深度学习开发绕不开一个现实问题Windows上用PyTorch做GPU训练性能损耗很大而且很多底层编译工具链比如编译自定义CUDA算子在纯Windows环境下就是灾难。但直接装双系统切换麻烦虚拟机性能又扛不住GPU训练。WSL2Windows Subsystem for Linux version 2是折中方案里最接近完美的那个——它的架构是用轻量级虚拟机跑一个真正的Linux内核和系统调用完全兼容不像WSL1那样靠翻译层CUDA可以直接透传调用Windows侧的显卡驱动GPU训练性能损失控制在个位数百分比。从我搜的资料来看pytorch环境搭建wsl这个搜索量一直居高不下说明现在有大量的人在做同样的事。这篇文章我全程在WSL2里的Ubuntu 20.04上操作这套流程在Ubuntu 22.04上同样适用只是apt源版本略有差异。2. WSL2的搭建把Ubuntu 20.04安装并配置到能扛得住深度学习的程度很多教程一上来就让你装CUDA、装PyTorch但我见过太多人卡在前面WSL本身都没装利索。WSL2的安装有几个版本迭代Windows 10和Windows 11的步骤不完全一样这里我把完整流程和原理一起讲清楚。2.1 开启Windows虚拟化平台WSL2依赖Windows的虚拟化功能所以第一步是确认BIOS里开了虚拟化Intel VT-x或者AMD SVM然后在Windows功能里勾选“适用于Linux的Windows子系统”和“虚拟机平台”。这一步点完需要重启电脑。Windows 11用户可以直接在管理员PowerShell里执行wsl --install它会一次性装好所有需要的功能组件。Windows 10用户建议手动勾选因为自动安装脚本有时会漏掉“虚拟机平台”这一项导致后面WSL2起不来或者显示版本是1。检查是否开启成功的办法是在PowerShell里执行wsl --status如果输出里有“默认版本2”说明内核已经在走WSL2如果显示版本1需要执行wsl --set-default-version 2强制切换。2.2 安装Ubuntu 20.04发行版发行版的选择看起来是个小决定实际上影响后续所有依赖的版本。我这个项目用的很多视觉库比如libgl1、libglib2.0-0在Ubuntu 22.04的源里已经换成了更新版本反而会和老版CUDA的依赖产生冲突。Ubuntu 20.04是兼容性最稳的版本NVIDIA官方对它的Container Toolkit支持也最成熟。安装方式我建议从Microsoft Store搜索“Ubuntu 20.04”安装不要用wsl --install -d Ubuntu-20.04命令行安装。Store版本在创建用户时会引导你设置UNIX用户名和密码命令行版本有时候会跳过这个交互直接以root身份默认创建后面文件权限会乱套。装好后进入Ubuntu终端第一件事是换apt源sudo sed -i s/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list sudo apt update sudo apt upgrade -y注意如果你用的是国内网络不换源的apt update会慢到怀疑人生而且经常超时这一步千万别省。2.3 WSL2的内存和CPU配置优化WSL2默认的内存配额是宿主机内存的一半CPU核数不限磁盘空间支持动态扩容。但对深度学习这种动辄占几十GB显存和内存的负载来说默认配置并不合理。我需要手动创建C盘用户目录下或者用\\wsl$\访问也行的.wslconfig文件路径是C:\Users\你的用户名\.wslconfig。[wsl2] memory16GB processors8 swap8GB localhostForwardingtrue这里memory建议给到物理内存的一半以上但不能全给否则Windows本体卡死。swap设到8GB是为了防止某个数据集加载瞬间内存爆掉。改完这个文件之后在PowerShell里执行wsl --shutdown再重新进入Ubuntu配置才会生效。还有一个很多人不知道的优化点WSL2的虚拟磁盘文件ext4.vhdx默认放在C盘C盘空间紧张会导致磁盘扩容失败或者性能骤降。通过wsl --export和wsl --import可以把整个发行版迁移到D盘具体命令是wsl --export Ubuntu-20.04 D:\wsl\ubuntu.tar wsl --unregister Ubuntu-20.04 wsl --import Ubuntu-20.04 D:\wsl\ubuntu D:\wsl\ubuntu.tar注意用--import方式迁移后的默认用户会变成root需要再单独用ubuntu2004.exe config --default-user 用户名恢复普通用户身份否则后面所有文件操作都要加sudo很闹心。2.4 在WSL2里配置必要的开发工具链深度学习环境不是光有conda就完事系统层面的编译工具链必须先装好。PyTorch在安装时会编译一些C扩展比如后面要装Torchvision的某些算子没有GCC的裸环境会直接报错。我习惯在装任何Python库之前先把这些系统依赖一次装齐sudo apt install -y build-essential gcc g make cmake git wget curl sudo apt install -y libgl1 libglib2.0-0 libsm6 libxrender1 libxext6 sudo apt install -y libopenblas-dev libatlas-base-dev liblapack-devlibgl1和libglib2.0-0这两个是OpenCV的运行时依赖不装的话后面import cv2必报libGL.so.1: cannot open shared object file错误。这个错误在深度学习环境搭建里出现频率极高几乎是新手致命的第一个坑提前装好能省一次排错。3. GPU驱动和CUDA版本匹配专为PyTorch训练做的一套底层层环境搭建的核心风险集中在GPU这一层。CUDA工具包的版本和PyTorch的预编译版本必须对齐差一个版本小版本都会出现torch.cuda.is_available()返回False这种让人抓狂的情况。3.1 显卡驱动在WSL2里的特殊性首先必须明确WSL2里不需要安装Linux版NVIDIA驱动。WSL2的GPU透传机制是直接把Windows侧的GPU驱动映射进Linux内核的所以Windows宿主机上只要装了较新的NVIDIA驱动建议460版本以上WSL2里执行nvidia-smi就能直接看到显卡信息。这一步经常会有人搞错在Ubuntu里跑sudo apt install nvidia-driver-xxx结果装坏了整个WSL2的内核模块最后只能重置发行版。验证驱动是否透传成功nvidia-smi如果输出正常显示显卡型号和驱动版本恭喜底层GPU通路已经通了。版本号建议记录一下后面选CUDA版本要用。3.2 CUDA工具包和cuDNN的版本选型逻辑PyTorch各版本对CUDA版本有明确对应关系比如PyTorch 2.x系列同时支持CUDA 11.8和12.1两个分支。我个人的选型原则是选PyTorch官方预编译里标注为“stable”的那一档CUDA版本不要追最新也不要用老掉牙的版本。截至本文写作时间PyTorch 2.1.0对应CUDA 11.8/12.1均稳定我用的是CUDA 11.8因为它在WSL2里的兼容记录最干净TensorRT配套的转件也支持得最全。安装CUDA Toolkit时NVIDIA官网给的命令是一套runfile安装方式但在WSL2里并不推荐。WSL2环境里只需要装CUDA Toolkit这个开发工具包不需要装驱动模块用runfile安装时切记加--toolkit参数wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run --toolkit --silent装完后配置环境变量echo export PATH/usr/local/cuda-11.8/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc nvcc --versioncuDNN的安装也不复杂去NVIDIA官网下载适配CUDA 11.8的cuDNN 8.9.x版本按照安装包的tar文件解压后复制到CUDA目录即可。3.3 创建conda虚拟环境隔离才是环境搭建的核心课题深度学习项目的依赖管理必须用虚拟环境这是一个老生常谈但又总有人忽略的问题。同一个机器上不同项目要求的PyTorch版本、OpenCV版本可能截然不同全装在base环境里到后期升级依赖就是一场灾难。我用miniconda而不是Anaconda因为Anaconda预装了一堆我用不到的包体积大而且容易带进来不兼容的传递依赖。wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-py39_23.3.1-0-Linux-x86_64.sh bash Miniconda3-py39_23.3.1-0-Linux-x86_64.sh安装完conda之后配好清华源然后创建项目专用的环境。这个环境对应项目标题里的系统名我直接取名叫attentionconda create -n attention python3.9 -y conda activate attentionPython版本选3.9而不是最新的3.11是因为PyTorch虽然已经在跟进新版本但很多相关的视觉库比如某些老版本的OpenCV、dlib在3.10以上的编译支持不完全。3.9是生态兼容性最平衡的选择。3.4 安装PyTorch和TorchvisionPyTorch的安装是环境搭建的分水岭——装好了后面所有东西都能跑装坏了你会在各种报错里挣扎一整晚。官方给出的conda安装命令是conda install pytorch2.1.0 torchvision0.16.0 torchaudio2.1.0 pytorch-cuda11.8 -c pytorch -c nvidia但是直接执行这个命令在国内容易因为访问外网下载慢而失败。我的做法是先在conda源里配置好PyTorch的国内镜像再把安装命令跑通。配置~/.condarc文件添加pytorch的镜像通道然后执行上述安装命令时去掉-c pytorch -c nvidia参数让它走镜像源。装完之后立刻验证GPU可用性python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))正确的输出应该类似2.1.0、True、NVIDIA GeForce RTX 3060之类的显卡型号。如果is_available()返回了False不要急着怀疑安装过程先检查前面nvidia-smi是否能正常工作。大概率是驱动透传问题或者CUDA环境变量没刷新生效。4. 项目骨架搭建把课堂专注度分析系统需要的依赖一次装齐环境搭建的下一个环节是围绕项目本身去准备代码和依赖。这个项目虽然叫“专注度分析”但最底层的模块是目标检测和姿态估计所以我会把ultralyticsYOLOv8的官方仓库作为核心依赖再铺开其他工具库。4.1 核心依赖清单和安装命令进入虚拟环境在项目目录下执行安装。这里我强调一下所有项目依赖都要在虚拟环境里装不要用sudo pip去装系统的Python包那样会把环境搞得一塌糊涂。pip install ultralytics pip install opencv-python pip install albumentations pip install onnx onnxruntime pip install scikit-learn scipy matplotlib pandas pip install tqdm tensorboardultralytics这个包很厚道它会帮你把torch、torchvision、opencv、numpy等一堆基础依赖自动拉进来版本兼容性管理得比我自己手动装要稳妥得多。装完opencv-python之后跑一下python -c import cv2; print(cv2.__version__)验证一下。很多人在这一步会卡在libGL.so.1的报错上如果你前面按照第2.4节装了libgl1 libglib2.0-0这里应该一次通过。4.2 设计项目目录结构环境搭建不只是装库一个条理清晰的项目目录结构是环境搭建的一部分它决定了后面数据怎么组织、训练日志往哪里写、模型权重存哪里。我自己用的是这套目录结构attention_analysis_system/ ├── data/ │ ├── raw/ # 原始课堂视频数据 │ ├── annotations/ # 标注文件 │ └── processed/ # 预处理后的数据 ├── models/ # 训练好的权重文件 │ ├── detection/ # 检测模型权重 │ └── pose/ # 姿态模型权重 ├── configs/ # 所有配置文件 │ ├── dataset.yaml # 数据集配置 │ └── train.yaml # 训练超参数配置 ├── scripts/ # 数据处理脚本 ├── src/ # 核心代码 │ ├── detection/ # 检测相关 │ ├── pose/ # 姿态估计相关 │ ├── attention/ # 专注度分析逻辑 │ └── utils/ # 工具函数 └── runs/ # 训练和推理的输出这套结构的好处是数据、代码、输出彻底分离训练过程产生的日志和权重不会污染代码目录。配合YOLOv8自带的推理输出文件夹也不冲突。4.3 跑通第一个YOLOv8推理Demo环境搭得对不对拿一个真实模型跑一遍推理是最直接的验证。YOLOv8官方仓库里带了预训练权重下载一个yolov8n.pt在公开视频上做目标检测测试from ultralytics import YOLO model YOLO(yolov8n.pt) results model.predict(sourcehttps://ultralytics.com/images/bus.jpg, saveTrue, projectruns/inference, namedemo)如果环境正常几秒钟之后就能在runs/inference/demo/目录看到带检测框标注的输出图片。这一步验证的不只是YOLOv8能不能跑真正验证的是OpenCV读取图像、NumPy数组处理、PyTorch张量推理这一整条数据流水线是否通畅。跑通检测Demo后顺手验证姿态模型model YOLO(yolov8n-pose.pt) results model.predict(sourcehttps://ultralytics.com/images/bus.jpg, saveTrue, projectruns/inference/pose_demo)姿态模型能跑通意味着后续提取人脸关键点和身体关键点这条主线是从底层就通的。4.4 数据预处理依赖的补充聚焦课堂视频场景课堂场景的视频流有自己的特点长时间连续、码率高、分辨率大。后面做数据预处理会大量用到视频抽帧、图片缩放、数据增强这些操作。这部分在环境上就要提前备好工具库pip install ffmpeg-python imageio imageio-ffmpeg sudo apt install -y ffmpegffmpeg在Linux上的安装尤其要提醒一下在WSL2里直接sudo apt install ffmpeg装的是系统版本imageio-ffmpeg则会自带一个独立可执行文件两者并存有时候会导致编码器冲突。我的经验是优先让imageio-ffmpeg接管Python侧的调用系统级ffmpeg只在命令行做视频切割或转码时用两边不要混着调用同一个文件。5. 搭建过程中的问题排查记录我在这个环境上踩过的坑环境搭建最大的特点就是确定性低明明照着教程一步步来就是有人会翻车。这部分我把自己在这次搭建中真实遇到的几个问题完整记录下来包括排查思路和最终解法希望你能直接绕过去。5.1 问题一torch.cuda.is_available()返回False现象是PyTorch装好后GPU抱怨连接不上。排查链路是这样的先跑nvidia-smi确认显卡驱动正常透传再跑nvcc --version确认CUDA工具包版本和PyTorch编译的CUDA版本一致——装的是CUDA 11.8PyTorch也必须选pytorch-cuda11.8这个变体最后检查conda环境里是否有多个CUDA相关的环境变量残留。最后定位是.bashrc里导出的CUDA路径和conda环境冲突把LD_LIBRARY_PATH里手动添加的路径注释掉重启终端后恢复正常。这个过程教会我的一个判断逻辑是nvidia-smi输出的是驱动支持的CUDA最高版本而这个数字是上限而不是当前生效版本。PyTorch真正用的是自己编译时的CUDA Runtime库两者数字不一定要一样但PyTorch的Runtime版本不能超过驱动支持上限。很多教程把这两者混为一谈是各种误判的根源。5.2 问题二libGL.so.1缺失导致OpenCV无法导入这个问题在新装的Ubuntu 20.04 WSL2环境里几乎必现。报错内容长这样ImportError: libGL.so.1: cannot open shared object file: No such file or directory根因是OpenCV的Python包依赖了系统的OpenGL库但干净的Ubuntu默认不装。解法是sudo apt install -y libgl1 libglib2.0-0。这个坑我在第2.4节已经提前打了预防针但如果你没装到那一步这里再补一次。5.3 问题三YOLOv8训练时内存溢出OOM课堂场景数据集图片分辨率高YOLOv8训练时batch size稍大就会把16GB内存吃满。排查发现WSL2默认分配的内存才宿主机一半而且.wslconfig设置没生效——原因是文件放到了错误的用户目录。WSL2读取的是Windows当前登录用户目录下的.wslconfig不是Linux侧的/home目录。修正后重新wsl --shutdown再进内存配额变成16GB训练基本稳定。5.4 问题四pip install ultralytics很慢或卡死国内网络环境下装任何大型Python包都会遇到这个问题。解法是配置pip镜像源pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pip/simple紧接着还有个细节YOLOv8下载预训练权重时走的是 GitHub 的 release 地址国内访问极不稳定。我的做法是手动下载yolov8n.pt文件和yolov8n-pose.pt文件放到models/目录下再用YOLO(models/yolov8n.pt)指定路径加载绕开自动下载。5.5 问题五conda激活环境后命令行出现(base)想删掉这个不算报错但容易让人困惑。WSL2里安装Miniconda后每次打开终端都会自动进入base环境对并不需要默认激活的人来说很烦。执行conda config --set auto_activate_base false然后重新打开终端即可。还有一个提升日常用感的配置把conda和pip的默认缓存目录从系统盘挪到数据盘避免Cache占满C盘。原理和WSL2迁移是一样的环境搭建阶段多花十分钟后面能省出一堆磁盘空间。6. 自检清单环境搭建到什么程度算真正完成很多人在装完PyTorch之后就觉得环境搭建任务结束了实际上后面模型一跑就会出现问题。我给自己定了一个自检清单从底层往上逐项验收每项都通过才敢说环境是合格的。检查层级检查命令/代码期望结果系统层uname -aLinux 5.x及以上内核GPU层nvidia-smi正常显示显卡型号和驱动CUDA层nvcc --version显示CUDA 11.8Python层python --version3.9.xPyTorch层python -c import torch; print(torch.cuda.is_available())TrueOpenCV层python -c import cv2; print(cv2.__version__)无报错YOLO层运行一次推理Demo输出带检测框的图片数据层python -c import albumentations, onnx, tensorboard全部无报错每一项都过完这套环境才真正具备了启动项目开发的条件。我遇到过不少人前面几步全过但到YOLO推理Demo这一步卡了好几天就是因为在OpenCV或者权重下载这些细节上翻车。自检之后还有一类容易被忽略的工作是给后面协作的人写README。不管你是自己做还是团队一起做把上述所有安装步骤、版本号和坑位整理成一个ENV.md文件放进项目根目录能省掉大量“你环境怎么配的”这类沟通成本。我每次都写因为搭过一遍环境的人都懂记忆并不可靠文档才是真的。7. 一些实战心得环境搭建的心态与节奏最后聊聊这次的体会。第一环境搭建不要一口气全装完再验证。最好的节奏是每装一个关键节点就立刻验证比如装完CUDA就验nvcc装完PyTorch就验GPU可用性装完OpenCV就验导入全部通过再进入下一层。一旦哪一步失败排查范围能立刻锁定在那一个环节而不是要从头开始猜。第二版本锁定是环境搭建的灵魂。我安装时把conda环境里所有关键包写进了一个requirements-lock.txtpip freeze requirements-lock.txt后面不管是重装环境还是给同事复现直接照着这个文件恢复版本完全一致避免了“在我机器上明明能跑”的经典甩锅现场。第三WSL2无论多方便它依然不是物理Linux。如果你后面要做对硬件延迟极其敏感的实时视频处理或者要直接操作多个USB摄像头做多路采集建议在开发环境稳定后再准备一台物理Linux服务器做正式训练和推理测试。WSL2适合开发和调试真正的生产环境还是要跑在裸Linux上这一点项目初期就应该想清楚。