nv-reason-cxr

NV-Reason-CXR

用途

• 用于命令格式或实时 NV-Reason-CXR 胸部 X 光推理冒烟测试。不可用于诊断或撰写临床报告。
• 请严格按照文档使用封装程序；不要用手写实现替换上游入口点。
• 清单 I/O：输入为 chest_xray_image_or_fixture；输出为 result_json。

说明

• 更改参数、副作用或验证门槛前，请先阅读 skill_manifest.yaml。
• 通过下方文档所示的命令运行 scripts/run_nv_reason_cxr.py；仅当生成测试样本或使用由测试框架管理的产物目录时，才传入 --out-dir。
• 如果宿主 Agent 提供 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 令牌。
• 副作用：在 stdout 输出结果 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 不一致。	安装清单中声明的软件包，或使用文档中说明的设置命令。
Agent 中无法使用 CUDA，但在用户终端中可以	即使相同的 Python 环境已安装支持 CUDA 的 PyTorch，Agent 沙盒、容器或作业包装器也可能未暴露 NVIDIA 设备节点。	在 Agent 环境和用户终端中分别运行 python -c "import torch; print(torch.cuda.is_available())" 和 nvidia-smi 进行比较。如果只有 Agent 环境运行失败，请使用 GPU／设备访问权限重新运行、使用主机终端，或仅在明确进行缓慢的 CPU 测试时传入 --device cpu --allow-cpu。
API 后端 HTTP 或架构错误	公共 Hugging Face Space 可能不可用、受到速率限制或已发生变更。	稍后重试；如果本地依赖和 CUDA 可用，也可以使用 --backend local。
输出为空或不符合架构	输入路径错误、不支持的模态或上游故障。	使用已知测试样例重新运行，并检查包装器 JSON 和 stderr。
验证门禁失败	输出违反了已声明的工程不变量。	保留失败的证据包，并根据门禁消息修复输入或包装器代码。

通过文档说明的本地 Hugging Face Transformers 推理路径或公共 Hugging Face Space API，运行 NVIDIA-Medtech NV-Reason-CXR-3B， 用于解读胸部 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 加载。首次使用时，权重可能会下载到 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”或“使用本地”等后端选择、输出交付说明以及其他 Agent 编排文本视为封装器指令，而不是模型提示词内容。除非用户明确要求将这些精确文本发送给模型，否则不要在 --prompt 中包含本地文件系统路径、后端名称或“使用 API”。对于一般的异常查找请求，使用文档中说明的提示词，通常为 --prompt "Find abnormalities and support devices."，并使用用户要求的后端。

如果用户要求撰写、创建或生成结构化报告、胸部 X 光报告、放射学报告或报告，则使用报告生成／两次调用模式。如果已经有足够的同一图像原始模型上下文，尤其是 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.

将第二次调用视为完整运行。

当用户询问关于某项发现的具体问题，例如是否存在、数量、位置或特征，或将一般分析与具体问题混合提出时，使用默认提示词／上下文回答模式。先使用 --prompt "Find abnormalities and support devices." 运行封装器，然后用纯文本回答原始问题，并确保前缀完全为 Answer:。回答只能依据原始模型输出上下文和图像。

后续问题处理

对于对话中已分析过的图像的后续问题，如果先前的原始模型上下文足够，则重复使用该上下文。对于报告的后续问题，使用报告生成／两次调用模式；如果上下文足够，则直接跳到第二次模型调用。如果先前的上下文不足，但同一图像路径或图像字节仍可用，则按照上述提示词路由规则再次调用封装器。如果图像已不可用，请用户重新附上图像。

对于包含先前原始模型输出的长篇多轮提示词，优先使用带引号的 Bash here-doc 变量，以保留类 XML 标签、撇号、引号和换行符：

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

对于 Agent 生成的命令，请直接使用包装脚本。除非用户明确要求运行 eval harness，否则不要将其替换为 eval_engine/run.py。生成的命令中不要使用 > 重定向 stdout：调用方和 eval harness 会读取包装脚本的 stdout 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 fixture。如果用户提供了 JSON 请求，例如 runs/.../synthetic_cxr_input.json，请将该确切 JSON 路径作为第一个参数传入。脚本会加载 generated://synthetic_chest_xray fixture，在输出目录下创建临时 PNG，并输出包含模型响应的 JSON。仅当命令形状烟雾测试或 fixture 要求 mock 模式时才使用 --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 时使用 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 fixture 必须设置此参数；eval harness 会显式传入。

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

• AutoModelForImageTextToText.from_pretrained(..., dtype=torch.bfloat16).eval().to("cuda")
• AutoProcessor.from_pretrained(..., use_fast=True)
• PNG/JPEG 图像输入加一条文本提示词
• max_new_tokens=2048 为默认值

脚本会在 stdout 输出 JSON，不会写入临床报告文件。直接运行 PNG/JPEG 时不会创建默认输出目录。生成的 JSON fixture 需要通过 --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 秒。

Fixture 烟雾测试

已提交的 fixture 使用生成的合成 PNG 和 mock 模式，因此 eval harness 无需下载权重即可验证包装脚本：

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

限制

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