1.1 项目功能#

一句话：

YOLO26-Dual = 双骨干（RGB/IR）+ 多层融合（P3/P4/P5）+ YOLO 检测头。

与单流基线 YOLO 相比，变化点是：

• 输入从单张图变成 rgb + ir 双流输入；
• Backbone 分成两条独立分支（权重不共享）；
• 在多尺度位置做融合，融合模块可替换；
• 训练器/验证器/推理器都走双流逻辑。

1.2 Can / Can’t#

1.3 设计原则#

• opt-in 设计：只有命中双流条件（如 dual_stream: True / rgbir 配置）才进入双流路径；
• 向后兼容：不影响单流 YOLO 的正常训练与推理；
• 可替换融合层：融合模块通过在注册表中注册管理，便于实验与扩展；
• 最小侵入改造：尽量复用原生解析器与头部结构，降低上游同步成本，便于上游仓库Ultralytics更新时同步更新。

2.1 环境#

1
cd YOLO26-Dual
2
conda create -n yolo26dual python=3.10 -y
3
conda activate yolo26dual
4
pip install -U pip
5
pip install -e .

如需测试依赖：

1
pip install -e ".[dev]"

2.2 数据准备（以 LLVIP 数据集为示例，可替换为任意 RGB+IR 数据集）#

1
python scripts/prepare_llvip.py

prepare_llvip.py 此脚本可将 LLVIP 数据集处理为本项目可用的路径结构。

每个数据集对数据存放的格式不同，对此强烈建议让AI帮你处理。详见本文AI提示词部分。

2.3 健康检查#

1
python scripts/verify_dataset.py --data ultralytics/cfg/datasets/LLVIP.yaml
2
python scripts/verify_all_modules.py
3
python scripts/audit_tfblock_gates.py
4
pytest tests/test_dual_stream.py -v

verify_dataset.py 此脚本用于快速检查数据集配置文件是否符合双流YOLO训练需要。

verify_all_modules.py 生产环境中无用，

• 作用：全模块普查。
• 详情：它会自动遍历项目中定义的所有融合模块，挨个加载并跑一次前向传播和反向传播。
• 目的：确保每个模块都没语法错误，且梯度能回传，防止某个冷门模块坏了没人发现。但是生产环境会有人每次运行前检查所有融合模块吗？

2.4 跑一个 10 epoch baseline#

这里假定你本地安装好了修改后的Ultralytics库，已经切换了环境

1
yolo detect train \
2
  model=ultralytics/cfg/models/26/yolo26-rgbir.yaml \
3
  data=ultralytics/cfg/datasets/LLVIP.yaml \
4
  epochs=10 imgsz=640 batch=16 device=0 \
5
  optimizer=AdamW compile=False multi_scale=0 augment=False \
6
  project=runs/detect name=baseline_10e

注：这里用 LLVIP.yaml 只是示例。若你使用 KAIST / FLIR / M3FD 或自建数据集，只需要把 data=... 换成对应 YAML，并确保配置文件中包含 ir_train / ir_val 字段。

4.1 路由入口#

• ultralytics/models/yolo/model.py
  • _is_dual_stream()：判断是否双流
  • task_map：双流 detect 路由到专用 model/trainer/validator/predictor

4.2 模型解析与前向核心#

• ultralytics/nn/tasks.py
  • _FUSION_REGISTRY：融合模块映射表
  • parse_dual_stream_model()：构建双骨干+融合+头
  • parse_dual_stream_head()：融合输出接入 head
  • DualStreamDetectionModel：_predict_once() 和 loss()
  • 关键实现：把所有层拼成 flat Sequential 的 self.model，确保 stride / EMA / state_dict 与 Ultralytics 主流程兼容

4.3 数据与训练验证#

• ultralytics/data/dataset.py
  • YOLODualStreamDataset
• ultralytics/models/yolo/detect/train.py
  • DualStreamDetectionTrainer
• ultralytics/models/yolo/detect/val.py
  • DualStreamDetectionValidator
• ultralytics/models/yolo/detect/dual_stream_predict.py
  • DualStreamPredictor

4.4 融合模块实现#

• ultralytics/nn/modules/block.py
  • 基础：ChannelFusion / AddFusion / TransformerFusion
  • 注意力块：TransformerFusionBlock
  • 扩展方法：TFusion、CombinedFusionBlocks、SFEG、CAFF、ICFusion、MaxFusion、ConcatFusion、Add、DFSC、CSSA

4.5 双流判定与解析流程#

1
if self._is_dual_stream():
2
    task_map["detect"] = {
3
        "model": DualStreamDetectionModel,
4
        "trainer": DualStreamDetectionTrainer,
5
        "validator": DualStreamDetectionValidator,
6
        "predictor": DetectionPredictor  # MVP 回退
7
    }

4.6 修改文件清单#

6.1 示例：LLVIP 结构#

1
datasets/LLVIP/
2
├── rgb/
3
│   ├── train/
4
│   │   └── images/
5
│   │       ├── 000001.jpg
6
│   │       └── ...
7
│   └── val/
8
│       └── images/
9
│           └── ...
10
├── ir/
11
│   ├── train/
12
│   │   └── images/
13
│   │       ├── 000001.jpg
14
│   │       └── ...
15
│   └── val/
16
│       └── images/
17
│           └── ...
18
└── rgb/
19
    ├── train/
