yolov8必须通过ultralytics库加载，不能用torch.load；自定义数据集需yaml配置且路径相对yaml文件；训练推理须遵循其封装逻辑，直接修改底层需谨慎。
YOLOv8不是PyTorch原生模型，别直接 import torch.nn 试图加载
Ultralytics 的 YOLOv8 是封装在 ultralytics 包里的高层接口，底层虽用 PyTorch 实现，但不提供标准 torch.nn.Module 实例供你手动构建前向逻辑。常见错误是看到 .pt 文件就以为能用 torch.load() + model.load_state_dict() 加载——会失败，因为权重结构和 PyTorch 原生模型不兼容。
正确路径只有一条：from ultralytics import YOLO，然后用 YOLO('yolov8n.pt') 初始化。这个对象内部管理了完整的模型图、预处理、NMS、后处理逻辑，跳过它等于重写一半 Ultralytics。
- 自定义数据集训练时，
model.train()调用的是ultralytics.engine.trainer.Trainer，不是 PyTorch 的nn.Module.train() -
model.predict()返回的是ultralytics.engine.results.Results对象，不是 raw tensor；要取 bbox 需访问results[0].boxes.xyxy，不是model(x)直接输出 - 想改 backbone 或 head？得继承
ultralytics.nn.tasks.DetectionModel，而不是从torch.nn.Module开始写
自定义数据集必须用 YAML 描述，且路径必须是绝对路径或相对于 YAML 文件的相对路径
Ultralytics 强制要求数据配置通过 .yaml 文件声明，例如 mydata.yaml：
train: ../datasets/mydata/train/images val: ../datasets/mydata/val/images nc: 3 names: ['cat', 'dog', 'bird']
注意：train 和 val 路径不是相对于 Python 工作目录，而是相对于该 YAML 文件所在位置。很多人把 YAML 放在项目根目录，但图片在 ./data/ 下，结果报错 FileNotFoundError: No images found in ...，其实只是路径解析错了。
- 推荐全部用绝对路径，比如
train: /home/user/datasets/mydata/train/images，避免歧义 -
names必须是 list，不能是 dict 或 tuple；顺序必须和 label txt 中的 class id 严格对齐（0-indexed） - 每张图对应的 label 文件（如
xxx.txt）必须和图像同名、放在labels/子目录下，且格式为class_id center_x center_y width height（归一化坐标）
训练时 batch_size 不是你显存决定的，而是由 workers + persistent_workers + pin_memory 共同影响 dataloader 效率
很多人调大 batch_size 后发现 GPU 利用率卡在 10%，nvidia-smi 显示显存占满但 GPU-Util 很低——问题往往不在模型，而在数据加载阻塞。Ultralytics 默认启用 workers=8，但在某些 Linux 系统（尤其 WSL 或容器环境）下，num_workers > 0 反而因 fork 问题拖慢速度。
- Windows 上建议设
workers=0（禁用多进程），否则可能报BrokenPipeError或训练卡死 - Linux 上若 CPU 核心少于 8，把
workers降到min(4, os.cpu_count())更稳 - 开启
persistent_workers=True（Ultralytics v8.1.0+ 默认）可复用 worker 进程，减少反复初始化开销 -
pin_memory=True对 GPU 训练有加速作用，但仅在 DataLoader 使用cuda()之前有效；Ultralytics 内部已默认启用，无需额外设置
推理时想获取原始输出（logits / confidence scores），别用 predict() 返回的 Results 做逆向工程
model.predict(...) 默认做完了 NMS、置信度阈值过滤、坐标反归一化，返回的是“人眼友好”的结果。如果你需要原始 head 输出（比如做模型集成、蒸馏、或分析某层特征），必须绕过 predict 接口，直接调用模型的 forward 方法：
from ultralytics.models.yolo.detect import DetectionPredictor
model = YOLO('yolov8n.pt')
# 获取未后处理的 logits
preds = model.model(model.preprocess(img_tensor)) # 返回三个尺度的 (bs, c, h, w) 张量
但要注意：model.model 是底层 DetectionModel 实例，它的输入必须是预处理后的 torch.Tensor（BCHW，归一化到 [0,1]，尺寸能被 32 整除），不能直接喂 PIL.Image 或 cv2.ndarray。
- 预处理函数在
model.predictor.inference()里，但它是私有方法；稳妥做法是复用DetectionPredictor.preprocess() - 原始输出是三个 feature map（如 80×80、40×40、20×20），每个点对应 anchor-based 的 4+1+nc 维向量，需自己 decode bbox 和 class score
- Ultralytics 没公开 anchor 设计细节（如 stride、base size），所以自己 decode 容易出错；真需要原始输出，建议直接读
ultralytics/nn/modules.py里的Detect.forward实现逻辑
真正难的不是跑通，而是搞清哪一层该动、哪一层动了反而破坏 pipeline。Ultralytics 把太多东西焊死了，表面简单，内里修改成本远高于从头写个 PyTorch Detection Trainer。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
