nv-generate-mr-brain

NV-Generate-MR-Brain

目的

• NV-Generate-CTMR rflow-mr-brain v1 を使用して、合成 T1、T2、FLAIR、SWI、または MRA 脳 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 コマンドを実行してください。
• コマンド形式の確認では、パッケージのインストール、リポジトリのクローン、重みのダウンロード、GPU 推論の開始は行わないでください。指定された設定パスに加え、明示的な --output-dir、--modality、--random-seed の値を指定した、正確なラッパーコマンドのみを出力してください。
• 実行する場合は、単一の bash コードブロックを出力し、python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" の手順を同じコマンド内に含めてください。実行環境は nibabel／MONAI がない新しい環境の場合があるため、インストール手順を省くと ModuleNotFoundError が発生します。
• --modality mri_mra を選択した場合は、上流の報告によると MRA のトレーニング範囲は限定的で、出力品質は保証されないことを明記してください。
• rm、mkdir、または --output-dir のクリーンアップを追加しないでください。ディレクトリはラッパーが作成します。既存のものを削除するのではなく、新しい --output-dir を使用してください。
• 実行結果の証拠として扱う前に、出力された JSON と、対応する検証ガイダンスを確認してください。

例

コマンド形式の確認のみ（セットアップや実行は行いません）：

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

実行する場合は、使用方法 に記載されているセットアップ対応コマンドを使用してください。

利用可能なスクリプト

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

前提条件

• 実行時の要件：マニフェストで指定されている場合は GPU/CUDA、runtime.side_effects.pip_packages に記載された Python パッケージ。
• 副作用：生成された出力を呼び出し元の --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:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
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 には、ユーザーが指定したリクエストパスを設定する必要があります。

前提条件

NV_GENERATE_ROOT が既存のローカルチェックアウトを指している場合、ラッパーはそれを使用し、結果に現在のコミットを記録します。それ以外の場合は、推奨されるコミットに固定されたデフォルトのチェックアウトを一度作成してください。

if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=da438fec6484cdb6f421f8c7051d954ebefff730
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe"
  if [ ! -d "$NV_GENERATE_ROOT/.git" ]; then
    git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git "$NV_GENERATE_ROOT"
    git -C "$NV_GENERATE_ROOT" checkout --detach "$NV_GENERATE_COMMIT"
  fi
fi
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

ラッパーは、NV_GENERATE_ROOT がマニフェストのコミットと完全に一致し、追跡対象ファイルに変更がない場合にのみ、上流のコードを実行します。モデルの重みは models/ 配下で追跡対象外として保持し、上流の設定を編集する代わりに、ラッパー用の上書き JSON を使用してください。子プロセスに渡されるのは、実行環境、CUDA、ロケール、証明書の変数の許可リストに含まれるものだけです。API キー、トークン、パスワード、および無関係な親プロセスの環境変数は引き継がれません。

再利用するオートエンコーダーと MR-Brain v1 チェックポイントは、マニフェストで指定された正確なリビジョンからダウンロードしてください。

python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-CT models/autoencoder_v1.pt \
  --revision 75ac080fb1083c403793563477724c038e7d430c \
  --local-dir "$NV_GENERATE_ROOT"
python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-MR-Brain models/diff_unet_3d_rflow-mr-brain_v1.pt \
  --revision ef9759bf221265b2704569cdeeac20bbf03b62ee \
  --local-dir "$NV_GENERATE_ROOT"

ラッパーは、推論を開始する前に、ダウンロードした両方のファイルを、公開されている Git LFS の SHA-256 オブジェクト ID と照合して検証します。

実行には、少なくとも 16 GB の VRAM を搭載した 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:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
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 脳モダリティ名は、mri、mri_t1、mri_t2、 mri_flair、mri_mra、mri_swi、mri_t1_skull_stripped、 mri_t2_skull_stripped、mri_flair_skull_stripped、 mri_mra_skull_stripped、mri_swi_skull_stripped です。これらは README に記載されている、上流の configs/modality_mapping.json の ID に対応します。 FOV とセットアップの詳細については、references/fov-and-downloads.md を参照してください。

固定された v1 設定には、軸位 T1w のデフォルト値として dim=[256,256,128]、 spacing=[0.94,0.94,1.36]、推論ステップ数 30、 cfg_guidance_scale=2 が設定されています。モデル固有の検証によって上書きが正当化されない限り、ステージングされた設定値を維持してください。古い例では v0 の 256^3／1 mm のジオメトリや、ガイダンススケール 10 が記載されていることがあります。MRA は v1 でサポートされていますが、上流のトレーニングデータのレポートに含まれる MRA スキャンは少ないため、出力品質は保証されません。

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

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

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