X_SSL_Net/tmp/docs/training/当前项目详解与纯文本架构流程图.md

当前项目详解与纯文本架构流程图

1. 当前项目定位

当前项目的现役主路径已经收缩为一个纯净的超声分割全监督基线。

现在真实生效的模型与训练链路只有一条：

输入图像 -> 纯 SwinV2 编码器 -> 纯分割解码器 -> 分割头 -> seg_logits -> 分割损失

当前主路径已经满足以下要求：

1. 不调用 FWTA
2. 不调用 FWTA 编码器
3. 不存在边界分支
4. 不存在边界损失
5. 不存在一致性损失
6. 配置文件中不再使用 aux_loss
7. 实验脚本中不再做边界相关消融

这份文档只描述当前真实主链，不再记录历史结构语义。

---

2. 当前项目一句话概述

X_SSL_Net 当前可以理解为：

一个面向超声图像分割的纯单头 2D segmentation baseline，主干为 SwinV2 encoder + segmentation decoder。

---

3. 当前主链总览

3.1 当前训练入口

训练统一从下面这个入口启动：

tools/train.py

它负责：

1. 读取 YAML 配置
2. 接收命令行 --set 覆盖参数
3. 构建 trainer
4. 调用 trainer.train()

3.2 当前 trainer

当前正式 trainer 仍然叫：

SupervisedSegmentationTrainer

但它现在已经只做纯分割训练，不再处理任何边界辅助分支。

3.3 当前模型

当前现役模型是：

SegmentationModel2d

它的内部结构为：

1. SwinV2Encoder2d
2. SegmentationDecoder2d
3. SegmentationHead2d

最终只输出：

1. seg_logits

---

4. 目录职责总览

X_SSL_Net/
|
|-- tools/
|   |-- train.py
|   |-- run_us_experiments.sh
|   `-- summarize_results.py
|
|-- configs/
|   |-- segmentation/
|   `-- swinv2/
|
|-- lib/
|   |-- trainers/
|   |-- modules/
|   |-- data/
|   `-- tools/
|
`-- tmp/docs/training/

4.1 tools/

1. tools/train.py 统一训练启动入口
2. tools/run_us_experiments.sh 纯分割实验脚本
3. tools/summarize_results.py 汇总 best.pth 中的实验结果

4.2 configs/segmentation/

1. train_sup_us_template.yaml 当前最核心的纯分割训练模板
2. us_exp_sup_busi.yaml BUSI 示例配置
3. us_exp_sup_busi_ablation.yaml 目前内容已与普通纯分割配置对齐，不再承载边界消融语义

4.3 lib/trainers/

1. builder.py trainer 注册与构建
2. base.py 训练公共底座
3. supervised.py 当前纯分割训练流程实现

4.4 lib/modules/

1. swinv2_encoder_2d.py 纯 SwinV2 编码器封装
2. decoder_2d.py 当前纯分割解码器实现
3. segmentation_2d.py 当前主模型封装
4. build_swinv2.py SwinV2 backbone 构建器

4.5 lib/data/

1. builder.py 构建样本索引
2. loaders.py 构建 dataset 与 dataloader
3. datasets.py 真正读取 image 和 mask
4. augment.py 数据增强

4.6 lib/tools/

当前主路径真正会用到的核心工具只有：

1. loss.py 主分割损失构建
2. metrics.py Dice / IoU 等验证指标
3. optim.py optimizer 和 scheduler 构建

---

5. 当前纯文本架构图

5.1 训练系统总架构图

