nv-reason-cxr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NV-Reason-CXR

Purpose

用途

Used for command-shape or live NV-Reason-CXR chest X-ray reasoning smoke tests. Not for diagnosis or clinical reporting.
Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
Manifest I/O: inputs are
```
chest_xray_image_or_fixture
```
; outputs are
```
result_json
```
.

用于命令形式或实时的NV-Reason-CXR胸部X光推理冒烟测试。不用于诊断或临床报告。
严格按照文档说明使用该包装器；请勿用手写实现替换上游入口点。
清单输入输出：输入为
```
chest_xray_image_or_fixture
```
；输出为
```
result_json
```
。

Instructions

操作说明

Read
```
skill_manifest.yaml
```
before changing arguments, side effects, or validation gates.
Run
```
scripts/run_nv_reason_cxr.py
```
through the documented command below; keep outputs under a caller-provided run directory.
If a host agent exposes
```
run_script
```
, use
```
run_script("scripts/run_nv_reason_cxr.py", args=[...])
```
; otherwise run the Bash/Python command shown below.
Check the emitted JSON and paired verifier guidance before treating the run as evidence.

在修改参数、副作用或验证门限前，请先阅读
```
skill_manifest.yaml
```
。
通过以下文档记录的命令运行
```
scripts/run_nv_reason_cxr.py
```
；将输出保存在调用方提供的运行目录下。
如果宿主Agent暴露
```
run_script
```
方法，请使用
```
run_script("scripts/run_nv_reason_cxr.py", args=[...])
```
；否则运行下方所示的Bash/Python命令。
在将运行结果作为证据前，请检查生成的JSON及配套的验证器指南。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/run_nv_reason_cxr.py`	Primary entrypoint declared by skill_manifest.yaml.	`PATH_TO_CXR_OR_FIXTURE --out-dir OUT_DIR [--mock] [--check-setup]`

脚本	用途	参数
`scripts/run_nv_reason_cxr.py`	skill_manifest.yaml中声明的主要入口点。	`PATH_TO_CXR_OR_FIXTURE --out-dir OUT_DIR [--mock] [--check-setup]`

Prerequisites

前置条件

Runtime requirements: GPU/CUDA when declared by the manifest; Python packages listed in
```
runtime.side_effects.pip_packages
```
.
Side effects: writes JSON outputs under the caller's
```
--out-dir
```
, may cache model assets under
```
~/.cache/huggingface/
```
, and may contact
```
https://huggingface.co
```
or
```
https://github.com
```
outside
```
--mock
```
mode.
Run commands from the repository root unless an existing section below says otherwise.

运行时要求：清单中声明需要GPU/CUDA；需安装
```
runtime.side_effects.pip_packages
```
中列出的Python包。
副作用：在调用方指定的
```
--out-dir
```
下写入JSON输出，可能在
```
~/.cache/huggingface/
```
下缓存模型资产，且在非
```
--mock
```
模式下可能连接
```
https://huggingface.co
```
或
```
https://github.com
```
。
除非下方已有章节说明，否则请从仓库根目录运行命令。

Limitations

局限性

This is a thin wrapper. Image preprocessing, model inference, and decoding are delegated to Hugging Face Transformers and the NV-Reason-CXR-3B model.
Output is not a diagnosis, clinical report, treatment recommendation, or triage decision. It is engineering evidence and must be reviewed by a qualified professional before any medical use.
The model may hallucinate findings, miss subtle abnormalities, misread support devices, or produce overconfident prose.
The committed fixture uses a generated synthetic PNG and deterministic mock response so CI can verify wrapper behavior without downloading model weights. Mock mode is not a substitute for model inference.
Not for clinical deployment, clinical interpretation, autonomous diagnosis, treatment decisions.

这是一个轻量包装器。图像预处理、模型推理和解码均委托给Hugging Face Transformers和NV-Reason-CXR-3B模型处理。
输出内容并非诊断结果、临床报告、治疗建议或分诊决策。它属于工程证据，在任何医疗用途前必须经过合格专业人员的审核。
模型可能会虚构发现结果、遗漏细微异常、误判辅助设备，或生成过于自信的描述文本。
已提交的测试用例使用生成的合成PNG和确定性模拟响应，以便CI在不下载模型权重的情况下验证包装器行为。模拟模式不能替代模型推理。
不用于临床部署、临床解读、自主诊断或治疗决策。

Troubleshooting

故障排查

Error	Cause	Fix
Missing dependency or import error	Runtime package drift from `skill_manifest.yaml` .	Install the packages declared in the manifest or use the documented setup command.
Empty or schema-invalid output	Wrong input path, unsupported modality, or upstream failure.	Re-run with a known fixture and inspect the wrapper JSON plus stderr.
Validation gate failure	Output violated a declared engineering invariant.	Keep the failed evidence pack and use the gate message to repair inputs or wrapper code.

Runs NVIDIA-Medtech

NV-Reason-CXR-3B

for chest X-ray image interpretation through the documented Hugging Face Transformers inference path. The wrapper does not reimplement the model, image preprocessing, or decoding.

错误	原因	解决方法
依赖缺失或导入错误	运行时包与 `skill_manifest.yaml` 存在差异。	安装清单中声明的包，或使用文档记录的设置命令。
输出为空或不符合JSON Schema	输入路径错误、模态不支持或上游执行失败。	使用已知测试用例重新运行，并检查包装器的JSON输出及标准错误信息。
验证门限失败	输出违反了已声明的工程约束。	保留失败的证据包，并根据门限提示修复输入或包装器代码。

通过文档记录的Hugging Face Transformers推理路径，运行NVIDIA-Medtech的

NV-Reason-CXR-3B

进行胸部X光图像解读。该包装器未重新实现模型、图像预处理或解码逻辑。

Exact Runnable Surface

可运行的精确路径

For command-shape smoke tests and JSON fixtures, use this repo-root wrapper path exactly:

bash

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

For live image inference, omit

--mock

only when the user asks for live model inference. Do not invent

Medical AI Skills run

eval_engine/run.py

infer.py

, or

python -m nv_reason_cxr

commands for ordinary user runs.

对于命令形式的冒烟测试和JSON测试用例，请严格使用以下仓库根目录下的包装器路径：

bash

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

对于实时图像推理，仅当用户要求实时模型推理时才省略

--mock

参数。在普通用户运行时，请勿自行使用

Medical AI Skills run

、

eval_engine/run.py

、

infer.py

或

python -m nv_reason_cxr

命令。

Preconditions

预置条件

Install the inference dependencies in the environment that will run the skill:

bash

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

The model weights are loaded from

nvidia/NV-Reason-CXR-3B

through Transformers. They may download to the Hugging Face cache on first use. Set

TRANSFORMERS_OFFLINE=1

or pass

--local-files-only

only after the weights are already cached.

CUDA is expected for practical inference. CPU execution may work for small tests but is slow and must be requested explicitly.

Check the local environment before downloading weights or running inference:

bash

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

The setup report checks importable dependencies, CUDA visibility, Hugging Face cache state, and the recommended next step.

Operational environment variables:

Variable	When to use
`MOCK_NV_REASON_CXR`	Set to `1` for deterministic command-shape smoke tests without model inference.
`NV_REASON_CXR_MODEL`	Override the Hugging Face model id only for compatibility probes.
`HF_HOME`	Point at a pre-populated Hugging Face cache.
`HF_TOKEN`	Authenticate model downloads when required by the local environment.
`TRANSFORMERS_OFFLINE`	Set to `1` only after weights are already cached.
`HF_HUB_OFFLINE`	Set to `1` only after Hugging Face assets are already cached.

在将运行该技能的环境中安装推理依赖：

bash

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

模型权重通过Transformers从

nvidia/NV-Reason-CXR-3B

加载。首次使用时可能会下载到Hugging Face缓存中。仅当权重已缓存后，才可设置

TRANSFORMERS_OFFLINE=1

或传递

--local-files-only

参数。

实际推理需依赖CUDA。CPU执行可能适用于小型测试，但速度很慢且必须显式指定。

在下载权重或运行推理前检查本地环境：

bash

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`	当本地环境要求时，用于模型下载的身份验证。
`TRANSFORMERS_OFFLINE`	仅在权重已缓存后设置为 `1` 。
`HF_HUB_OFFLINE`	仅在Hugging Face资产已缓存后设置为 `1` 。

