{"skill":{"slug":"yolo-expert","displayName":"yolo-expert","summary":"提供基于ultralytics库的YOLO模型加载、推理、训练、验证、导出及目标跟踪功能，并辅以源码解析与示例代码。","description":"# YOLO Expert Skill\n\n**触发条件：** 使用者询问 YOLO / Ultralytics 相关问题时激活。\n\n**行为：** 从 ultralytics GitHub 源码（`/root/ultralytics/`）出发回答，不自创代码，所有示例均来自官方内置函数。\n\n**源码位置：** `/root/ultralytics/`（已克隆，保持 `git pull` 更新）\n\n---\n\n## 源码下载/更新\n\n```bash\n# 克隆（如果还没有）\ngit clone --depth 1 https://github.com/ultralytics/ultralytics.git /root/ultralytics\n\n# 更新到最新\ncd /root/ultralytics && git pull\n```\n\n---\n\n## 框架架构\n\n### 核心模块\n```\nultralytics/\n├── models/                  # YOLO/YOLOWorld/YOLOE 等模型封装类\n├── nn/tasks.py             # DetectionModel/SegmentationModel 等 PyTorch 模型\n├── nn/modules/             # Conv/C3/SPPF 等神经网络层\n├── engine/\n│   ├── model.py               # Model 基类（统一 API）\n│   ├── trainer.py             # BaseTrainer（训练器）\n│   ├── predictor.py           # BasePredictor（推理器）\n│   ├── validator.py           # BaseValidator（验证器）\n│   └── exporter.py          # 模型导出\n├── utils/\n│   ├── metrics.py             # DetMetrics（指标）\n│   ├── plotting.py          # plot_results()（绘图）\n│   ├── loss.py              # 各种 Loss\n│   └── nms.py               # NMS\n└── solutions/              # 即用型方案（Heatmap/ObjectCounter 等）\n```\n\n### 模型继承\n```\nModel (engine/model.py) — 统一 API\n  └── YOLO\n        ├── YOLOWorld\n        └── YOLOE\n\nBaseModel (nn/tasks.py)\n  ├── DetectionModel\n  ├── OBBModel\n  ├── SegmentationModel\n  ├── PoseModel\n  ├── ClassificationModel\n  └── ...\n```\n\n---\n\n## 核心 API 一览\n\n| 功能 | 调用方式 |\n|------|----------|\n| 推理 | `model.predict(source, stream=False, **kwargs)` |\n| 训练 | `model.train(data=..., epochs=..., **kwargs)` |\n| 验证 | `model.val(data=..., **kwargs)` |\n| 导出 | `model.export(format=\"onnx\", **kwargs)` |\n| 调参 | `model.tune(use_ray=False, iterations=..., **kwargs)` |\n| 跟踪 | `model.track(source, persist=False, **kwargs)` |\n| benchmark | `model.benchmark(format=\"onnx\", **kwargs)` |\n| 绘制训练曲线 | `plot_results(file=\"results.csv\")` |\n| 绘制推理结果 | `results[0].plot()` |\n\n---\n\n## 推理（predict）\n\n官方签名：`model.predict(source=None, stream=False, predictor=None, **kwargs)`\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")\n\n# 基本推理\nresults = model.predict(\"bus.jpg\")\n\n# 批量图片\nresults = model.predict([\"img1.jpg\", \"img2.jpg\"])\n\n# 视频推理（流式，生成器模式）\nfor r in model.predict(\"video.mp4\", stream=True):\n    print(r.boxes)          # 每帧检测结果\n    print(r.boxes.xyxy)    # 框坐标 (N,4)\n    print(r.boxes.conf)     # 置信度 (N,)\n    print(r.boxes.cls)     # 类别ID (N,)\n\n# 结果保存/显示\nresults[0].save()          # 保存 result.jpg\nresults[0].show()          # 显示图片\nresults[0].plot()          # 返回带标注的 np.ndarray 图片\nresults[0].save_txt(\"labels/\")    # 保存 YOLO 格式标签\nresults[0].save_crop(\"crops/\")    # 保存裁剪图\n\n# 常用参数\nresults = model.predict(\n    source=\"bus.jpg\",\n    conf=0.25,          # 置信度阈值\n    iou=0.45,           # NMS IOU 阈值\n    imgsz=640,          # 输入分辨率\n    device=\"0\",          # GPU 编号\n    half=True,          # FP16 推理\n    augment=True,       # TTA 测试增强\n    visualize=False,    # 可视化特征图\n    classes=[0, 1],     # 只检测指定类别\n)\n```\n\n---\n\n## 训练（train）\n\n官方签名：`model.train(data=..., epochs=..., **kwargs)`\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")  # 或 \"yolo26n.yaml\" 从零训练\n\nresults = model.train(\n    data=\"coco8.yaml\",       # 数据集配置文件\n    epochs=100,              # 训练轮数\n    imgsz=640,               # 输入分辨率\n    device=\"0\",               # GPU 编号，或 \"cpu\"\n    batch=16,                # 批量大小\n    project=\"runs/detect\",   # 保存路径\n    name=\"train\",\n    exist_ok=True,           # 覆盖已有实验\n    pretrained=True,         # 使用预训练权重\n    optimizer=\"SGD\",         # 优化器：SGD/Adam/AdamW/RMSprop\n    lr0=0.01,               # 初始学习率\n    lrf=0.01,               # 最终学习率 (lr0 * lrf)\n    momentum=0.937,\n    weight_decay=0.0005,\n    warmup_epochs=3.0,     # 热身轮数\n    warmup_momentum=0.8,\n    warmup_bias_lr=0.1,\n    box=7.5,                 # Box loss 权重\n    cls=0.5,                # Cls loss 权重\n    dfl=1.5,                # DFL loss 权重\n    mosaic=1.0,             # 马赛克增强\n    mixup=0.0,             # MixUp 增强\n    copy_paste=0.0,        # Copy-paste 增强\n    close_mosaic=10,       # 最后 N 轮关闭 mosaic\n    amp=True,              # 自动混合精度\n    cache=False,            # 缓存图片到内存\n    workers=8,             # 数据加载线程数\n    verbose=True,          # 显示详细日志\n)\n```\n\n---\n\n## 验证（val）\n\n官方签名：`model.val(data=..., **kwargs)`\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")\n\nmetrics = model.val(data=\"coco8.yaml\")\n\n# 常用指标属性\nprint(metrics.box.map)              # mAP50-95（COCO 指标）\nprint(metrics.box.map50)            # mAP50\nprint(metrics.box.map75)            # mAP75\nprint(metrics.box.metric_precision) # Precision\nprint(metrics.box.metric_recall)   # Recall\n\n# 如果是分割任务\nprint(metrics.mask.map)             # mask mAP\n\n# 如果是姿态任务\nprint(metrics.kpt.map)             # keypoint mAP\n```\n\n---\n\n## 导出（export）\n\n官方签名：`model.export(format=\"\", **kwargs)`\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")\n\n# 导出格式：onnx/tensorrt/coreml/paddle/tflite/...\nmodel.export(format=\"onnx\", imgsz=640, half=True, opset=12)\nmodel.export(format=\"tensorrt\", imgsz=640, batch=1, half=True)\nmodel.export(format=\"coreml\", imgsz=640)\nmodel.export(format=\"paddle\", imgsz=640)\nmodel.export(format=\"tflite\", imgsz=640, int8=True, keras=True)\n```\n\n---\n\n## 调参（tune）\n\n官方签名：`model.tune(use_ray=False, iterations=10, **kwargs)`\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")\n\n# 内置调参（默认）\nresults = model.tune(\n    data=\"coco8.yaml\",\n    epochs=30,\n    iterations=300,\n    optimizer=\"AdamW\",\n    lr0=0.001,\n    weight_decay=0.0005,\n    batch=16,\n)\n\n# 使用 Ray Tune（需 pip install ray）\nresults = model.tune(\n    use_ray=True,\n    iterations=20,\n    data=\"coco8.yaml\",\n)\n```\n\n---\n\n## 跟踪（track）\n\n官方签名：`model.track(source=None, persist=False, tracker=\"bytetrack.yaml\", **kwargs)`\n\n```python\nfrom ultralytics import YOLO\n\nmodel = YOLO(\"yolo26n.pt\")\n\nresults = model.track(\n    source=\"video.mp4\",\n    persist=True,                  # 跨帧保持跟踪\n    tracker=\"bytetrack.yaml\",    # 跟踪器配置\n    conf=0.25,\n    iou=0.45,\n    classes=[0],                  # 只跟踪人\n)\n\n# 流式跟踪\nfor r in model.track(source=\"video.mp4\", stream=True, persist=True):\n    print(r.boxes.id)            # 跟踪 ID（每帧重排）\n    print(r.boxes.xyxy)         # 框坐标\n    print(r.boxes.cls)          # 类别\n```\n\n---\n\n## 绘制训练曲线（plot_results）\n\n官方签名：`plot_results(file=\"path/to/results.csv\", dir=\"\", on_plot=None)`\n\n```python\nfrom ultralytics.utils.plotting import plot_results\n\n# 方式1：直接指定 CSV 文件\nplot_results(\"runs/detect/train2/results.csv\")\n\n# 方式2：指定目录（自动找 results.csv）\nplot_results(dir=\"runs/detect/train2/\")\n\n# 结果保存为同目录下的 results.png\n```\n\n---\n\n## Results 对象属性\n\n`model.predict()` 返回 `List[Results]`，每个 Results 对应一张图/一帧：\n\n```python\nresults = model.predict(\"bus.jpg\")[0]\n\nresults.boxes         # 检测框（Boxes 对象）\nresults.masks        # 分割掩码（Masks 对象，若有）\nresults.probs        # 分类概率（Probs 对象，若为分类模型）\nresults.keypoints    # 关键点（Keypoints 对象，若为姿态模型）\nresults.obb          # 有向框（OBBs 对象，若为 OBB 模型）\n\n# Boxes 常用属性\nresults.boxes.xyxy   # 左上右下坐标 (N,4)\nresults.boxes.xywh   # 中心点+宽高 (N,4)\nresults.boxes.conf   # 置信度 (N,)\nresults.boxes.cls   # 类别 ID (N,)\nresults.boxes.id     # 跟踪 ID（仅 track 模式）(N,)\nresults.boxes.data   # 完整 tensor (N,6) [xyxy, conf, cls]\n\n# 绘制结果图\nimg = results.plot()  # 返回 BGR np.ndarray，可 cv2.imwrite 保存\n```\n\n---\n\n## 数据集配置（YAML）\n\n### 检测任务\n```yaml\npath: ./datasets/coco8        # 数据集根目录（相对或绝对路径）\ntrain: images/train             # 训练图片相对 path 的路径\nval: images/val              # 验证图片相对 path 的路径\n\nnc: 80                        # 类别数量\nnames: ['person', 'car', ...] # 类别名称列表\n```\n\n### 分割任务\n标签格式（`.txt`，每行一个多边形）：\n```\n# class_id x1 y1 x2 y2 x3 y3 ...（归一化到 0-1）\n0 0.1 0.2 0.3 0.2 0.2 0.4 0.1 0.4\n1 0.5 0.5 0.6 0.6 0.5 0.6\n```\n\n### 目录结构\n```\ndataset/\n├── images/\n│   ├── train/\n│   │   └── *.jpg\n│   └── val/\n│       └── *.jpg\n└── labels/           # 与 images 平级，同名 .txt\n    ├── train/\n    │   └── *.txt\n    └── val/\n        └── *.txt\n```\n\n---\n\n## 指标解读\n\n| 指标 | 含义 |\n|------|------|\n| `box.map` | COCO mAP50-95（核心指标，越高越好） |\n| `box.map50` | IoU>0.5 即算正确 |\n| `box.map75` | IoU>0.75 才算正确，更严格 |\n| `box.metric_precision` | 预测框中正确目标的比例 |\n| `box.metric_recall` | 真实目标中被检出的比例 |\n| `mask.map` | 实例分割 mAP |\n| `pose.map` | 关键点 mAP |\n\n---\n\n## 性能优化\n\n| 参数 | 作用 |\n|------|------|\n| `device=\"0\"` / `[0,1,2,3]` | 指定 GPU |\n| `device=\"cpu\"` | CPU 推理 |\n| `half=True` | FP16 加速+省显存 |\n| `batch=4`（显存不够时减小） | 减小显存占用 |\n| `imgsz=320`（越低越快） | 减小输入分辨率 |\n| `stream=True` | 视频流推理，省内存 |\n| `model.fuse()` | 融合 Conv+BN，加速推理 |\n| `augment=True` | TTA 测试增强 |\n\n---\n\n## Solutions 即用型场景\n\n从 `ultralytics.solutions` 导入，全部为官方内置方案：\n\n```python\nfrom ultralytics.solutions import (\n    Heatmap,           # 热力图（目标轨迹密度）\n    ObjectCounter,     # 区域计数（进入/离开多边形区域）\n    SpeedEstimator,    # 速度估计（跟踪 + 速度计算）\n    DistanceCalculation, # 两目标间距离计算\n    RegionCounter,      # 区域内目标统计\n    QueueManager,      # 队列长度管理\n    SecurityAlarm,     # 安防报警（越界检测）\n    ObjectBlurrer,     # 目标模糊（隐私保护）\n    ObjectCropper,     # 目标裁剪\n    AIGym,            # AI 健身姿态评估\n    Analytics,        # 人流/车流分析\n    VisionEye,        # 视觉跟随\n    TrackZone,        # 轨迹区域\n)\n```\n\n### 使用方式（通用模式）\n```python\nfrom ultralytics.solutions import Heatmap\nimport cv2\n\n# 初始化，传入模型\nheatmap = Heatmap(model=\"yolo26n.pt\")\n\n# 读视频逐帧处理\ncap = cv2.VideoCapture(\"video.mp4\")\nwhile cap.isOpened():\n    ret, frame = cap.read()\n    if not ret:\n        break\n    res = heatmap.process(frame)   # 处理帧\n    cv2.imshow(\"result\", res.plot()) # 可视化\n    if cv2.waitKey(1) & 0xFF == ord(\"q\"):\n        break\ncap.release()\ncv2.destroyAllWindows()\n```\n\n其他 Solutions（ObjectCounter/SpeedEstimator 等）调用方式完全相同，均为 `实例.process(frame)` 或 `实例.estimate(frame)` 返回 `SolutionResults`，用 `.plot()` 可视化。\n\n---\n\n## 报错排查\n\n| 报错 | 解决方案 |\n|------|----------|\n| `No module named 'ultralytics'` | 克隆源码：`git clone --depth 1 https://github.com/ultralytics/ultralytics.git /root/ultralytics` |\n| `CUDA out of memory` | 减小 `batch`、`imgsz`，或开启 `half=True` |\n| `dataset not found` | 检查 `data=` YAML 路径，YAML 内用相对路径 |\n| `UnicodeDecodeError` | Windows 路径含中文，改成英文路径 |\n| 训练完没有 `results.csv` | 确认 `model.train()` 正常完成，检查 `project/name/` 目录 |\n| 推理结果为空 | 确认图片有目标，或降低 `conf` 阈值 |\n\n---\n\n**回答时：** 先 `memory_search` 查记忆，再阅读 `/root/ultralytics` 源码中对应的文件和函数回答。所有示例代码均来自官方内置函数，不自创。\n","tags":{"latest":"1.0.2"},"stats":{"comments":0,"downloads":344,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":3},"createdAt":1778135750782,"updatedAt":1778492867743},"latestVersion":{"version":"1.0.2","createdAt":1778146268495,"changelog":"- 源码参考范围更改为本地克隆的 ultralytics GitHub 源码（/root/ultralytics），并持续保持 git pull 最新。\n- 行为说明中移除网络安装 pip 的指令，改为只引用本地源码，无自创代码，所有示例严格来源于官方内置函数。\n- 新增明确的“源码下载/更新”说明，详述 git clone、git pull 路径和命令。\n- 其余内容（架构、API 说明、用法示例等）保持一致。","license":"MIT-0"},"metadata":null,"owner":{"handle":"ggyybb","userId":"s17dwtrmbh0atzzgj7fprv5e21843gga","displayName":"ggyybb","image":"https://avatars.githubusercontent.com/u/61568153?v=4"},"moderation":null}