nv-generate-ct-rflow

NV-Generate-CT（rflow-ct）

目的

• NV-Generate-CTMR rflow-ct を使用して、合成 CT ボリュームとマスクを生成します。レビューなしで本番環境のトレーニングデータに使用しないでください。
• ラッパーはドキュメントに記載されたとおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• 通常の実行では、カスタム推論コードを作成しないでください。設定のステージング、出力パス、ラベルマッピングの根拠、および検証はラッパーが管理します。
• マニフェスト I/O：入力は config_infer_override、出力は synthetic_ct_volumes と result_json です。

手順

• 引数、副作用、または検証ゲートを変更する前に、skill_manifest.yaml を読んでください。
• 以下に記載されたコマンドを使用して scripts/run_rflow_ct.py を実行してください。出力は呼び出し元から指定された実行ディレクトリの下に保持してください。
• ホストエージェントで run_script を利用できる場合は、run_script("scripts/run_rflow_ct.py", args=[...]) を使用してください。それ以外の場合は、以下に示す Bash/Python コマンドを実行してください。
• 単一の bash コードブロックを出力し、python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" の手順を同じコマンド内に含めてください。実行環境が nibabel／MONAI のない新規環境の場合があるため、インストールを省略すると ModuleNotFoundError が発生します。
• rm、mkdir、または --output-dir のクリーンアップを追加しないでください。ラッパーが出力ディレクトリを作成します。既存のディレクトリを削除する代わりに、新しい --output-dir を使用してください。
• 実行結果を根拠として扱う前に、出力された JSON と、対応する検証ガイダンスを確認してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/_anatomy.py	主エントリーポイントで使用される内部ヘルパーです。	インポート専用。直接呼び出さないでください。
scripts/_summary_card.py	主エントリーポイントで使用される内部ヘルパーです。	インポート専用。直接呼び出さないでください。
scripts/list_anatomies.py	カタログまたは解剖部位の検索に使用するヘルパーコマンドです。	[--region REGION] [--filter TEXT] [--controllable]
scripts/run_rflow_ct.py	skill_manifest.yaml で宣言された主エントリーポイントです。	CONFIG_INFER.json --output-dir OUT_DIR [--random-seed N] [--version rflow-ct] [--yes]
scripts/run_ct_mask.py	スタンドアロンの raw MAISI マスク生成に使用する、高度な診断ヘルパーです。	REQUEST.json --output-dir OUT_DIR [--random-seed N] [--preflight-only] [--yes]
scripts/run_ct_from_mask.py	MAISI ラベルマスクから CT 画像を生成するための高度なヘルパーです。	REQUEST.json --output-dir OUT_DIR [--random-seed N] [--yes]
scripts/run_ct_image.py	対応するラベルなしで CT 画像のみを生成するための高度なヘルパーです。	MODEL_CONFIG.json --output-dir OUT_DIR [--version rflow-ct] [--random-seed N] [--yes]

前提条件

• 必須の環境変数：NV_GENERATE_ROOT。
• 実行時の要件：マニフェストで宣言されている場合は GPU/CUDA、runtime.side_effects.pip_packages に記載された Python パッケージ。
• 副作用：生成した出力を呼び出し元の --output-dir の下に書き込みます。モデルアセットを ~/.cache/huggingface/ にキャッシュする場合があり、セットアップ中に https://huggingface.co または https://github.com に接続する場合があります。
• 以下の既存のセクションで別途指定されていない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• これは薄いラッパーです。推論、サンプリング、デコードはすべて NVIDIA-Medtech/NV-Generate-CTMR の scripts.inference に委譲されます。$NV_GENERATE_ROOT の下にあるコードを変更しないでください。
• rflow-ct には CUDA が必要であり、デフォルトの 256³ output_size では最低でも約 16 GB の VRAM が必要です。より大きな output_size（例：512×512×768）には A100/H100 が必要です。
• 出力ボリュームは合成データです。独立した品質レビューなしで、本番環境の医療技術モデルのトレーニングデータとして使用しないでください。
• 臨床導入、臨床的解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
依存関係の不足またはインポートエラー	skill_manifest.yaml の実行時パッケージとの不整合です。	マニフェストに記載されたパッケージをインストールするか、文書化されたセットアップコマンドを使用してください。
出力が空、またはスキーマが無効	入力パスの誤り、サポートされていないモダリティ、または上流での失敗です。	既知のフィクスチャを使って再実行し、ラッパーの JSON と stderr を確認してください。
検証ゲートの失敗	出力が宣言されたエンジニアリング上の不変条件に違反しています。	失敗したエビデンスパックを保持し、ゲートメッセージを参考に入力またはラッパーコードを修正してください。