20
    │   └── labels/
21
    │       ├── 000001.txt
22
    │       └── ...
23
    └── val/
24
        └── labels/
25
            └── ...

硬约束：

• RGB 与 IR 必须同名配对；
• 标注在 RGB 路径下（YOLO 规则）；
• IR 路径仅存图像，不存 labels。

6.2 数据 YAML#

ultralytics/cfg/datasets/LLVIP.yaml：

1
path: ../datasets/LLVIP
2
train: rgb/train/images
3
val: rgb/val/images
4
ir_train: ir/train/images
5
ir_val: ir/val/images
6
names:
7
  0: person

⚠️ 注意：如果不写 ir_train / ir_val，你跑出来的是“伪双流”（RGB 转灰度作为 IR）。

如果找不到对应的 IR 图像，系统自动使用 *灰度回退*（将 RGB 转为灰度图并复制到 3 通道作为合成 IR）。适用于管线验证，但实际效果需要真实 IR 数据。

6.3 自定义数据集YAML模板#

1
path: ../datasets/YourDataset
2
train: rgb/train/images
3
val: rgb/val/images
4
ir_train: ir/train/images
5
ir_val: ir/val/images
6
names:
7
  0: person
8
  1: car

如果你的原始数据不是这个结构，先写一个预处理脚本把目录整理成这个格式再训练。（可让 AI 帮忙完成）

6.4 避免隐式失败：数据集校验工具#

由于 YOLODualStreamDataset 在找不到 IR 图像时会静默回退到灰度图，这可能导致你误以为自己在跑双流，实际跑的是“假双流”。

强烈建议在训练前运行校验脚本：

1
python scripts/verify_dataset.py --data ultralytics/cfg/datasets/LLVIP.yaml

• 绿色 ✅ Success：说明所有 RGB 都有对应的 IR 图片。
• 红色 ❌ Failed：会列出缺失 IR 的文件名。

规则1：optimizer != "Muon"#

原因：TransformerFusionBlock 包含 1D 可学习参数 (LearnableCoefficient, LearnableWeights)，Muon 优化器要求参数为 2D。

可选的优化器类型：SGD, Adam, RMSprop.

不要用 auto。因为 auto 策略有时会根据模型结构自动切到 Muon或其他实验性优化器，为了避免不可控的报错，还是建议显式指定。

规则2：compile=False#

原因：双流路径包含自定义路由，当前阶段不建议 compile。

规则3：multi_scale=0#

原因：RGB/IR 需要同步缩放，异步会破坏配准。

规则4：augment=False#

原因：几何增强若不双流同步，错配会直接污染训练。当前实现里也不建议把 Mosaic/MixUp 直接用于 IR 分支。

8.1 路线总览#

8.2 第一阶段：健康检查#

1
python scripts/verify_dataset.py --data ultralytics/cfg/datasets/LLVIP.yaml
2
pytest tests/test_dual_stream.py -v

8.3 第二阶段：基线短训#

1
yolo detect train \
2
  model=ultralytics/cfg/models/26/yolo26-rgbir.yaml \
3
  data=ultralytics/cfg/datasets/LLVIP.yaml \
4
  epochs=10 imgsz=640 batch=16 device=0 \
5
  optimizer=AdamW compile=False multi_scale=0 augment=False \
6
  project=runs/detect name=baseline_10e

或使用Python脚本类型：

1
model.train(
2
    data="LLVIP.yaml",
3
    epochs=100,
4
    imgsz=640,
5
    batch=64,                # 2×RTX 3090 (24GB) 推荐
6
    device="0,1",            # 多卡 DDP 训练
7
    optimizer="AdamW",       # 必须
8
    workers=8,
9
    compile=False,           # 必须关闭
10
    multi_scale=0,           # 必须关闭
11
    augment=False,           # 推荐关闭
12
    close_mosaic=10,
13
)

8.4 第三阶段：正式训练 （以 TransformerFusionBlock为例）#

1
python scripts/train_fusion_tfblock.py

该脚本脚本里有 batch 回退（64→32→16），比手动盲试更稳。

备注：当前脚本默认 device="0,1"（双卡）。如果你只有一张卡，建议先改成 device="0" 再跑。

8.5 理解训练日志#

训练过程中你会常见到这些字段：

如果 loss 明显下降但 mAP 长时间不动，优先检查：

1. 数据标注与配对是否正确；
2. 是否出现了“伪双流”（IR 没真正参与）；
3. 学习率和 batch 是否过激导致震荡。

8.6 资源与规模参考（经验之谈）#

9.1 常用的索引对照#

9.2 配置文件位置#

1
ultralytics/cfg/models/26/
2
├── yolo26-rgbir.yaml                # 基线: ChannelFusion (P3/P4) + TransformerFusion (P5)
3
└── yolo26-rgbir-tfblock-all.yaml    # 实验: TransformerFusionBlock (全阶段)

