nv-segment-ct-finetune

NV-Segment-CT ファインチューニング

目的

• NV-Segment-CT VISTA3DをCT NIfTIラベルでスモークテストまたはデータセットのファインチューニングに使用します。臨床検証には使用しないでください。
• 上流のMONAIバンドルエントリーポイントをラップします。手書きのトレーニングコードや推論コードに置き換えないでください。
• マニフェストの入力は、dataset_dir、datalist、target_anatomy、label_mapping、smoke、sanity、auto_seg、skip_formal_evalです。
• マニフェストの出力は、finetuned_ckptとスキーマ検証済みのresult_jsonです。

手順

• scripts/run_finetune.pyを実行してください。通常のスキル使用時に、bundle/以下のファイルや上流のチェックアウトにパッチを適用しないでください。
• 単独のBashで実行する場合は、ラッパーより前に新規環境のセットアップ行を含めてください。ベンチマークの仮想環境は空の状態で始まります。
• リポジトリのルートから、コミット済みのスクリプトをそのまま実行してください。このスキルを実行時ディレクトリにコピーしたり、生成されるコマンドでrmやクリーンアップコマンドを使用したりしないでください。
• ホストがrun_scriptを公開している場合は、run_script("scripts/run_finetune.py", args=[...])を使用してください。それ以外の場合は、リポジトリのルートから実行してください。
• 最短のワークフローチェックには--smokeを使用してください。MSD Task06 Lung Tumorの再現には--sanityを使用してください。
• Task06の参照情報、出力フィールドの定義、または手動でのバンドルセットアップに関する注意事項が必要な場合にのみ、references/task06-and-results.mdを読んでください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/run_finetune.py	skill_manifest.yamlで宣言された主要なエントリーポイントです。設定をステージングし、MONAIを実行して、output.jsonを書き出します。	[FIXTURE_OR_DATASET] --output-dir OUT_DIR [--smoke] [--sanity] [--auto-seg] [--dataset-dir DIR] [--datalist JSON] [--target-anatomy TEXT] [--label-mapping JSON] [--patch-size JSON]

前提条件

• GPUで実行する場合は、CUDA対応のTorchを備えたPython 3.10以降が必要です。
• skill_manifest.yamlに記載されたランタイムパッケージ。特に、monai==1.4.0、numpy<2、nibabel、scipy、typer、PyYAML、fire、pytorch-ignite、einops、huggingface_hubが必要です。
• オプションの環境変数：CUDA_VISIBLE_DEVICESは使用可能なGPUを制限します。NPROC_PER_NODEはGPU数を上書きし、2以上の値を指定すると、sanity以外の実行でマルチGPUモードが選択されます。
• 副作用：skills/nv-segment-ct-finetune/bundle/configs/以下に生成されたバンドル設定を書き込みます。これにはskills/nv-segment-ct-finetune/bundle/configs/auto_override.json、skills/nv-segment-ct-finetune/bundle/configs/train_continual_task06_lung.json、skills/nv-segment-ct-finetune/bundle/configs/dfw_no_logging.jsonが含まれます。チェックポイントとエビデンスを--output-dir以下に書き込み、モデルアセットを~/.cache/huggingface/以下にキャッシュすることがあります。また、https://huggingface.coまたはhttps://raw.githubusercontent.comに接続することがあります。

新規環境のセットアップ：

python -m pip install "monai==1.4.0" "numpy<2" pytorch-ignite einops nibabel scipy typer PyYAML fire huggingface_hub

既知の上流互換性に関する制約：

• DFW Task06の参照環境：Python 3.10.16、MONAI 1.4.0、Torch 2.7.0+cu126。
• スモークテスト、sanity、エビデンスの実行には、正確にmonai==1.4.0を使用してください。MONAI 1.5.xでは、ブール値ラベルが原因で上流のファインチューニング損失関数がクラッシュすることがあります。
• 生成されるコマンドで、依存関係をmonai>=1.4,<1.6と幅のある範囲にしないでください。

使用方法

スモークテスト規模のワークフローチェック：

python -m pip install "monai==1.4.0" "numpy<2" pytorch-ignite einops nibabel scipy typer PyYAML fire huggingface_hub && \
python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  PATH_TO_DATASET \
  --smoke \
  --patch-size '[64,64,64]' \
  --output-dir runs/nvseg_smoke

ステージング済みのデータセットをPATH_TO_DATASETとして使用してください。マイクロフィクスチャには、skills/nv-segment-ct-finetune/fixtures/spleen_microを使用してください。スモークモードでは、配線、設定生成、チェックポイント読み込み、ランタイム互換性を確認します。品質基準を示すものではありません。

MSD Task06 Lung Tumorのsanity再現：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  /path/to/Task06 \
  --sanity \
  --output-dir runs/nvseg_task06_sanity

