前言

YOLOv13 是 YOLO 系列的全新一代实时目标检测框架，在保持极高推理速度的同时显著提升了检测精度，广泛适用于嵌入式部署、工业质检、智能安防等多种场景。该版本提供了 Nano、Small、Large、X-Large 四种模型规格，用户可以根据计算资源和具体任务需求灵活选择最适合的模型。

YOLOv13 在结构设计上引入了多项关键创新：HyperACE 模块（Hypergraph-based Adaptive Cross-scale Encoding） 通过将多尺度特征图的像素视为超图节点，使用可学习超边构建自适应建模多尺度特征之间的高阶语义关联，并借助线性消息传递提高复杂环境下的特征融合与感知能力。FullPAD 机制（Full-pipeline Aggregation and Distribution） 基于 HyperACE 模块，将增强后的跨尺度特征依次传递至骨干网络、特征融合层（neck）以及检测头（head），实现网络中信息的全路径聚合与分发，从而显著提升梯度传导效率和多层特征协同表现。此外，为提升推理效率并减轻模型体积，YOLOv13 引入了一系列轻量化结构设计，使用 深度可分离卷积（Depthwise Separable Convolution, DSConv）替代大核普通卷积，有效减少参数量与计算开销，同时保持或提升检出准确率。

本教程以 Ubuntu 20.04 操作系统 为基础，面向个人开发者与工程实践需求，详细介绍 YOLOv13 的安装配置、数据集准备、模型训练与推理部署等完整流程，帮助读者从零完成模型构建与应用。
在开始操作之前，请确保系统已正确安装 Anaconda 或 Miniconda，以便创建和管理 Python 虚拟环境；同时已安装官方版本的 NVIDIA 显卡驱动，以确保 GPU 能够被正常识别并用于训练或推理。可使用以下命令验证 GPU 状态，并记录输出中的 CUDA Version，后续安装 PyTorch 时将作为参考：

nvidia-smi

---

一、下载 YOLOv13 源码

YOLOv13 目前未归属于 Ultralytics 官方分支，通常采用开源社区维护版本。您可以选择以下任一方式获取源码：

方式一：通过网页手动下载

1. 访问 YOLOv13 项目主页

2. 点击 Code > Download ZIP

   

3. 下载后解压至本地任意目录。

方式二：通过 Git 克隆

git clone https://github.com/iMoonLab/yolov13.git
cd yolov13

---

二、配置运行环境

2.1 创建并激活 Conda 虚拟环境

conda create -n yolov13 python=3.11 -y
conda activate yolov13

建议使用 Python 3.11 版本以确保与依赖项（如 FlashAttention）兼容。

2.2 安装依赖项

1. 将 requirements.txt 文件内容替换为以下：

   # torch==2.2.2 
   # torchvision==0.17.2
   # flash_attn-2.7.3+cu11torch2.2cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
   timm==1.0.14
   albumentations==2.0.4
   onnx==1.14.0
   onnxruntime==1.15.1
   pycocotools==2.0.7
   PyYAML==6.0.1
   scipy==1.13.0
   onnxslim==0.1.31
   onnxruntime-gpu==1.18.0
   gradio==4.44.1
   opencv-python==4.9.0.80
   psutil==5.9.8
   py-cpuinfo==9.0.0
   huggingface-hub==0.23.2
   safetensors==0.4.3
   numpy==1.26.4
   supervision==0.22.0
   thop
   seaborn
   

2. 使用国内源安装依赖

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2.3 配置 PyTorch 环境

1. 访问 PyTorch 官网历史版本页

2. 选择 Pytorch Version >= 2.4.0 Conda/Wheel 安装命令（CUDA 版本应不高于本机 nvidia-smi 输出结果）

   
   3. 终端运行安装命令

   pip install torch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 --index-url https://download.pytorch.org/whl/cu121
   

2.4 安装 FlashAttention（可选）

1. 打开 FlashAttention Releases (Linux) 页面

2. 下载适配当前系统架构和 CUDA 版本的 .whl 文件（推荐 v2.7.3）至 yolov13 目录下

   

