README.md

metadata

library_name: transformers
tags:
  - vision-language
  - medical
  - radiology
  - chest-xray
  - qwen2.5-vl
pipeline_tag: image-text-to-text
base_model: Qwen/Qwen2.5-VL-7B-Instruct

EvidenceAIResearch/VReason-QwenVL

VReason-QwenVL model checkpoint for chest X-ray visual reasoning and report generation.

What is included

• Model weights (safetensors shards)
• Tokenizer and config files
• generation_config.json
• Built-in model.visual_reason(...) method available via trust_remote_code=True

Installation

pip install -r requirements.txt
pip install cxas-vreason

If cxas-vreason is not yet available in your environment, install from this repo:

pip install "git+https://huggingface.co/EvidenceAIResearch/VReason-QwenVL#subdirectory=cxas_vreason"

Quick start (Transformers)

import torch
from PIL import Image
from transformers import AutoProcessor, AutoModelForVision2Seq

repo_id = "EvidenceAIResearch/VReason-QwenVL"
processor = AutoProcessor.from_pretrained(repo_id, trust_remote_code=True)
model = AutoModelForVision2Seq.from_pretrained(
    repo_id,
    torch_dtype=torch.float16,
    trust_remote_code=True,
).eval().cuda()

image = Image.open("frontal.jpg").convert("RGB")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": image},
            {
                "type": "text",
                "text": "Based on the provided chest radiograph, explain your diagnosis procedure and write a report.",
            },
        ],
    }
]

prompt = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = processor(text=[prompt], images=[[image]], return_tensors="pt").to(model.device)
output_ids = model.generate(**inputs, max_new_tokens=1024)
text = processor.batch_decode(output_ids, skip_special_tokens=False)[0]
print(text)

Visual reasoning method

After loading with trust_remote_code=True, the model exposes:

• model.visual_reason(...)

This method can:

• reasoning.json with regions, sub-regions, and extracted reasoning text
• Generate ROI image artifacts for anatomy/pathology tool calls (blur/crop/blurcrop)

Example:

out = model.visual_reason(
    processor=processor,
    image="frontal.jpg",
    generate_roi=True,
    output_dir="./visual_reason_out",
    viz_mode="blurcrop",
)
print(out["report"])

Notes:

• trust_remote_code=True is required to enable model.visual_reason(...).
• Pass generate_roi=False when you only need structured text parsing.

Limitations

• Intended for research use only.
• Not a medical device; outputs must not be used as sole clinical evidence.
• Performance can vary by data source and imaging protocol.

---

Citation

@unpublished{ye2026visual,
  title={Visual Reasoning Enables Evidence-Grounded Radiology {AI}},
  author={Ye, Shuchang and Robertson, Harry and Moghadam, Alireza
          and Shu, Matthew and Harb, Nathan and Li, Jennifer
          and Mogdil, Aadhar and Raythatha, Jineel and Shen, Yujia
          and Song, Xinyun and Tan, Xinchen and Fu, Xiaolong
          and Meng, Mingyuan and Bi, Lei and Yang, Jean YH
          and Kim, Jinman},
  year={2026},
}