9.3 基线配置: yolo26-rgbir.yaml#

9.4 TFBlock-All 配置: yolo26-rgbir-tfblock-all.yaml#

9.5 融合配置段语法#

1
fusion:
2
  - {rgb_idx: 4,  ir_idx: 4,  module: <模块名>, args: [参数列表]}
3
  - {rgb_idx: 6,  ir_idx: 6,  module: <模块名>, args: [参数列表]}
4
  - {rgb_idx: 10, ir_idx: 10, module: <模块名>, args: [参数列表]}

• rgb_idx / ir_idx: 骨干网络输出层索引 (两个骨干结构相同)
• module: 融合模块类名 (必须在 _FUSION_REGISTRY 中注册)
• args: 传递给模块构造函数的参数

9.6 可用融合模块#

当前仓库可直接使用的实验配置：

• yolo26n-rgbir-add.yaml -> Add
• yolo26n-rgbir-caff.yaml -> CAFF
• yolo26n-rgbir-combined.yaml -> CombinedFusionBlocks
• yolo26n-rgbir-concatfusion.yaml -> ConcatFusion
• yolo26n-rgbir-cssa.yaml -> CSSA
• yolo26n-rgbir-dfsc.yaml -> DFSC
• yolo26n-rgbir-icfusion.yaml -> ICFusion
• yolo26n-rgbir-maxfusion.yaml -> MaxFusion
• yolo26n-rgbir-sfeg.yaml -> SFEG
• yolo26n-rgbir-tfblock-all.yaml -> TransformerFusionBlock
• yolo26n-rgbir-tfusion.yaml -> TFusion

9.7 自定义融合配置示例#

1
# 混合使用不同融合模块
2
fusion:
3
  - {rgb_idx: 4,  ir_idx: 4,  module: ChannelFusion,         args: [512]}
4
  - {rgb_idx: 6,  ir_idx: 6,  module: AddFusion,             args: [512]}
5
  - {rgb_idx: 10, ir_idx: 10, module: TransformerFusionBlock, args: [16, 16, 4]}

9.8 模型规模选择#

模型支持多种规模 (scale)，通过 scales 字段定义：

1
scales:
2
  n: [0.50, 0.25, 1024]   # nano: 深度 0.50, 宽度 0.25, 最大通道 1024
3
  s: [0.50, 0.50, 1024]   # small: 深度 0.50, 宽度 0.50

默认使用 n (nano) 规模。如未在文件名中指定 scale (如 yolo26n-rgbir.yaml)，系统会自动选择 n。

9.9 建议实验策略#

1. 先进行模块可用性验证；
2. 再做 1~3 epoch 快速筛选；
3. 挑 Top 候选做 50~100 epoch 长训；
4. 只比较同条件实验（相同 seed、batch、imgsz、数据划分）。

10.1 审计门定义#

• G1：前向传播与形状检查
• G2：IR 敏感性（改 IR 后输出应变化）
• G3：IR 梯度回流（IR 分支应有梯度）
• G4：模型结构检查（例如 TFBlock 数量）
• G5：解析器语义审计（AST 级检查）

10.2 当前关键审计指标#

对应文件：

• artifacts/tfblock_all/ir_sensitivity.json
• artifacts/tfblock_all/ir_grad_flow.json
• artifacts/tfblock_all/parse_model_semantic_proof.txt
• artifacts/tfblock_all/final_report.md

11.1 验证#

1
from ultralytics import YOLO
2

3
model = YOLO("runs/detect/baseline_10e/weights/best.pt")
4
metrics = model.val(data="ultralytics/cfg/datasets/LLVIP.yaml")
5
print("mAP50:", metrics.box.map50)
6
print("mAP50-95:", metrics.box.map)

11.2 推理（自动配对，隐式IR）#

1
results = model.predict(source="datasets/LLVIP/rgb/val/images/010001.jpg")

11.3 推理（显式 IR）#

1
results = model.predict(
2
    source="datasets/LLVIP/rgb/val/images/010001.jpg",
3
    ir_source="datasets/LLVIP/ir/val/images"
4
)

11.4 AutoBackend 注意事项#

autobackend.py 对 dict 输入（{"rgb":..., "ir":...}）的支持主要面向 PyTorch 后端。

简而言之：

• 训练/验证/本地 PyTorch 推理没问题；
• 非 PyTorch 推理后端要额外验证输入路径是否兼容。

12.1 AssertionError: len(G.shape) == 2#

• 原因：优化器路径不兼容 1D 参数；
• 处理：显式 optimizer="AdamW"。

12.2 Input type Float and weight type Half#

• 原因：AMP 下 dtype 不一致；
• 处理：
  1. 融合模块输出 cast 回输入 dtype；
  2. 检查双流 loss() 是否在 autocast 上下文中重算 preds。

12.3 KeyError: 'ir_img'#

• 原因：数据配置或加载链路断了；
• 处理：
  • 检查 ir_train/ir_val 是否存在；
  • 检查 IR 路径与同名配对是否成立；
  • 检查是否走到了 YOLODualStreamDataset。

12.4 输出对 IR 不敏感#

