nv-segment-ct-finetune

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

目的

• CT NIfTI ラベルを使用した NV-Segment-CT VISTA3D のスモークテストまたはデータセットのファインチューニングに使用します。上流の固定チャネル Softmax ワークフローと、オプションの MLflow トラッキングを含みます。臨床検証には使用しません。
• 上流の MONAI バンドルエントリーポイントをラップします。手書きのトレーニングコードや推論コードに置き換えないでください。
• マニフェストの入力は dataset_dir、datalist、target_anatomy、label_mapping、smoke、sanity、auto_seg、softmax、skip_formal_eval、mlflow_tracking_uri、mlflow_experiment_name、mlflow_run_name です。
• マニフェストの出力は 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 を使用してください。
• 以下の基準に従って、標準ワークフローと --softmax ワークフローのいずれかを選択してください。--softmax を --auto-seg または --sanity と組み合わせないでください。
• どちらのワークフローでも、トレーニングフェーズで MLflow を有効にするには --mlflow-experiment-name を設定してください。--mlflow-tracking-uri と --mlflow-run-name の指定には、実験名が必要です。正式な事前／事後評価には MLflow の認証情報は渡されません。
• Task06 の参考情報、出力フィールドの定義、またはバンドルの手動セットアップに関する注意が必要な場合にのみ、references/task06-and-results.md を参照してください。

ワークフローの選択

以下の条件をすべて満たす場合にのみ、--softmax を使用してください。

• 完全なクラスセットがトレーニング前にわかっており、推論リクエストごとに変わりません。
• ラベルは相互排他的です。各ボクセルは背景か、ちょうど1つの前景クラスのいずれかです。
• すべての前景データセットラベルが既存の VISTA3D クラス ID に対応し、従来型の固定チャネル出力が必要です。

ポイントプロンプトを引き続き使用する必要がある場合、推論時にクラスを動的に選択する場合、ラベルが重複する場合、または Task06 の --sanity による再現が必要な場合は、標準ワークフローを使用してください。

--label-mapping '[[1,3],[2,13]]' の場合、チャネル 0 は背景、チャネル 1 は VISTA3D クラス 3 で初期化されたデータセットラベル 1、チャネル 2 は VISTA3D クラス 13 で初期化されたデータセットラベル 2 を表します。生成された model_softmax.pt を上流の configs/inference_softmax.json で使用する場合は、エントリーとその順序を維持してください。nv-segment-ct と nv-segment-ctmr の推論スキルでは、現時点でこの固定チャネル推論パスは公開されていません。

利用可能なスクリプト

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

前提条件

• 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 が必要です。MLflow トラッキングを有効にする場合は、mlflow>=2.10,<4 をインストールしてください。
• オプションの環境変数：CUDA_VISIBLE_DEVICES は認識される GPU を制限します。NPROC_PER_NODE は GPU 数を上書きし、値が >=2 の場合、sanity 以外の実行ではマルチ GPU モードが選択されます。NVSEG_FINETUNE_AUTO_VENV=0 は、キャッシュされた MONAI 1.4 互換環境を無効にします。リモートトラッキングでは、DATABRICKS_CONFIG_PROFILE、DATABRICKS_HOST、DATABRICKS_TOKEN、MLFLOW_TRACKING_CLIENT_CERT_PATH、MLFLOW_TRACKING_INSECURE_TLS、MLFLOW_TRACKING_PASSWORD、MLFLOW_TRACKING_SERVER_CERT_PATH、MLFLOW_TRACKING_TOKEN、MLFLOW_TRACKING_USERNAME を使用する場合があります。これらの変数は MLflow が明示的に有効にされた場合にのみ引き渡され、無関係な認証情報は引き渡されません。
• --softmax には、ピン留めされた NVIDIA-Medtech のソースチェックアウトも必要です。NV_SEGMENT_CT_ROOT にその NV-Segment-CT ディレクトリを設定するか、NV_SEGMENT_CTMR_ROOT に隣接する NV-Segment-CTMR ディレクトリを設定してください。ラッパーは公式の softmax 設定と実装をそのまま読み込み、生成されたオーバーライドは --output-dir の下にのみ書き込みます。
• 実行出力：生成されたバンドル設定は skills/nv-segment-ct-finetune/bundle/configs/ の下に保存されます。これには auto_override.json、train_continual_task06_lung.json、dfw_no_logging.json が含まれます。チェックポイントとエビデンスは --output-dir の下に保存され、有効時にはローカルトラッキングデータが <output-dir>/mlruns に保存されます。
• 依存関係のキャッシュ場所：MONAI 互換パッケージは ~/.cache/nvidia-skills/venvs/nv-segment-ct-finetune-monai14/、モデルアセットは ~/.cache/huggingface/ に保存されます。これらは再利用可能なランタイムファイルであり、エージェントへの指示でも、別の実行を許可するものでもありません。互換環境のセットアップが承認されていない場合は、NVSEG_FINETUNE_AUTO_VENV=0 を設定してください。その場合は、呼び出し側が用意した互換環境を使用してください。
• ネットワークアクセス：モデルと設定のダウンロードでは https://huggingface.co および https://raw.githubusercontent.com を使用します。リモートトラッキングでは、明示的に有効化された場合に限り、呼び出し側が承認した MLflow または Databricks の送信先にのみ接続します。ラベル辞書のダウンロードでは、ピン留めされたソースホスト上の HTTPS を受け入れ、リダイレクトは拒否します。

