nv-generate-mr-brain

NV-Generate-MR-Brain

目的

• NV-Generate-CTMR の rflow-mr-brain を使用して、合成脳 MRI ボリュームを生成します。本番環境の学習データには使用しないでください。
• ラッパーはドキュメントに記載されたとおりに使用してください。アップストリームのエントリーポイントを手書きの実装に置き換えないでください。
• 通常の実行では、独自の推論コードを書かないでください。設定のステージング、出力パス、検証はラッパーが担当します。
• マニフェスト I/O：入力は model_config_override、出力は synthetic_mr_brain_volumes と result_json です。

手順

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

利用可能なスクリプト

スクリプト	目的	引数
scripts/run_mr_brain.py	skill_manifest.yaml で宣言されたプライマリエントリーポイントです。	MODEL_CONFIG.json --output-dir OUT_DIR --modality mri_t1 [--random-seed N] [--yes]

前提条件

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

制限事項

• これは薄いラッパーです。推論、サンプリング、デコーディングはすべて NVIDIA-Medtech/NV-Generate-CTMR の scripts.diff_model_infer に委譲されます。$NV_GENERATE_ROOT 以下のコードや、リポジトリ内のフォールバックである .workbench_data/upstreams/NV-Generate-CTMR は変更しないでください。
• rflow-mr-brain は画像のみの合成脳 MRI ボリュームを生成します。対応するセグメンテーションマスクは出力しません。
• 出力ボリュームは合成データです。独立した品質レビューなしに、本番環境の医療技術モデルの学習データとして安全に使用することはできません。
• 臨床展開、臨床解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

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

アップストリームの NVIDIA-Medtech/NV-Generate-CTMR による、MR 脳画像のみの生成ワークフローをラップします。このラッパーは、拡散サンプリングやオートエンコーダーのデコーディングを再実装しません。設定の上書きをステージングし、rflow-mr-brain 用にドキュメントに記載された python -m scripts.diff_model_infer コマンドを実行した後、生成された NIfTI ボリュームを要約します。

実行可能なインターフェース

ユーザーが実行するコマンドでは、リポジトリのルートを基準とした次のラッパーパスをそのまま使用してください。

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py PATH_TO_MR_BRAIN_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 1234

generate.sh、infer.py、Medical AI Skills run、または python -m nv_generate_mr_brain コマンドをでっち上げないでください。PATH_TO_MR_BRAIN_CONFIG.json には、ユーザーが指定したリクエストパスを使用してください。

前提条件

上流リポジトリを一度クローンしてインストールしてください。この Medical AI Skills のチェックアウトでは、存在する場合はリポジトリ内のキャッシュパスを優先してください。

mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Generate-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git \
    .workbench_data/upstreams/NV-Generate-CTMR
export NV_GENERATE_ROOT=.workbench_data/upstreams/NV-Generate-CTMR
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

MR-brain の重みをダウンロードしてください。

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr-brain --root_dir ./ --model_only

実行時には、VRAM が 16 GB 以上の NVIDIA GPU が必要です。上流の実行経路には CPU フォールバックはありません。

NV_GENERATE_ROOT が未設定の場合、または古いクローンを指している場合、ラッパーは .workbench_data/upstreams/NV-Generate-CTMR も検索します。

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

使用方法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234

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

サポートされている MR-brain のモダリティ名は、mri、mri_t1、mri_t2、mri_flair、mri_swi、mri_t1_skull_stripped、mri_t2_skull_stripped、mri_flair_skull_stripped、mri_swi_skull_stripped です。これらは、README に記載されている上流の configs/modality_mapping.json の ID に対応します。 FOV とセットアップの詳細については、references/fov-and-downloads.md を参照してください。

フィクスチャ引数は、configs/config_maisi_diff_model_rflow-mr-brain.json に対する小規模な JSON オーバーライドです。上流のデフォルト値に CLI のモダリティとランダムシードを適用するには、default を指定してください。一般的なオーバーライドキーは dim、spacing、num_inference_steps、cfg_guidance_scale、modality です。

各実行では、ステージングされた設定、モデルの一覧、上流コマンド、出力のジオメトリ、間隔、アフィン変換、強度範囲、およびデータが非定数かつ有限であることのチェックが記録されます。出力ボリュームは合成データであり、独立したレビューなしに本番のトレーニングデータとして使用するのは安全ではありません。

臨床的な解釈、本番環境へのデプロイ、自律的な診断、または規制当局への申請には使用しないでください。