使用 YAML2ModelGraph 可视化 Ultralytics YOLO 模型架构：从 model YAML 一键生成 SVG 架构图

Ultralytics YOLO 系列（YOLO26、YOLO11、YOLOv8 等）的模型结构是用声明式的 YAML 文件定义的，阅读这类文件时只能看到一串串 [from, repeats, module, args]，难以直观把握 backbone、neck、head 的整体拓扑与数据流向。YAML2ModelGraph 是一个社区工具，能直接把 Ultralytics 的 model YAML 渲染成类似论文插图风格的 SVG 架构图，适合在文档中说明自定义模型、在训练前快速检查 backbone/neck/head 结构，也适合把架构图嵌入 Markdown/技术报告用于沟通。读完本文，你将掌握该工具的安装、命令行用法、主题与节点元数据开关，并能结合仓库内的模型 YAML 与解析源码理解图上的每个节点从何而来。

一、先认识被可视化的对象：Ultralytics YOLO model YAML

要理解架构图，先要理解图的“数据源”。Ultralytics 仓库中每种模型的骨架定义都存放在 ultralytics/cfg/models/ 下的 YAML 文件中，例如 YOLO26 检测版位于 ultralytics/cfg/models/26/yolo26.yaml，同目录还包含 yolo26-pose.yaml、yolo26-seg.yaml、yolo26-obb.yaml、yolo26-cls.yaml 等任务变体。

以 yolo26.yaml 为例，文件顶部是模型级参数，随后是 backbone 与 head 两段列表：

# Parameters
nc: 80                 # 类别数
end2end: True          # 是否使用 end-to-end（免 NMS）模式
reg_max: 1             # DFL bins
scales:                # 复合缩放常量，'model=yolo26n.yaml' 会按 'n' 缩放
  # [depth, width, max_channels]
  n: [0.50, 0.25, 1024]
  s: [0.50, 0.50, 1024]
  m: [0.50, 1.00, 512]
  l: [1.00, 1.00, 512]
  x: [1.00, 1.50, 512]

# YOLO26n backbone
backbone:
  # [from, repeats, module, args]
  - [-1, 1, Conv, [64, 3, 2]]            # 0-P1/2
  - [-1, 1, Conv, [128, 3, 2]]           # 1-P2/4
  - [-1, 2, C3k2, [256, False, 0.25]]
  - [-1, 1, Conv, [256, 3, 2]]           # 3-P3/8
  - [-1, 2, C3k2, [512, False, 0.25]]
  - [-1, 1, Conv, [512, 3, 2]]           # 5-P4/16
  - [-1, 2, C3k2, [512, True]]
  - [-1, 1, Conv, [1024, 3, 2]]          # 7-P5/32
  - [-1, 2, C3k2, [1024, True]]
  - [-1, 1, SPPF, [1024, 5, 3, True]]    # 9
  - [-1, 2, C2PSA, [1024]]               # 10

# YOLO26n head
head:
  - [-1, 1, nn.Upsample, [None, 2, "nearest"]]
  - [[-1, 6], 1, Concat, [1]]            # cat backbone P4
  - [-1, 2, C3k2, [512, True]]           # 13
  - [-1, 1, nn.Upsample, [None, 2, "nearest"]]
  - [[-1, 4], 1, Concat, [1]]            # cat backbone P3
  - [-1, 2, C3k2, [256, True]]           # 16 (P3/8-small)
  - [-1, 1, Conv, [256, 3, 2]]
  - [[-1, 13], 1, Concat, [1]]           # cat head P4
  - [-1, 2, C3k2, [512, True]]           # 19 (P4/16-medium)
  - [-1, 1, Conv, [512, 3, 2]]
  - [[-1, 10], 1, Concat, [1]]           # cat head P5
  - [-1, 1, C3k2, [1024, True, 0.5, True]] # 22 (P5/32-large)
  - [[16, 19, 22], 1, Detect, [nc]]      # Detect(P3, P4, P5)