+----------------------------------------------------------------------------------+
|                              当前纯分割训练系统                                  |
+----------------------------------------------------------------------------------+
|                                                                                  |
|  tools/train.py                                                                  |
|      |                                                                           |
|      v                                                                           |
|  读取 YAML 配置 + 应用 --set 覆盖                                                |
|      |                                                                           |
|      v                                                                           |
|  build_trainer(cfg)                                                              |
|      |                                                                           |
|      v                                                                           |
|  SupervisedSegmentationTrainer                                                   |
|      |                                                                           |
|      +------------------- build() -------------------+                           |
|      |                                               |                           |
|      v                                               v                           |
|  build_dataloader()                            SegmentationModel2d               |
|      |                                               |                           |
|      v                                               v                           |
|  SegmentationRecordDataset                     SwinV2Encoder2d                   |
|      |                                               |                           |
|      v                                               v                           |
|  image, mask batch                            multi-scale features               |
|                                                        |                         |
|                                                        v                         |
|                                              SegmentationDecoder2d              |
|                                                        |                         |
|                                                        v                         |
|                                                decoded feature                   |
|                                                        |                         |
|                                                        v                         |
|                                                SegmentationHead2d                |
|                                                        |                         |
|                                                        v                         |
|                                                     seg_logits                   |
|                                                        |                         |
|                                                        v                         |
|                                                     seg_loss                     |
|                                                        |                         |
|                                                        v                         |
|                                            backward + optimizer.step()           |
|                                                        |                         |
|                                                        v                         |
|                                          validation / metric / checkpoint        |
|                                                                                  |
+----------------------------------------------------------------------------------+

5.2 模型内部结构图

Input Image [B, 3, H, W]
    |
    v
SwinV2Encoder2d
    |
    +-- feature_0  (可选 patch_embed 特征)
    +-- feature_1
    +-- feature_2
    +-- feature_3
    `-- feature_4
            |
            v
SegmentationDecoder2d
    |
    +-- Decode Block 1: deepest + skip_3
    +-- Decode Block 2: upsample + skip_2
    +-- Decode Block 3: upsample + skip_1
    `-- Decode Block 4: upsample + skip_0
            |
            v
decoded feature
    |
    v
SegmentationHead2d
    |
    v
seg_logits
    |
    v
上采样回输入分辨率

5.3 数据系统结构图

dataset.root
    |
    v
build_dataset_index(dataset_name, root)
    |
    v
apply split
    |
    v
SegmentationRecordDataset
    |
    +-- 读取 image
    +-- 读取 mask
    +-- 应用 augmentation
    +-- resize image/mask
    |
    v
DataLoader
    |
    v
batch = {
    image,
    mask,
    dataset_name,
    sample_id,
    split,
    class_name,
    meta
}

---

6. 当前纯文本流程图

6.1 启动流程图

[开始]
   |
   v
执行 tools/train.py --config xxx.yaml --set key=value ...
   |
   v
parse_args()
   |
   v
load_yaml_config()
   |
   v
apply_dotlist_overrides()
   |
   v
build_trainer(cfg)
   |
   v
trainer.build()
   |
   +--> 构建 model
   +--> 构建 optimizer
   +--> 构建 scheduler
   +--> 构建 train loader
   +--> 构建 val loader
   +--> 恢复 checkpoint（如配置）
   `--> 初始化 SwanLab（如启用）
   |
   v
trainer.train()
   |
   v
[进入 epoch 循环]

6.2 单个 epoch 流程图

[epoch 开始]
   |
   v
model.train()
optimizer.zero_grad()
   |
   v
for batch in train_loader:
   |
   +--> 取 image, mask
   |
   +--> model(image)
   |      |
   |      `--> seg_logits
   |
   +--> 计算 seg_loss
   |
   +--> total_loss = seg_loss
   |
   +--> backward()
   |
   +--> 如果到达 accum_steps:
   |      |
   |      +--> 可选 gradient clipping
   |      +--> optimizer.step()
   |      +--> scaler.update()
   |      `--> optimizer.zero_grad()
   |
   `--> 记录 step 日志
   |
   v
epoch 结束后 scheduler.step()
   |
   v
如果需要验证:
   |
   +--> model.eval()
   +--> 遍历 val_loader
   +--> 统计 val loss
   `--> 统计 Dice / IoU
   |
   v
保存 checkpoint
   |
   v
判断 early stopping

6.3 单次前向传播流程图

image
  |
  v
SegmentationModel2d.forward()
  |
  +--> features = encoder(image)["features"]
  |
  +--> decoder_out, _ = decoder(features)
  |
  `--> seg_logits = segmentation_head(decoder_out, output_size=input_size)
           |
           v
return {
  seg_logits
}

---

7. 当前模型链路详解

7.1 SegmentationModel2d

文件：lib/modules/segmentation_2d.py

这是当前主模型封装。

它的职责非常直接：

1. 调用编码器提取多尺度特征
2. 调用解码器恢复高分辨率分割特征
3. 调用分割头输出 seg_logits

