nv-segment-ct

NV-Segment-CT

目的

• CT NIfTI ボリュームに対して NV-Segment-CT VISTA3D を実行し、ラベルマップのエビデンスを記録するために使用します。臨床的解釈には使用しません。
• ラッパーは文書に記載されたとおりに使用してください。アップストリームのエントリーポイントを手書きの実装に置き換えないでください。
• マニフェストの入出力：入力は ct_volume、出力は label_map と result_json です。

手順

• 引数、副作用、検証ゲートを変更する前に、skill_manifest.yaml を読んでください。
• 以下に記載されたコマンドで scripts/run_vista3d.py を実行し、出力は呼び出し元が指定する実行ディレクトリに保存してください。
• ホストエージェントが run_script を公開している場合は、run_script("scripts/run_vista3d.py", args=[...]) を使用してください。それ以外の場合は、以下に示す Bash/Python コマンドを実行してください。
• 実行結果をエビデンスとして扱う前に、出力された JSON と、対応する検証ガイダンスを確認してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/run_vista3d.py	skill_manifest.yaml で宣言されている主要エントリーポイントです。	PATH_TO_CT.nii.gz [--output-dir OUT_DIR] [--label-prompts IDS]

前提条件

• 実行時要件：マニフェストに記載がある場合は GPU/CUDA が必要です。Python パッケージは runtime.side_effects.pip_packages に記載されています。
• 副作用：ダウンロードしたバンドルを skills/nv-segment-ct/bundle/ に書き込み、モデルアセットを ~/.cache/huggingface/ にキャッシュする場合があります。また、初回セットアップ時に https://huggingface.co へ接続する場合があります。任意の脾臓フィクスチャ取得スクリプトは、MSD09 を https://msd-for-monai.s3-us-west-2.amazonaws.com からダウンロードします。
• 以下の既存セクションに別途記載がない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• これは薄いラッパーです。推論、前処理、後処理はすべて、bundle/ 内の公式 hugging_face_pipeline.HuggingFacePipelineHelper に委譲されます。bundle/ 内のコードを変更しないでください。
• transformers は 4.x リリースである必要があります。HF モデルコードは 5.x より前のイディオム（例：_tied_weights_keys）を使用しています。
• デバイスは自動検出されます（利用可能な場合は cuda、それ以外は cpu）。--device フラグで上書きできます。
• 出力はスキーマ上有効でも、意味的には空の場合があります（例：入力の解剖学的構造に一致しないラベルプロンプト）。健全性ゲートでは、要求された各解剖学的構造について、前景ボクセルが少なくとも 1 つあることを確認します。
• 臨床導入、臨床的解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

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

アップストリームの nvidia/NV-Segment-CT ヘルパーをラップします。ラッパーは VISTA3D の推論を再実装しません。

正確に実行可能な方法

CT セグメンテーションを実行する場合は、リポジトリのルートにある以下のラッパーパスをそのまま使用してください。

python skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz --label-prompts "1,3,5,14" --output-dir OUT_DIR

infer.py、Medical AI Skills run、python -m nv_segment_ct、または解剖学的名称だけのフラグを作らないでください。脾臓、肝臓、右腎臓、左腎臓には、必須の VISTA3D ラベル ID として 1,3,5,14 を正確に指定してください。

前提条件

このスキルは、ランタイム依存関係が事前インストールされていない Python 3.12 環境を想定しています。文書に記載されたコマンドが必要なものをすべてインストールします。 固定された依存関係の一覧は requirements.txt にあります。

1 回限りのダウンロードが 2 つあります（1 つ目は文書に記載されたコマンドで実行されます。フィクスチャの取得は別の手順であり、初期セットアップ時に実行します）。

# Spleen example fixture from Decathlon MSD09 (~1.5 GB tar, ~11 MB
# fixture extracted into skills/nv-segment-ct/fixtures/spleen_03.nii.gz):
python skills/nv-segment-ct/fixtures/fetch_spleen_fixture.py

どちらのダウンロード（以下のバンドルとフィクスチャ）も gitignore の対象です（Medical AI Skills のポリシーにより、医療データやモデルの重みを git に含めません）。取得スクリプトは冪等であり、tar を .workbench_data/datasets/ にキャッシュするため、再実行しても何も行われません。

実行時には、CUDA を使用できる NVIDIA GPU が必要です。CPU へのフォールバックもサポートされていますが、低速です。

使用方法

Medical AI Skills リポジトリのルートから、手順をすべて単一のコマンドで実行すると、新しい Python 3.12 venv に対してスキルが自動的にセットアップされます。

pip install -r skills/nv-segment-ct/requirements.txt && \
huggingface-cli download nvidia/NV-Segment-CT \
  --local-dir skills/nv-segment-ct/bundle/ && \
python skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz \
  --label-prompts "1,3,5,14" \
  --output-dir vista3d_outputs

ユーザーが解剖部位を指定した場合は、実行前に VISTA3D クラス ID に変換してください。一般的な腹部 CT のリクエストの場合：

解剖部位	VISTA3D クラス ID
肝臓	1
脾臓	3
右腎臓	5
左腎臓	14

「脾臓、肝臓、右腎臓、左腎臓をセグメント化する」の場合、正しい --label-prompts の値は厳密に "1,3,5,14" です。別のラベル辞書にある腎臓の ID に置き換えないでください。このラッパーは指定されたラベルセットを検証し、出力されたマスクに指定セット外のラベルが含まれている場合、実行を無効と判定します。

pip install の手順は必須です。アクティブな環境に monai/torch などがすでにインストールされているとは想定しないでください。huggingface-cli download の手順も仕様の一部です。この手順では約 832 MB のモデルバンドルを skills/nv-segment-ct/bundle/ にダウンロードします（初回実行後はキャッシュされ、以降の呼び出しでは何も行われません）。

label-prompts は VISTA3D クラス ID です。エビデンス出力には、入力ジオメトリ、出力マスクのパス、確認されたラベル ID、想定外のラベル、クラスごとのボクセル数、出力マスクヘッダーの間隔から計算されたクラスごとの物理体積、実行時間、モデルの識別情報、およびマスクの形状、アフィン変換の一致、ラベルセット、前景ピクセル数、クラス体積の範囲など、コードから固定的に導出される成果物のチェック結果が記録されます。

--ground-truth PATH を渡すと、参照ラベルマップのパスが input.ground_truth_path に記録されます。このスキルは Dice を計算しません。計算はペアの検証ツールが行います。

解剖学的な妥当性（クラスごとの体積範囲、断片化、左右対称性、肝臓が脾臓より大きいこと）と、任意で記録済みのグラウンドトゥルースに対するクラスごとの Dice/IoU を、verifiers/ct_segmentation_quality_v1 がチェックします。

臨床的な解釈、本番環境へのデプロイ、または CT 以外のモダリティには使用しないでください。