3. 执行安装命令

   pip install ./flash_attn-2.7.3+cu12torch2.4cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
   

---

三、准备数据集

3.1 构建数据集目录结构

1. 在 yolov13 目录下新建 data 文件夹

2. 在 yolov13/data/ 目录下建立以下文件夹：

   data/
   ├── Annotations/     # 存放 .xml 标注文件
   ├── images/          # 存放原始图像（.jpg）
   ├── ImageSets/       # 数据集划分列表
   └── labels/          # 转换后的 YOLO 格式标签
   

   建议使用 labelimg 工具对图像进行 VOC 格式标注，标注结果保存为 .xml 文件置于 Annotations/ 文件夹

3.2 数据集划分

在项目根目录下创建 split_train_val.py 脚本，运行后将在 ImageSets/ 生成 train.txt、val.txt、test.txt 等文件

import os
import randomtrainval_percent = 0.9
train_percent = 0.9
xmlfilepath = 'data/Annotations'
txtsavepath = 'data/ImageSets'
total_xml = os.listdir(xmlfilepath)num = len(total_xml)
list = range(num)
tv = int(num * trainval_percent)
tr = int(tv * train_percent)
trainval = random.sample(list, tv)
train = random.sample(trainval, tr)ftrainval = open('data/ImageSets/trainval.txt', 'w')
ftest = open('data/ImageSets/test.txt', 'w')
ftrain = open('data/ImageSets/train.txt', 'w')
fval = open('data/ImageSets/val.txt', 'w')for i in list:name = total_xml[i][:-4] + '\n'if i in trainval:ftrainval.write(name)if i in train:ftrain.write(name)else:fval.write(name)else:ftest.write(name)ftrainval.close()
ftrain.close()
fval.close()
ftest.close()

3.3 转换数据格式

