# X_SL_Net 项目阶段汇报（2026-05-06）

## 1. 阶段性结论

本阶段已经把 `X_SL_Net` 从早期的多路线探索，收敛成一条清晰、可运行、可训练、可解释的当前主线：

```text
2D 超声图像分割
-> XNet2d
-> CNN + Wavelet + VMamba-style SS2D 混合编码
-> X-shaped decoder
-> 单分割头 seg_logits
-> 全监督 DiceCE 训练
```

具备以下完整工程闭环：

```text
启动脚本
-> 配置系统
-> 数据划分
-> DataLoader
-> 模型构建
-> GPU 训练
-> 验证指标
-> checkpoint
-> 实验结果汇总
-> 项目文档
```

这份文档已经把当前项目从启动到模型、从数据到训练、从 loss 到 checkpoint 的完整链路用纯文本架构图系统梳理完成。

## 2. 当前项目主线

当前 active 主线已经明确为：

```text
XNet2d = X-shaped CNN-Wavelet-VMamba hybrid segmentation network
```

真实训练链路是：

```text
shell script
-> tools/train.py
-> SupervisedSegmentationTrainer
-> SegmentationRecordDataset / DataLoader
-> XNet2d
-> seg_logits
-> DiceCE loss / BCE fallback
-> Dice / IoU validation
-> best.pth / last.pth
```

当前模型只训练一个分割头：

```text
outputs["seg_logits"]
```

当前主链不再混入：

1. `SAM2`
2. `SwinV2` 旧配置
3. `FWTA` 旧实验分支
4. 边界辅助分支
5. 半监督 trainer

这让项目叙事变得清楚：当前阶段先把 `XNet2d` 作为 2D 超声分割主干跑稳，再围绕核心模块做消融与扩展。

## 3. 已完成的主要工作

### 3.1 完成 XNet2d 工程原型

已实现当前主模型：

```text
lib/modules/xnet_2d.py
```

核心模块包括：

```text
XNet2d
├─ XNetStem2d
├─ XNetEncoder2d
├─ XTEB2d
├─ XLocalBranch2d
├─ XWaveletBranch2d
├─ XSSMGlobalBranch2d
├─ XNetDecoder2d
├─ XCRB2d
├─ XFrequencyRefine2d
└─ XNetSegHead2d
```

当前默认配置下的参数量：

```text
total parameters:     9,432,129
trainable parameters: 9,432,129
```

### 3.2 完成 VMamba-style SS2D 接入

当前 global branch 已接入项目内本地副本：

```text
lib/modules/lib_mamba/vmamba.py::SS2D
```

来源边界已经明确：

```text
VMamba-style SS2D operator
```

同时已确认真实环境中：

```text
selective_scan_cuda_oflex import OK
WITH_SELECTIVESCAN_OFLEX = True
```

### 3.3 修复 SS2D 后端性能问题

早期训练很慢的核心原因已经定位并解决：

```text
ssm_backend=auto 曾经被错误强制到 torch fallback
```

现在逻辑已经调整为：

```text
ssm_backend = auto
  |
  +-- CUDA tensor -> oflex
  |
  +-- CPU tensor  -> torch fallback
```

当前默认配置：

```yaml
ssm_forward_type: v3
ssm_backend: auto
```

实际速度验证：

```text
XNet2d 128x128 单张 eval 前向:
avg_forward_sec ≈ 0.0245s
```

BUSI 训练验证：

```text
batch_size = 8
image_size = 256
num_steps = 78
iter_time ≈ 0.09 - 0.11s / step
GPU memory ≈ 850 MB
```

当前 oflex 快路径已经生效，训练速度从早期 torch fallback 的 `1.6 - 1.9s/step` 级别，提升到 `0.1s/step` 左右。

### 3.4 解决 FFT AMP warning

`XFrequencyRefine2d` 中使用 `torch.fft.rfft2`，在 AMP 下曾触发：

```text
ComplexHalf support is experimental
```

已修复为：

```text
FFT 计算前显式转 float32
频域处理完成后再转回输入 dtype
```

现在 frequency refine 可在 AMP 训练下正常运行，不再产生该 warning。

### 3.5 完成全监督训练入口切换

当前 trainer 已从旧模型切换到：

```text
lib.modules.XNet2d
```

当前训练入口：

```text
tools/train.py
```

当前 trainer：

```text
lib/trainers/supervised.py::SupervisedSegmentationTrainer
```

训练流程已经跑通：

```text
model forward
loss backward
gradient clipping
optimizer step
scheduler step
validation
best/last checkpoint save
```

### 3.6 完成配置收敛

旧的 SwinV2 / 肺超 / 历史 segmentation 配置已经清理。

当前保留的主配置：