1
python scripts/audit_tfblock_gates.py

重点看 Gate2 与 Gate3。

12.5 git pull 后冲突或异常#

先保护本地改动：

1
git add .
2
git commit -m "wip"  # 或 git stash

再进行同步，不要直接硬拉。具体可询问 AI 如何解决。

14.1 同步流程图#

14.2 常规命令#

1
git remote add upstream https://github.com/ultralytics/ultralytics.git   # 首次
2
git fetch upstream
3
git log --oneline main..upstream/main | head -20
4
git checkout main
5
git merge upstream/main

14.3 冲突处理最小流程#

当你在合并输出里看到 CONFLICT 或冲突标记时：

1
<<<<<<< HEAD
2
...你的内容...
3
=======
4
...upstream内容...
5
>>>>>>> upstream/main

处理原则：

1. 上游 bugfix/性能修复优先保留；
2. 双流核心能力必须补回；
3. 处理后确认冲突标记已清理干净。

14.4 冲突高发文件#

• ultralytics/nn/modules/block.py
• ultralytics/nn/tasks.py
• ultralytics/models/yolo/model.py
• ultralytics/data/dataset.py
• ultralytics/models/yolo/detect/train.py
• ultralytics/models/yolo/detect/val.py

14.5 合并后的最低验证#

1
python -c "from ultralytics import YOLO; YOLO('ultralytics/cfg/models/26/yolo26-rgbir.yaml'); print('dual build ok')"
2
python -c "from ultralytics import YOLO; YOLO('yolo26n.yaml'); print('single build ok')"
3
python scripts/audit_tfblock_gates.py

14.6 同步频率建议#

15.1 常用脚本#

/scripts 下当前常用脚本：

• verify_dataset.py：校验 RGB/IR 数据集配对完整性
• prepare_llvip.py：LLVIP 解压+结构检查+配对检查
• verify_all_modules.py：11 模块前向+梯度可用性检查
• audit_tfblock_gates.py：G1~G4 审计
• audit_parse_semantic.py：G5 解析器语义审计
• train_fusion_tfblock.py：TFBlock 正式训练（含 batch 回退）
• train_tfblock.py：smoke/full 入口训练
• compare_fusion_feasibility.py：融合可行性对比
• generate_fusion_configs.py：批量生成融合配置
• audit_fusion_migration.py：迁移模块审计
• verify_tfblock_roundtrip.py：权重回环验证

15.2 artifacts 产物#

artifacts/tfblock_all/ 下你会看到这类文件：

建议：跑长训之前至少执行一次 verify_all_modules.py + audit_tfblock_gates.py，并保存对应 artifacts。

数据准备#

审计与测试#

训练#

模型配置 (cfg/models/26/)#

数据集配置 (cfg/datasets/)#

验证脚本 (scripts/)#

新增融合模块配置 (cfg/models/26/)#

1. 拉取上游最新代码#

1
git fetch upstream

2. 查看上游有哪些新提交#

1
# 查看上游比你多了多少提交
2
git log --oneline main..upstream/main | head -20

3. 合并上游更新#

1
# 确保在 main 分支
2
git checkout main
3

4
# 合并上游 (推荐用 merge，保留完整历史)
5
git merge upstream/main

如果不想产生 merge commit，也可以用 git rebase upstream/main，但 rebase 风险更高，不推荐新手使用。

4. 解决冲突#

合并时可能会出现冲突（CONFLICT）。以下是最可能冲突的文件和对应的处理策略：

5. 冲突解决实操#

当 Git 提示冲突时，打开冲突文件会看到类似：

1
<<<<<<< HEAD
2
我们的代码
3
=======
4
上游的代码
5
>>>>>>> upstream/main

处理原则：

1. 上游的原有代码 → 用上游的版本（他们修 bug、优化性能等）
2. 我们新增的代码 → 保留（双流功能）
3. 同一行的不同修改 → 需逐行判断，通常以上游为准再手动加回我们的改动

1
# 解决所有冲突后
2
git add .
3
git commit -m "merge: sync upstream ultralytics (描述上游更新内容)"
4
git push

6. 验证合并结果#

合并后务必运行以下验证：

1
# 1. 模型能正常构建
2
python -c "from ultralytics import YOLO; m = YOLO('ultralytics/cfg/models/26/yolo26-rgbir.yaml'); print('✅ 基线模型构建成功')"
3

4
# 2. TFBlock 模型能构建
5
python -c "from ultralytics import YOLO; m = YOLO('ultralytics/cfg/models/26/yolo26-rgbir-tfblock-all.yaml'); print('✅ TFBlock 模型构建成功')"
6

7
# 3. 前向传播测试
8
python -c "
9
import torch
10
from ultralytics import YOLO
11
m = YOLO('ultralytics/cfg/models/26/yolo26-rgbir.yaml')
12
m.model.cuda().eval()
13
rgb = torch.randn(1,3,640,640).cuda()
14
ir = torch.randn(1,3,640,640).cuda()
15
with torch.no_grad():
16
    out = m.model({'rgb': rgb, 'ir': ir})
17
print('✅ 前向传播成功')
18
"
19