使用 voc_label.py 将 VOC 标注转为 YOLO 格式，并生成 labels/*.txt 与 train.txt 等路径列表（请注意将 classes 列表修改为你的目标类别）

import xml.etree.ElementTree as ET
import os
from os import getcwdsets = ['train', 'val', 'test']
classes = ['填写自己的类别']
abs_path = os.getcwd()
print(abs_path)def convert(size, box):dw = 1. / (size[0])dh = 1. / (size[1])x = (box[0] + box[1]) / 2.0 - 1y = (box[2] + box[3]) / 2.0 - 1w = box[1] - box[0]h = box[3] - box[2]x = x * dww = w * dwy = y * dhh = h * dhreturn x, y, w, hdef convert_annotation(image_id):in_file = open('data/Annotations/%s.xml' % (image_id), encoding='UTF-8')out_file = open('data/labels/%s.txt' % (image_id), 'w')tree = ET.parse(in_file)root = tree.getroot()size = root.find('size')w = int(size.find('width').text)h = int(size.find('height').text)for obj in root.iter('object'):# difficult = obj.find('difficult').textdifficult = obj.find('difficult').textcls = obj.find('name').textif cls not in classes or int(difficult) == 1:continuecls_id = classes.index(cls)xmlbox = obj.find('bndbox')b = (float(xmlbox.find('xmin').text), float(xmlbox.find('xmax').text), float(xmlbox.find('ymin').text),float(xmlbox.find('ymax').text))b1, b2, b3, b4 = b# 标注越界修正if b2 > w:b2 = wif b4 > h:b4 = hb = (b1, b2, b3, b4)bb = convert((w, h), b)out_file.write(str(cls_id) + " " + " ".join([str(a) for a in bb]) + '\n')wd = getcwd()
for image_set in sets:if not os.path.exists('data/labels/'):os.makedirs('data/labels/')image_ids = open('data/ImageSets/%s.txt' % (image_set)).read().strip().split()list_file = open('data/%s.txt' % (image_set), 'w')for image_id in image_ids:list_file.write(abs_path + '/data/images/%s.jpg\n' % (image_id))convert_annotation(image_id)list_file.close()

3.4 编写数据集配置文件

在yolov13/data目录下创建 data.yaml，内容如下：

# 路径请根据实际情况填写，需为 train/val/test 图片路径列表的绝对路径
train: /home/your_username/yolov13/data/train.txt
val: /home/your_username/yolov13/data/val.txt
test: /home/your_username/yolov13/data/test.txt# 修改为你的类别总数
nc: 5# 类别名称列表，应与 voc_label.py 中填写的类别顺序完全一致
names: ['填写自己的类别']

3.5 下载预训练权重

1. 在yolov13目录下创建 weights 文件夹

2. 打开 YOLOv13 项目主页

3. 下滑找到 YOLOv13-N YOLOv13-S ...，点击并下载至 yolov13/weights 文件夹

   

---

四、模型训练

在项目根目录下创建 train.py，内容如下（根据需要修改对应参数）：

from ultralytics import YOLOif __name__ == '__main__':# 初始化模型，加载预训练权重model = YOLO('weights/yolov13n.pt')  # 可替换为 yolov13s.pt、yolov13m.pt 等其他版本# 启动模型训练results = model.train(data='/home/your_username/yolov13/data/data.yaml',  # 修改为您的数据集配置文件的绝对路径epochs=180,      # 总训练轮数，视数据集规模与性能要求调整batch=4,         # 每轮训练的批量大小，取决于显存大小（如 8GB 显存建议 batch=4~8）workers=2,       # 数据加载线程数，推荐设为 CPU 核心数的一半左右imgsz=640,       # 输入图像尺寸，训练时将图像缩放至该大小（YOLO 通常为 640×640）mosaic=1.0,      # Mosaic 数据增强概率，范围为 0.0~1.0（适当提高可增强鲁棒性）mixup=0.0,       # MixUp 数据增强权重，适用于多目标融合背景，适当使用可缓解过拟合copy_paste=0.1,  # Copy-Paste 增强比例，常用于分割任务，对检测任务影响较小device=0         # 训练所使用的设备编号，0 表示第 1 块 GPU；如无 GPU 请设置为 'cpu')

运行训练命令：

python train.py

训练过程中将自动保存模型权重与日志，默认输出路径为 runs/detect/ 目录。

---

五、模型推理

1. 静态图像或视频文件推理：在项目根目录下创建 inference.py 文件，用于实现对图像或视频文件的目标检测功能，示例代码如下：

   from ultralytics import YOLO
   import cv2if __name__ == '__main__':# 加载训练好的模型model = YOLO('runs/detect/train/weights/best.pt')  # 修改为实际路径，或替换为 yolov13n.pt 等预训练权重# 指定输入源，可为图像路径、视频路径results = model.predict(source='data/images/test.jpg',  # 输入图像路径save=True,                      # 是否保存带有预测框的输出图像conf=0.25,                      # 置信度阈值（过滤低置信度目标）iou=0.45,                       # NMS 阈值，用于消除重叠框device=0                        # 推理设备，0 表示使用 GPU，'cpu' 表示使用 CPU)
   

   默认预测结果将保存至 runs/detect/predict/ 目录下

2. 摄像头画面实时推理：在项目根目录下创建 detect.py 文件，实现对来自本地摄像头的视频流进行实时目标检测，示例代码如下：

   import cv2
   from ultralytics import YOLOif __name__ == '__main__':# 加载模型model = YOLO('runs/detect/exp/weights/best.pt')  # 替换为你的权重路径# 打开摄像头cap = cv2.VideoCapture(0)if not cap.isOpened():print("无法打开摄像头")exit()while True:ret, frame = cap.read()if not ret:print("无法读取视频帧")break# 推理results = model.predict(frame, conf=0.25, iou=0.45, device=0, verbose=False)# 可视化结果（Ultralytics 返回的是带坐标的图像）annotated_frame = results[0].plot()# 显示图像cv2.imshow('YOLOv13 Camera Detection', annotated_frame)# 按下 q 退出if cv2.waitKey(1) & 0xFF == ord('q'):breakcap.release()cv2.destroyAllWindows()
   

---