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

1. 阶段性结论

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

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

具备以下完整工程闭环：

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

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

2. 当前项目主线

当前 active 主线已经明确为：

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

真实训练链路是：

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

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

outputs["seg_logits"]

当前主链不再混入：

SAM2
SwinV2 旧配置
FWTA 旧实验分支
边界辅助分支
半监督 trainer

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

3. 已完成的主要工作

3.1 完成 XNet2d 工程原型

已实现当前主模型：

lib/modules/xnet_2d.py

核心模块包括：

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

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

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

3.2 完成 VMamba-style SS2D 接入

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

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

来源边界已经明确：

VMamba-style SS2D operator

同时已确认真实环境中：

selective_scan_cuda_oflex import OK
WITH_SELECTIVESCAN_OFLEX = True

3.3 修复 SS2D 后端性能问题

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

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

现在逻辑已经调整为：

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

当前默认配置：

ssm_forward_type: v3
ssm_backend: auto

实际速度验证：

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

BUSI 训练验证：

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 下曾触发：

ComplexHalf support is experimental

已修复为：

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

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

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

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

lib.modules.XNet2d

当前训练入口：

tools/train.py

当前 trainer：

lib/trainers/supervised.py::SupervisedSegmentationTrainer

训练流程已经跑通：

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

3.6 完成配置收敛

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

当前保留的主配置：

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

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

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 完成数据链路整理

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

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

数据流程已经梳理为：

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

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

scripts/generate_project_split.py

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

3.8 完成 tmp 目录整理

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

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

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

scripts/generate_project_split.py

4. 当前 XNet2d 架构亮点

4.1 Encoder 是三分支结构

XTEB2d 是当前 encoder 的基本单元。

结构：

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

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

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

4.2 Decoder 是 X-shaped 信息流

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

它包含两类路径：

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

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

纯文本结构：

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 输入下的张量尺寸流

默认输入：

[B, 3, 256, 256]

Encoder：

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：

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

最终输出：

seg_logits: [B, 1, 256, 256]

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

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

核心流程图如下：

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：

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. 文档沉淀

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

当前核心文档包括：

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

其中最重要的是：

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

该文档已经覆盖：

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

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

7. 当前已验证结果

7.1 环境验证

真实环境：

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 后端：

oflex import OK
WITH_SELECTIVESCAN_OFLEX = True

7.2 前向验证

XNet2d GPU 前向已通过：

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

速度：

avg_forward_sec: 0.0245

7.3 BUSI 短训验证

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

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 已经完成：

best.pth
last.pth

已有验证输出目录：

outputs/validation/xnet_gpu_smoke
outputs/validation/xnet_oflex_b4
outputs/validation/xnet_oflex_b8
outputs/validation/xnet_b8_w2

8. 当前项目状态总结

当前已经完成：

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

9. 下一步计划

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

继续验证：

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

9.2 核心消融

优先做：

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

9.3 论文主线

建议优先落在：

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

10. 结论

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

2026-05-06_XNet项目阶段汇报.md 12 KB Vēsture Neapstrādāts