X_SSL_Net/docs/experiments/一键实验脚本使用说明.md

优化一键实验脚本使用说明

1. 脚本位置

tools/run_optimized_supervised.sh

该脚本服务当前 XNet2d 全监督超声分割主线。

2. 脚本做什么

脚本会自动完成：

1. 根据 DATASET 解析数据集根目录
2. 对需要项目级划分的数据集调用 scripts/generate_project_split.py
3. 调用 tools/train.py
4. 使用 configs/segmentation/optimized/*.yaml
5. 训练前打印实际生效的 dataset、image_size、batch_size、amp、lr 和 SwanLab 配置

3. 可改环境变量

DATASET="${DATASET:-BUSI}"
SEED="${SEED:-42}"
RUN_ALL="${RUN_ALL:-0}"
EXTRA_SET_ARGS="${EXTRA_SET_ARGS:-}"

含义：

1. DATASET：选择数据集
2. SEED：项目级 split 随机种子
3. RUN_ALL：设为 1 时依次跑内置全部监督数据集
4. EXTRA_SET_ARGS：追加给 tools/train.py --set 的覆盖参数

脚本固定使用：

/opt/miniforge3/envs/xnet_mamba/bin/python

4. 支持的数据集名称

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

5. 常用跑法

跑单个数据集：

DATASET=BUSI bash tools/run_optimized_supervised.sh

短跑调试：

DATASET=BUSI \
EXTRA_SET_ARGS="train.epochs=2 train.batch_size=2 train.val_batch_size=2 logging.use_swanlab=false" \
bash tools/run_optimized_supervised.sh

一次跑全部监督数据集：

RUN_ALL=1 bash tools/run_optimized_supervised.sh

6. 当前配置文件

当前正式优化训练配置在：

configs/segmentation/optimized/

所有优化配置统一使用 384x384、amp=true，并默认打开 SwanLab cloud，同时将本地日志保存在 swanlog/。

7. XNet 消融示例

关闭 wavelet branch：

DATASET=BUSI \
EXTRA_SET_ARGS="model.use_wavelet_branch=false checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_no_wavelet logging.experiment_name=xnet_busi_no_wavelet" \
bash tools/run_optimized_supervised.sh

关闭 frequency refine：

DATASET=BUSI \
EXTRA_SET_ARGS="model.use_frequency_refine=false checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_no_freq logging.experiment_name=xnet_busi_no_freq" \
bash tools/run_optimized_supervised.sh

关闭两者：

DATASET=BUSI \
EXTRA_SET_ARGS="model.use_wavelet_branch=false model.use_frequency_refine=false checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_no_wavelet_no_freq logging.experiment_name=xnet_busi_no_wavelet_no_freq" \
bash tools/run_optimized_supervised.sh

强制 SS2D 使用 torch fallback：

DATASET=BUSI \
EXTRA_SET_ARGS="model.ssm_backend=torch checkpoint.dir=outputs/experiments/supervised_ablation/BUSI_ssm_torch logging.experiment_name=xnet_busi_ssm_torch" \
bash tools/run_optimized_supervised.sh

8. 当前推荐实验顺序

先跑：

1. BUSI
2. DDTI
3. TN3K
4. TG3K

再扩：

1. BUS_UC
2. BUS-BRA
3. BUS-UCLM
4. OTU_2d
5. CCAUI

当前项目的论文主线更适合优先落在甲状腺或乳腺 2D 超声分割。