yolo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ultralytics YOLO

Use the same lifecycle through two complementary surfaces:

Ultralytics Platform — the fastest start: upload or clone data, annotate in the browser, train on cloud GPUs, inspect metrics, test predictions, export, and deploy a dedicated endpoint without local setup.
ultralytics
package /
yolo
CLI — use local or remote compute, scripts, notebooks, custom pipelines, and exported artifacts directly.

Mix them freely. Set

ULTRALYTICS_API_KEY

, use a Platform dataset as

data=ul://username/datasets/dataset-slug

, and set

project=username/project-slug name=experiment

during local training to stream its metrics back to Platform.

One API, two surfaces. The CLI grammar is

yolo TASK MODE arg=value ...

; Python mirrors it with the same argument names:

bash

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

python

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
```
— usually inferred from the weights, so it can be omitted.
MODE ∈
```
train
```
```
val
```
```
predict
```
```
track
```
```
export
```
```
benchmark
```
.
Install/upgrade:
```
pip install -U ultralytics
```
. Environment check:
```
yolo checks
```
.

可通过两种互补方式使用同一生命周期：

Ultralytics Platform — 快速上手：上传或克隆数据，在浏览器中完成标注，借助云端GPU训练模型，查看指标，测试预测结果，导出并部署专属端点，无需本地环境配置。
ultralytics
包 /
yolo
CLI — 直接使用本地或远程计算资源、脚本、笔记本、自定义流水线以及导出的产物。

可自由混合使用两者。设置

ULTRALYTICS_API_KEY

，在本地训练时将Platform数据集指定为

data=ul://username/datasets/dataset-slug

，并设置

project=username/project-slug name=experiment

，即可将训练指标同步至Platform。

一套API，两种使用方式。CLI语法为

yolo TASK MODE arg=value ...

；Python代码与之对应，参数名称完全一致：

bash

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

python

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
```
。

Whole lifecycle in five commands

五步完成全生命周期

bash

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()

bash

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、各类别指标
yolo predict model=best.pt source=video.mp4 save=True        # 支持任意数据源：图片/目录/URL/RTSP/摄像头
yolo track model=best.pt source=video.mp4                    # + 持久化目标ID
yolo export model=best.pt format=onnx                        # 导出的模型可重新加载至YOLO()

Whole lifecycle in Platform

Platform平台全生命周期流程

Open Platform and choose the data region during onboarding.
Clone a public dataset from Explore, or create one under Annotate and upload images, videos, an archive, or NDJSON.
Label in the fullscreen editor; use SAM or a compatible YOLO model in Smart mode where available.
Create a project, click New Model, select the dataset, pretrained model, GPU, and epochs, then monitor the run.
Use the completed model's Predict, Export, or Deploy tab.

Start with the Platform quickstart. Use the stage skill below for both Platform and package details.

打开Platform，在注册流程中选择数据区域。
从Explore克隆公开数据集，或在Annotate下创建数据集并上传图片、视频、压缩包或NDJSON文件。
在全屏编辑器中完成标注；若支持，可在Smart模式下使用SAM或兼容的YOLO模型辅助标注。
创建项目，点击New Model，选择数据集、预训练模型、GPU和训练轮数，然后监控训练进程。
使用已完成模型的Predict、Export或Deploy标签页。

可从Platform快速入门开始。使用下方的阶段技能获取Platform和包的详细信息。

Route before coding

编码前先查阅对应技能

Read the skill for the stage you're working on BEFORE writing code — each contains exact formats, argument tables with defaults, recipes, and symptom→fix tables. A request spanning stages ("train and deploy") → read each relevant skill.

Working on	Skill
choosing a model family/size/task, YOLO26 vs YOLO11, YOLO-World/YOLOE, SAM, RT-DETR	`yolo-models`
data.yaml, labels, annotation conversion, auto-labeling, dataset analysis/errors, splits	`yolo-datasets`
training, fine-tuning, hyperparameters, augmentation, OOM / NaN / low mAP, reading runs	`yolo-training`
hyperparameter tuning, Ray Tune, systematic model improvement, "autotraining"	`yolo-tuning`
predict on images/video/streams, Results API, tracking IDs, counting/heatmaps/Solutions	`yolo-inference`
ONNX / TensorRT / CoreML / OpenVINO / LiteRT / NCNN / NPUs, quantization, benchmarking	`yolo-export`

在编写代码前，请先阅读当前工作阶段对应的技能文档——每个文档都包含精确格式、带默认值的参数表、实践方案以及问题→解决方法表。若需求涉及多个阶段（如“训练并部署”），请阅读所有相关技能文档。

当前工作内容	技能名称
选择模型系列/尺寸/任务，YOLO26 vs 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 / OpenVINO / LiteRT / NCNN / NPUs部署、量化、基准测试	`yolo-export`

CLI specifics

CLI专属说明