其中每条 [from, repeats, module, args] 的含义是：

• from：输入来自哪一层。-1 表示上一层；正数（或索引列表如 [[-1, 6]]）表示跨层拼接来源；注释中的 # 0-P1/2 表示该层在 backbone+head 连读序号下的全局索引及其输出步长。
• repeats：模块重复次数，实际会被 scales 的 depth 系数缩放（见 parse_model 的 n = max(round(n * depth), 1)）。
• module：模块名，如 Conv、C3k2、SPPF、C2PSA、Concat、nn.Upsample、Detect。对应源码实现分别位于 ultralytics/nn/modules/conv.py（Conv、Concat）、ultralytics/nn/modules/block.py（SPPF、C3k2、C2PSA）、ultralytics/nn/modules/head.py（Detect）。
• args：模块构造参数（通道数、卷积核等）。nc、reg_max 等顶层变量会被解析引用。

架构解析发生在 parse_model：它依次遍历 d["backbone"] + d["head"] 两段列表，按行号维护每层输出通道，从而推算 Concat 拼接后的通道数与 Detect 头接收的特征金字塔输入。加载模型时该字典会被保存在 model.yaml 属性中（见 tasks.py 中 _initialize_yolo_model）。YAML2ModelGraph 做的就是读取同一份字典，把它还原成一张网络拓扑图——因此图中节点的顺序、连线、模块名与你训练/导出时真正使用的结构完全一致。

二、YAML2ModelGraph 是什么

YAML2ModelGraph 是围绕 Ultralytics YOLO 模型 YAML 设计的社区可视化工具：输入一个 model YAML（例如上面的 yolo26.yaml 或其任意自定义变体），输出一份矢量 SVG 架构图。矢量图放大不失真，可直接嵌入论文、技术文档或会议幻灯片。

在 Ultralytics 官方文档中，它被收录于 docs/en/integrations/index.md 的第三方集成列表，定位是“直接从 Ultralytics YOLO 的 YAML 配置生成可发表的 SVG 架构图”。应用场景主要包括：

• 文档化自定义模型：当你基于 YAML 修改或新增模块（例如换掉某阶段的模块、增加分支）时，用工具生成与模型 YAML 同步的架构图，避免手工画图与代码脱节；
• 检查 backbone/neck/head 结构：训练或改动配置前，先可视化确认下采样倍数、跨层拼接（FPN/PAN 结构）以及多尺度输出头是否正确；
• 分享与评审：将 SVG 放入 Git 仓库或 README，让协作者无需运行代码即可审阅结构。

三、安装

YAML2ModelGraph 以源码方式使用：克隆项目仓库，并安装唯一的 Python 依赖 PyYAML 即可：

git clone https://github.com/WangQvQ/YAML2ModelGraph.git
cd YAML2ModelGraph
pip install pyyaml

从源码结构看，工具主要包含 main.py（命令行入口与 DISPLAY_CONFIG 默认值）、themes.py（主题配色与字体配置）与 examples/（示例 YAML，如 examples/yolo26.yaml）。生成的 SVG 为纯矢量描述，运行过程不需要安装 Graphviz，从而避免了常见的 Graphviz 版本兼容问题。

四、基本用法：从 YAML 生成一张架构图

使用项目自带的 YOLO26 示例生成一张 SVG：

python main.py examples/yolo26.yaml output.svg

命令接收两个位置参数：输入模型 YAML 路径与输出 SVG 路径。由于解析逻辑基于 Ultralytics 的 YAML schema（backbone/head、from/repeats/module/args），你同样可以把仓库中的任意 model YAML 喂给它。例如在仓库根目录下，将 ultralytics/cfg/models/26/yolo26.yaml（或其 s/m/l/x 缩放规格）复制到工具目录后执行，即可得到对应规模的架构图；也可以直接可视化自定义结构以检查 backbone/neck/head 的拓扑。

默认输出为单一 head 节点的聚合视图；若希望按尺度拆开看检测头，使用 --head multi 参数，让 P3、P4、P5 各自的 head 分离开：

