btvit-cli 0.2.5

Typer CLI package for the Vit medical multi-axis Vision Transformer project.

btvit-cli

基于 PyTorch 的三轴 ViT 医学影像二分类 CLI。

安装

pip install btvit-cli
vit --version

当前主线

项目现在只保留一条流程：

1. axis 阶段分别训练 x / y / z 三个轴的单轴 ViT
2. fusion 阶段复用三轴 encoder，训练患者级 fusion_nn 头
3. pred 阶段支持两种患者级输出：
   • weighted_vote
   • fusion_nn
   • both

每个患者的每张 (16, 368) 灰度图都作为独立样本共享患者标签，不再使用旧的中间特征缓存或跨轴组合穷举训练流程。

快速开始

1. 导出模板

vit get --path ./configs

导出内容：

• model_config.yaml
• data_config.yaml
• training_config.yaml
• experiment_config.yaml
• multi_axis_config.yaml
• monitoring_config.yaml
• USAGE.md

2. 训练三轴 ViT

vit train --config configs/base --stage axis --axis x --init same --verbose
vit train --config configs/base --stage axis --axis y --init same --verbose
vit train --config configs/base --stage axis --axis z --init same --verbose

关键参数：

• --stage axis
• --axis x|y|z
• --config <yaml_dir>
• --init same|random
• --init-seed <int>：控制模型初始化
• --random-seed <int>：全局 seed 回退值
• --train-split-seed <int>：控制患者划分
• --data 可选。未提供时使用 multi_axis.axis_data_paths.<axis>
• --label 可选。未提供时使用配置文件中的标签路径

3. 训练 fusion 头

vit train --config configs/base --stage fusion --fusion concat --init same --verbose

fusion 阶段会默认解析：

• experiments/<name>/axis-x/checkpoints/best_model.pth
• experiments/<name>/axis-y/checkpoints/best_model.pth
• experiments/<name>/axis-z/checkpoints/best_model.pth

也可以显式覆盖：

• --axis-checkpoint-x
• --axis-checkpoint-y
• --axis-checkpoint-z
• --fusion sum|concat

4. 患者级预测

vit pred --mode weighted_vote --config configs/base --data dataset/predict_root
vit pred --mode fusion_nn --config configs/base --data dataset/predict_root --fusion concat
vit pred --mode both --config configs/base --data dataset/predict_root --label dataset/label.csv --fusion sum

预测模式：

• weighted_vote：单图概率 -> 轴内患者均值 -> 三轴均值；均值 > 2/3 判阳性
• fusion_nn：单图特征 -> 轴内患者均值 -> sum|concat -> fusion head
• both：同时输出两条分支

预测数据支持：

1. 根目录包含 data-x/、data-y/、data-z/
2. 平铺 PNG 目录，文件名为 {patient_id}_{Z}_{Y}_{X}.png

输出结构

训练输出：

experiments/<experiment_name>/
  axis-x/
    checkpoints/
    results/
    logs/
  axis-y/
    checkpoints/
    results/
    logs/
  axis-z/
    checkpoints/
    results/
    logs/
  fusion/
    checkpoints/
    results/
    logs/
  testset/
    data-x/
    data-y/
    data-z/
    label.csv

预测输出：

• predictions.csv
• prediction_summary.json
• confusion_matrix_weighted_vote.png，当有标签且启用 weighted_vote
• confusion_matrix_fusion_nn.png，当有标签且启用 fusion_nn

配置要点

• training.common：设备、worker、混合精度等公共训练参数
• random_seed / init.init_mode / init.init_seed：训练可复现性设置
• training.axis：单轴 ViT 训练参数
• training.fusion：fusion 头训练参数
• train_split.train_split_random_seed：患者划分随机种子
• train_split.csv_split_random_seed：CSV 重划分随机种子
• multi_axis.patient_pooling：患者内均值聚合规则
• multi_axis.weighted_vote：固定三轴投票开关
• multi_axis.fusion_head：患者级 fusion 头配置，包含 fusion: sum|concat
• monitoring.axis / monitoring.fusion / monitoring.prediction：分阶段监控与 fusion_nn 预测阈值

训练可复现性

• --init same 现在是默认模式。它会固定模型初始化，并为训练 DataLoader 使用固定随机生成器，从而让相同配置更容易复现。
• --init random 保持随机初始化，适合对比不同初始化带来的结果波动。
• --init-seed 只控制模型初始化；--train-split-seed 只控制患者划分；--random-seed 作为这些 seed 的全局回退值。
• --init same 会关闭 torch.backends.cudnn.benchmark，因此训练可能比随机模式略慢。

开发

conda activate Vit
pip install -e .
vit --help

构建：

conda run -n Vit python -m build

许可证

Apache-2.0