sanityプリセットは、シングルGPUのDFWレシピに従います。fold-0での検証、lung tumorに対するラベルマッピング[[1, 23]]、自動クラスプロンプトセグメンテーション、パッチ[128,128,128]、5エポックを使用し、トレーニング前後に元の間隔のconfigs/evaluate.jsonでスコアを評価します。参照値の期待範囲は、事前トレーニング済みDiceが約0.6697、トレーニングのベストDiceが約0.6905、ファインチューニング後の正式なDiceが約0.6836です。

ユーザーデータのファインチューニング：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  --dataset-dir /path/to/dataset \
  --datalist /path/to/datalist.json \
  --target-anatomy "lung tumor" \
  --auto-seg \
  --epochs 5 \
  --patch-size '[128,128,128]' \
  --output-dir runs/nvseg_user_finetune

ローカルのラベル値が独自のもの、または解剖学的構造の名前が曖昧な場合は、--label-mapping '[[1, 23]]'を使用してください。

例

ステージング済みの小規模データセットでスモークテストを実行：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  runs/with_vs_without_nv/_inputs/nv_segment_ct_finetune/input_dataset \
  --smoke \
  --patch-size '[64,64,64]' \
  --output-dir runs/nvseg_smoke

ローカルのMSDキャッシュでTask06 sanityを実行：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  .workbench_data/datasets/Task06_Lung \
  --sanity \
  --output-dir runs/nvseg_task06_sanity

データ契約

• 推奨レイアウト：dataset/imagesTr/*.nii.gz および dataset/labelsTr/*.nii.gz。
• ベース名によって、ラベルと画像が1対1で対応している必要があります。
• 対象ラベルの値がトレーニングラベルに含まれている必要があります。
• 患者単位で分割する場合は、データリストを使用してください。バンドルのデフォルトの fold は 0 なので、fold: 0 のエントリーが検証用、それ以外のすべてのフォールドがトレーニング用になります。
• トレーニングするすべての前景ラベルを、bundle/label_dict.json にある既存の VISTA3D グローバルクラス ID に対応付ける必要があります。このスキルでは新しいクラスを作成できません。

結果

まず、実行ディレクトリの output.json を確認してください。

• formal_pretrained_val_dice および formal_finetuned_val_dice：正式評価が有効な場合の、元の間隔における評価前後のスコアです。
• training_start_val_dice、val_dice_per_epoch、training_best_val_dice：トレーニング中の検証記録です。
• finetuned_ckpt_matches_pretrained_weights：val_at_start=true のときに発生する、エポック0のチェックポイントの落とし穴を検出します。
• recommended_ckpt：保持するチェックポイントです。最終エポックや model_finetune.pt をそのまま使用しないでください。
• runtime.oom、runtime.peak_gpu_mb、およびフェーズログ：OOM、検証の遅延、プロセスの失敗を区別するのに役立ちます。

判断基準：正式評価の元の間隔における前後のスコアがある場合は、そちらを優先してください。健全性回復では、テンソルが同一の「ファインチューニング済み」チェックポイントを却下してください。improved: false はラッパーの失敗ではなく、有効な証拠として扱ってください。

制限事項

• 薄いラッパーです。トレーニング、検証、変換、チェックポイントの保存は bundle/ 内の上流バンドルに委譲されます。
• 自動導出されるプランはヒューリスティックです。呼び出し側が指定する --patch-size、--cache-rate、--epochs、--learning-rate が優先されます。
• Task06 の健全性確認用レシピでは、DFW の参照設定に合わせてシングル GPU 実行を強制します。他のデータセットでマルチ GPU モードを使用するには、ホスト側の torchrun サポートが必要です。
• ペア検証ツールは CPU 専用で、証拠パックを監査します。GPU によるセグメンテーションを再実行するものではありません。
• 臨床導入、臨床解釈、自律診断、規制当局への申請には使用できません。

トラブルシューティング

エラー	原因	対処法
依存関係の不足またはインポートエラー	skill_manifest.yaml からのランタイムのずれ。	上記のパッケージをインストールするか、文書化されている環境を使用してください。
Task06 の事前学習済み Dice が低い	設定、チェックポイント、データ分割、または依存関係にずれがあります。	トレーニングのロジックを変更する前に、環境フィールドとステージングされた設定を比較してください。
model_finetune.pt が事前学習済みのものと一致する	val_at_start=true により、エポック0が最良として選択されました。	recommended_ckpt を使用してください。変更後のチェックポイントで正式評価の Dice が向上しない限り、健全性回復は失敗として扱ってください。
正式評価の Dice フィールドがない	正式評価に失敗したか、スキップされました。	eval_pretrained.log、eval_finetuned.log、metrics.csv を確認してください。
GPU のメモリ不足	パッチまたはキャッシュの設定が大きすぎます。	--patch-size を小さくする、--cache-rate を下げる、またはワーカー数を減らしてください。
検証ケースがない	データリストに fold: 0 がありません。	検証用のエントリーを少なくとも1つ指定してください。

検証

品質ゲートが重要な場合は、実装済みの検証ツールを実行してください。

python -m eval_engine.run_trusted skills/nv-segment-ct-finetune \
  --fixture skills/nv-segment-ct-finetune/fixtures/spleen_micro \
  --out runs/nvseg_trusted