```text
configs/segmentation/train_sup_us_template.yaml
configs/segmentation/us_exp_sup_busi.yaml
configs/segmentation/us_exp_sup_busi_ablation.yaml
```

当前模型配置已经统一为 XNet 字段：

```yaml
encoder_channels: [32, 64, 128, 192]
encoder_depths: [2, 2, 2, 2]
decoder_channels: [128, 64, 32]
use_wavelet_branch: true
ssm_forward_type: v3
ssm_backend: auto
use_frequency_refine: true
```

### 3.7 完成数据链路整理

当前支持的数据集入口包括：

```text
BUS-UCLM
BUSI
BUS-BRA
BUS_UC
CCAUI
DDTI
OTU_2d
TN3K
TG3K
```

数据流程已经梳理为：

```text
build_dataset_index
-> apply split
-> SegmentationRecordDataset
-> augmentation
-> resize
-> collate
-> DataLoader
```

项目级 split 脚本已从 `tmp/` 移到正式脚本目录：

```text
scripts/generate_project_split.py
```

当前启动脚本会自动调用该脚本为 BUSI、DDTI 等数据集生成或加载 `train/val` 划分。

### 3.8 完成 tmp 目录整理

`tmp/` 根目录下散落的临时代码已归类：

```text
tmp/scripts/inspect/   数据与 dataloader 检查脚本
tmp/scripts/smoke/     XNet 前向、配置、速度冒烟脚本
tmp/scripts/legacy/    历史 Swin / 旧训练脚本
tmp/artifacts/         历史报告、临时 checkpoint、session 文件
tmp/docs/              当前项目文档
```

当前主训练不再直接依赖 `tmp/` 下的脚本，唯一原本依赖的 split 脚本已进入：

```text
scripts/generate_project_split.py
```

## 4. 当前 XNet2d 架构亮点

### 4.1 Encoder 是三分支结构

`XTEB2d` 是当前 encoder 的基本单元。

结构：

```text
Input X
│
├─ Local branch
│  ├─ DWConv3x3
│  └─ DWConv5x5
│
├─ Wavelet branch
│  ├─ Haar DWT
│  ├─ LL low-frequency branch
│  ├─ LH/HL/HH high-frequency branch
│  └─ inverse Haar transform
│
├─ Global branch
│  └─ VMamba-style SS2D
│
├─ branch fusion
├─ channel gate
├─ residual add
└─ FFN
```

这个设计对应超声图像的三个核心问题：

```text
local branch   -> 局部纹理、边缘、斑点噪声
wavelet branch -> 高频边界、低频轮廓
SS2D branch    -> 长程依赖、全局结构一致性
```

### 4.2 Decoder 是 X-shaped 信息流

当前 decoder 不只是普通 U-Net skip。

它包含两类路径：

```text
same-scale path:
  E3 -> D4
  E2 -> D3
  E1 -> D2

diagonal guide path:
  E4 -> D4
  E3 -> D3
  E2 -> D2
```

纯文本结构：

```text
Encoder: E1 ---------------------------> D2
            \                          /
             \                        /
Encoder:      E2 -------------------> D3
               \      guide to D2   /
                \                  /
Encoder:         E3 -------------> D4
                  \ guide to D3  /
                   \            /
Encoder:            E4 --------/
                     guide to D4
```

这也是 `XNet` 命名的结构依据：同尺度细节路径与斜向语义引导路径共同构成 X-shaped 信息流。

### 4.3 256 输入下的张量尺寸流

默认输入：

```text
[B, 3, 256, 256]
```

Encoder：

```text
Stem -> [B, 32, 64, 64]
E1   -> [B, 32, 64, 64]
E2   -> [B, 64, 32, 32]
E3   -> [B,128, 16, 16]
E4   -> [B,192,  8,  8]
```

Decoder：

```text
D4 -> [B,128, 16, 16]
D3 -> [B, 64, 32, 32]
D2 -> [B, 32, 64, 64]
Head -> [B, 1, 256, 256]
```

最终输出：

```text
seg_logits: [B, 1, 256, 256]
```

## 5. 当前启动到模型的完整流程

这一部分已经在 `tmp/docs/training/当前项目详解与纯文本架构流程图.md` 中完整梳理。

核心流程图如下：

```text
User command
  |
  | DATASET=BUSI bash tools/run_us_experiments.sh
  v
tools/run_us_experiments.sh
  |
  ├─ read DATASET / SEED / EXTRA_SET_ARGS
  ├─ dataset_root(DATASET)
  ├─ if needed: scripts/generate_project_split.py
  └─ python tools/train.py --config ... --set ...
        |
        v
tools/train.py
  |
  ├─ parse args
  ├─ load yaml
  ├─ apply --set overrides
  ├─ build_trainer(cfg)
  └─ trainer.train()
        |
        v
SupervisedSegmentationTrainer
  |
  ├─ build XNet2d
  ├─ build optimizer / scheduler / loss
  ├─ build train and val dataloaders
  ├─ run training loop
  ├─ run validation
  └─ save checkpoint
```

