前言

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

---