新しい環境をセットアップする場合：

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

MLflow トラッキングを有効にする場合は、以下もインストールしてください：

python -m pip install "mlflow>=2.10,<4"

既知の上流互換性制約：

• DFW Task06 のリファレンス：Python 3.10.16、MONAI 1.4.0、Torch 2.7.0+cu126。
• smoke、sanity、エビデンスの実行では、正確に monai==1.4.0 を使用してください。MONAI 1.5.x では、ブール値ラベルが原因で上流のファインチューニング損失がクラッシュすることがあります。
• 生成されるコマンドで、依存関係を monai>=1.4,<1.6 にしないでください。
• 呼び出し側が上書きしない限り、softmax ワークフローでは上流のデフォルトである 100 エポックと学習率 1e-4 が維持されます。

--softmax 用のソースを一度だけセットアップする場合：

export NV_SEGMENT_CTMR_COMMIT=cb921f5c58837c0f42a713855d68b32af88e1cdd
export NV_SEGMENT_CTMR_CHECKOUT="$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5"
if [ ! -d "$NV_SEGMENT_CTMR_CHECKOUT/.git" ]; then
  git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git "$NV_SEGMENT_CTMR_CHECKOUT"
fi
git -C "$NV_SEGMENT_CTMR_CHECKOUT" checkout --detach "$NV_SEGMENT_CTMR_COMMIT"
export NV_SEGMENT_CT_ROOT="$NV_SEGMENT_CTMR_CHECKOUT/NV-Segment-CT"

使い方

スモークスケールのワークフローチェック：

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 の妥当性確認用再現：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  /path/to/Task06 \
  --sanity \
  --output-dir runs/nvseg_task06_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]]' を使用します。

任意のローカル MLflow トラッキング：

python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  --dataset-dir /path/to/dataset \
  --datalist /path/to/datalist.json \
  --target-anatomy "lung tumor" \
  --epochs 5 \
  --mlflow-experiment-name nvseg-finetune \
  --mlflow-run-name trial-01 \
  --output-dir runs/nvseg_mlflow

これは、MONAI のドキュメントに記載された --tracking mlflow の経路と組み込みの rank-zero ハンドラーを使用します。--mlflow-tracking-uri を指定しない場合、データは <output-dir>/mlruns に保存されます。Databricks を含む、呼び出し元が承認したリモート URI は、リモートトラッキングを意図する場合に限り渡してください。MLflow によって、パッチサイズ、変換、オプティマイザーの値、DataLoader の設定、その他のトレーニング設定が変わることはありません。

相互排他的なラベルに対する固定チャネルの softmax ファインチューニング：

export NV_SEGMENT_CT_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Segment-CTMR-cb921f5/NV-Segment-CT"
python skills/nv-segment-ct-finetune/scripts/run_finetune.py \
  --dataset-dir /path/to/dataset \
  --datalist /path/to/datalist.json \
  --label-mapping '[[1,3],[2,13]]' \
  --softmax \
  --epochs 100 \
  --output-dir runs/nvseg_softmax

これは、上流の configs/train_continual_softmax.json に処理を委譲します。checkpoints/model_softmax.pt が生成されます。元の model.pt はネットワークの初期化には使われますが、configs/inference_softmax.json とは互換性がありません。そのため、ラッパーは実行が正常に完了した後、生成された softmax チェックポイントを推奨します。

使用例

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

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 の妥当性確認を実行：

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。
• ベース名で、ラベルと画像が一対一に対応している必要があります。
• 対象のラベル値がトレーニングラベルに含まれている必要があります。
• 患者単位の分割が重要な場合は、datalist を使用します。バンドルのデフォルトの fold は 0 です。そのため、fold: 0 のエントリーは検証用、その他の fold はすべてトレーニング用です。
• トレーニングするすべての前景ラベルは、bundle/label_dict.json にある既存の VISTA3D グローバルクラス ID にマッピングする必要があります。このスキルでは新しいクラスを作成できません。
• --softmax モードでは、マッピングの最初の列が保存されるデータセットラベル、2 番目の列が事前学習済み VISTA クラス 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 のチェックポイント問題を検出します。softmax では異なるチェックポイントアーキテクチャが使われます。
• recommended_ckpt：記録されたワークフローとメトリクスから導かれたチェックポイントの推奨。チェックポイントを選択する前に、これらの記録を確認してください。最終エポックやファイル名だけでは、改善した証拠になりません。推奨内容を呼び出し元に報告してください。デプロイはこのスキルの対象外です。
• invocation.mlflow_tracking：選択したトラッキング URI、実験名、任意の実行名。トラッキングが無効の場合は null。
• runtime.oom、runtime.peak_gpu_mb、およびフェーズログ：OOM、検証の遅延、プロセスの失敗を区別します。