它不再负责：

1. 边界输出
2. 多分支辅助预测
3. 任何历史先验注入接口

7.2 SwinV2Encoder2d

文件：lib/modules/swinv2_encoder_2d.py

职责：

1. 构建 SwinV2 backbone
2. 输出多尺度特征列表
3. 支持是否包含 patch embed 特征
4. 支持是否输出多尺度特征

当前主链只使用它的：

1. features

7.3 SegmentationDecoder2d

文件：lib/modules/decoder_2d.py

这是当前纯分割解码器。

每层解码块 SegmentationDecodeBlock2d 的工作方式是：

1. 对高层特征上采样
2. 对 skip 特征做通道映射
3. 拼接后卷积融合
4. 用 DecodeRefineBlock2d 做轻量残差细化

当前已经没有：

1. FWTA 注入接口
2. stability prior
3. saliency prior
4. boundary hint

7.4 SegmentationHead2d

文件：lib/modules/segmentation_2d.py

职责：

1. 接收解码器输出特征
2. 经过卷积块生成分割 logits
3. 上采样到输入分辨率

最终输出：

1. seg_logits

---

8. 当前训练器链路详解

8.1 SupervisedSegmentationTrainer

文件：lib/trainers/supervised.py

虽然类名仍然保留 SegmentationTrainer 字样，但当前内容已经是纯单头分割训练。

8.2 build()

build() 当前做的事：

1. 构建 SegmentationModel2d
2. 构建 optimizer
3. 构建 scheduler
4. 构建主分割 loss
5. 构建 train loader
6. 构建 val loader
7. 恢复 checkpoint
8. 初始化日志系统

8.3 _compute_losses()

当前 loss 计算已经简化为：

outputs = model(image)
seg_logits = outputs["seg_logits"]
seg_loss = criterion(seg_logits, mask)
total_loss = seg_loss

也就是：

total_loss = seg_loss

8.4 train()

当前训练循环做的事：

1. 前向得到 seg_logits
2. 计算 seg_loss
3. backward
4. 可选梯度累计
5. 可选梯度裁剪
6. optimizer step
7. scheduler step
8. 验证集评估
9. checkpoint 与 early stopping

---

9. 当前数据系统详解

9.1 当前输入输出格式

SegmentationRecordDataset 返回：

1. image
2. mask
3. dataset_name
4. sample_id
5. split
6. class_name
7. meta

9.2 当前数据读取流程

1. 读 RGB 图像，归一化到 [0, 1]
2. 读二值分割 mask
3. 对 image 和 mask 做联合增强
4. resize 到配置指定尺寸
5. 送入 DataLoader

9.3 当前支持的数据集

当前 lib/data/builder.py 支持：

1. BUS-UCLM
2. BUSI
3. BUS-BRA
4. BUS_UC
5. CCAUI
6. DDTI
7. OTU_2d
8. TN3K
9. TG3K

---

10. 当前损失、指标与优化流程

10.1 当前损失

当前主路径只保留主分割损失。

默认配置示例：

loss:
  name: dicece
  task_mode: binary
  params:
    include_background: true
    lambda_dice: 0.7
    lambda_ce: 0.3

也就是说当前优化目标只围绕 mask 分割本身。

10.2 当前指标

当前验证指标通常为：

1. dice
2. iou

10.3 当前优化器

默认配置：

1. adamw
2. 支持 warmup + cosine scheduler

10.4 当前 AMP

当前仍支持：

1. torch.autocast
2. GradScaler

---

11. 关键配置变量解释（中英对照）

11.1 trainer.name

1. 中文：训练器名称
2. English: trainer name
3. 作用：决定实例化哪个 trainer
4. 当前值：supervised_segmentation

11.2 train.seed

1. 中文：随机种子
2. English: random seed
3. 作用：控制随机性

11.3 train.epochs

1. 中文：训练轮数
2. English: number of epochs
3. 作用：决定最大训练轮数

11.4 train.batch_size

1. 中文：训练 batch 大小
2. English: training batch size
3. 作用：控制每批样本数

11.5 train.val_batch_size

1. 中文：验证 batch 大小
2. English: validation batch size
3. 作用：控制验证批次大小

11.6 train.accum_steps

