简介面向计算机视觉研究者与开发者的 YOLOv8 实例分割与目标检测完整工程包聚焦从模型训练到部署的全流程落地适合希望快速验证算法、搭建产品原型或开展科研实验的中高级技术人员。压缩包共 788 个文件约 26.63MB以 173 个 Python 脚本和 347 个 Markdown 文档为主体配合 75 个 YAML 配置、预训练权重与 ONNX 模型以及 Dockerfile、C 推理源码和示例图片覆盖训练、推理、导出与多环境部署环节。已有 528 人学习下载在目标检测与实例分割实践中具备一定参考价值也反映出该工程包受关注程度。包内提供预训练模型、数据集示例、训练脚本和文档指南读者可据此理解配置组织、掌握自定义数据训练与模型导出方法并参考 C 推理与容器化文件完成部署验证目录组织清晰便于按模块检索可减少环境搭建和流程串联中的试错成本。1. 从一份 rar 开始YOLOv8 最容易骗人的地方是「装完了」第一次在一台新机器上装 YOLOv8 做实例分割最容易被误导的不是安装过程而是安装结果。pip install ultralytics一路正常from ultralytics import YOLO也不报错等到真正开始训练才在第一个 epoch 前面卡住或者干脆让 GPU 闲置用 CPU 慢慢跑。这套「人工智能项目 YOLOv8 实例分割 目标检测 模型训练部署」的工程包难点从来不在代码而在环境显卡驱动、CUDA、PyTorch、ultralytics 四层版本必须对齐任何一层差一个小版本报错信息都可能指向完全无关的地方。下面按我自己装机的顺序走一遍适合刚拿到压缩包、准备从零跑通训练和推理的人。2. 环境清单与版本对齐Python 3.10 PyTorch 2.1 CUDA 11.8 怎么定动手之前先把版本定下来这一步省下来的时间比后面调参多得多。YOLOv8 本身对版本不算苛刻官方只要求 Python 3.8 以上、PyTorch 1.8 以上但这是「能跑」的下限不是「跑得舒服」的下限。目标检测和实例分割要处理大量图片解码、数据增强和 mask 计算Python 3.8/3.9 在部分依赖上已经开始遇到 wheel 缺失的问题Python 3.12 又太新个别包还没跟上。我一般固定在 Python 3.10属于既稳又有完整预编译包的区间。2.1 驱动、CUDA、PyTorch 是三层而不是一层很多人会把nvidia-smi右上角显示的CUDA Version: 12.2理解成「本机装了 CUDA 12.2」然后在 PyTorch 官网照着这个数字选安装命令结果装完torch.cuda.is_available()还是 False。这里有三个独立的东西第一层是显卡驱动nvidia-smi显示的 CUDA Version 是「这个驱动最高能支持的 CUDA 运行时版本」是上限不是已安装版本。第二层是 CUDA Runtime用 conda 或 pip 装 PyTorch 时它会自带一份运行时库装在site-packages/nvidia/下不需要你在系统里单独装完整 CUDA Toolkit。第三层才是 PyTorch 自己的编译版本比如torch-2.1.2cu118这个cu118才是真正要匹配的东西。所以正确的判断顺序是先看驱动版本够不够nvidia-smi里 Driver VersionLinux 一般 525 以上、Windows 一般 531 以上就能带 cu118 和 cu121再选一个 PyTorch 官方提供的 cu 版本最后装。系统里装没装 CUDA Toolkit对「跑训练」这件事基本没影响。注意只有当你要自己编自定义算子、导出 TensorRT、或者跑nvcc相关的编译时才需要本地完整的 CUDA Toolkit并且版本要和 PyTorch 的 cu 后缀一致。2.2 一张表我验证过和不敢用的组合下面这几组是我在不同机器上实际装过、能正常跑完训练的组合。显卡驱动足够新的前提下优先选中间那组cu118 的轮子最全遇到怪问题的概率最低。场景PythonPyTorch / torchvisionCUDA 运行时备注求稳首选3.102.1.2 / 0.16.2cu118轮子齐全30 系、40 系都稳新卡新驱动3.102.2.2 / 0.17.2cu121驱动需 535 以上老机器、无独显3.102.1.2 / 0.16.2cpu只能推理和小样本调试不建议3.12任意任意部分依赖缺预编译包不建议3.81.8.xcu111新版 ultralytics 会提示版本过低表里的 torchvision 版本必须和 PyTorch 配对单独升级 torchvision 是最常见的翻车方式之一——import torchvision直接抛operator torchvision::nms does not exist看着像 ultralytics 的问题其实是这两个包版本错位。2.3 用 conda 起一个干净环境不要动 base不管机器上原来有没有 Python 环境我都建议新开一个别往 base 里装。原因是 ultralytics 会带进 opencv、numpy、matplotlib、pandas 这一串依赖很容易和机器上原有的科学计算环境打架出了问题连回滚都难。# 1. 建一个独立的 Python 3.10 环境名字随便起我这里叫 yolov8 conda create -n yolov8 python3.10 -y # 2. 激活。后面所有命令都必须在这个环境里执行 conda activate yolov8 # 3. 确认当前 python 指向的是 conda 环境不是系统自带的 which python # Linux / macOS应输出 .../envs/yolov8/bin/python where python # Windows应输出 ...\envs\yolov8\python.exe # 4. 装 PyTorch注意这里用的是 PyTorch 官方源不要换成普通镜像 pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu118第 4 步为什么单独指定--index-url因为普通的 pip 镜像里放的是 CPU 版 wheel装了之后torch.cuda.is_available()永远是 False而且不会有任何报错提示属于最隐蔽的一类踩坑。PyTorch 官方源里才有cu118后缀的 GPU 版本。装完之后顺手把 pip 的缓存目录指到大盘上后面下权重、下依赖都用得上# 把 pip 缓存放到数据盘避免系统盘被撑爆路径按自己机器改 export PIP_CACHE_DIR/data/cache/pipWindows 下等价的做法是set PIP_CACHE_DIRD:\cache\pip或者直接在系统环境变量里加一条。这个设置不影响功能但装机次数多了就知道有用。2.4 装完先验证 torch再谈 ultralytics顺序很重要PyTorch 没通装 ultralytics 只会把问题往后推。所以我一般在这就停下来验一次。python -c import torch print(torch:, torch.__version__) # 期望看到 2.1.2cu118 print(cuda available:, torch.cuda.is_available()) # 期望 True print(cuda runtime:, torch.version.cuda) # 期望 11.8 print(device count:, torch.cuda.device_count()) if torch.cuda.is_available(): print(device name:, torch.cuda.get_device_name(0)) torch.__version__里带cu118说明装的是 GPU 版cuda available为 True 说明驱动和运行时握手成功。如果这里是 False先别急着往下走第 5 章有具体的排查路径。再补一个真实计算的小测试比is_available()更能说明问题python -c import torch a torch.randn(1024, 1024, devicecuda) b torch.randn(1024, 1024, devicecuda) c a b torch.cuda.synchronize() # 强制等待 GPU 计算完成否则报错可能被吞掉 print(ok, c.mean().item()) 加上torch.cuda.synchronize()是血泪经验。CUDA 是异步执行的很多显存错误和算子错误在提交任务时不报直到同步点才抛出来。不加这一句你可能在一个「看起来成功」的矩阵乘之后到训练时才炸。3. 解压与安装 ultralytics从 rar 包到能 import 的第一步环境通了接下来处理工程包本身。这一步看起来只是解压加 pip实际上 Sequence 错了后面全是返工。3.1 解压位置中文路径和空格是两把容易造成麻烦的因素先把压缩包解到一个纯英文、无空格、层级不深的目录比如/data/projects/yolov8-seg或D:\projects\yolov8-seg。原因不是矫情OpenCV 在 Windows 上读带中文的路径会返回 NoneYOLO 的数据加载器拿到的就是空图训练一开始 loss 是 nan你查半天以为是学习率问题。空格则容易在 shell 脚本、yaml 路径、subprocess 调用里被截断。# 解压Linux 下需要 unrarWindows 用 7-Zip 或 WinRAR 手动解 mkdir -p /data/projects/yolov8-seg unrar x ultralytics.rar /data/projects/yolov8-seg/ # 进去看一眼再决定下一步 cd /data/projects/yolov8-seg ls -la find . -maxdepth 2 -name *.py -o -maxdepth 2 -name *.yaml | head -20find那行的作用是快速确认目录结构有哪些训练脚本、配置文件在哪一层。不要跳过这一步直接 pip install很多工程包里的脚本会 import 同目录的模块路径不对就ModuleNotFoundError。提示解压后先复制一份原始目录做备份后面改配置、换数据集都在副本上做出了问题能一键退回。3.2 装 ultralytics 与它的依赖在线一条命令离线两步走如果目标机器能联网安装本身很简单# 装 ultralytics会自动带入 opencv-python、pillow、pyyaml、matplotlib 等依赖 pip install ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple # 确认装上的版本8.x 系列的接口基本一致 pip show ultralytics | head -5内网机器或者机房不让出网的场景就得走离线。做法是在一台同系统、同 Python 版本的联网机器上把 wheel 全下下来再整体拷过去# 联网机器上执行把 ultralytics 及其依赖下到 wheels 目录 pip download ultralytics -d ./wheels -i https://pypi.tuna.tsinghua.edu.cn/simple # 单独下 PyTorch 的 GPU 版必须走官方源否则拿到 CPU 版 pip download torch2.1.2 torchvision0.16.2 \ --index-url https://download.pytorch.org/whl/cu118 -d ./wheels # 打包拷到目标机器后离线安装 pip install --no-index --find-links./wheels ultralytics--no-index表示完全不访问网络--find-links指定本地目录。这两个参数一起用pip 就只在本地找包找不到会直接报错不会偷偷联网超时卡十分钟。离线安装最常见的失败是依赖不全解决办法是先把pip download那步在联网机器上跑完整别只下 ultralytics 一个包。装完可以跑一次官方自检它会输出 Python 版本、torch 版本、CUDA 状态、依赖是否齐全yolo checks这个命令的输出适合截图存档后面出问题拿来对比。3.3 权重文件放哪、怎么确认没下成半截YOLOv8 的预训练权重是按需下载的第一次YOLO(yolov8n-seg.pt)时会去拉文件。实例分割要用的后缀是-seg常见的有yolov8n-seg.pt最小最快、yolov8s-seg.pt、yolov8m-seg.pt字母越大精度越高、显存吃得越多。新手先用 n 版跑通链路别一上来就上 m 或 l。下载失败的表现很有迷惑性文件确实生成了但只有几 KB加载时报UnpicklingError或PytorchStreamReader failed locating file。判断方法很简单——正常权重大小在几 MB 到上百 MB 量级只有几 KB 的一定是坏的删掉重下。# 手动确认权重文件大小小于 1MB 的基本可以判定为下载失败 ls -lh *.pt # 如果自动下载一直失败可以先下载好再放到工程根目录YOLO 会优先用本地文件 # 放置位置与训练脚本同级或者用绝对路径在代码里指定自动下载慢的话我一般的做法是提前把.pt文件放在工程根目录代码里直接写文件名ultralytics 检测到本地已存在就不再联网。3.4 一次 30 秒冒烟测试把问题挡在训练之前装完不要直接上训练集先跑一个最小闭环。这一步能同时验证ultralytics 能 import、权重能加载、CUDA 能被调用、推理链路是通的。# smoke_test.py放在工程根目录执行 from ultralytics import YOLO # 用最小模型加载失败会在这里就报出来而不是等到训练中途 model YOLO(yolov8n-seg.pt) # 随便找一张图或者用 numpy 造一张纯色图只为跑通链路 import numpy as np img np.zeros((640, 640, 3), dtypenp.uint8) results model(img, device0, verboseFalse) # device0 表示用第一块 GPU r results[0] print(boxes:, r.boxes.shape if r.boxes is not None else None) print(masks:, none if r.masks is None else r.masks.data.shape) print(speed:, r.speed) # 里面能看到 preprocess / inference / postprocess 耗时如果masks那行打印出none说明加载的不是-seg权重而是检测权重——这是新手最常搞混的地方检测模型没有 mask 输出。如果speed里的 inference 是几十毫秒量级说明在 GPU 上如果是几百毫秒甚至更久八成还在 CPU 上跑回去看第 2 章的 CUDA 验证。注意纯色图识别不到任何目标是正常的这个脚本验证的是链路不是精度。看不到结果不代表环境有问题。4. 数据集与配置落地data.yaml、标签格式和实例分割掩码链路通了真正的坑才刚开始。YOLOv8 训练失败的原因里环境问题占三成数据格式和配置占七成而且后者报错往往更含糊。4.1 images 与 labels 的镜像目录一个字母都不能差YOLO 系列的约定是标签文件放在与图片同名的.txt里目录结构镜像对应。ultralytics 找标签的逻辑是——把路径里的/images/替换成/labels/后缀换成.txt。所以目录名写错一个字母图片全找到了标签一个没找到。mydata/ ├── images/ │ ├── train/ │ │ ├── 001.jpg │ │ └── 002.jpg │ └── val/ │ └── 003.jpg └── labels/ ├── train/ │ ├── 001.txt │ └── 002.txt └── val/ └── 003.txt三个硬性要求图片和标签必须同名后缀不同images和labels的层级必须完全对称标签文件必须存在哪怕里面是空的表示这张图没有目标空文件和缺失文件是两回事缺失会触发警告并可能被静默跳过。# 训练前先做一次一致性检查找出没有对应标签的图片 python - EOF from pathlib import Path root Path(/data/mydata) imgs list(root.glob(images/**/*.jpg)) missing [p for p in imgs if not (root / labels / p.parent.name / (p.stem .txt)).exists()] print(图片总数:, len(imgs), 缺标签:, len(missing)) for p in missing[:5]: print( , p) EOF这个脚本很短但很值。跑一次就能知道是「标签目录层级不对」还是「个别图片确实没标」避免训练开始后看到一堆No labels found警告却不知道从哪查。4.2 data.yaml 六个字段写错一个训到一半才报错data.yaml是整个训练的数据入口ultralytics 通过它定位训练集、验证集、类别数。字段不多但有几个容易写错的地方。# data.yaml保存为 UTF-8 编码不要用记事本存成带 BOM 的格式 path: /data/mydata # 数据集根目录建议绝对路径省得相对路径算错 train: images/train # 相对 path 的路径不要写 ./images/train val: images/val test: images/test # 可选没有就删掉这行 nc: 3 # 类别数可以省略ultralytics 会从 names 推断 names: # 类别名键从 0 开始连续 0: person 1: helmet 2: vest几个必须说清的点path用绝对路径最保险相对路径是相对「执行训练命令时的当前目录」不是相对 yaml 文件位置这是最容易算错的一处train和val是相对path的不要写重复前缀names用字典或列表都行但索引必须从 0 连续中间断号会导致类别映射错乱模型学出来的类别全是错的而且不会报错。注意yaml 里不要用 Tab 缩进只能用空格。Tab 会触发ScannerError报错行号还经常指向莫名其妙的位置。编码问题在 Windows 上尤其常见。中文类别名比如「安全帽」本身没问题前提是文件存成 UTF-8。用notepad另存为 ANSI 的话读出来是乱码类别名全变成问号训练照跑但画图时标签没法看。4.3 标注格式检测框四列分割多边形一串坐标同一个工程包里目标检测和实例分割是两套标注很多人卡在这。两者都是归一化坐标0~1 之间的小数差别只在列数。检测框是每行 5 个数# 检测标签格式类别 cx cy w h中心点 宽高全部归一化 0 0.512 0.433 0.201 0.318 2 0.104 0.887 0.086 0.142分割是每行不定长类别 一串x y顶点。# 实例分割标签格式类别 x1 y1 x2 y2 ... xn yn多边形顶点按顺序连成闭合区域 0 0.312 0.288 0.401 0.291 0.455 0.372 0.447 0.451 0.336 0.443 0.298 0.365 1 0.701 0.102 0.788 0.115 0.795 0.203 0.712 0.196顶点数量没有硬性限制但少于 3 个点构不成多边形会被跳过顶点顺序要沿轮廓走一圈顺序乱了会得到自交的图形mask 就是坏的。归一化除的是图片的宽和高不是长边——这一点和某些标注工具的习惯不同转换时容易搞错。如果手上是 VOC 的 XML 或 COCO 的 JSON需要转成上面这两种 txt。转换脚本的核心就是遍历每张图的标注按x/宽、y/高归一化后按行写出同时复制图片到images/下。分割任务别偷懒把检测框转成矩形 mask虽然 ultralytics 支持这么干但模型学到的边界永远是横平竖直的精度上限很低。4.4 启动训练一条命令和五个真正影响结果的参数配置齐了就能起训。命令行和 Python 两种写法等价我习惯用命令行日志和参数记录更清楚方便复现。yolo segment train \ modelyolov8n-seg.pt \ data/data/mydata/data.yaml \ epochs100 \ imgsz640 \ batch8 \ device0 \ workers4 \ projectruns/seg \ nameexp01 \ patience30 \ ampTrue \ cacheFalse逐项说清楚哪些必须改model用-seg后缀用错了就是检测任务data给绝对路径省得路径解析出岔子imgsz640是精度和速度的平衡点小目标多可以试 960但显存翻倍batch是最该按显卡调的一个8G 显存跑 640 大概能到 8~16跑不动就往下减别硬撑device0指定 GPU多卡写device0,1。workers是数据加载进程数Windows 上必须设成 0否则会因为没有if __name__ __main__保护而反复重启进程表现为训练卡住不动。patience30是早停30 轮验证指标不涨就停省时间。ampTrue开混合精度显存大概能省三成精度影响很小默认就是开的。训练日志里重点看三处开头打印的Overriding model.yaml nc80 with nc3说明类别数被正确覆盖每个 epoch 的box_loss、seg_loss、cls_loss是否在下降mAP50(M)这个带 M 的指标才是 mask 的平均精度检测的mAP50(B)只能参考。4.5 训练产物与推理衔接best.pt 之后做什么训练结束后所有东西都在runs/seg/exp01/下。weights/best.pt是验证集上表现最好的权重weights/last.pt是最后一轮的results.csv是逐轮指标args.yaml是这次训练用的全部参数——这个文件别删后面复现实验全靠它labels/下是验证集的可视化结果可以直接看分割边界准不准。推理直接用 best.ptfrom ultralytics import YOLO model YOLO(runs/seg/exp01/weights/best.pt) results model(/data/mydata/images/val/003.jpg, conf0.25, # 置信度阈值漏检多就调低 iou0.7, # NMS 的 IoU 阈值重叠目标多就调高 retina_masksTrue) # 输出原图分辨率的 mask而不是缩放到 160x160 r results[0] print(检测框:, r.boxes.xyxy.shape) print(类别:, r.boxes.cls.tolist()) print(mask:, r.masks.data.shape) # [N, H, W]N 是实例数 r.save(filenamepred_003.jpg) # 把框和 mask 画到图上retina_masksTrue这个参数值得单独记默认情况下 ultralytics 为了速度会把 mask 缩到低分辨率再上采样边缘是糊的开了之后按原图尺寸输出可视化质量差很多代价是慢一点。做交付或者写报告的时候一定要开。5. 常见问题排查装完不动、CUDA 假可用、显存炸掉的 5 个坑下面这五条是我装机时遇到过不止一次的按「现象 → 原因 → 解决」记方便对照。5.1 安装期三条最容易翻车的记录坑一torch.cuda.is_available()返回 False但nvidia-smi一切正常。现象是驱动、显卡都认PyTorch 就是不用 GPU。九成原因是装成了 CPU 版 torch——pip install torch从普通镜像装默认就是 CPU 轮子版本号里不带cu。判断方法python -c print(torch.__version__)看到的是2.1.2cpu或者干脆没有后缀就是装错了。解决是先pip uninstall torch torchvision -y卸干净再用--index-url https://download.pytorch.org/whl/cu118重装。少部分情况是驱动太老nvidia-smi报CUDA Version: 11.4而装的是 cu118 的包那就得先升级驱动。坑二import ultralytics报numpy或cv2相关的符号错误。现象是ImportError: numpy.core.multiarray failed to import或者undefined symbol: ...。原因是环境里存在两套 numpy——conda 装的旧版和 pip 装的新版混在一起或者 opencv 是系统apt install的而 ultralytics 又装了个 pip 版。解决办法是统一用 pip 管pip uninstall numpy opencv-python opencv-python-headless -y然后pip install ultralytics让它自己解析依赖。注意opencv-python和opencv-python-headless不能共存服务器上没有图形界面就用 headless 版。坑三权重文件只有几 KB加载时报PytorchStreamReader failed。现象是yolov8n-seg.pt生成了但加载时抛异常。原因是首次下载被中断留下了一个残缺文件而 ultralytics 看到文件存在就认为下好了不会重新拉。解决是ls -lh *.pt看大小几 KB 的直接rm掉重下网络不稳的话手动下载好放进工程根目录。5.2 运行期两条最常见的失败坑四训练刚启动就刷一屏No labels found或WARNING: No labels found in ...。现象是图片数正常但Background类别的数量异常高最后 mAP 接近 0。原因有两个一是labels目录名或层级不对ultralytics 把/images/替换成/labels/后找不到对应文件二是 txt 里的坐标没归一化全是大整数被判定为非法行丢弃。先用 4.1 那个一致性检查脚本确认目录再看几个 txt 文件里的数值是不是都在 0~1 之间。分割任务还要检查每行是不是偶数个坐标多一个或少一个数整行会被跳过。坑五第 1 个 epoch 就CUDA out of memory。现象是刚打印完超参数就崩或者跑到第几十个 batch 才崩。原因是batch和imgsz的组合超过了显存。解决顺序是先把batch减半再考虑imgsz640降到 512然后确认ampTrue打开了最后才是cacheFalsecacheTrue会把整个数据集缓存到内存或显存小数据集快大数据集直接爆炸。实在不行用batch-1让 ultralytics 自动估一个能装下的值但自动值偏保守只是用来探底。提示显存不够时不要第一时间去改模型结构先把 batch 和 imgsz 这两项调下来九成的 OOM 都能解决。6. 装完怎么验证三条命令确认检测和分割真的在跑环境能 import、训练能启动都不算装完。我判断一套 YOLOv8 分割环境是否真的可用会走三条验证命令从「权重能跑」到「指标能算」再到「能导出去部署」逐层确认。第一条是验证命令它会在验证集上重算一遍指标。这一步的意义是确认 best.pt 不是坏的、data.yaml 在推理阶段也能被正确解析yolo segment val modelruns/seg/exp01/weights/best.pt data/data/mydata/data.yaml imgsz640 batch8 device0期望输出里同时出现Box(P, R, mAP50, mAP50-95)和Mask(P, R, mAP50, mAP50-95)两组指标且 mask 那一组的 mAP50 和训练日志最后一轮对得上。如果只有 Box 没有 Mask说明加载的是检测权重。第二条是单图推理重点看 mask 输出而不是框验证项命令或代码期望结果GPU 可用torch.cuda.is_available()True权重类型r.masks is not NoneTruemask 维度r.masks.data.shape[N, H, W]N 为实例数推理耗时r.speed[inference]个位数到几十毫秒可视化r.save(filenamecheck.jpg)图上多边形与目标边缘贴合第三条是导出验证部署链路。model.export(formatonnx, opset12, simplifyTrue, dynamicFalse, imgsz640)会生成同目录的best.onnx再用onnxruntime加载一次并跑一张图比对输出维度和 PyTorch 侧一致。导出成功但推理结果对不上一般是imgsz和导出时不一致或者忘了做 letterbox 预处理这类问题在部署到 C 或服务端时特别常见。三条命令全绿我才会认为这台机器「装完了」。从那以后我每次装完环境都会强制走一遍这三条验证——不管多赶时间。因为最快的翻车方式就是跳过验证直接上生产数据然后在训练跑到第 40 个 epoch 时才发现 mask 输出根本不存在。希望帮到你。本文还有配套的精品资源点击获取