⚡

胸部X光影像推理（NV-Reason-CXR）Skill nv-reason-cxr

该技能封装 NVIDIA NV-Reason-CXR-3B 视觉语言模型，用于对胸部 X 光（CXR）图像进行医学影像推理，识别异常影像表现与支持设备，并生成结构化的自然语言解读。支持本地 GPU 推理和 Hugging Face Space API 两种后端，并提供 mock 模式用于无模型冒烟测试。输出为工程验证用途的 JSON，不用于临床诊断。关键词：胸部X光、CXR、医学影像推理、异常检测、支持设备、视觉语言模型、NVIDIA、Hugging Face、医疗AI。

医学影像推理 0 次安装 0 次浏览 更新于 9/6/2026
名称 nv-reason-cxr
描述 用于命令形态或实时 NV-Reason-CXR 胸部 X 光推理冒烟测试。不用于诊断或临床报告。
开源协议 Apache-2.0 allowed-tools: Bash metadata:
作者 NVIDIA MedTech Team tags: - MedTech - CXR - reasoning

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；仅在生成夹具或由 harness 管理的产物目录时传递 --out-dir。
  • 如果宿主代理暴露了 run_script，请使用 run_script("scripts/run_nv_reason_cxr.py", args=[...])；否则运行下方所示的 Bash/Python 命令。
  • 在将运行作为证据之前，请检查生成的 JSON 和配套的验证器指南。
  • 报告完成运行时，请返回完整的包装器 JSON，或至少返回完整的 output.response_text，与模型生成的 <think>...</think> 和 <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 token。
  • 副作用：在 stdout 上输出结果 JSON；可能会在调用方的 --out-dir 下写入生成的 fixture 工件；可能会在本地推理时将模型资产缓存到 ~/.cache/huggingface/；在 --mock 模式之外可能会联系 https://huggingface.co、https://github.com 或 https://*.hf.space。
  • 除非下面现有章节另有说明，否则请从仓库根目录运行命令。

限制

  • 这是一个轻量包装器。图像预处理、模型推理和解码委托给 Hugging Face Transformers 和 NV-Reason-CXR-3B 模型。
  • 输出不是诊断、临床报告、治疗建议或分诊决定。它是工程证据，在任何医疗使用之前必须由合格的专业人员审查。
  • 模型可能产生幻觉发现、忽略细微异常、误读支持设备或生成过度自信的文本。
  • 提交的 fixture 使用生成的合成 PNG 和确定性 mock 响应，这样 CI 无需下载模型权重即可验证包装器行为。Mock 模式不能替代模型推理。
  • hf-space-api 后端依赖于公共 Hugging Face Space 的可用性和 API 兼容性。
  • 不用于临床部署、临床解释、自主诊断或治疗决策。

故障排除

错误 原因 修复
缺少依赖或导入错误 skill_manifest.yaml 声明的运行包版本漂移。 安装清单中声明的包或使用文档化的设置命令。
代理中 CUDA 不可用，但在用户终端中可用 代理沙箱、容器或作业包装器可能不暴露 NVIDIA 设备节点，即使同一 Python 环境安装了支持 CUDA 的 PyTorch。 比较代理上下文和用户终端中的 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。
输出为空或 schema 无效 输入路径错误、模态不受支持或上游失败。 使用已知 fixture 重新运行，并检查包装器 JSON 和 stderr。
验证门失败 输出违反了已声明的工程不变式。 保留失败的证据包，并使用门消息修复输入或包装器代码。

运行 NVIDIA-Medtech NV-Reason-CXR-3B，用于胸部 X 光图像解读，方式是通过文档化的本地 Hugging Face Transformers 推理路径或公共 Hugging Face Space API。包装器不会重新实现模型、图像预处理或解码。

精确可运行表面

对于命令形态冒烟测试和 JSON fixtures，请完全使用此仓库根包装路径：

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 token。后端将图像和提示发送到公共 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 光报告、放射学报告或报告，则使用报告生成/两次调用模式。如果同一图像已存在足够的原始模型上下文，尤其是来自“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

直接使用包装器脚本生成代理命令。除非用户明确要求运行 eval 平台，否则不要用 eval_engine/run.py 替换它。不要在生成的命令中使用 > 重定向 stdout：调用方和 eval 平台都会读取包装器的 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 fixtures，在输出目录下创建临时 PNG，并输出包含模型响应的 JSON。仅对命令形态冒烟测试或请求 mock 模式的 fixtures 使用 --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 fixtures 时需要；eval 平台显式传递该参数。

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

  • 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 fixtures 需要 --out-dir 用于临时合成图像。结果 JSON 记录输入图像元数据、提示、模型 id、运行时模式、响应文本和已知限制。如果 runtime.truncated_by_max_new_tokens 为 true，请使用更高 --max-new-tokens 值重新运行。

报告提醒：对于 local 和 hf-space-api 后端，请遵循说明中的完成运行规则。

hf-space-api 后端调用固定的公共 Hugging Face Space https://nvidia-nv-reason-cxr.hf.space，HTTP 超时为 300 秒。

Fixture 冒烟测试

提交的 fixture 使用生成式合成 PNG 和 mock 模式，使 eval 平台无需下载权重即可验证包装器：

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

限制

这仅是研究和工程工具。它未经临床诊断、治疗决策、分诊、面向患者的报告或监管使用验证。模型输出可能产生幻觉、遗漏细微发现，或过度陈述不确定性。合格的专业人员必须审查医疗工作流中的任何使用。