nv-generate-mr

NV-Generate-MR

目的

• NV-Generate-CTMR の rflow-mr を使用して、合成ボディ MRI ボリュームを生成します。ペアのマスクや本番用のトレーニングデータには使用しないでください。
• ラッパーはドキュメントどおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• 通常の実行にカスタムの推論コードを書かないでください。設定の準備、出力パス、検証はラッパーが担当します。
• マニフェストの入出力：入力は model_config_override、出力は synthetic_mr_volumes と result_json です。

手順

• 引数、副作用、検証ゲートを変更する前に、skill_manifest.yaml を読んでください。
• 以下に記載されたコマンドを使用して scripts/run_mr.py を実行してください。出力は呼び出し元が指定した実行ディレクトリに保存してください。
• ホストエージェントが run_script を提供している場合は、run_script("scripts/run_mr.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.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 は画像のみの合成 MRI ボリュームを生成します。ペアのセグメンテーションマスクは出力しません。
• 上流の README では、脳 MRI 合成には代わりに rflow-mr-brain を推奨しています。この用途には skills/nv-generate-mr-brain を使用してください。
• NV-Generate-MR の重みは、上流で NVIDIA 非商用とされています。法務および品質の確認なしに、出力を本番用のトレーニングデータとして使用しないでください。
• 臨床導入、臨床的解釈、自律的な診断、規制当局への申請には使用しないでください。

トラブルシューティング

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

上流の NVIDIA-Medtech/NV-Generate-CTMR による、MR 画像のみの生成ワークフローをラップしています。ラッパーは拡散サンプリングやオートエンコーダーのデコードを再実装しません。設定のオーバーライドを準備し、rflow-mr 用のドキュメントに記載された python -m scripts.diff_model_infer コマンドを実行してから、生成された NIfTI ボリュームを要約します。

正確に実行できるコマンド

新しいベンチマーク環境でユーザーが実行するコマンドには、以下のセットアップとリポジトリルートのラッパーコマンドをそのまま使用してください。

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py PATH_TO_MR_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 0

generate.sh、infer.py、Medical AI Skills run、python -m nv_generate_mr などのコマンドを作り出さないでください。PATH_TO_MR_CONFIG.json は、ユーザーが指定したリクエストのパスである必要があります。

前提条件

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

if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=61c4ec709b84cad468852243c48e250bec732074
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7"
  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"

MR の重みをダウンロードします。

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

ランタイムには 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/scripts/run_mr.py を呼び出す前に Medical AI Skills リポジトリに戻ってください。

使用方法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py \
  PATH_TO_MR_CONFIG.json \
  --output-dir runs/nv_generate_mr_demo \
  --modality mri_t1 \
  --random-seed 0

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

サポートされている rflow-mr のモダリティ名は mri、mri_t1、mri_t2、mri_flair で、上流の MR 画像生成ガイドに対応しています。上流の README では、脳画像を合成する場合は代わりに rflow-mr-brain を推奨しています。その場合は skills/nv-generate-mr-brain を使用してください。 FOV とセットアップの詳細については、references/fov-and-downloads.md を参照してください。

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

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

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