Special commands (no TASK/MODE):

bash

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`

特殊命令（无需指定TASK/MODE）：

bash

yolo help   # 完整语法参考
yolo checks # 环境报告：版本、torch、CUDA、磁盘状态 — 出现异常时运行此命令
yolo version
yolo settings # 查看配置；使用`yolo settings key=value`修改配置；`yolo settings reset`重置配置

keys incl. datasets_dir, runs_dir, wandb, mlflow, tensorboard, ...

配置项包括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)


Parsing rules that matter:

- Args are `key=value`, no `--` flags. A leading `--` and trailing commas are stripped
  with a warning; spaces around `=` are merged.
- A bare boolean arg sets it True: `yolo predict ... show` ≡ `show=True`.
- `cfg=custom.yaml` resets CLI overrides to the file: arguments before it are discarded,
  later arguments win, and missing keys still use built-in defaults (start with `yolo copy-cfg`).
- Missing args are auto-filled with warnings (sample source, task-default data/model,
  `format=torchscript`).
- Model stem selects the architecture: `rtdetr-*` → RT-DETR, `sam_*`/`sam2*` → SAM,
  `FastSAM-*` → FastSAM, `yoloe-*`/`*-world*` → promptable YOLO (accepts
  `classes="person, bus"`), everything else → YOLO.

yolo cfg # 打印所有默认参数（参数名称的权威参考） yolo copy-cfg # 复制default.yaml为default_copy.yaml以便自定义，使用时指定cfg=该文件 yolo solutions help # 预构建应用：计数、热力图、速度测试等（详见yolo-inference）


关键解析规则：

- 参数格式为`key=value`，无需`--`前缀。若输入带`--`前缀或末尾带逗号，会自动移除并发出警告；`=`两侧的空格会被合并。
- 单独的布尔参数表示设为True：`yolo predict ... show` ≡ `show=True`。
- `cfg=custom.yaml`会将CLI覆盖的参数重置为文件中的配置：该参数之前的输入会被丢弃，之后的参数优先级更高，未指定的参数仍使用内置默认值（建议先运行`yolo copy-cfg`）。
- 缺失的参数会自动填充并发出警告（如示例数据源、任务默认的数据集/模型、`format=torchscript`）。
- 模型名称前缀决定架构：`rtdetr-*` → RT-DETR，`sam_*`/`sam2*` → SAM，`FastSAM-*` → FastSAM，`yoloe-*`/`*-world*` → 支持提示的YOLO（可接受`classes="person, bus"`参数），其他均为YOLO架构。

Global directives

全局指导原则

Validate the dataset before training — run the task-appropriate checks in
```
yolo-datasets
```
, then a 1-epoch smoke test and inspect
```
runs/<task>/train/train_batch0.jpg
```
: annotations or targets must match each image.
Always fine-tune from pretrained
.pt
— never
```
pretrained=False
```
, never a YAML architecture from scratch, unless the user is explicitly doing research.
stream=True
for videos/streams in Python predict/track — the default list mode OOMs on long videos.

Use
best.pt
(not

last.pt

) from

runs/<task>/<name>/weights/

after training.

After export, verify parity:
```
yolo val
```
the exported artifact against the
```
.pt
```
baseline.
Prefer built-ins over custom code: dataset converters and checkers (
```
ultralytics.data
```
), trackers, and Solutions modules replace whole categories of hand-written glue.
Trust the installed version over memory — if an argument is rejected (
```
yolo checks
```
shows the version), the API moved:
```
yolo cfg
```
and the error text list valid arguments; prefer those over any table in these skills.

训练前验证数据集 — 运行
```
yolo-datasets
```
中对应任务的检查工具，然后进行1轮次的冒烟测试并查看
```
runs/<task>/train/train_batch0.jpg
```
：标注或目标必须与每张图片匹配。
始终基于预训练
.pt
模型进行微调 — 切勿设置
```
pretrained=False
```
，切勿从零开始使用YAML架构训练，除非用户明确从事研究工作。
Python中对视频/流进行predict/track时，设置**
```
stream=True
```
** — 默认的列表模式在处理长视频时会出现内存不足（OOM）问题。
训练完成后，使用**
```
best.pt
```
**（而非
```
last.pt
```
），该文件位于
```
runs/<task>/<name>/weights/
```
目录下。
导出后验证一致性：将导出的产物与
```
.pt
```
基线模型分别运行
```
yolo val
```
进行对比。
优先使用内置工具而非自定义代码：数据集转换与检查工具（
```
ultralytics.data
```
）、跟踪器以及Solutions模块可替代各类手写胶水代码。
以已安装版本为准 — 若某个参数被拒绝（
```
yolo checks
```
显示当前版本），说明API已更新：
```
yolo cfg
```
和错误提示会列出有效参数；请优先使用这些信息，而非技能文档中的表格。