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 コマンドを実行してください。
• ドキュメントに記載された Python 3.10 仮想環境を作成し、その環境のバイナリを直接呼び出してください。呼び出し元のアクティブな環境にはモデル依存関係をインストールしないでください。
• 実行を証拠として扱う前に、出力された JSON と対応する検証ガイダンスを確認してください。

利用可能なスクリプト

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

前提条件

• ランタイム要件：venv をサポートする Python 3.10、およびマニフェストで宣言されている場合は GPU／CUDA が必要です。モデルパッケージは固定された上流の要件ファイルから取得します。ローカルではラッパー固有のパッケージのみ追加されます。
• 副作用：隔離環境を ~/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51/ に作成し、ダウンロードした バンドルを skills/nv-segment-ct/bundle/ に書き込み、モデル資産を ~/.cache/huggingface/ にキャッシュする場合があります。また、初回セットアップ時に https://huggingface.co と https://raw.githubusercontent.com に接続する場合があります。任意の脾臓 フィクスチャ取得スクリプトは、MSD09 を https://msd-for-monai.s3-us-west-2.amazonaws.com からダウンロードします。
• 以下のセクションに別途記載がない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• これは薄いラッパーです。推論、前処理、後処理はすべて、bundle/ 内の公式 hugging_face_pipeline.HuggingFacePipelineHelper に委任されます。bundle/ 内のコードは変更しないでください。
• transformers==4.46.3 は、上流の要件に含まれる Torch 2.0.1 との互換性を確認したラッパー用オーバーレイです。より新しい Transformers リリースでは、この古い Torch バックエンドが無効になる場合があります。
• 固定された上流の要件には Torch 2.0.1 が含まれます。このレガシーな再現環境では、固定された NVIDIA モデル資産のみを使用してください。信頼できないチェックポイントは読み込まないでください。
• デバイスは自動検出されます（利用可能な場合は cuda、それ以外は cpu）。--device フラグで上書きできます。
• 出力はスキーマ上は有効でも、意味的に空の場合があります（例：入力の解剖構造に一致しないラベルプロンプト）。サニティゲートでは、要求された解剖構造ごとに少なくとも 1 つの前景ボクセルがあることを確認します。
• 臨床導入、臨床的な解釈、自律診断、規制当局への申請には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
環境の作成中に ensurepip is not available が発生する	ホストの Python インストールに OS の venv パッケージが含まれていません。	対応する Python 3.10 の venv サポートパッケージをインストールするか、virtualenv -p python3.10 で同じ隔離環境を作成してください。
依存関係の不足またはインポートエラー	skill_manifest.yaml の宣言とランタイムパッケージに差異があります。	マニフェストに宣言されたパッケージをインストールするか、ドキュメントに記載されたセットアップコマンドを使用してください。
出力が空、またはスキーマが無効	入力パスの誤り、非対応のモダリティ、または上流処理の失敗です。	既知のフィクスチャを使用して再実行し、ラッパーの JSON と stderr を確認してください。
検証ゲートの失敗	出力が宣言されたエンジニアリング上の不変条件に違反しています。	失敗した証拠パックを保持し、ゲートのメッセージを参考に入力またはラッパーコードを修正してください。

上流の nvidia/NV-Segment-CT ヘルパーをラップしています。このラッパーは VISTA3D の推論を再実装していません。

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

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

"$NV_SEGMENT_CT_VENV/bin/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 を正確に使用してください。

前提条件

このスキルでは、venv をサポートする Python 3.10 インタープリターを想定しています。ドキュメントに記載されているコマンドは、専用の環境を作成し、不変の NVIDIA-Medtech コミット f9f5f51b589e5dc9c23c453cf5138398e4084056 にある NV-Segment-CT/requirements.txt からモデルの依存関係をインストールします。Hugging Face バンドルには requirements.txt は含まれていません。

一度だけ行うダウンロードが 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 へのフォールバックもサポートされていますが、処理は低速です。

使い方

スキルリポジトリのルートから、ブートストラップを最後まで実行します。呼び出し元のアクティブな環境を変更しないよう、仮想環境のバイナリを直接呼び出してください。

export NV_SEGMENT_CT_VENV="${NV_SEGMENT_CT_VENV:-$HOME/.cache/nvidia-skills/venvs/nv-segment-ct-f9f5f51}"
export NV_SEGMENT_CT_REQUIREMENTS="${NV_SEGMENT_CT_REQUIREMENTS:-https://raw.githubusercontent.com/NVIDIA-Medtech/NV-Segment-CTMR/f9f5f51b589e5dc9c23c453cf5138398e4084056/NV-Segment-CT/requirements.txt}"

if [ ! -x "$NV_SEGMENT_CT_VENV/bin/python" ]; then
  python3.10 -m venv "$NV_SEGMENT_CT_VENV"
fi

"$NV_SEGMENT_CT_VENV/bin/python" -m pip install \
  -r "$NV_SEGMENT_CT_REQUIREMENTS" \
  "transformers==4.46.3" \
  "typer>=0.9"

"$NV_SEGMENT_CT_VENV/bin/hf" download nvidia/NV-Segment-CT \
  --revision afb51518689f71e6abb367ee6301b2cd0225c66a \
  --local-dir skills/nv-segment-ct/bundle/

"$NV_SEGMENT_CT_VENV/bin/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 に置き換えないでください。ラッパーは要求されたラベルのセットを検証し、出力マスクに要求されたセット以外のラベルが含まれている場合、実行を無効と判定します。

インストールとダウンロードの手順は不可欠です。モデル環境を管理するのは固定された上流ファイルで、この薄いラッパーをサポートするのは Transformers と Typer です。hf 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 以外のモダリティには使用しないでください。