20
# 4. 标准 YOLO 单流模型不受影响
21
python -c "from ultralytics import YOLO; m = YOLO('yolo11n.pt'); print('✅ 标准模型正常')"

Q: 合并后原有功能不正常了怎么办？#

A: 用 git log --oneline -10 查看最近提交，用 git revert <commit> 回退合并提交。或者用 git reset --hard HEAD~1 完全撤销合并（慎用，会丢失未推送的改动）。

Q: 可以只同步特定文件吗？#

A: 可以用 git checkout upstream/main -- path/to/file 只拉取特定文件，但不推荐，容易造成代码不一致。

Q: upstream 的 main 分支改名了怎么办？#

A: 用 git remote show upstream 查看默认分支名，将命令中的 upstream/main 替换为实际分支名。

1.1 融合模块接口规范#

所有融合模块必须遵循以下接口：

1
class YourFusion(nn.Module):
2
    def __init__(self, c_rgb, c_ir, c_out, **kwargs):
3
        """
4
        Args:
5
            c_rgb (int): RGB 特征通道数 (由解析器自动传入)
6
            c_ir  (int): IR 特征通道数 (由解析器自动传入)
7
            c_out (int): 输出通道数
8
            **kwargs:    其他自定义参数
9
        """
10
        super().__init__()
11
        ...
12

13
    def forward(self, x_rgb, x_ir):
14
        """
15
        Args:
16
            x_rgb (Tensor): RGB 特征, shape (B, C_rgb, H, W)
17
            x_ir  (Tensor): IR 特征,  shape (B, C_ir,  H, W)
18

19
        Returns:
20
            Tensor: 融合后的特征, shape (B, C_out, H, W)
21
        """
22
        ...

关键约束：

• __init__ 的前两个参数必须是 c_rgb 和 c_ir，由解析器自动从骨干网络的通道数推断并传入
• forward 必须接受两个位置参数 (x_rgb, x_ir)
• 返回值必须是单个张量，尺寸与输入的空间分辨率一致 (H, W 不变)

1.2 编写模块代码#

在 ultralytics/nn/modules/block.py 文件末尾添加你的模块。以下是现有模块的参考实现：

1
class ChannelFusion(nn.Module):
2
    """Concat + 1×1 Conv 融合"""
3

4
    def __init__(self, c_rgb, c_ir, c_out):
5
        super().__init__()
6
        self.conv = Conv(c_rgb + c_ir, c_out, 1)
7

8
    def forward(self, x_rgb, x_ir):
9
        return self.conv(torch.cat([x_rgb, x_ir], dim=1))

1
class AddFusion(nn.Module):
2
    """投影 + 逐元素相加"""
3

4
    def __init__(self, c_rgb, c_ir, c_out):
5
        super().__init__()
6
        self.proj_rgb = Conv(c_rgb, c_out, 1) if c_rgb != c_out else nn.Identity()
7
        self.proj_ir  = Conv(c_ir,  c_out, 1) if c_ir  != c_out else nn.Identity()
8

9
    def forward(self, x_rgb, x_ir):
10
        return self.proj_rgb(x_rgb) + self.proj_ir(x_ir)

1.3 注册到框架#

完成模块编写后，需要在三个位置注册：

1
# ultralytics/nn/modules/block.py 顶部
2
# 确保你的类名包含在模块的导出列表中

1
from .block import (
2
    ...,
3
    YourFusion,  # ← 添加这一行
4
)

1
# ultralytics/nn/tasks.py (约第 1844 行)
2
from ultralytics.nn.modules.block import (..., YourFusion)
3

4
_FUSION_REGISTRY = {
5
    "ChannelFusion": ChannelFusion,
6
    "AddFusion": AddFusion,
7
    "TransformerFusion": TransformerFusion,
8
    "TransformerFusionBlock": TransformerFusionBlock,
9
    "TFBlock": TransformerFusionBlock, # Alias
10
    "TFusion": TFusion,
11
    "Combined": Combined,
12
    "SFEG": SFEG,
13
    "CAFF": CAFF,
14
    "ICFusion": ICFusion,
15
    "MaxFusion": MaxFusion,
16
    "Concat": ConcatFusion, # Alias
17
    "ConcatFusion": ConcatFusion,
18
    "Add": AddFusion, # Alias
19
    "DFSC": DFSC,
20
    "CSSA": CSSA,
21
    "YourFusion": YourFusion,              # ← 添加这一行
22
}

1.4 在解析器中添加实例化逻辑#

打开 ultralytics/nn/tasks.py，找到 parse_dual_stream_model 函数中 Step 3 的融合层构建循环（约第 2032 行）。在 for fi, f_spec in enumerate(fusion_specs) 循环中，已有 4 个分支处理不同模块类型：

1
# ultralytics/nn/tasks.py — parse_dual_stream_model 函数内部
2

3
for fi, f_spec in enumerate(fusion_specs):
4
    c_rgb = bb_ch_map[f_spec["rgb_idx"]]  # 自动获取 RGB 通道数
5
    c_ir = bb_ch_map[f_spec["ir_idx"]]    # 自动获取 IR 通道数
