Skip to content

Commit c716de1

Browse files
isLinXuisLinXu
committed
add wiki for MoE
1 parent f56f2d0 commit c716de1

4 files changed

Lines changed: 757 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@
4040
</div>
4141
<br>
4242

43+
[English](README.md) | [简体中文](README_CN.md)
44+
4345
---
4446

4547
## 💡 A Humble Beginning (Introduction)
@@ -72,6 +74,10 @@ Comprehensive experiments on five large-scale benchmarks demonstrate the superio
7274
<p><i>YOLO-Master introduces ES-MoE blocks to achieve "compute-on-demand" via dynamic routing.</i></p>
7375
</div>
7476

77+
### 📚 In-Depth Documentation
78+
For a deep dive into the design philosophy of MoE modules, detailed routing mechanisms, and optimization guides for deployment on various hardware (GPU/CPU/NPU), please refer to our Wiki:
79+
👉 **[Wiki: MoE Modules Explained](wiki/MoE_Modules_Explanation_EN.md)**
80+
7581

7682
## 📖 Table of Contents
7783

@@ -272,7 +278,7 @@ Train a new model on your custom dataset or COCO.
272278
from ultralytics import YOLO
273279

274280
# Load a model
275-
model = YOLO('yolo_master.yaml') # build a new model from YAML
281+
model = YOLO('cfg/models/master/v0/det/yolo-master-n.yaml') # build a new model from YAML
276282