上流の NVIDIA-Medtech/NV-Generate-CTMR の rectified-flow 合成パイプラインをラップしています。このラッパーは拡散、 サンプリング、自動エンコーダーのデコードを再実装せず、プロジェクトの README に記載されたとおりに 上流の scripts.inference エントリーポイントをシェル経由で呼び出し、 生成された画像／マスクのペアを検査します。

前提条件

1. 上流リポジトリをクローンし、NV_GENERATE_ROOT をその場所に設定します（一度だけ）。

   test -d "$HOME/nv-generate-ctmr/.git" || \
     git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git $HOME/nv-generate-ctmr
   export NV_GENERATE_ROOT=$HOME/nv-generate-ctmr
   pip install -r "$NV_GENERATE_ROOT/requirements.txt"
   

2. rflow-ct の重みとマスク候補データセットを クローン内にダウンロードします（一度だけ、約 5.5 GB）。

   cd "$NV_GENERATE_ROOT"
   python -m scripts.download_model_data --version rflow-ct --root_dir "./"
   

   マスク候補（datasets/all_masks_flexible_size_and_spacing_4000）は拡散サンプラーの 条件付けに使用されるため、--model_only で省略すると、 推論スクリプトは起動時にファイル不足エラーで失敗します。 解剖学的サイズの条件ファイルも CT の全データダウンロードに含まれており、 制御可能なマスク生成に必要です。

3. NVIDIA GPU（VRAM 16 GB 以上）と CUDA が必要です。CPU へのフォールバックはありません。

エージェントが生成するユーザー向け実行コマンドでは、「使用方法」にある短いラッパーコマンドを優先してください。NV_GENERATE_ROOT またはリポジトリ内の上流キャッシュがすでに存在する場合は、クローンやモデルのダウンロード手順を先頭に追加しないでください。新しい Python 環境では、アクティブな環境でインポートが利用可能であることがすでに確認されている場合を除き、ラッパーを実行する前に pip install -r "$NV_GENERATE_ROOT/requirements.txt" も含めてください。重みがキャッシュされていても、Python パッケージがキャッシュされているとは限りません。 ラッパーは medical-AI-skills リポジトリのルートから実行してください。セットアップで cd "$NV_GENERATE_ROOT" が必要な場合は、 skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py を呼び出す前に Medical AI Skills リポジトリに戻ってください。

使用方法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/nv-generate-ctmr}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
  PATH_TO_CONFIG_INFER.json \
  --output-dir runs/nv_generate_ct_rflow_demo \
  --random-seed 0 \
  --version rflow-ct

PATH_TO_CONFIG_INFER.json は、ユーザーの実際のリクエスト／設定ファイルの パスに置き換えてください。ユーザーがそのフィクスチャの実行を明示的に 求めていない限り、このドキュメントのフィクスチャパスをコピーしないでください。ユーザーが「ケースリクエストは runs/.../chest_lung_tumor_controllable.json にあります」と指定した場合、その正確なパスを scripts/run_rflow_ct.py の最初の位置引数に指定します。

フィクスチャ引数は config_infer.json の上書きファイルです。num_output_samples、body_region、anatomy_list、controllable_anatomy_size、output_size、spacing を置き換えられます。上流の設定をそのまま使うには default を渡してください。ラッパーは実行前に、上書き設定を上流のツリーに配置します。

フィクスチャカタログ

fixtures/ には、よく使われるペア合成のユースケース向けに厳選された設定が付属しています。胸部の肺葉、制御可能な肺腫瘍を含む胸部、腹部の実質臓器、制御可能な肝腫瘍を含む腹部、頭部＋頸椎、骨盤が含まれます。 表の全容は fixtures/README.md を参照してください。