从 batch 到 loss：

```text
DataLoader batch
  |
  +-- image [B,3,256,256]
  +-- mask  [B,1,256,256]
  |
  v
XNet2d(image)
  |
  v
seg_logits [B,1,256,256]
  |
  v
DiceCELoss(seg_logits, mask)
  |
  v
backward + optimizer.step
```

## 6. 文档沉淀

本阶段不是只写代码，也完成了系统性文档沉淀。

当前核心文档包括：

```text
tmp/docs/training/当前项目详解与纯文本架构流程图.md
tmp/docs/method/XNet_method.md
tmp/docs/method/lib_mamba_source_note.md
tmp/docs/operations/Start.md
tmp/docs/experiments/一键实验脚本使用说明.md
tmp/docs/experiments/实验结果汇总脚本说明.md
tmp/docs/paper/超声分割主流方法与分领域方向判断_2026-04-30.md
```

其中最重要的是：

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

该文档已经覆盖：

1. 项目定位
2. shell 启动入口
3. YAML 配置系统
4. trainer 构建流程
5. BaseTrainer 公共能力
6. 数据集 index 与 split
7. Dataset / augmentation / collate / DataLoader
8. XNet2d 总体结构
9. XTEB2d 三分支细节
10. XCRB2d decoder 细节
11. SS2D / oflex 后端选择
12. forward 输出
13. loss、validation、metric、checkpoint
14. 日志字段与性能解释
15. 推荐实验命令和消融路线

这份文档可以直接用于项目汇报、组会讲解、后续交接和论文方法章节前置梳理。

## 7. 当前已验证结果

### 7.1 环境验证

真实环境：

```text
conda env: xnet_mamba
python: /opt/miniforge3/envs/xnet_mamba/bin/python
torch: 2.10.0+cu126
cuda: True
GPU: NVIDIA GeForce RTX 4070 Ti SUPER
```

SS2D 后端：

```text
oflex import OK
WITH_SELECTIVESCAN_OFLEX = True
```

### 7.2 前向验证

XNet2d GPU 前向已通过：

```text
keys: ['decoder_features', 'encoder_features', 'guides', 'logits', 'seg_logits']
seg_logits: (1, 1, 128, 128)
```

速度：

```text
avg_forward_sec: 0.0245
```

### 7.3 BUSI 短训验证

`batch_size=8`、`image_size=256`、`ssm_backend=auto`、`ssm_forward_type=v3` 下：

```text
train samples: 624
val samples: 156
train steps: 78
val steps: 20
iter_time: about 0.09 - 0.11s / step
gpu_memory: about 850 MB
```

一轮 smoke test 已经完成：

```text
best.pth
last.pth
```

已有验证输出目录：

```text
outputs/validation/xnet_gpu_smoke
outputs/validation/xnet_oflex_b4
outputs/validation/xnet_oflex_b8
outputs/validation/xnet_b8_w2
```

## 8. 当前项目状态总结

当前已经完成：

1. 明确项目主线：`XNet2d` 2D 超声分割
2. 实现 XNet2d 主模型
3. 接入 VMamba-style SS2D
4. 修复 `auto` 后端，确保 CUDA 下优先 oflex
5. 修复 FFT AMP warning
6. 清理旧 SwinV2 / FWTA / boundary 主链残留
7. 收敛 YAML 配置
8. 跑通 GPU 前向
9. 跑通 BUSI 全监督短训
10. 生成 best/last checkpoint
11. 整理 `tmp/` 目录
12. 将主链 split 脚本移到 `scripts/`
13. 完成当前项目详解与纯文本架构流程图
14. 完成实验脚本和结果汇总说明
15. 形成方法、来源、训练、运行、实验多层文档

## 9. 下一步计划

### 9.1 训练稳定性和验证模型效果

继续验证：

```text
BUSI batch_size=8 多 epoch
DDTI smoke
TN3K smoke
TG3K smoke
```

### 9.2 核心消融

优先做：

```text
use_wavelet_branch=false
use_frequency_refine=false
ssm_backend=torch
use_global_branch_stage1=true
encoder_depths=[2,2,3,2]
```

### 9.3 论文主线

建议优先落在：

```text
甲状腺超声：DDTI / TN3K / TG3K
乳腺超声：BUSI / BUS_UC / BUS-BRA / BUS-UCLM
```

## 10. 结论

本阶段我已经完成了从方法设计、模型实现、SS2D 加速、训练入口切换、配置清理、数据链路、GPU 验证、实验脚本到系统文档的完整闭环，把项目从早期多路线探索推进到一个可训练、可复现、可汇报的 `XNet2d` 超声分割工程原型。