判定ルール：正式な元の間隔での実行前後のスコアがある場合は、それを優先します。妥当性確認でテンソルが完全に同一の「ファインチューニング済み」チェックポイントは不採用とします。improved: false は有効な証拠として扱い、ラッパーの失敗とは見なしません。

制限事項

• 薄いラッパーです。トレーニング、検証、変換、チェックポイントの保存は、上流バンドルの bundle/ に委任されます。
• テンソルの比較では、制限付きの weights_only=True チェックポイント読み込みを使用します。サポートされていないシリアライズ済みオブジェクトがあると比較エラーになり、制限のない pickle 読み込みで再試行することはありません。この比較は、上流のトレーニング／チェックポイントローダーのセキュリティ監査ではありません。
• 再現記録のみ：成功した5エポックの Task06 実行では、NVIDIA RTX 6000 Ada 48 GB GPU 1基で、Python 3.12.3、CUDA 13.0 対応の PyTorch 2.12.0+cu130、MONAI 1.4.0、NumPy 1.26.4、PyTorch-Ignite 0.5.4、NiBabel 5.4.2、SciPy 1.16.0、einops 0.8.2、Fire 0.7.1、Hugging Face Hub 0.36.2、Transformers 4.57.6、 Typer 0.25.1、PyYAML 6.0.3、MLflow 3.14.0 を使用しました。これらのバージョンは検証環境を示すものであり、追加のパッケージ制約ではありません。また、ほかのバージョンでは動作しないという主張でもありません。
• 自動導出されるプランはヒューリスティックです。呼び出し側が指定した --patch-size、--cache-rate、--epochs、--learning-rate が優先されます。
• --softmax と --sanity は併用できません。Task06 の参照スコアと元の間隔での事前／事後評価は、標準の VISTA3D 継続学習ワークフローに対応しています。Softmax 実行ではトレーニングの検証推移が記録されますが、品質を主張するには、タスク固有の評価を別途行う必要があります。
• Task06 の sanity レシピでは、DFW の参照結果に合わせるため、意図的に単一 GPU での実行を強制します。ほかのデータセットでマルチ GPU モードを使うには、ホスト側で torchrun をサポートする必要があります。
• ペア検証ツールは CPU のみで動作し、エビデンスパックを監査します。GPU によるセグメンテーションを再実行するものではありません。
• MLflow のサポートはオプションで、MONAI に組み込まれたトラッキングハンドラーを使用します。トラッキングエラーは上流の MONAI 実行の一部であるため、ファインチューニングコマンドが失敗する場合があります。
• 臨床導入、臨床的解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
依存関係の不足またはインポートエラー	skill_manifest.yaml に記載された環境とのずれです。	上記のパッケージをインストールするか、記載された環境を使用してください。
Task06 の事前学習済み Dice が低い	設定、チェックポイント、データ分割、または依存関係が想定と異なります。	トレーニングロジックを変更する前に、環境フィールドとステージング済みの設定を比較してください。
model_finetune.pt が事前学習済みモデルと一致する	val_at_start=true により、エポック 0 が最良として選択されました。	recommended_ckpt を使用してください。変更後のチェックポイントで正式な Dice が改善しない限り、sanity の回復は失敗として扱ってください。
正式な Dice フィールドがない	正式な評価に失敗したか、スキップされました。	eval_pretrained.log、eval_finetuned.log、metrics.csv を確認してください。
GPU のメモリ不足	パッチまたはキャッシュの設定が大きすぎます。	--patch-size を小さくするか、--cache-rate を下げるか、ワーカー数を減らしてください。
検証ケースがない	データリストに fold: 0 がありません。	検証用エントリーを少なくとも1つ指定してください。
--softmax requires the pinned ... checkout	8月版の Softmax 設定／実装が存在しないか、チェックアウトが別のコミットになっています。	cb921f5c58837c0f42a713855d68b32af88e1cdd をチェックアウトし、NV_SEGMENT_CT_ROOT または NV_SEGMENT_CTMR_ROOT を設定してください。
MLflow のトラッキングに失敗する	MLflow がない、認証情報が無効、または実験にアクセスできません。	finetune.log を確認し、MLflow クライアントの設定を修正して再実行してください。トラッキングを無効にするには --mlflow-experiment-name を省略してください。

検証

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

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