License

许可证

The upstream repository code is Apache-2.0. The model weights are released under the NVIDIA OneWay Noncommercial License Agreement. Users are responsible for complying with the model-weight terms before live inference.

上游仓库代码采用Apache-2.0许可证。模型权重根据NVIDIA单向非商业许可协议发布。用户在进行实时推理前需负责遵守模型权重的相关条款。

Usage

使用方法

From Medical AI Skills repo root:

bash

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.png \
  --prompt "Find abnormalities and support devices." \
  --out-dir runs/nv_reason_cxr_case

Use the wrapper script directly for agent-generated commands. Do not replace it with

eval_engine/run.py

unless the user explicitly asks to run the eval harness. Do not redirect stdout with

in generated commands: callers and the eval harness read the wrapper's stdout JSON, including

output.response_text

, to verify the run. The direct runnable surface is:

bash

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

may be a PNG/JPEG image or a JSON fixture. If the user provides a JSON request such as

runs/.../synthetic_cxr_input.json

, pass that exact JSON path as the first argument. The script will load

generated://synthetic_chest_xray

fixtures, create the temporary PNG under the output directory, and emit JSON with

output.response_text

. Use

--mock

only for command-shape smoke tests or fixtures that request mock mode; omit

--mock

for live model inference.

For JPEG input:

