竞赛指南: YOLO-Master 贡献路径

ncnn 贡献指南见 竞赛指南: ncnn YOLO-Master 架构见 精读: yolo-master 部署链见 跨赛道: YOLO → 端侧

调研元信息

一句话定位

YOLO-Master 是腾讯优图 CVPR 2026 工作（ES-MoE YOLO），~80 文件、6 个 good-first-issue、agent/ 目录为犀牛鸟最友好切入点——用 Python 就能贡献，无需 GPU 训练。

日常类比

想象一个大学实验室发布了一个「智能分诊机器人」的开源原型：核心算法（MoE 路由）需要医学博士才能改，但前台接待系统（agent/）、使用说明书（docs/wiki/）、展示界面（app.py Gradio）任何实习生都能优化。犀牛鸟就是从「前台」做起，逐步理解「后台算法」的过程。

agent/ 目录深度解读 [源码]

架构总览

graph TD
    subgraph agent/
        A[scripts/] -->|thin wrapper| B[runtime/cli/dispatcher.py]
        B --> C[core_handlers.py<br/>train/val/predict/export]
        B --> D[multimodal_handlers.py<br/>VLM/LLM inference]
        B --> E[moe_tools.py<br/>MoE diagnose/prune]
        B --> F[pipeline.py<br/>end-to-end experiments]
        G[runtime/evaluation/] --> H[metrics.py]
        I[runtime/multimodal/] --> J[fusion.py + visual.py]
        K[runtime/open_world/] --> L[taxonomy.py<br/>LVIS 1203 + V3Det 13204]
    end
    
    M[SKILL.md] -.->|AI agent 读| B
    N[assets/] -.->|prompts + taxonomy| I

关键文件职责

执行模型

用户/AI 请求 → scripts/ (thin entry) → dispatcher.py (路由)
    → core_handlers (yolo CLI 封装)
    → multimodal_handlers (YOLO + VLM pipeline)
    → moe_tools (诊断/剪枝)
    → pipeline (端到端实验)

Apple Silicon 支持：SKILL.md 明确 mps 为 heavy compute 默认设备，失败自动回退 CPU。

贡献分级

Good-First-Issue 候选 [Issue]

YOLO-Master 有 19 open issues，6 个标记 good-first-issue：

非 GFI 但有价值的 issues

与 Ultralytics 的关系

YOLO-Master 基于 Ultralytics 框架构建：

ultralytics/ (上游框架代码, AGPL-3.0)
├── nn/modules/moe/  ← YOLO-Master 核心创新（10 文件）
├── cfg/models/       ← MoE YAML 配置
└── 其余               ← 标准 Ultralytics

agent/                ← YOLO-Master 独有（技能封装层）
docs/ + wiki/         ← YOLO-Master 独有文档

改 MoE vs 改 Ultralytics 通用层的区别：

MoE 模块速览（含部署风险）[源码]

10 个 MoE 相关文件在 ultralytics/nn/modules/moe/：

• modules.py：10+ MoE 变体（ES_MOE → UltraOptimizedMoE → HybridAdaptiveGateMoE…）
• routers.py：7 种路由器（BaseRouter → UltraEfficientRouter）
• experts.py：8 种专家实现（SimpleExpert → SharedInvertedExpertGroup）
• analysis.py：ExpertUsageTracker + RoutingCollapseDetector
• diagnostics.py + history.py：运行时诊断记录
• pruning.py：MoE → 单专家剪枝
• loss.py：MoE 专用损失函数

部署核心风险（link → challenges.md #8）：

• MoE 动态路由 = 条件分支 → ONNX/ncnn 静态图不直接支持
• 推荐 workaround：pruning.py 蒸馏为单专家 → 标准导出链
• 见 跨赛道文档 详细方案

MoE 稳定版本建议 [文档]

来自 docs/plans/moe_stable_version_analysis.md：

第一周行动计划

环境矩阵

已知风险与边界

读完你应能

• 在 Mac 上完成 pip install -e . 并用 MPS 跑通一次 predict
• 说出 agent/ 目录的四个核心文件及其职责
• 区分 MoE 路由（core_handlers.py）和 MoE 诊断（moe_tools.py）的功能边界
• 为至少一个 good-first-issue 写出复现步骤
• 解释 YOLO-Master 与 Ultralytics 的上下游关系，以及这如何影响你的贡献策略

Mermaid: YOLO-Master 贡献者路径

graph LR
    subgraph L1-入门[第1周]
        A1[pip install -e .] --> A2[predict on MPS]
        A2 --> A3[读 agent/SKILL.md]
        A3 --> A4[GFI PR: docs/wiki]
    end
    subgraph L2-功能[第2-3周]
        B1[新 agent handler] --> B2[Gradio 功能]
        B2 --> B3[multimodal pipeline]
    end
    subgraph L3-研究[第4周+]
        C1[MoE 诊断/分析] --> C2[路由改进]
        C2 --> C3[INT8 量化对齐]
    end
    A4 --> B1
    B3 --> C1

证据等级