ヘルパーコマンド

# Browse the 132-class label_dict grouped by body region.
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --region chest
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --controllable
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --filter tumor

# Validate a fixture and preview cost without launching inference.
NV_GENERATE_ROOT=$HOME/nv-generate-ctmr \
  python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
    skills/nv-generate-ct-rflow/fixtures/abdomen_liver_spleen.json \
    --output-dir runs/preview --preflight-only

高度なヘルパーは、このスキル内でデバッグやあまり一般的でないCT生成モードに使用します。ユーザーがそのモードを明示的に求めた場合にのみ使用してください。

# Raw MAISI mask diagnostic, useful for checking lung tumor -> label 23.
python skills/nv-generate-ct-rflow/scripts/run_ct_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_mask_lung_tumor.json \
  --output-dir runs/ct_mask_debug --preflight-only

# CT image from an existing MAISI label mask with body label 200.
python skills/nv-generate-ct-rflow/scripts/run_ct_from_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_from_mask_request_example.json \
  --output-dir runs/ct_from_mask_demo

# CT image-only generation without paired labels.
python skills/nv-generate-ct-rflow/scripts/run_ct_image.py \
  skills/nv-generate-ct-rflow/fixtures/ct_image_only_default.json \
  --output-dir runs/ct_image_only_demo --version rflow-ct

ラッパーは呼び出しのたびに（--preflight-only の指定にかかわらず）事前チェックを実行します。チェック項目は、設定スキーマの制約、上流の label_dict と照合した解剖学的名称、サポートされる値の集合に含まれる body_region、controllable_anatomy_size の制約、上流のCT出力サイズと間隔の仕様、体の部位を考慮した x/y FOV の最小値、$NV_GENERATE_ROOT/datasets/ 配下のデータセットの有無、CUDA が利用可能であること、推定ピークVRAM／実行時間です。推定実行時間が5分、またはピークVRAMが30 GBを超える実行を続行するには、--yes が必要です。

呼び出しのたびに python -m scripts.inference -t configs/config_network_rflow.json -i configs/config_infer.json -e configs/environment_rflow-ct.json --random-seed <s> --version rflow-ct を実行します。出力エビデンスには、上流の git コミット、モデルチェックポイントのハッシュ、レンダリングされた設定、サンプルごとの画像／マスクのジオメトリ、マスクのラベル集合、画像のHU範囲の概要、クラスごとのボクセル体積が記録されます。

controllable_anatomy_size が空でない場合、上流は保存されるペアのラベルマップに対して、より広範な anatomy_list を無視し、ラベルを制御対象の解剖学的名称に絞り込みます。保存されるペアのラベル値はローカルの 1..N の序数であり、元の MAISI ラベルIDではありません。保存された出力ラベルを元のラベルに対応付けるには、result_json の output.output_label_mapping を参照してください。たとえば、出力ラベル 1 は MAISI ラベル 23（lung tumor）を表す場合があります。 キュレーション済みの肺腫瘍の例では、制御可能なサイズをおよそ 0.5 以上にすることをおすすめします。0.2 などの小さな値を指定すると、シードによってはラベル23の成分が存在しないか、非常に小さくなることがあります。

FOV とセットアップの詳細については、references/fov-and-downloads.md を参照してください。高度なヘルパーのラベル空間の詳細については、references/ct-mask-label-space.md と references/ct-from-mask-format.md を参照してください。

ビジュアルサンプルカード

NIfTI のペアとともに、ラッパーは出力ディレクトリに summary.html を書き込みます。サンプルごとの中央スライスの三方向表示（軸位／冠状断／矢状断）にラベルを重ねて表示し、レンダリングされた設定と検証用の集計値を表にまとめます。3D Slicer を起動せずに結果を目視で確認できます。スキップするには --no-summary-card を渡してください。

解剖学的な妥当性（ラベル集合の整合性、CTとしてのボクセルHU範囲、画像／マスクのジオメトリの一致、宣言された出力ラベルの存在、肺葉のHU下限）は、verifiers/ct_synthesis_quality_v1 によってチェックされます。

臨床的な解釈、本番環境への展開に使用する学習データ、または合成研究以外の用途には使用しないでください。