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

## 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. 目录职责总览

```text
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 训练系统总架构图

```text
+----------------------------------------------------------------------------------+
|                              当前纯分割训练系统                                  |
+----------------------------------------------------------------------------------+
|                                                                                  |
|  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 模型内部结构图

```text
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 数据系统结构图

```text
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 启动流程图

```text
[开始]
   |
   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 流程图

```text
[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 单次前向传播流程图

```text
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 计算已经简化为：

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

也就是：

```text
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 当前损失

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

默认配置示例：

```yaml
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 语义。