YOLOv11环境搭建与官方Demo运行

昨天深夜调试产线模型时同事突然发来消息“新到的工控机跑不动YOLOv11CUDA版本对不上产线明天要试跑。” 这种场景太熟悉了——环境配置永远是算法落地的第一道坎。今天我们就从最实际的搭建过程开始避开那些文档里没写的坑。环境准备阶段别急着pip install先看硬件。如果是英伟达显卡打开终端输入nvidia-smi查看驱动版本右上角显示的CUDA Version只是驱动支持的最高版本不是实际安装的。真正需要的是nvcc -V输出的运行时版本。这两个经常不一致我吃过亏——用11.7的驱动装了12.1的PyTorch训练时直接卡死。创建conda环境时建议用Python 3.9。3.10以后某些包兼容性有问题特别是老产线上的Ubuntu 18.04系统。名字别用yolov11这种以后可能还要装v10、v12混在一起容易乱。我习惯叫yolo_env后面加日期标签。依赖安装的细节官方requirements.txt通常比较激进直接装容易冲突。先装PyTorch去官网用命令行安装记得带上--index-url参数指定国内源。这里有个坑PyTorch的CUDA版本必须低于等于nvidia-smi显示的版本。比如显示11.7就装torch2.0.1cu117。装完一定要验证importtorchprint(torch.__version__)# 看版本对不对print(torch.cuda.is_available())# 必须返回Trueprint(torch.cuda.get_device_name(0))# 看看显卡认出来没曾经有次卡在这结果是驱动太老重装驱动才解决。其他依赖逐行安装别用pip install -r requirements.txt一把梭。看到opencv-python时注意如果要做视频流分析得装opencv-python-headless否则GUI依赖可能冲突。还有thop、tqdm这些工具包等跑通demo再补都来得及。克隆代码的讲究别在Windows下直接git clone路径分隔符问题能让你debug半天。用WSL2或者Linux实体机。仓库拉下来先看目录结构重点找detect.py和train.py这是入口文件。现在的YOLO系列喜欢把配置放yaml里models/目录下的yolov11.yaml先扫一眼了解结构就行。权重文件去官方GitHub的Release页面下载别在第三方网站下我遇到过权重被篡改导致精度掉10%的情况。下载完用md5校验这个习惯能省很多事。第一个Demo运行先别训练用detect脚本快速验证。命令这样写python detect.py--weights yolov11n.pt--source data/images/bus.jpg--device0注意几个参数--device 0指定第一块GPU如果没GPU写--device cpu--source可以接图片、视频、摄像头编号0是默认摄像头甚至rtsp流地址。第一次运行会下载预训练模型如果慢就手动把权重文件放到提示的路径。运行成功会在runs/detect/下生成结果。如果报错找不到模块大概率是环境路径问题在项目根目录加个空文件__init__.py试试。我遇到过PyCharm把项目根目录设成了父文件夹所有import全报错。常见报错处理“CUDA out of memory”是最常见的。别急着改batch size先看是不是有其他程序占显存。用nvidia-smi看进程有时候上次训练异常退出进程没杀干净。Linux下用kill -9 PID强制结束。“ImportError: libGL.so.1”这种是OpenCV的依赖问题装一下sudo apt install libgl1-mesa-glx。如果是docker环境基础镜像可能缺库建议用nvidia官方镜像。还有种隐蔽错误训练时loss突然变nan。先检查数据标注有没有坐标超出图像范围再检查学习率YOLOv11对学习率敏感官方配置里的lr0参数别乱改。个人经验建议环境配置本质是版本管理。用pip freeze requirements.txt导出环境但注意这会把所有包都导出最好手动整理核心依赖。生产环境推荐用Docker把基础镜像、驱动、CUDA、Python包全部固化。我们团队现在用Dockerfile私有镜像仓库新机器部署只要一条pull命令。开发机建议装两个环境一个稳定版用于部署验证一个尝鲜版试新特性。conda的environment.yml比requirements.txt好用能指定Python版本和通道。最后提醒YOLO系列更新快但别盲目追新。YOLOv11如果跑不通退回到v10或v8可能更稳。产线项目优先考虑稳定性GitHub的issue页面比官方文档更有参考价值看看别人踩过的坑能省自己很多时间。环境搭好只是第一步下次我们聊数据准备——那些标注文件里的魔鬼细节。