nv-reason-cxr

NV-Reason-CXR

目的

• コマンド形式または実際の NV-Reason-CXR の胸部 X 線推論のスモークテストに使用します。診断や臨床報告には使用しないでください。
• ラッパーはドキュメントに記載されたとおりに使用してください。上流のエントリーポイントを手書きの実装に置き換えないでください。
• マニフェストの入出力：入力は chest_xray_image_or_fixture、出力は result_json です。

手順

• 引数、副作用、検証ゲートを変更する前に、skill_manifest.yaml を読んでください。
• 下記のドキュメントに記載されたコマンドで scripts/run_nv_reason_cxr.py を実行してください。--out-dir は、生成するフィクスチャまたはハーネスが管理するアーティファクトディレクトリにのみ指定してください。
• ホストエージェントが run_script を提供している場合は、run_script("scripts/run_nv_reason_cxr.py", args=[...]) を使用してください。それ以外の場合は、下記の Bash/Python コマンドを実行してください。
• 実行結果を証拠として扱う前に、出力された JSON と対応する検証ガイダンスを確認してください。
• 実行完了を報告する際は、ラッパーの JSON 全体、または少なくとも出力されたとおりの完全な output.response_text を返してください。モデルが生成した `` セクションや <answer>...</answer> セクションも含めてください。ユーザーから明示的に要約を求められない限り、結果をラベルだけに簡略化しないでください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/run_nv_reason_cxr.py	skill_manifest.yaml で宣言されている主要なエントリーポイントです。	PATH_TO_CXR_OR_FIXTURE [--out-dir OUT_DIR] [--backend local|hf-space-api] [--mock] [--check-setup]

前提条件

• ローカルバックエンドの要件：マニフェストに記載されている場合は GPU/CUDA、runtime.side_effects.pip_packages に記載された Python パッケージ。
• API バックエンドの要件：Hugging Face Space へのパブリックネットワークアクセス。ローカルの PyTorch、Transformers、CUDA、モデルキャッシュ、Hugging Face トークンは不要です。
• 副作用：標準出力に結果の JSON を出力します。呼び出し元の --out-dir 以下に生成したフィクスチャのアーティファクトを書き込む場合があります。ローカル推論用のモデルアセットを ~/.cache/huggingface/ 以下にキャッシュする場合があります。また、--mock モード以外では https://huggingface.co、https://github.com、または https://*.hf.space に接続する場合があります。
• 下記の既存セクションに別途記載がない限り、リポジトリのルートからコマンドを実行してください。

制限事項

• これは薄いラッパーです。画像の前処理、モデル推論、デコードは Hugging Face Transformers と NV-Reason-CXR-3B モデルに委ねられます。
• 出力は診断、臨床報告、治療の推奨、トリアージの判断ではありません。これはエンジニアリング上の証拠であり、医療目的で使用する前に資格を有する専門家が確認する必要があります。
• モデルは所見を幻覚したり、微妙な異常を見落としたり、補助装置を読み違えたり、過度に自信のある文章を生成したりする場合があります。
• コミット済みのフィクスチャでは、生成された合成 PNG と決定論的なモック応答を使用しているため、モデルの重みをダウンロードせずに CI でラッパーの動作を検証できます。モックモードはモデル推論の代替ではありません。
• hf-space-api バックエンドは、Hugging Face Space の公開状態と API 互換性に依存します。
• 臨床現場への導入、臨床的な解釈、自律的な診断、治療の判断には使用しないでください。

トラブルシューティング

エラー	原因	対処方法
依存関係の不足またはインポートエラー	skill_manifest.yaml に記載されたランタイムパッケージとの不整合です。	マニフェストに記載されたパッケージをインストールするか、ドキュメントに記載されたセットアップコマンドを使用してください。
ユーザーのターミナルでは CUDA を利用できるのに、エージェントからは利用できない	同じ Python 環境に CUDA 対応の PyTorch がインストールされていても、エージェントのサンドボックス、コンテナー、またはジョブラッパーから NVIDIA デバイスノードにアクセスできない場合があります。	エージェントのコンテキストとユーザーのターミナルで、python -c "import torch; print(torch.cuda.is_available())" と nvidia-smi の結果を比較してください。エージェントのコンテキストでのみ失敗する場合は、GPU／デバイスへのアクセスを許可して再実行するか、ホストのターミナルを使用してください。または、明示的な低速の CPU テストに限り、--device cpu --allow-cpu を指定してください。
API バックエンドの HTTP エラーまたはスキーマエラー	公開 Hugging Face Space が利用できない、レート制限されている、または変更されている可能性があります。	後でもう一度実行するか、ローカルの依存関係と CUDA が利用できる場合は --backend local を使用してください。
出力が空、またはスキーマが無効	入力パスの誤り、未対応のモダリティ、または上流でのエラーです。	既知のフィクスチャを使って再実行し、ラッパーの JSON と標準エラー出力を調べてください。
検証ゲートの失敗	出力が宣言されたエンジニアリング上の不変条件に違反しています。	失敗時のエビデンスパックを保持し、ゲートのメッセージを参考に入力またはラッパーコードを修正してください。