bash

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.jpg \
  --prompt "Describe the chest X-ray findings." \
  --out-dir runs/nv_reason_cxr_case

Flags:

```
--model-id
```
— Hugging Face model id, default
```
nvidia/NV-Reason-CXR-3B
```
.
```
--device auto|cuda|cpu
```
— default
```
auto
```
, using CUDA when available.
```
--allow-cpu
```
— required for live CPU inference; CPU runs can be very slow.
```
--torch-dtype auto|float16|bfloat16|float32
```
— default
```
auto
```
, using bfloat16 on CUDA and float32 on CPU, matching the published BF16 model.
```
--max-new-tokens
```
— generation cap, default 2048.
```
--local-files-only
```
— use only locally cached Hugging Face assets.
```
--mock
```
— deterministic dry-run response for CI and wiring checks.
```
--prompt-preset findings|comprehensive|educational|structured
```
— optional known-good prompt presets from the model card/demo behavior.

The tested local live path uses:

AutoModelForImageTextToText.from_pretrained(..., dtype=torch.bfloat16).eval().to("cuda")

AutoProcessor.from_pretrained(..., use_fast=True)

PNG/JPEG image input plus one text prompt
```
max_new_tokens=2048
```
by default

The script emits JSON on stdout and writes no clinical report files. It records input image metadata, prompt, model id, runtime mode, response text, and known limitations. If

runtime.truncated_by_max_new_tokens

true

, rerun with a higher

--max-new-tokens

value.

从Medical AI Skills仓库根目录执行：

bash

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.png \
  --prompt "Find abnormalities and support devices." \
  --out-dir runs/nv_reason_cxr_case

对于Agent生成的命令，请直接使用包装器脚本。除非用户明确要求运行评估工具，否则请勿替换为

eval_engine/run.py

。在生成的命令中请勿使用

重定向标准输出：调用方和评估工具会读取包装器的标准输出JSON（包括

output.response_text

）来验证运行结果。可直接运行的路径如下：

bash

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，并生成包含

output.response_text

的JSON。仅在命令形式冒烟测试或测试用例要求模拟模式时使用

--mock

；实时模型推理时请省略该参数。

对于JPEG输入：

bash

python skills/nv-reason-cxr/scripts/run_nv_reason_cxr.py PATH_TO_CXR.jpg \
  --prompt "Describe the chest X-ray findings." \
  --out-dir runs/nv_reason_cxr_case

参数说明：

```
--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
```
— 可选的预设优质提示词，来自模型卡片/演示行为。

经过测试的本地实时路径使用：

AutoModelForImageTextToText.from_pretrained(..., dtype=torch.bfloat16).eval().to("cuda")

AutoProcessor.from_pretrained(..., use_fast=True)

PNG/JPEG图像输入加一个文本提示词
默认
```
max_new_tokens=2048
```

脚本会在标准输出中生成JSON，且不会写入临床报告文件。它会记录输入图像元数据、提示词、模型ID、运行时模式、响应文本以及已知局限性。如果

runtime.truncated_by_max_new_tokens

为

true

，请使用更高的

--max-new-tokens

值重新运行。

Fixture Smoke Test

测试用例冒烟测试

The committed fixture uses a generated synthetic PNG and mock mode so the eval harness can verify the wrapper without downloading weights:

bash

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

已提交的测试用例使用生成的合成PNG和模拟模式，因此评估工具无需下载权重即可验证包装器：

bash

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

Limits

限制说明

This is research and engineering tooling only. It is not validated for clinical diagnosis, treatment decisions, triage, patient-facing reporting, or regulatory use. Model outputs can hallucinate, miss subtle findings, or overstate uncertainty. A qualified professional must review any use in a medical workflow.

这仅为研究和工程工具。未针对临床诊断、治疗决策、分诊、面向患者的报告或监管用途进行验证。模型输出可能产生幻觉、遗漏细微发现或夸大不确定性。在医疗工作流中使用时，必须由合格专业人员进行审核。