Ultralytics YOLO11：YOLO 系列视觉 AI 工具包｜部署与使用全指南
适用版本说明：本文基于 ultralytics 官方仓库（
ultralytics/ultralytics）PyPI 最新稳定版本撰写（撰写时仓库主线已迭代至 YOLO26/预告 YOLO27，但 YOLO11 权重与 API 在同一ultralytics包内持续受支持，pip install ultralytics后即可加载yolo11*.pt全系列权重，文末 YOLO11 型号表引自官方 docs.ultralytics.com/models/yolo11）。仓库 star 数超 4 万，CI 持续运行，是当前最活跃的开源目标检测框架之一。
Ultralytics 是 YOLO 系列算法的官方实现与维护方，ultralytics Python 包把目标检测（detect）、实例分割（segment）、图像分类（classify）、姿态估计（pose）、旋转框检测（OBB）、深度估计以及多目标追踪（track）统一到一个 API 下。无论你用 CLI 一行命令跑通推理，还是用 Python API 完成训练—验证—导出全流程，甚至把它部署到 Jetson/TensorRT 边缘设备，都是同一套配置体系。本文从零开始，覆盖 pip 安装、Docker 官方镜像、训练与自定义数据集、模型导出与常见报错排查。
一、项目介绍与适用场景
Ultralytics（公司）在多年 YOLO 基础研究之上持续发布 SOTA 模型：从 YOLOv3/v5/v8 到 YOLO11，再到 2025 年后的 YOLO26。本教程聚焦 YOLO11（2024 年 9 月发布）这一广泛用于生产的版本，同时说明同一套用法适用于包内全部代次模型。
YOLO11 的技术定位：
统一的模型家族：
yolo11n / yolo11s / yolo11m / yolo11l / yolo11x五档规模，对应每类任务的后缀变体（-seg、-cls、-pose、-obb）。统一的训练/推理接口：
YOLO("yolo11n.pt")一个类搞定所有任务，CLI 与 Python 参数完全一致。多格式部署：一行
model.export()可导出 ONNX、TensorRT、OpenVINO、CoreML、TFLite、NCNN 等十余种格式。
适用人群：
不适合的场景：
需要 Transformer 级别长序列视频理解的纯语义任务（这不是检测器的工作范围）。
对训练代码深度魔改、需要完全自定义网络结构的研究（可改但 AGPL 开源义务较重，见第十一章）。
纯 CPU 上追求极低延迟的高并发在线服务——建议导出 ONNX/OpenVINO 后用对应推理引擎，而不是直接跑 PyTorch。
二、核心功能逐条拆解
目标检测（detect）：输入图像，输出 80 类（COCO）边界框与置信度。YOLO11 检测头在同等精度下比 YOLOv8 参数量更少、速度更快。
实例分割（segment）：除边界框外输出像素级掩膜，
yolo11n-seg等 5 档规模可选，适合抠图、区域统计。图像分类（classify）：
yolo11*-cls在 ImageNet 1000 类上预训练，训练分辨率 224。姿态估计（pose）：输出人体 17 个关键点（COCO keypoints），可用于健身计数、跌倒检测。
旋转框检测（OBB）：在 DOTAv1 上预训练，输出带角度的旋转框，适合遥感影像、航拍目标。
多目标追踪（track）：对视频流中的检测目标跨帧关联并分配 ID，兼容检测/分割/姿态/OBB 模型，内部支持 BoT-SORT 与 ByteTrack。
CLI 一行式用法：
yolo predict model=yolo11n.pt source=bus.jpg，所有任务/模式共用同一参数体系（mode=、task=）。Python API：
model.train() / model.val() / model.predict() / model.export() / model.track()五大方法覆盖完整生命周期。自动下载：首次使用时模型权重从官方 GitHub release 自动下载；官方数据集（如 coco8、coco）自动下载并校验。
多格式导出：ONNX、TensorRT、OpenVINO、CoreML、TFLite（含 INT8）、NCNN 等，一次
export(format=...)完成。集成生态：与 Weights & Biases、Comet ML、Roboflow、Intel OpenVINO 等官方集成，训练日志一键上报。
结果可视化与流处理：
result.plot()直接画框，model.track(source=0, show=True)支持摄像头实时画面。
三、全套官方链接
四、硬件与环境前置要求
五、多平台部署步骤
5.1 pip 安装（Linux / macOS / Windows 通用）
# 建议先建虚拟环境
python3 -m venv yolo-env
source yolo-env/bin/activate # Windows: yolo-env\Scripts\activate
# 方式 A：CPU 或已有合适 torch 环境时直接装
pip install ultralytics
GPU 版（CUDA 12.1 示例）——先装 GPU 版 torch 再装 ultralytics，避免 pip 拉到 CPU 版 torch 覆盖：
# CUDA 12.1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
# 或 CUDA 11.8
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install ultralytics
python -c "import torch; print(torch.__version__, torch.cuda.is_available())" # 应输出 True
Conda 安装（官方支持）：
conda install -c conda-forge ultralytics
验证安装：
yolo predict model=yolo11n.pt source='https://ultralytics.com/images/bus.jpg'
# 或
yolo version
5.2 Docker 官方镜像
官方镜像族（来自 docs.ultralytics.com/guides/docker-quickstart，以官方文档为准）：
注意：官方文档中 GPU 镜像 tag 为
latest（不含latest-gpu），Jetson 镜像按 JetPack 版本细分；新文档推荐用 CDI 方式--device nvidia.com/gpu=all替代旧式--gpus all（Docker ≥ 28.2.0 且 nvidia-container-toolkit ≥ 1.18）。Windows Docker Desktop（WSL2 后端）仍使用--gpus all。
# 拉取并运行 GPU 镜像（新式 CDI 写法）
sudo docker pull ultralytics/ultralytics:latest
sudo docker run -it --ipc=host --device nvidia.com/gpu=all ultralytics/ultralytics:latest
# 传统写法（兼容性最好）
sudo docker run -it --ipc=host --gpus all ultralytics/ultralytics:latest
# CPU 镜像
sudo docker run -it --ipc=host ultralytics/ultralytics:latest-cpu
# 挂载本地目录 + 后台训练，输出持久化
sudo docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
yolo train model=yolo11n.pt data=coco8.yaml epochs=50 project=/w/runs
--ipc=host 共享宿主 IPC 命名空间，使 PyTorch 的 DataLoader 多进程共享内存可用，容器内训练/多进程推理必须加。
5.3 Windows
# 前置：安装 Python 3.10+ 与 CUDA 驱动
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install ultralytics
yolo predict model=yolo11n.pt source=bus.jpg
5.4 macOS
# Apple Silicon 支持 MPS 加速
brew install python
python3 -m venv yolo-env && source yolo-env/bin/activate
pip install ultralytics
yolo predict model=yolo11n.pt source=bus.jpg device=mps
5.5 源码安装
git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics
pip install -e .
yolo predict model=yolo11n.pt source=bus.jpg
六、配置文件全部参数解释
6.1 settings.yaml（全局设置）
位于 ~/.config/Ultralytics/settings.yaml（Linux）、%APPDATA%\Ultralytics\settings.yaml（Windows），可在 Python 中运行以下命令查看与修改：
from ultralytics import settings
print(settings) # 查看全部
settings.update({"datasets_dir": "/data/datasets"})
6.2 训练/推理通用参数（train & predict 共用，摘自官方 cfg 文档）
6.3 推理（predict）参数
6.4 自定义数据集 YAML（带注释完整示例）
# mydataset.yaml —— 目标检测数据集配置
path: /data/datasets/mydataset # 数据集根目录（或相对 settings 中 datasets_dir）
train: images/train # 训练集图片目录（相对 path）
val: images/val # 验证集图片目录
test: images/test # 可选：测试集
names: # 类别：索引从 0 开始
0: person
1: car
2: dog
# 实例分割数据集额外使用 labels 同名 .txt 中的多边形坐标，YAML 写法相同。
标注格式为每图一个同名 .txt：class x_center y_center width height，坐标归一化到 0~1（OBB 为 8 值多边形格式）。
七、启动、后台常驻、开机自启、改端口
YOLO 通常是"跑完即退"的批处理任务，"常驻服务"主要针对流式推理/Web 场景。
前台启动（一次性任务）：
yolo predict model=yolo11n.pt source=video.mp4 save=True
Linux systemd 常驻（RTSP 流实时检测示例）：
# /etc/systemd/system/yolo-stream.service
[Unit]
Description=YOLO RTSP stream detection
After=network-online.target
[Service]
Type=simple
WorkingDirectory=/opt/yolo
ExecStart=/opt/yolo/yolo-env/bin/yolo predict model=yolo11n.pt source=rtsp://camera.local/stream stream_buffer=False save=True project=/opt/yolo/out
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now yolo-stream # 开机自启
journalctl -u yolo-stream -f # 看日志
Supervisor 方式：
[program:yolo-stream]
command=/opt/yolo/yolo-env/bin/yolo predict model=yolo11n.pt source=rtsp://camera.local/stream save=True
directory=/opt/yolo
autostart=true
autorestart=true
stderr_logfile=/var/log/yolo.err.log
stdout_logfile=/var/log/yolo.out.log
Windows： 官方未提供 Windows 服务化方案，替代方式为 NSSM 或计划任务：
# NSSM
nssm install YoloStream "C:\path\yolo-env\Scripts\yolo.exe" "predict model=yolo11n.pt source=rtsp://camera.local/stream save=True"
nssm start YoloStream
Docker Compose 常驻（GPU）：
# docker-compose.yml
services:
yolo:
image: ultralytics/ultralytics:latest
restart: always
ipc: host
devices:
- nvidia.com/gpu=all # 旧版 Docker 用 deploy.resources.reservations.devices + gpus
volumes:
- ./data:/work/data
- ./out:/work/out
command: >-
yolo predict model=yolo11n.pt source=/work/data/stream.mp4
save=True project=/work/out
改端口/输出位置： YOLO 本身不开网络端口；输出的"端口"概念由你自建的 API 服务决定。例如用 FastAPI 包装推理：
# server.py —— 简单推理 HTTP 服务
from fastapi import FastAPI, UploadFile
from ultralytics import YOLO
import numpy as np, cv2
app = FastAPI()
model = YOLO("yolo11n.pt")
@app.post("/detect")
async def detect(file: UploadFile):
img = cv2.imdecode(np.frombuffer(await file.read(), np.uint8), cv2.IMREAD_COLOR)
results = model(img)
return results[0].boxes.data.tolist()
# 启动：uvicorn server:app --host 0.0.0.0 --port 8000
反向代理（Nginx）示例：
location /detect/ {
proxy_pass http://127.0.0.1:8000/;
client_max_body_size 50m;
}
八、功能实操教程
8.1 第一次推理（CLI）
yolo predict model=yolo11n.pt source='https://ultralytics.com/images/bus.jpg'
# 输出形如：
# image 1/1 bus.jpg: 640x480 4 persons, 1 bus, 91.6ms
# Results saved to runs/detect/predict
8.2 Python API 完整生命周期
from ultralytics import YOLO
model = YOLO("yolo11n.pt")
# 训练（官方微型数据集 coco8，几秒即可跑通全流程验证环境）
results = model.train(data="coco8.yaml", epochs=20, imgsz=640, device=0)
# 验证
metrics = model.val() # 返回 mAP50-95 等指标
print(metrics.box.map) # mAP50-95
# 推理
res = model("path/to/image.jpg")
res[0].show()
print(res[0].boxes.cls) # 类别索引
print(res[0].boxes.conf) # 置信度
# 导出 ONNX
path = model.export(format="onnx") # 返回 yolo11n.onnx 路径
8.3 训练自定义数据集
按第六章 6.4 准备
mydataset.yaml与标注。训练：
yolo train model=yolo11n.pt data=mydataset.yaml epochs=100 imgsz=640 batch=16 device=0
训练产物在
runs/detect/train/：weights/best.pt（最优）、results.png（曲线）、confusion_matrix.png。用
best.pt推理：
yolo predict model=runs/detect/train/weights/best.pt source=test.jpg
8.4 视频流多目标追踪
from ultralytics import YOLO
model = YOLO("yolo11n.pt")
results = model.track(source="video.mp4", tracker="botsort.yaml", show=True, stream=True)
for r in results:
print(r.boxes.id) # 每帧目标 ID（追踪专属属性）
8.5 导出 TensorRT 并在边缘设备推理
# 在有 GPU 的机器上导出（Jetson 上直接装 ultralytics 后执行）
yolo export model=yolo11n.pt format=engine half=True device=0
# 推理
yolo predict model=yolo11n.engine source=stream.mp4
ONNX 精简导出（nms 参数随版本变化，以官方导出文档为准）：
yolo export model=yolo11n.pt format=onnx opset=12
8.6 姿态估计
yolo pose predict model=yolo11n-pose.pt source=person.jpg
from ultralytics import YOLO
r = YOLO("yolo11n-pose.pt")("person.jpg")[0]
print(r.keypoints.xyn) # 17 个关键点归一化坐标
8.7 摄像头实时检测（GUI 环境）
yolo predict model=yolo11n.pt source=0 show=True # source=0 为默认摄像头
8.8 纯 Python 调用公开接口批量处理
from ultralytics import YOLO
import cv2, glob
model = YOLO("yolo11s.pt")
for p in glob.glob("images/*.jpg"):
img = cv2.imread(p)
r = model(img, conf=0.4, classes=[0])[0] # 只要 person 类
if len(r.boxes):
print(p, len(r.boxes), float(r.boxes.conf.max()))
九、全套报错故障排查
十、升级、回滚与卸载
版本查看：
yolo version
pip show ultralytics
docker image ls ultralytics/ultralytics
升级（pip）：
pip install -U ultralytics
# 国内加速：pip install -U ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple
升级（Docker）：
docker pull ultralytics/ultralytics:latest
# 停旧容器后用新镜像重建（镜像本身无状态，数据在挂载卷里）
回滚到指定版本：
pip install ultralytics==8.3.0
docker run -it --ipc=host ultralytics/ultralytics:8.3.0-cpu
完整卸载清理清单：
# 1. 卸载 Python 包
pip uninstall -y ultralytics
# 2. 删除全局设置、缓存权重、下载的数据集（按 settings.yaml 中各目录删除）
rm -rf ~/.config/Ultralytics
# 3. 删除训练输出
rm -rf runs/
# 4. Docker 清理
docker rm -f <yolo容器>
docker rmi ultralytics/ultralytics:latest
docker volume rm <相关数据卷> # 确认无训练产物后
# 5. 虚拟环境
deactivate && rm -rf yolo-env
十一、商用许可与合规风险提示
合规要点：
AGPL 传染性强：仅"内部使用且不分发"在多数解读下也有开源义务争议，上线商业服务前请务必咨询法务或购买企业许可。
商标："Ultralytics" 与 "YOLO" 相关品牌由 Ultralytics 公司持有（YOLO 作为算法名本身历史复杂，但 Ultralytics YOLO 产品标识受保护），商用宣传中注意措辞。
无 API 费用：软件本身免费下载使用，不产生官方 API 费用；但
sync/HUB 功能会与 Ultralytics 云端交互，可在settings中关闭sync。出网行为：首次运行会从 GitHub 下载权重与字体、从 Ultralytics 服务器下载数据集；离线环境需预置这些文件。
sync=True会发送匿名使用统计，敏感环境应关闭。生产风险：模型输出不保证 100% 准确，涉及安全/合规决策的场景（如安防执法）需人工复核；预训练模型基于 COCO 等公开数据集，域外场景必须重新训练验证。
附录：命令速查
# 安装
pip install ultralytics
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
# 推理
yolo predict model=yolo11n.pt source=bus.jpg save=True
yolo predict model=yolo11n.pt source=0 show=True # 摄像头
yolo segment predict model=yolo11n-seg.pt source=img.jpg
yolo pose predict model=yolo11n-pose.pt source=img.jpg
yolo obb predict model=yolo11n-obb.pt source=aerial.jpg
# 训练 / 验证
yolo train model=yolo11n.pt data=coco8.yaml epochs=100 imgsz=640 device=0
yolo val model=yolo11n.pt data=coco8.yaml
# 追踪 / 导出
yolo track model=yolo11n.pt source=video.mp4
yolo export model=yolo11n.pt format=onnx
yolo export model=yolo11n.pt format=engine half=True device=0
# Docker
docker run -it --ipc=host --gpus all ultralytics/ultralytics:latest
docker run -it --ipc=host ultralytics/ultralytics:latest-cpu
docker run --rm -it -v "$(pwd)":/w -w /w ultralytics/ultralytics:latest \
yolo train model=yolo11n.pt data=coco8.yaml project=/w/runs
# 设置
yolo settings # 查看全局设置