277283
# Train the model
278284
results = model.train(

‎README_CN.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
<div align="center">
2+
<h1>YOLO-MASTER</h1>
3+
4+
5+
<p align="left"> <a href="https://huggingface.co/spaces/xx"> <img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue" alt="Hugging Face Spaces"> </a> <a href="https://colab.research.google.com/github/isLinXu/YOLO-Master"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"> </a> <a href="https://arxiv.org/abs/2512.23273"> <img src="https://img.shields.io/badge/arXiv-2512.23273-b31b1b.svg" alt="arXiv"> </a> <a href="https://github.com/isLinXu/YOLO-Master/releases"> <img src="https://img.shields.io/badge/%F0%9F%93%A6-Model%20Zoo-orange" alt="Model Zoo"> </a> <a href="./LICENSE"> <img src="https://img.shields.io/badge/License-AGPL%203.0-blue.svg" alt="AGPL 3.0"> </a> <a href="https://github.com/ultralytics/ultralytics"> <img src="https://img.shields.io/badge/Ultralytics-YOLO-blue" alt="Ultralytics"> </a> </p>
6+
7+
8+
<p align="center">
9+
YOLO-Master:
10+
<b><u>M</u></b>OE-<b><u>A</u></b>ccelerated with
11+
<b><u>S</u></b>pecialized <b><u>T</u></b>ransformers for
12+
<b><u>E</u></b>nhanced <b><u>R</u></b>eal-time Detection.
13+
</p>
14+
</div>
15+
16+
<div align="center">
17+
<div style="text-align: center; margin-bottom: 8px;">
18+
<a href="https://github.com/isLinXu" style="text-decoration: none;"><b>Xu Lin</b></a><sup>1*</sup>&nbsp;&nbsp;
19+
<a href="https://pjl1995.github.io/" style="text-decoration: none;"><b>Jinlong Peng</b></a><sup>1*</sup>&nbsp;&nbsp;
20+
<a href="https://scholar.google.com/citations?user=fa4NkScAAAAJ" style="text-decoration: none;"><b>Zhenye Gan</b></a><sup>1</sup>&nbsp;&nbsp;
21+
<a href="https://scholar.google.com/citations?hl=en&user=cU0UfhwAAAAJ" style="text-decoration: none;"><b>Jiawen Zhu</b></a><sup>2</sup>&nbsp;&nbsp;
22+
<a href="https://scholar.google.com/citations?user=JIKuf4AAAAAJ&hl=zh-TW" style="text-decoration: none;"><b>Jun Liu</b></a><sup>1</sup>
23+
</div>
24+
25+
<div style="text-align: center; margin-bottom: 4px; font-size: 0.95em;">
26+
<sup>1</sup>Tencent Youtu Lab &nbsp;&nbsp;&nbsp;
27+
<sup>2</sup>Singapore Management University
28+
</div>
29+
30+
<div style="text-align: center; margin-bottom: 12px; font-size: 0.85em; color: #666; font-style: italic;">
31+
<sup>*</sup>Equal Contribution
32+
</div>
33+
34+
<div style="text-align: center;">
35+
<div style="font-family: 'Courier New', Courier, monospace; font-size: 0.85em; background-color: #f6f8fa; padding: 10px; border-radius: 6px; display: inline-block; line-height: 1.4; text-align: left;">
36+
{gatilin, jeromepeng, wingzygan, juliusliu}@tencent.com <br>
37+
jwzhu.2022@phdcs.smu.edu.sg
38+
</div>
39+
</div>
40+
</div>
41+
<br>
42+
43+
[English](README.md) | [简体中文](README_CN.md)
44+
45+
---
46+
47+
## 💡 初心 (Introduction)
48+
49+
> **"探索 YOLO 中动态智能的前沿。"**
50+
51+
这项工作代表了我们对实时目标检测 (RTOD) 演进的热情探索。据我们所知，**YOLO-Master 是首个在通用数据集上将混合专家 (MoE) 架构与 YOLO 深度融合的工作。**
52+
53+
大多数现有的 YOLO 模型依赖于静态的密集计算——即对简单的天空背景和复杂的拥挤路口分配相同的计算预算。我们认为检测模型应该更加“自适应”，就像人类视觉系统一样。虽然这次初步探索可能并不完美，但它展示了 **高效稀疏 MoE (ES-MoE)** 在平衡高精度与超低延迟方面的巨大潜力。我们将致力于持续迭代和优化，以进一步完善这一方法。
54+
55+
展望未来，我们从 LLM 和 VLM 的变革性进步中汲取灵感。我们将致力于完善这一方法，并将这些见解扩展到基础视觉任务中，最终目标是解决更具雄心的前沿问题，如开放词汇检测和开放集分割。
56+
57+
<details>
58+
<summary>
59+
<font size="+1"><b>摘要 (Abstract)</b></font>
60+
</summary>
61+
现有的实时目标检测 (RTOD) 方法通常采用类 YOLO 架构，因为它们在精度和速度之间取得了良好的平衡。然而，这些模型依赖于静态密集计算，对所有输入应用统一的处理，导致表示能力和计算资源的分配不当，例如在简单场景上过度分配，而在复杂场景上服务不足。这种不匹配导致了计算冗余和次优的检测性能。
62+
63+
为了克服这一限制，我们提出了 YOLO-Master，这是一种新颖的类 YOLO 框架，为 RTOD 引入了实例条件自适应计算。这是通过高效稀疏混合专家 (ES-MoE) 块实现的，该块根据场景复杂度动态地为每个输入分配计算资源。其核心是一个轻量级的动态路由网络，通过多样性增强目标指导专家在训练期间的专业化，鼓励专家之间形成互补的专业知识。此外，路由网络自适应地学习仅激活最相关的专家，从而在提高检测性能的同时，最大限度地减少推理过程中的计算开销。
64+
65+
在五个大规模基准测试上的综合实验证明了 YOLO-Master 的优越性。在 MS COCO 上，我们的模型实现了 42.4% 的 AP 和 1.62ms 的延迟，比 YOLOv13-N 高出 +0.8% mAP，推理速度快 17.8%。值得注意的是，在具有挑战性的密集场景中收益最为明显，同时模型在典型输入上保持了效率并维持了实时推理速度。代码: [isLinXu/YOLO-Master](https://github.com/isLinXu/YOLO-Master)
66+
</details>
67+
68+
---
69+
70+
## 🎨 架构
71+
72+
<div align="center">
73+
<img width="90%" alt="YOLO-Master Architecture" src="https://github.com/user-attachments/assets/6caa1065-af77-4f77-8faf-7551c013dacd" />
74+
<p><i>YOLO-Master 引入 ES-MoE 块，通过动态路由实现“按需计算”。</i></p>
75+
</div>
76+
77+
### 📚 深度文档
78+
关于 MoE 模块的设计理念、路由机制详解以及针对不同硬件（GPU/CPU/NPU）的部署优化指南，请参阅我们的 Wiki 文档：
79+
👉 **[Wiki: MoE 模块详解与演进](wiki/MoE_Modules_Explanation.md)**
80+
81+
## 📖 目录
82+
83+
- [初心](#-初心-introduction)
84+
- [架构](#-架构)
85+
- [更新](#-更新-latest-first)
86+
- [主要结果](#-主要结果)
87+
- [检测](#检测)
88+
- [分割](#分割)
89+
- [分类](#分类)
90+
- [检测示例](#-检测示例)
91+
- [支持的任务](#-支持的任务)
92+
- [快速开始](#-快速开始)
93+
- [安装](#安装)
94+
- [验证](#验证)
95+
- [训练](#训练)
96+
- [推理](#推理)
97+
- [导出](#导出)
98+
- [Gradio 演示](#gradio-演示)
99+
- [社区与贡献](#-社区与贡献)
100+
- [许可证](#-许可证)
101+
- [致谢](#-致谢)
102+
- [引用](#-引用)
103+
104+
## 🚀 更新 (Latest First)
105+
106+
- **2025/12/30**: arXiv 论文发布。
107+
108+
## 📊 主要结果
109+
### 检测
110+
<div align="center">
111+
<img width="450" alt="Radar chart comparing YOLO models on various datasets" src="https://github.com/user-attachments/assets/743fa632-659b-43b1-accf-f865c8b66754"/>
112+
</div>
113+
114+
115+
<div align="center">
116+
<p><b>表 1. 五个基准测试上与最先进 Nano 级检测器的比较。</b></p>
117+
<table style="border-collapse:collapse; width:100%; font-family:sans-serif; text-align:center; border-top:2px solid #000; border-bottom:2px solid #000; font-size:0.9em;">
118+
<thead>
119+
<tr style="border-bottom:1px solid #ddd;">
120+
<th style="padding:8px; border-right:1px solid #ddd;">数据集</th>
121+
<th colspan="2" style="border-right:1px solid #ddd;">COCO</th>
122+
<th colspan="2" style="border-right:1px solid #ddd;">PASCAL VOC</th>
123+
<th colspan="2" style="border-right:1px solid #ddd;">VisDrone</th>
124+
<th colspan="2" style="border-right:1px solid #ddd;">KITTI</th>
125+
<th colspan="2" style="border-right:1px solid #ddd;">SKU-110K</th>
126+
<th>效率</th>
127+
</tr>
128+
<tr style="border-bottom:1px solid #000;">
129+
<th style="padding:8px; border-right:1px solid #ddd;">方法</th>
130+
<th>mAP<br>(%)</th>
131+
<th style="border-right:1px solid #ddd;">mAP<sub>50</sub><br>(%)</th>
132+
<th>mAP<br>(%)</th>
133+
<th style="border-right:1px solid #ddd;">mAP<sub>50</sub><br>(%)</th>
134+
<th>mAP<br>(%)</th>
135+
<th style="border-right:1px solid #ddd;">mAP<sub>50</sub><br>(%)</th>
136+
<th>mAP<br>(%)</th>
137+
<th style="border-right:1px solid #ddd;">mAP<sub>50</sub><br>(%)</th>
138+
<th>mAP<br>(%)</th>
139+
<th style="border-right:1px solid #ddd;">mAP<sub>50</sub><br>(%)</th>
140+
<th>延迟<br>(ms)</th>
141+
</tr>
142+
</thead>
143+
<tbody>
144+
<tr>
145+
<td style="padding:6px; text-align:left; border-right:1px solid #ddd;">YOLOv10</td>
146+
<td>38.5</td><td style="border-right:1px solid #ddd;">53.8</td>
147+
<td>60.6</td><td style="border-right:1px solid #ddd;">80.3</td>
148+
<td>18.7</td><td style="border-right:1px solid #ddd;">32.4</td>
149+
<td>66.0</td><td style="border-right:1px solid #ddd;">88.3</td>
150+
<td>57.4</td><td style="border-right:1px solid #ddd;">90.0</td>
151+
<td>1.84</td>
152+
</tr>
153+
<tr>
154+
<td style="padding:6px; text-align:left; border-right:1px solid #ddd;">YOLOv11-N</td>
155+
<td>39.4</td><td style="border-right:1px solid #ddd;">55.3</td>
156+
<td>61.0</td><td style="border-right:1px solid #ddd;">81.2</td>
157+
<td>18.5</td><td style="border-right:1px solid #ddd;">32.2</td>
158+
<td>67.8</td><td style="border-right:1px solid #ddd;">89.8</td>
159+
<td>57.4</td><td style="border-right:1px solid #ddd;">90.0</td>
160+
<td>1.50</td>
161+
</tr>
162+
<tr>
163+
<td style="padding:6px; text-align:left; border-right:1px solid #ddd;">YOLOv12-N</td>
164+
<td>40.6</td><td style="border-right:1px solid #ddd;">56.7</td>
165+
<td>60.7</td><td style="border-right:1px solid #ddd;">80.8</td>
166+
<td>18.3</td><td style="border-right:1px solid #ddd;">31.7</td>
167+
<td>67.6</td><td style="border-right:1px solid #ddd;">89.3</td>
168+
<td>57.4</td><td style="border-right:1px solid #ddd;">90.0</td>
169+
<td>1.64</td>
170+
</tr>
171+
<tr style="border-bottom:1px solid #000;">
172+
<td style="padding:6px; text-align:left; border-right:1px solid #ddd;">YOLOv13-N</td>
173+
<td>41.6</td><td style="border-right:1px solid #ddd;">57.8</td>
174+
<td>60.7</td><td style="border-right:1px solid #ddd;">80.3</td>
175+
<td>17.5</td><td style="border-right:1px solid #ddd;">30.6</td>
176+
<td>67.7</td><td style="border-right:1px solid #ddd;">90.6</td>
177+
<td>57.5</td><td style="border-right:1px solid #ddd;">90.3</td>
178+
<td>1.97</td>
179+
</tr>
180+
<tr style="background-color:#f9f9f9;">
181+
<td style="padding:8px; text-align:left; border-right:1px solid #ddd;"><b>YOLO-Master-N</b></td>
182+
<td><b>42.4</b></td><td style="border-right:1px solid #ddd;"><b>59.2</b></td>
183+
<td><b>62.1</b></td><td style="border-right:1px solid #ddd;"><b>81.9</b></td>
184+
<td><b>19.6</b></td><td style="border-right:1px solid #ddd;"><b>33.7</b></td>
185+
<td><b>69.2</b></td><td style="border-right:1px solid #ddd;"><b>91.3</b></td>
186+
<td><b>58.2</b></td><td style="border-right:1px solid #ddd;"><b>90.6</b></td>
187+
<td><b>1.62</b></td>
188+
</tr>
189+
</tbody>
190+
</table>
191+
</div>
192+
193+
### 分割
194+
195+
| **模型** | **尺寸** | **mAPbox (%)** | **mAPmask (%)** | **增益 (mAPmask)** |
196+
| --------------------- | -------- | -------------- | --------------- | ------------------ |
197+
| YOLOv11-seg-N | 640 | 38.9 | 32.0 | - |
198+
| YOLOv12-seg-N | 640 | 39.9 | 32.8 | Baseline |
199+
| **YOLO-Master-seg-N** | **640** | **42.9** | **35.6** | **+2.8%** 🚀 |
200+
201+
### 分类
202+
203+
| **模型** | **数据集** | **输入尺寸** | **Top-1 Acc (%)** | **Top-5 Acc (%)** | **对比** |
204+
| --------------------- | ------------ | -------------- | ----------------- | ----------------- | ----------------- |
205+
| YOLOv11-cls-N | ImageNet | 224 | 70.0 | 89.4 | Baseline |
206+
| YOLOv12-cls-N | ImageNet | 224 | 71.7 | 90.5 | +1.7% Top-1 |
207+
| **YOLO-Master-cls-N** | **ImageNet** | **224** | **76.6** | **93.4** | **+4.9% Top-1** 🔥 |
208+
209+
## 🖼️ 检测示例
210+
211+
<div align="center">
212+
<img width="1416" height="856" alt="Detection Examples" src="https://github.com/user-attachments/assets/0e1fbe4a-34e7-489e-b936-6d121ede5cf6" /> </div>
213+
<table border="0"> <tr> <td align="center" style="font-weight: bold; background-color: #f6f8fa;"> <b>检测</b> </td> <td width="45%"> <img src="https://github.com/user-attachments/assets/db350acd-1d91-4be6-96b2-6bdf8aac57e8" alt="Detection 1" style="width:100%; display:block; border-radius:4px;"> </td> <td width="45%"> <img src="https://github.com/user-attachments/assets/b6c80dbd-120e-428b-8d26-ea2b38a40b47" alt="Detection 2" style="width:100%; display:block; border-radius:4px;"> </td> </tr> <tr> <td align="center" style="font-weight: bold; background-color: #f6f8fa;"> <b>分割</b> </td> <td width="45%"> <img src="https://github.com/user-attachments/assets/edb05e3c-cd83-41db-89f8-8ef09fc22798" alt="Segmentation 1" style="width:100%; display:block; border-radius:4px;"> </td> <td width="45%"> <img src="https://github.com/user-attachments/assets/ea138674-d7c7-48fb-b272-3ec211d161bf" alt="Segmentation 2" style="width:100%; display:block; border-radius:4px;"> </td> </tr> </table>
214+
215+
216+
217+
## 🧩 支持的任务
218+
219+
YOLO-Master 建立在强大的 Ultralytics 框架之上，继承了对各种计算机视觉任务的支持。虽然我们的研究主要集中在实时目标检测，但代码库支持：
220+
221+
| 任务 | 状态 | 描述 |
222+
|:-----|:------:|:------------|
223+
| **目标检测** | ✅ | 具有 ES-MoE 加速的实时目标检测。 |
224+
| **实例分割** | ✅ | 实验性支持 (继承自 Ultralytics)。 |
225+
| **姿态估计** | 🚧 | 实验性支持 (继承自 Ultralytics)。 |
226+
| **OBB 检测** | 🚧 | 实验性支持 (继承自 Ultralytics)。 |
227+
| **图像分类** | ✅ | 图像分类支持。 |
228+
229+
## ⚙️ 快速开始
230+
231+
### 安装
232+
233+
<details open>
234+
<summary><strong>通过 pip 安装 (推荐)</strong></summary>
235+
236+
```bash
237+
# 1. 创建并激活新环境
238+
conda create -n yolo_master python=3.11 -y
239+
conda activate yolo_master
240+
241+
# 2. 克隆仓库
242+
git clone https://github.com/isLinXu/YOLO-Master
243+
cd YOLO-Master
244+
245+
# 3. 安装依赖
246+
pip install -r requirements.txt
247+
pip install -e .
248+
249+
# 4. 可选: 安装 FlashAttention 以加速训练 (需要 CUDA)
250+
pip install flash_attn
251+
```
252+
</details>
253+
254+
### 验证
255+
256+
在 COCO 数据集上验证模型精度。
257+
258+
```python
259+
from ultralytics import YOLO
260+
261+
# 加载预训练模型
262+
model = YOLO("yolo_master_n.pt")
263+
264+
# 运行验证
265+
metrics = model.val(data="coco.yaml", save_json=True)
266+
print(metrics.box.map) # map50-95
267+
```
268+
269+
### 训练
270+
271+
在自定义数据集或 COCO 上训练新模型。
272+
273+
```python
274+
from ultralytics import YOLO
275+
276+
# 加载模型
277+
model = YOLO('cfg/models/master/v0/det/yolo-master-n.yaml') # 从 YAML 构建新模型
278+
279+
# 训练模型
280+
results = model.train(
281+
data='coco.yaml',
282+
epochs=600,
283+
batch=256,
284+
imgsz=640,
285+
device="0,1,2,3", # 使用多 GPU
286+
scale=0.5,
287+
mosaic=1.0,
288+
mixup=0.0,
289+
copy_paste=0.1
290+
)
291+
```
292+
293+
### 推理
294+
295+
对图像或视频进行推理。
296+
297+
**Python:**
298+
```python
299+
from ultralytics import YOLO
300+
301+
model = YOLO("yolo_master_n.pt")
302+
results = model("path/to/image.jpg")
303+
results[0].show()
304+
```
305+
306+
**CLI:**
307+
```bash
308+
yolo predict model=yolo_master_n.pt source='path/to/image.jpg' show=True
309+
```
310+
311+
### 导出
312+
313+
将模型导出为其他格式以进行部署 (TensorRT, ONNX 等)。
314+
315+
```python
316+
from ultralytics import YOLO
317+
318+
model = YOLO("yolo_master_n.pt")
319+
model.export(format="engine", half=True) # 导出为 TensorRT
320+
# 格式: onnx, openvino, engine, coreml, saved_model, pb, tflite, edgetpu, tfjs
321+
```
322+
323+
### Gradio 演示
324+
325+
启动本地 Web 界面以交互式测试模型。此应用程序提供了一个用户友好的 Gradio 仪表板，用于模型推理，支持自动模型扫描、任务切换（检测、分割、分类）和实时可视化。
326+
327+
```bash
328+
python app.py
329+
# 在浏览器中打开 http://127.0.0.1:7860
330+
```
331+
332+
## 🤝 社区与贡献
333+
334+
我们欢迎贡献！有关如何参与的详细信息，请查看我们的 [贡献指南](CONTRIBUTING.md)。
335+
336+
- **Issues**: 在 [这里](https://github.com/isLinXu/YOLO-Master/issues) 报告错误或请求功能。
337+
- **Pull Requests**: 提交您的改进。
338+
339+
## 📄 许可证
340+
341+
本项目采用 [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE) 许可证。
342+
343+
## 🙏 致谢
344+
345+
这项工作建立在优秀的 [Ultralytics](https://github.com/ultralytics/ultralytics) 框架之上。非常感谢社区的贡献、部署和教程！
346+
347+
## 📝 引用
348+
349+
如果您在研究中使用 YOLO-Master，请引用我们的论文：
350+
351+
```bibtex
352+
@article{lin2025yolomaster,
353+
title={{YOLO-Master}: MOE-Accelerated with Specialized Transformers for Enhanced Real-time Detection},
354+
author={Lin, Xu and Peng, Jinlong and Gan, Zhenye and Zhu, Jiawen and Liu, Jun},
355+
journal={arXiv preprint arXiv:},
356+
year={2025}
357+
}
358+
```
359+
360+
⭐ **如果您觉得这项工作有用，请给仓库点个星！**

0 commit comments

Comments
 (0)