NVIDIA-Medtech NV-Reason-CXR-3B を使って、ドキュメントに記載されたローカルの Hugging Face Transformers 推論パス、または公開 Hugging Face Space API 経由で胸部 X 線画像を解釈します。 このラッパーはモデル、画像の前処理、またはデコードを再実装しません。

正確な実行方法

コマンド形式のスモークテストと JSON フィクスチャには、リポジトリルートにある次のラッパーパスをそのまま使用してください。

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE --mock --out-dir OUT_DIR

ローカルで実際に画像を推論する場合、ユーザーがライブモデル推論を求めているときに限り、--mock を省略してください。 デフォルトのバックエンドはローカルです。

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE \
  --prompt "Find abnormalities and support devices." \
  --backend local

ローカルにモデルパッケージをインストールせずに公開 API で推論するには、次を使用してください。

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE \
  --prompt "Find abnormalities and support devices." \
  --backend hf-space-api

通常のユーザー実行に Medical AI Skills run、eval_engine/run.py、infer.py、または python -m nv_reason_cxr コマンドを作り出して使用しないでください。

前提条件

--backend local の場合は、このスキルを実行する環境に推論の依存関係をインストールしてください。

pip install torch==2.7.1 torchvision==0.22.1 transformers==4.56.1 Pillow

モデルの重みとリモートモデルコードは、Transformers を通じて nvidia/NV-Reason-CXR-3B のリビジョン 056bd0383b35226554da9dc5866e095df174ae19 から読み込まれます。初回使用時は Hugging Face キャッシュにダウンロードされる場合があります。 重みがすでにキャッシュされている場合に限り、TRANSFORMERS_OFFLINE=1 を設定するか、--local-files-only を渡してください。

実用的な推論には CUDA が必要です。小規模なテストであれば CPU でも動作する場合がありますが、処理が遅く、明示的な指定が必要です。

--backend hf-space-api の場合、ローカルの PyTorch、Transformers、CUDA、モデルキャッシュ、または Hugging Face トークンは必要ありません。このバックエンドは、画像とプロンプトを公開 nvidia/nv-reason-cxr Hugging Face Space に送信します。

重みのダウンロードや推論の実行前に、ローカル環境を確認してください。

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py --check-setup

セットアップレポートでは、インポート可能な依存関係、CUDA の認識状況、Hugging Face キャッシュの状態、および推奨される次の手順を確認します。

運用環境変数：

変数	使用する場面
MOCK_NV_REASON_CXR	モデル推論を行わずにコマンド形式の決定的なスモークテストを実施する場合は、1 に設定します。
NV_REASON_CXR_MODEL	互換性の確認に限り、Hugging Face のモデル ID を上書きします。
HF_HOME	事前にデータを格納した Hugging Face キャッシュを指定します。
HF_TOKEN	ローカル環境で必要な場合に限り、ローカルモデルのダウンロードに使用します。公開 API バックエンドでは不要です。
TRANSFORMERS_OFFLINE	重みがすでにキャッシュされている場合に限り、1 に設定します。
HF_HUB_OFFLINE	Hugging Face のアセットがすでにキャッシュされている場合に限り、1 に設定します。

プロンプトのルーティング

ラッパーを実行する前に、モデルに渡すプロンプトとユーザー向けの出力モードの両方を選択します。ルーティングの順序が重要です。モデルに渡す正確なプロンプトを求められた場合は、まずそのまま渡す／生出力のみのモードを使用します。それ以外の場合は、レポート生成のリクエストを一般的な分析や具体的な質問のルーティングより優先します。