python main.py examples/yolo26.yaml output.svg --head multi --theme paper_ryb

可选主题

--theme 参数可从以下主题中选择：paper、paper_ryb、candy、dark、ocean、retro、blueprint、forest、journal。其中 paper_ryb 属于暖色系“论文风”，适合直接作为论文/技术报告的配图；dark 适合深色背景的幻灯片；其余主题可用于区分不同的报告风格。主题的配色、节点形状与排版均配置在工具的 themes.py 中，可自行修改。

五、节点元数据：DISPLAY_CONFIG 开关

每个节点的“图例上显示哪些细节”由 YAML2ModelGraph main.py 中的 DISPLAY_CONFIG 控制。默认值如下：

DISPLAY_CONFIG = {
    "show_channels": True,
    "show_repeats": True,
    "show_stride": True,
    "show_args": False,
}

• show_channels：显示该层的输出通道数（对应 YAML 解析后每个模块实际的 c2，经过宽度系数缩放与 8 整除对齐，见 parse_model）；
• show_repeats：显示模块重复次数（例如 C3k2 的 repeats）；
• show_stride：显示该层相对输入的下采样倍数（对应 YAML 注释中的 P1/2 … P5/32）；
• show_args：显示完整构造参数，默认关闭以避免节点过于拥挤。

按需修改该字典后重新运行即可控制图的详略。例如调试深层细节时可将 show_args 置为 True，做整体概览图时则全部关闭。

值得一提的细节是：自定义 YAML 模块名会被自动渲染。由于模型加载端对 nn. 前缀模块、torchvision.ops.* 及 globals() 中已注册模块的解析机制（见 parse_model 中的模块解析逻辑），工具同样能识别你在 ultralytics/nn/modules/ 下新增并注册的模块类名，无需为每个新模块单独写绘图逻辑。

六、多尺度特征与连线在图中如何呈现

YOLO 头部是典型的 FPN/PAN 结构，理解工具输出时需要留意两点连线关系：

1. 下采样链：backbone 中每出现一次 Conv [c, 3, 2]，对应特征图尺度减半，P3/8、P4/16、P5/32 分别是 8/16/32 倍下采样的三个金字塔层级；
2. 跨层拼接：head 中 from: [[-1, 6]]、[[-1, 4]] 之类写法表示“当前层结果 + 之前第 6/4 层输出”经过 Concat 融合。在 --head multi 模式下，[16, 19, 22]（P3/P4/P5 的末端层）会分别连接到各自的 head 节点，图形化地呈现 YOLO 多尺度检测头的“三叉”结构。

这也是把 YAML 中难读的索引引用转换成可视化的最大价值：一次运行即可确认各尺度路径是否按预期汇合到 Detect。

七、局限性与注意事项

使用前请注意以下限制：

• 标准 Detect 头会被专门对齐绘制（多尺度 head 对齐、样式精美）；
• 其他任务头，如 OBB、Pose、Segment，目前会被渲染为通用的 neck 侧节点，不提供与 Detect 同等的专门对齐与样式；
• 因此，如果你的目标是可视化分割、姿态或旋转框检测头本身的结构细节，需要以工具当前支持范围为准（并可通过 docs/en/models/yolo26.md 与仓库中 ultralytics/cfg/models/26/ 下的任务变体 YAML 比对 head 定义），具体支持情况请查阅 YAML2ModelGraph 仓库的说明文档。

八、小结

YAML2ModelGraph 的价值在于把 Ultralytics 声明式的 model YAML 转化为可发布的 SVG 架构图：它读取的是与训练、导出完全一致的 YAML 结构，通过 --head multi 与 --theme 可灵活控制展示粒度与风格，通过 DISPLAY_CONFIG 可决定节点元数据的详略，且不依赖 Graphviz。在文档化自定义 YOLO 模型、审查 backbone/neck/head 结构、撰写技术报告等场景中，它都是让模型结构“一目了然”的实用辅助工具。