nv-generate-mr

NV-Generate-MR

目的

• NV-Generate-CTMR の rflow-mr を使用して、合成ボディ MRI ボリュームを生成します。ペアのマスクや、本番環境でのトレーニングデータには使用しないでください。
• ラッパーはドキュメントに記載されたとおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• 通常の実行では、カスタムの推論コードを書かないでください。設定のステージング、出力パス、検証はラッパーが担当します。
• マニフェスト I/O：入力は 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 Non-Commercial として記載されています。法務および品質のレビューなしに、出力を本番環境でのトレーニングデータとして使用しないでください。
• 臨床導入、臨床的解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
依存関係が不足している、またはインポートエラーが発生する	実行時パッケージが 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:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
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 には、ユーザーが指定したリクエストのパスを指定する必要があります。

前提条件

アップストリームリポジトリを一度クローンしてインストールします。この 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 の重みをダウンロードします。

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr --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/scripts/run_mr.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/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 オーバーライドです。default を指定すると、アップストリームのデフォルトに CLI のモダリティとランダムシードを適用して使用します。一般的なオーバーライドキーは dim、spacing、num_inference_steps、cfg_guidance_scale、modality です。

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

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