ユーザーが「このプロンプトをそのままモデルに渡して：...」のように、モデルに正確なプロンプトを送るよう明示的に求めた場合に限り、そのまま渡す／生出力のみのモードを使用します。--prompt には、その正確なモデルプロンプトだけを渡します。

ユーザーが胸部 X 線画像の異常の分析、検査、または発見を求めた場合は、異常分析モードを使用します。ローカル画像のパス、アップロードされたファイル名、「API を使用」や「ローカルを使用」などのバックエンドの選択、出力の受け渡し方法の指示、その他のエージェントのオーケストレーションに関するテキストは、モデルプロンプトの内容ではなく、ラッパーへの指示として扱います。ユーザーがその正確なテキストをモデルに送るよう明示的に求めない限り、ローカルファイルシステムのパス、バックエンド名、「API を使用」を--promptに含めないでください。一般的な異常発見のリクエストでは、通常は--prompt "Find abnormalities and support devices."という、ドキュメントに記載されたプロンプトを使用し、指定されたバックエンドを選びます。

ユーザーが構造化レポート、胸部 X 線レポート、放射線科レポート、またはレポートの執筆、作成、生成を求めた場合は、レポート生成／2 回呼び出しモードを使用します。同じ画像について、モデルの生の出力コンテキストがすでに十分に得られている場合（特にFind abnormalities and support devices.の出力がある場合）は、コンテキスト収集の呼び出しを省略します。それ以外の場合は、まずラッパーを--prompt "Examine the chest X-ray."で実行してコンテキストを収集しますが、その最初の呼び出しは表示しないでください。次に、複数ターンのトランスクリプトプロンプトを使って、ラッパーをもう一度実行します。

User: Find abnormalities and support devices.

Assistant:
<raw model context>

User: Write a structured report.

2 回目の呼び出しを完了した実行として扱います。

所見の有無、数、位置、特徴などに関する具体的な質問をユーザーがした場合、または一般的な分析と具体的な質問を組み合わせている場合は、デフォルトプロンプト／コンテキスト回答モードを使用します。ラッパーを--prompt "Find abnormalities and support devices."で実行してから、元の質問への回答を、正確にAnswer:を先頭に付けたプレーンテキストで返します。回答はモデルの生の出力コンテキストと画像だけに基づいてください。

フォローアップへの対応

会話ですでに分析した画像に関するフォローアップの質問には、以前のモデルの生のコンテキストが十分であれば再利用します。レポートに関するフォローアップでは、レポート生成／2 回呼び出しモードを使用し、コンテキストが十分な場合は2 回目のモデル呼び出しから直接始めます。以前のコンテキストが不十分で、同じ画像のパスまたは画像データを利用できる場合は、上記のプロンプトルーティングのルールに従ってラッパーを再度呼び出します。画像を利用できなくなっている場合は、ユーザーに再添付を依頼します。

以前のモデルの生の出力を含む長い複数ターンのプロンプトでは、XML 風のタグ、アポストロフィ、引用符、改行を保持できるよう、引用符で囲んだ Bash ヒアドキュメント変数の使用を推奨します。

IFS= read -r -d '' prompt <<'PROMPT'
User: Examine the chest X-ray.

Assistant:
<raw model context>

User: Write a structured report.
PROMPT

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.png \
  --prompt "$prompt" \
  --backend hf-space-api

貼り付けた長いトランスクリプトには、コマンド置換ではなくIFS= read -r -d '' prompt <<'PROMPT'を使用してください。

ライセンス

上流リポジトリのコードは Apache-2.0 です。モデルの重みは NVIDIA OneWay Noncommercial License Agreement に基づいて公開されています。ライブ推論の前に、モデルの重みに関する条件を遵守する責任はユーザーにあります。

使用方法

Medical AI Skills リポジトリのルートから実行します。

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.png \
  --prompt "Find abnormalities and support devices." \
  --backend local

モデルパッケージをローカルにインストールせずにパブリック API で推論する場合：

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.png \
  --prompt "Find abnormalities and support devices." \
  --backend hf-space-api

ユーザーのリクエストにローカルパスやバックエンドの指示が含まれている場合は、 その指示をモデルのプロンプトに含めないでください。

User request: find abnormalities in ~/Desktop/363.jpg (use API)

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py ~/Desktop/363.jpg \
  --prompt "Find abnormalities and support devices." \
  --backend hf-space-api