6
    mod_name = f_spec["module"]
7
    mod_cls = _FUSION_REGISTRY[mod_name]
8
    f_args = f_spec.get("args", [])
9

10
    # ---- 以下是各模块的实例化分支 ----
11

12
    if mod_cls is TransformerFusion:
13
        # ... 已有逻辑
14
    elif mod_cls is TransformerFusionBlock:
15
        # ... 已有逻辑
16
    elif mod_cls is ChannelFusion:
17
        c_out = f_args[0] if f_args else c_rgb
18
        c_out = make_divisible(min(c_out, max_channels) * width, 8)
19
        fusion_layers.append(mod_cls(c_rgb, c_ir, c_out))
20

21
    # ---- 添加你的模块分支 ----
22
    elif mod_cls is YourFusion:
23
        c_out = f_args[0] if f_args else c_rgb
24
        c_out = make_divisible(min(c_out, max_channels) * width, 8)
25
        # 从 f_args 中提取你自定义的参数
26
        your_param = f_args[1] if len(f_args) > 1 else default_value
27
        fusion_layers.append(mod_cls(c_rgb, c_ir, c_out, your_param))
28

29
    else:  # 默认分支 (AddFusion 等)
30
        c_out = f_args[0] if f_args else c_rgb
31
        c_out = make_divisible(min(c_out, max_channels) * width, 8)
32
        fusion_layers.append(mod_cls(c_rgb, c_ir, c_out))
33

34
    fused_channels[fi] = c_out  # 记录输出通道数，供 Head 使用

解析器关键说明：

• c_rgb 和 c_ir 由解析器自动从骨干网络的输出通道推断，不需要在 YAML 中指定
• f_args 对应 YAML 配置中的 args 列表
• width 和 max_channels 来自 scales 配置，用于按模型规模缩放通道数
• make_divisible(x, 8) 确保通道数是 8 的倍数 (GPU 计算效率)
• 如果你的模块遵循 (c_rgb, c_ir, c_out) 标准接口，通常可以直接使用 else 默认分支，无需添加专门的 elif

1.5 AMP 混合精度兼容性#

如果你的模块内部使用了以下操作，必须注意 AMP 兼容性：

推荐做法：在 forward 方法末尾添加 dtype 安全转换：

1
def forward(self, x_rgb, x_ir):
2
    input_dtype = x_rgb.dtype  # 记录输入 dtype
3

4
    # ... 你的融合逻辑 ...
5

6
    # 确保输出 dtype 与输入一致 (AMP 兼容)
7
    output = output.to(input_dtype)
8
    return output

1.6 完整示例：实现 SE-Fusion 模块#

以下用一个基于 Squeeze-and-Excitation 的融合模块作为完整示例：

1
# 在 ultralytics/nn/modules/block.py 末尾添加
2

3
class SEFusion(nn.Module):
4
    """Squeeze-and-Excitation based fusion for dual-stream features.
5

6
    Uses channel attention to adaptively weight RGB and IR features
7
    before element-wise addition.
8

9
    Reference: Hu et al., "Squeeze-and-Excitation Networks", CVPR 2018
10
    """
11

12
    def __init__(self, c_rgb, c_ir, c_out, reduction=16):
13
        """Initialize SEFusion.
14

15
        Args:
16
            c_rgb (int): RGB input channels.
17
            c_ir (int): IR input channels.
18
            c_out (int): Output channels.
19
            reduction (int): SE block channel reduction ratio.
20
        """
21
        super().__init__()
22
        self.proj_rgb = Conv(c_rgb, c_out, 1) if c_rgb != c_out else nn.Identity()
23
        self.proj_ir = Conv(c_ir, c_out, 1) if c_ir != c_out else nn.Identity()
24

25
        # SE block: 学习通道级注意力权重
