前言
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 官方分支,通常采用開源社區維護版本。您可以選擇以下任一方式獲取源碼:
方式一:通過網頁手動下載
-
訪問 YOLOv13 項目主頁
-
點擊 Code > Download ZIP
-
下載后解壓至本地任意目錄。
方式二:通過 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 安裝依賴項
-
將
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
-
使用國內源安裝依賴
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
2.3 配置 PyTorch 環境
-
訪問 PyTorch 官網歷史版本頁
-
選擇
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(可選)
-
打開 FlashAttention Releases (Linux) 頁面
-
下載適配當前系統架構和 CUDA 版本的
.whl
文件(推薦v2.7.3
)至yolov13
目錄下 -
執行安裝命令
pip install ./flash_attn-2.7.3+cu12torch2.4cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
三、準備數據集
3.1 構建數據集目錄結構
-
在
yolov13
目錄下新建data
文件夾 -
在
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 下載預訓練權重
-
在
yolov13
目錄下創建weights
文件夾 -
打開 YOLOv13 項目主頁
-
下滑找到
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/
目錄。
五、模型推理
-
靜態圖像或視頻文件推理:在項目根目錄下創建
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/
目錄下 -
攝像頭畫面實時推理:在項目根目錄下創建
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()