エージェントが生成したコマンドには、ラッパースクリプトを直接使用してください。ユーザーが評価ハーネスの実行を明示的に求めていない限り、eval_engine/run.py に置き換えないでください。呼び出し元と評価ハーネスは実行を検証するためにラッパーの標準出力の JSON を読み取るため、生成コマンドで > を使って標準出力をリダイレクトしないでください。直接実行可能な形式は次のとおりです。

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR_OR_FIXTURE \
  --mock \
  --out-dir runs/nv_reason_cxr_case

PATH_TO_CXR_OR_FIXTURE には、PNG/JPEG 画像または JSON フィクスチャを指定できます。ユーザーが runs/.../synthetic_cxr_input.json のような JSON リクエストを提供した場合は、その JSON のパスを最初の引数としてそのまま渡してください。スクリプトは generated://synthetic_chest_xray フィクスチャを読み込み、出力ディレクトリ内に一時 PNG を作成し、モデルの応答を含む JSON を出力します。--mock は、コマンド形式のスモークテスト、またはモックモードを要求するフィクスチャの場合にのみ使用してください。ライブモデル推論では --mock を省略してください。

JPEG 入力の場合：

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.jpg \
  --prompt "Describe the chest X-ray findings." \
  --backend local

フラグ：

• --backend local|hf-space-api — 推論バックエンド。デフォルトは local です。
• --model-id — Hugging Face モデル ID。デフォルトは nvidia/NV-Reason-CXR-3B です。
• --device auto|cuda|cpu — デフォルトは auto で、利用可能な場合は CUDA を使用します。
• --allow-cpu — ライブ CPU 推論には必須です。CPU での実行には非常に時間がかかる場合があります。
• --torch-dtype auto|float16|bfloat16|float32 — デフォルトは auto で、CUDA では bfloat16、CPU では float32 を使用します。公開されている BF16 モデルに合わせた設定です。
• --max-new-tokens — 生成上限。デフォルトは 2048 です。
• --local-files-only — ローカルにキャッシュされた Hugging Face アセットのみを使用します。
• --mock — CI と接続確認向けの決定論的なドライラン応答です。
• --prompt-preset findings|comprehensive|educational|structured — モデルカード／デモの動作に基づく、任意の既知の正常なプロンプトプリセットです。
• --out-dir — 任意のアーティファクトディレクトリです。生成された JSON フィクスチャでは必須で、評価ハーネスが明示的に渡します。

テスト済みのローカルライブ実行では、次を使用します。

• AutoModelForImageTextToText.from_pretrained(..., dtype=torch.bfloat16).eval().to("cuda")
• AutoProcessor.from_pretrained(..., use_fast=True)
• PNG/JPEG 画像入力と 1 つのテキストプロンプト
• デフォルトの max_new_tokens=2048

スクリプトは標準出力に JSON を出力し、臨床レポートファイルは書き込みません。PNG/JPEG を直接実行しても、デフォルトの出力ディレクトリは作成されません。生成された JSON フィクスチャでは、一時合成画像のために --out-dir が必要です。結果の JSON には、入力画像のメタデータ、プロンプト、モデル ID、実行モード、応答テキスト、既知の制限事項が記録されます。runtime.truncated_by_max_new_tokens が true の場合は、--max-new-tokens の値を増やして再実行してください。

レポートに関する注意：local と hf-space-api の両バックエンドで、Instructions に記載されている完了済み実行のルールに従ってください。

hf-space-api バックエンドは、固定のパブリック Hugging Face Space（https://nvidia-nv-reason-cxr.hf.space）を、HTTP タイムアウト 300 秒で呼び出します。

フィクスチャのスモークテスト

コミット済みのフィクスチャでは、生成した合成 PNG とモックモードを使用し、評価ハーネスが重みをダウンロードせずにラッパーを検証できるようにしています。

python eval_engine/run.py skills/nv-reason-cxr \
  --fixture skills/nv-reason-cxr/fixtures/synthetic_cxr_input.json \
  --out runs/nv_reason_cxr_smoke

制限事項

これは研究およびエンジニアリング用のツールに限られます。臨床診断、治療方針の決定、トリアージ、患者向けレポート作成、規制上の用途について検証されていません。モデルの出力には、事実と異なる内容が含まれたり、微妙な所見を見落としたり、不確実性を過度に強調したりする可能性があります。医療ワークフローで使用する場合は、必ず有資格の専門家が確認してください。