26
        self.se = nn.Sequential(
27
            nn.AdaptiveAvgPool2d(1),
28
            nn.Flatten(),
29
            nn.Linear(c_out * 2, c_out * 2 // reduction),
30
            nn.ReLU(inplace=True),
31
            nn.Linear(c_out * 2 // reduction, c_out * 2),
32
            nn.Sigmoid(),
33
        )
34

35
    def forward(self, x_rgb, x_ir):
36
        """Fuse features with SE-guided channel attention."""
37
        input_dtype = x_rgb.dtype
38

39
        rgb = self.proj_rgb(x_rgb)
40
        ir = self.proj_ir(x_ir)
41

42
        # 计算通道注意力
43
        combined = torch.cat([rgb, ir], dim=1)  # (B, 2*C_out, H, W)
44
        se_weight = self.se(combined)            # (B, 2*C_out)
45
        B, C2 = se_weight.shape
46
        C = C2 // 2
47
        w_rgb = se_weight[:, :C].view(B, C, 1, 1)
48
        w_ir = se_weight[:, C:].view(B, C, 1, 1)
49

50
        output = rgb * w_rgb + ir * w_ir
51
        return output.to(input_dtype)  # AMP 安全

1
# ultralytics/nn/modules/__init__.py — 添加导出
2
from .block import (..., SEFusion)
3

4
# ultralytics/nn/tasks.py — 添加注册
5
from ultralytics.nn.modules.block import (..., SEFusion)
6

7
_FUSION_REGISTRY = {
8
    ...,
9
    "SEFusion": SEFusion,
10
}

1
# 在 parse_dual_stream_model 的融合循环中添加
2
elif mod_cls is SEFusion:
3
    c_out = f_args[0] if f_args else c_rgb
4
    c_out = make_divisible(min(c_out, max_channels) * width, 8)
5
    reduction = f_args[1] if len(f_args) > 1 else 16
6
    fusion_layers.append(mod_cls(c_rgb, c_ir, c_out, reduction))

1
fusion:
2
  - {rgb_idx: 4,  ir_idx: 4,  module: SEFusion, args: [512, 16]}     # P3, reduction=16
3
  - {rgb_idx: 6,  ir_idx: 6,  module: SEFusion, args: [512, 16]}     # P4
4
  - {rgb_idx: 10, ir_idx: 10, module: SEFusion, args: [1024, 16]}    # P5

1
from ultralytics import YOLO
2

3
model = YOLO("ultralytics/cfg/models/26/yolo26-rgbir-se.yaml")
4
print(model.model)  # 确认 SEFusion 出现在模型结构中
5

6
# 快速前向测试
7
import torch
8
rgb = torch.randn(1, 3, 640, 640).cuda()
9
ir = torch.randn(1, 3, 640, 640).cuda()
10
model.model.cuda()
11
out = model.model({"rgb": rgb, "ir": ir})
12
print("✅ Forward pass succeeded!")

2.1 配置文件结构#

双流模型 YAML 配置文件包含 5 个主要部分：

1
# ============ 1. 全局参数 ============
2
nc: 80                    # 类别数 (训练时会被 data.yaml 覆盖)
3
end2end: True             # 是否使用端到端检测
4
reg_max: 1                # DFL 回归最大值
5
dual_stream: True         # ⚠️ 必须设为 True，框架据此判断是否构建双流模型
6

7
# ============ 2. 模型规模 ============
8
scales:
9
  n: [0.50, 0.25, 1024]   # [depth_multiple, width_multiple, max_channels]
10
  s: [0.50, 0.50, 1024]
11

12
# ============ 3. 骨干网络 (共享架构) ============
13
backbone:
14
  - [-1, 1, Conv, [64, 3, 2]]        # Layer 0
15
  - [-1, 1, Conv, [128, 3, 2]]       # Layer 1
16
  ...                                 # 与标准 YOLOv26 骨干相同
17

18
# ============ 4. 融合层 ============
19
fusion:
20
  - {rgb_idx: 4,  ir_idx: 4,  module: ChannelFusion,    args: [512]}
21
  - {rgb_idx: 6,  ir_idx: 6,  module: ChannelFusion,    args: [512]}
22
  - {rgb_idx: 10, ir_idx: 10, module: TransformerFusion, args: [1024, 4]}
23

24
# ============ 5. 检测头 ============
25
head:
26
  - [2, 1, nn.Upsample, [None, 2, "nearest"]]   # 索引 0,1,2 指向融合输出
27
  - [[-1, 1], 1, Concat, [1]]
28
  ...

2.2 fusion 段详解#

1
fusion:
2
  - {rgb_idx: 4, ir_idx: 4, module: ChannelFusion, args: [512]}
3
  #  ─────────  ────────  ──────────────────────  ──────────
4
  #     │          │              │                    │
5
  #     │          │              │                    └─ 传给模块的额外参数列表
6
  #     │          │              └─ 模块类名 (必须在 _FUSION_REGISTRY 中)
7
  #     │          └─ IR 骨干输出层索引
8
  #     └─ RGB 骨干输出层索引

参数说明：

2.3 骨干层索引对照表#

标准 YOLOv26 骨干（n-scale）各层输出对照：

通常只在 P3 (层4)、P4 (层6)、P5 (层10) 处进行融合。这些是 FPN 的标准特征提取点。

2.4 完整配置示例#

1
nc: 80
2
end2end: True
3
reg_max: 1
4
dual_stream: True
5

6
scales:
7
  n: [0.50, 0.25, 1024]
8
  s: [0.50, 0.50, 1024]
9

10
# 骨干: 直接复制标准 YOLOv26 骨干
11
backbone:
12
  - [-1, 1, Conv, [64, 3, 2]]
13
  - [-1, 1, Conv, [128, 3, 2]]
14
  - [-1, 2, C3k2, [256, False, 0.25]]
15
  - [-1, 1, Conv, [256, 3, 2]]
16
  - [-1, 2, C3k2, [512, False, 0.25]]     # Layer 4 → P3
17
  - [-1, 1, Conv, [512, 3, 2]]
18
  - [-1, 2, C3k2, [512, True]]            # Layer 6 → P4
19
  - [-1, 1, Conv, [1024, 3, 2]]
20
  - [-1, 2, C3k2, [1024, True]]
21
  - [-1, 1, SPPF, [1024, 5, 3, True]]
22
  - [-1, 2, C2PSA, [1024]]                # Layer 10 → P5
23

24
# 融合: 你可以混合使用不同模块
25
fusion:
26
  - {rgb_idx: 4,  ir_idx: 4,  module: SEFusion,              args: [512, 16]}
27
  - {rgb_idx: 6,  ir_idx: 6,  module: ChannelFusion,         args: [512]}
28
  - {rgb_idx: 10, ir_idx: 10, module: TransformerFusionBlock, args: [16, 16, 4]}
29

30
# 检测头: 与标准 yolo26-rgbir 完全相同，无需修改
31
# 融合输出索引: 0=P3-fused, 1=P4-fused, 2=P5-fused
32
head:
33
  - [2, 1, nn.Upsample, [None, 2, "nearest"]]
34
  - [[-1, 1], 1, Concat, [1]]
35
  - [-1, 2, C3k2, [512, True]]
36
  - [-1, 1, nn.Upsample, [None, 2, "nearest"]]
37
  - [[-1, 0], 1, Concat, [1]]
38
  - [-1, 2, C3k2, [256, True]]
39
  - [-1, 1, Conv, [256, 3, 2]]
40
  - [[-1, 5], 1, Concat, [1]]
41
  - [-1, 2, C3k2, [512, True]]
42
  - [-1, 1, Conv, [512, 3, 2]]
43
  - [[-1, 2], 1, Concat, [1]]
44
  - [-1, 1, C3k2, [1024, True, 0.5, True]]
45
  - [[8, 11, 14], 1, Detect, [nc]]

3.1 目录结构规范#

双流数据集需要 RGB 和 IR 图像一一对应，目录结构如下：

1
datasets/YourDataset/
2
├── rgb/
3
│   ├── train/
4
│   │   └── images/
5
│   │       ├── 000001.jpg       # RGB 图像
6
│   │       ├── 000002.jpg
7
│   │       └── ...
8
│   └── val/
9
│       └── images/
10
│           └── ...
11
├── ir/
12
│   ├── train/
13
│   │   └── images/
14
│   │       ├── 000001.jpg       # IR 图像 (与 RGB 同名)
15
│   │       ├── 000002.jpg
16
│   │       └── ...
17
│   └── val/
18
│       └── images/
19
│           └── ...
20
└── rgb/
21
    ├── train/
22
    │   └── labels/              # YOLO 格式标注 (写在 RGB 路径下)
23
    │       ├── 000001.txt
24
    │       └── ...
25
    └── val/
26
        └── labels/
27
            └── ...

关键规则：

• RGB 和 IR 图像必须同名（用于自动配对）
• 标注文件 (labels/) 放在 RGB 路径下（标准 YOLO 位置规则：将 images 替换为 labels）
• IR 目录下不需要标注文件
• 图像格式: JPG/PNG 均可，RGB 和 IR 可以不同格式

3.2 数据集配置文件#

1
# 数据集根目录 (绝对路径或相对于项目根目录)
2
path: ../datasets/YourDataset
3

4
# RGB 图像路径 (相对于 path)
5
train: rgb/train/images
6
val: rgb/val/images
7
test:                            # 可选
8

9
# IR 图像路径 (相对于 path)
10
ir_train: ir/train/images
11
ir_val: ir/val/images
12

13
# 类别定义
14
names:
15
  0: person
16
  1: car
17
  2: bicycle

配置文件位置：放在以下任意位置均可

• 项目根目录: YourDataset.yaml
• 标准目录: ultralytics/cfg/datasets/YourDataset.yaml

3.3 适配自己的数据集#

1
dataset/
2
├── images/
3
│   ├── 001_rgb.jpg
4
│   ├── 001_ir.jpg
5
│   └── ...
6
└── labels/
7
    ├── 001_rgb.txt
8
    └── ...

1
"""将非标准数据集转换为双流标准结构"""
2
import shutil
3
from pathlib import Path
4

5
src = Path("dataset/images")
6
dst_rgb = Path("dataset_new/rgb/train/images")
7
dst_ir = Path("dataset_new/ir/train/images")
8
dst_rgb.mkdir(parents=True, exist_ok=True)
9
dst_ir.mkdir(parents=True, exist_ok=True)
10

11
for f in src.glob("*_rgb.*"):
12
    base = f.name.replace("_rgb", "")
13
    shutil.copy(f, dst_rgb / base)
14

15
for f in src.glob("*_ir.*"):
16
    base = f.name.replace("_ir", "")
17
    shutil.copy(f, dst_ir / base)
18

19
# 标注文件同样处理
20
src_labels = Path("dataset/labels")
21
dst_labels = Path("dataset_new/rgb/train/labels")
22
dst_labels.mkdir(parents=True, exist_ok=True)
23

24
for f in src_labels.glob("*_rgb.txt"):
25
    base = f.name.replace("_rgb", "")
26
    shutil.copy(f, dst_labels / base)
27

28
print("✅ 数据集转换完成!")

1
# 最小化配置 (无 IR 数据)
2
path: ../datasets/YourDataset
3
train: images/train
4
val: images/val
5

6
# 不指定 ir_train/ir_val → 自动灰度回退
7

8
names:
9
  0: person