1. 中文：梯度累计步数
2. English: gradient accumulation steps
3. 作用：模拟更大有效 batch

11.7 train.amp

1. 中文：自动混合精度
2. English: automatic mixed precision
3. 作用：降低显存、提高吞吐

11.8 train.grad_clip.enabled

1. 中文：是否启用梯度裁剪
2. English: enable gradient clipping
3. 作用：提升训练稳定性

11.9 metrics.task_mode

1. 中文：指标任务模式
2. English: metric task mode
3. 作用：指定 binary 或 multiclass

11.10 loss.name

1. 中文：损失名称
2. English: loss name
3. 作用：指定分割损失类型

11.11 dataset.dataset_name

1. 中文：数据集名称
2. English: dataset name
3. 作用：决定用哪个数据集构建器

11.12 dataset.root

1. 中文：数据根目录
2. English: dataset root
3. 作用：决定从哪里读取数据

11.13 dataset.image_size

1. 中文：输入图像尺寸
2. English: input image size
3. 作用：控制 resize 大小

11.14 dataset.num_classes

1. 中文：分割类别数
2. English: number of classes
3. 作用：决定分割头输出通道数

11.15 model.model_name

1. 中文：backbone 名称
2. English: backbone model name
3. 作用：决定加载哪个 SwinV2 结构配置

11.16 model.decoder_channels

1. 中文：解码器通道数配置
2. English: decoder channel sizes
3. 作用：控制解码器每层输出维度

11.17 model.use_multiscale_features

1. 中文：是否使用多尺度特征
2. English: use multi-scale features
3. 作用：控制 encoder 是否输出多层特征给 decoder

11.18 model.include_patch_embed

1. 中文：是否包含 patch embed 特征
2. English: include patch embedding feature
3. 作用：控制最浅层特征是否进入解码链

11.19 optimizer.lr

1. 中文：学习率
2. English: learning rate
3. 作用：控制参数更新步长

11.20 checkpoint.monitor

1. 中文：监控指标
2. English: monitored metric
3. 作用：决定 best checkpoint 基于什么指标保存

---

12. 关键运行时变量解释（中英对照）

12.1 cfg

1. 中文：总配置字典
2. English: global config dictionary
3. 作用：控制整个训练流程

12.2 image

1. 中文：输入图像
2. English: input image
3. 典型形状：[B, C, H, W]

12.3 mask

1. 中文：真实分割掩膜
2. English: ground-truth mask
3. 典型形状：[B, 1, H, W]

12.4 features

1. 中文：编码器多尺度特征
2. English: multi-scale features
3. 作用：供 decoder 恢复空间细节

12.5 decoder_out

1. 中文：解码器输出特征
2. English: decoder output feature
3. 作用：作为分割头输入

12.6 seg_logits

1. 中文：分割 logits
2. English: segmentation logits
3. 作用：主预测结果

12.7 seg_loss

1. 中文：主分割损失
2. English: segmentation loss
3. 作用：训练优化目标

12.8 total_loss

1. 中文：总损失
2. English: total loss
3. 当前关系：total_loss = seg_loss

12.9 best_metric

1. 中文：最佳验证指标
2. English: best validation metric
3. 作用：控制 best checkpoint 与 early stopping

12.10 grad_scaler

1. 中文：混合精度梯度缩放器
2. English: gradient scaler
3. 作用：保证 AMP 下训练稳定

---

13. 当前实验脚本的真实含义

文件：tools/run_us_experiments.sh

当前脚本只做纯分割实验组织。

支持两种模式：

1. 单个数据集训练
2. 所有数据集批量训练

已经不再支持：

1. 边界辅助损失消融
2. 一致性损失消融
3. FWTA 消融

---

14. 当前状态的最简结论

当前项目已经完成主路径净化，可以用下面几句话概括：

1. 当前主模型是 SegmentationModel2d。
2. 当前主结构是 SwinV2Encoder2d + SegmentationDecoder2d + SegmentationHead2d。
3. 当前训练只做单头分割，不再有边界分支。
4. 当前总损失就是主分割损失，不再有边界损失和一致性损失。
5. 当前配置文件与实验脚本已经去掉 aux_loss 和相关消融入口。
6. 当前现役主链不再调用 FWTA，也不再对外保留 FWTA 语义。