yolo

Ultralytics YOLO

在三个互补的平台上运行同一套完整流程：

• Ultralytics Platform — 最快的入门方式：上传或克隆数据，在浏览器中标注，使用云 GPU 训练，检查指标，测试预测结果，导出，并部署专用端点，无需本地配置。
• ultralytics 包 / yolo CLI — 直接使用本地或远程计算资源、脚本、笔记本、自定义流水线和导出的产物。
• ul CLI（Python 3.11+，由 ultralytics 或 ultralytics-platform 安装）— 脚本化调用 Platform API 本身：ul cloud <resource> <operation> key=value 可在终端列出、创建、克隆、训练、导出和部署 Platform 资源（参见 platform-cli）。

ul cloud train|predict|export 会根据需要上传本地输入，并在 Platform 上运行。训练提交后即会返回；添加 watch 可跟踪进度并下载结果。ul cloud download 使用打印出的模型 URI，并在需要时等待；按 Ctrl-C 可停止等待，但不会取消训练。所有四个快捷命令都需要安装 ultralytics；ul cloud <resource> <operation> 命令则不需要。

ul cloud train model=yolo26n.pt data=ul://username/datasets/helmets epochs=100 project=helmets name=exp1 # → run URI and download command
ul cloud download model=ul://username/helmets/exp1                                                       # → weights/best.pt and results
ul cloud predict model=ul://username/helmets/exp1 source=video.mp4                                       # → annotated output
ul cloud export model=ul://username/helmets/exp1 format=onnx                                             # → downloaded artifact

可以自由混用这些方式。设置 ULTRALYTICS_API_KEY，将 Platform 数据集用作 data=ul://username/datasets/dataset-slug，并在本地训练时设置 project=username/project-slug name=experiment，即可将训练指标同步回 Platform。

yolo CLI 和 Python 共用同一套 API。CLI 语法为 yolo TASK MODE arg=value ...，Python 使用相同的参数名称：

yolo detect train data=data.yaml model=yolo26n.pt epochs=100 imgsz=640

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.train(data="data.yaml", epochs=100, imgsz=640)

• TASK ∈ detect segment semantic depth classify pose obb — 通常可从权重推断，因此可以省略。
• MODE ∈ train val predict track export benchmark。
• 安装/升级：pip install -U ultralytics。环境检查：yolo checks。

用五条命令跑完整流程

yolo detect train data=data.yaml model=yolo26n.pt epochs=100 # → runs/detect/train/weights/best.pt
yolo val model=best.pt data=data.yaml                        # mAP, per-class metrics
yolo predict model=best.pt source=video.mp4 save=True        # any source: image/dir/URL/RTSP/webcam
yolo track model=best.pt source=video.mp4                    # + persistent object IDs
yolo export model=best.pt format=onnx                        # exported model loads back into YOLO()

在 Platform 上跑完整流程

1. 打开 Platform，并在引导设置期间选择数据区域。
2. 从 Explore 克隆一个公开数据集，或在 Annotate 下创建数据集，并上传图片、视频、压缩包或 NDJSON。
3. 在全屏编辑器中标注；在适用时，可在 Smart 模式下使用 SAM 或兼容的 YOLO 模型。
4. 创建项目，点击 New Model，选择数据集、预训练模型、GPU 和轮数，然后监控运行进度。
5. 使用已完成模型的 Predict、Export 或 Deploy 标签页。

从 Platform 快速入门指南开始。以下阶段技能适用于 Platform 和软件包的详细信息。

编码前先查阅

编写代码前，先阅读当前阶段对应的技能文档——每个技能都位于与本目录同级的文件夹中（../<skill>/SKILL.md），其中包含准确的格式、带默认值的参数表、操作示例，以及“症状→解决方法”表。若请求涉及多个阶段（如“训练并部署”），请阅读每个相关技能文档。

工作内容	技能
选择模型系列／尺寸／任务，YOLO26 与 YOLO11 的比较、YOLO-World／YOLOE、SAM、RT-DETR	yolo-models
data.yaml、标签、标注转换、自动标注、数据集分析／错误、数据集划分	yolo-datasets
训练、微调、超参数、数据增强、OOM／NaN／mAP 偏低、查看运行记录	yolo-training
超参数调优、Ray Tune、系统性改进模型、“自动训练”	yolo-tuning
对图像／视频／流进行预测、Results API、跟踪 ID、计数／热力图／Solutions	yolo-inference
ONNX／TensorRT／CoreML／Core AI／OpenVINO／LiteRT／NCNN／NPU、量化、基准测试	yolo-export
在终端使用 Platform API：ul cloud <resource> <operation> 命令、ultralytics-platform、以脚本方式更改资源、回收站、部署和云端运行	platform-cli

CLI 特定说明

特殊命令（无 TASK/MODE）：

yolo help   # full syntax reference
yolo checks # env report: version, torch, CUDA, disk — run when anything is weird
yolo version
yolo settings # view; `yolo settings key=value` to set; `yolo settings reset`
# keys incl. datasets_dir, runs_dir, wandb, mlflow, tensorboard, ...
yolo cfg            # print every default argument (the ground truth for arg names)
yolo copy-cfg       # copy default.yaml → default_copy.yaml to customize, use with cfg=
yolo solutions help # prebuilt apps: count, heatmap, speed, ... (see yolo-inference)

重要解析规则：

• 参数格式为 key=value，不使用 -- 标志。若参数前缀为 -- 或末尾有逗号，会在发出警告后移除；= 两侧的空格会合并。
• 单独的布尔参数会被设为 True：yolo predict ... show ≡ show=True。
• cfg=custom.yaml 会加载文件中的值：无论 CLI 参数写在它前面还是后面，均优先于文件值；缺少的键仍使用内置默认值（请从 yolo copy-cfg 开始）。
• 缺少的参数会自动填入，并发出警告（示例数据源、任务默认数据／模型、format=torchscript）。
• 模型主文件名决定架构：rtdetr-* → RT-DETR，sam_*／sam2*／sam3*／mobile_sam → SAM，FastSAM-* → FastSAM，yolo_nas_* → NAS，yoloe-*／*-world* → 可通过提示词指定类别的 YOLO（接受 classes="person, bus"），其他所有情况 → YOLO。

全局指引

1. 训练前验证数据集——运行 yolo-datasets 中适用于相应任务的检查，然后进行 1 个 epoch 的冒烟测试，并检查 runs/<task>/train/train_batch0.jpg：标注或目标必须与每张图像相匹配。
2. 始终从预训练 .pt 微调——除非用户明确在进行研究，否则绝不使用 pretrained=False，也绝不从头开始使用 YAML 架构。
3. 在 Python predict／track 中处理视频／流时，使用 stream=True——默认的列表模式会在长视频上导致 OOM。
4. 训练后使用 runs/<task>/<name>/weights/ 中的 best.pt（而不是 last.pt）。
5. 导出后验证一致性：使用 yolo val 将导出产物与 .pt 基线进行比较。
6. 优先使用内置功能，而非自定义代码：数据集转换器和检查器（ultralytics.data）、跟踪器和 Solutions 模块可以替代整类手写胶水代码。
7. 以已安装的版本为准，而非凭记忆判断——如果参数被拒绝，说明 API 已有变更：yolo cfg 和错误文本会列出有效参数，yolo checks 会显示版本。请优先参考这些信息，而非这些技能文档中的任何表格。