• [17 Oct 2025] 🔩 CCD has been upgraded to support view classification for chest X-rays — see the Supported Expert Models section for details.
• [06 Oct 2025] 🎮 The online demo is available at Hugging Face Spaces. Feel free to try it out!
• [30 Sep 2025] 🗂️ The processed test data for quick start are now available — enjoy exploring with the provided guidelines!
• [27 Sep 2025] ⛳ Our preprint is now live on arXiv — check it out for details.

Multimodal large language models (MLLMs) are advancing radiology by combining image and text understanding, but often generate inaccurate or unsupported clinical details—so-called medical hallucinations. We propose Clinical Contrastive Decoding (CCD), a training-free and retrieval-free inference framework that integrates structured clinical signals from task‑specific radiology expert models. CCD reduces hallucinations and improves clinical accuracy without changing the base model. Experiments show CCD boosts performance on multiple datasets and models, offering a practical way to make radiology MLLMs more reliable.

• ⛏️ Installation
• ⚡ Quick Start
  • CLI Inference
  • Script Inference
  • Gradio Web Interface
• 🛠️ Advanced Usage
  • Supported MLLM Models
  • Supported Expert Models
  • Parameter Settings
• 🗂️ Dataset
• 📊 Evaluation
• 📝 Citation
• 📚 Acknowledgments
• 📜 License
• 🧰 Intended Use

Install the latest version directly from GitHub for quick setup:

uv pip install git+https://github.com/X-iZhang/CCD.git

If you plan to modify the code or contribute to the project, you can clone the repository and install it in editable mode:

1. Clone the repository and navigate to the project folder

git clone https://github.com/X-iZhang/CCD.git
cd CCD

2. Set up the environment and install in editable mode

conda create -n CCD python=3.10 -y
conda activate CCD
pip install uv # enable uv support
uv pip install -e .

git pull
uv pip install -e .

You can perform inference directly from the command line using our CLI tool:

python -m ccd.run_ccd \
  --model-path "X-iZhang/libra-maira-2" \
  --image "./path/to/Chest_Xray.jpg" \
  --question "Is there evidence of any abnormalities?" \
  --max-new-tokens 128

Optional arguments:

You can run inference programmatically using the ccd_eval function from ccd/run_ccd.py.
After installing this repository, you can easily launch a model (either your own trained model or ours) locally or in Google Colab.

from ccd import ccd_eval

# Run CCD inference on a chest X-ray
output = ccd_eval(
    model_path="X-iZhang/libra-maira-2",  # or your custom radiology MLLM
    image="./path/to/Chest_Xray.jpg",
    question="Describe the findings in this chest X-ray.",
    alpha=0.5,        # Clinical guidance weight
    beta=0.5,         # Expert token weight
    gamma=10,         # Token bias magnitude
    temperature=0.9,  # Sampling temperature
    top_p=0.9,        # Nucleus sampling probability
    top_k=50,         # Top-k sampling
    expert_model="DenseNet",    # or "MedSiglip"
    max_new_tokens=256
)
print(output)

from ccd import run_eval

# Run standard inference without CCD
output = run_eval(
    model_path="X-iZhang/libra-maira-2",
    image="./path/to/Chest_Xray.jpg",
    question="Describe the findings in this chest X-ray.",
    max_new_tokens=128,
    num_beams=1
)
print(output)

You can launch the Gradio demo locally with:

python -m ccd.app

• Or try it directly on 🤗 Hugging Face Spaces 🤗.

Once the Gradio web interface is launched, you can open it using the URL printed on your screen. You will notice that both the default MAIRA-2 model and the expert models are ready for setup, with more models available in the list. Simply upload a chest X-ray image, enter your question, and click 🚀Generate to view the results!

CCD is compatible with any radiology MLLM that follows the Libra/LLaVA architecture:

CCD integrates two expert models for clinical signal extraction:

• alpha (0.0-1.0): Weight for clinical guidance text

  • Higher = more influence from expert-generated guidance
  • Recommended: 0.3-0.7

• beta (0.0-1.0): Weight for direct token biasing

  • Higher = stronger push toward clinical terminology
  • Recommended: 0.3-0.7

• gamma (2, 5, 10): Maximum token bias magnitude

  • 2: Subtle influence
  • 5: Moderate influence
  • 10: Strong influence (default)

CCD supports multiple medical imaging datasets commonly used in radiology research:

• MIMIC-CXR — Chest X-ray images with corresponding radiology reports.
• IU-Xray — Chest X-ray dataset with structured annotations.
• CheXpert Plus — Large-scale dataset for chest X-ray interpretation.
• Medical-CXR-VQA — A dataset for visual question answering in chest X-rays.

For evaluating generated reports, we recommend using RadEval — a unified framework for radiology text evaluation that integrates multiple standard metrics. Details can be found in the GitHub repository.

You can install RadEval via pip:

pip install RadEval

If you find our paper and code useful in your research and applications, please cite using this BibTeX:

@misc{zhang2025ccdmitigatinghallucinationsradiology,
      title={CCD: Mitigating Hallucinations in Radiology MLLMs via Clinical Contrastive Decoding}, 
      author={Xi Zhang and Zaiqiao Meng and Jake Lever and Edmond S. L. Ho},
      year={2025},
      eprint={2509.23379},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2509.23379}, 
}

This project builds upon the following outstanding open-source works:

• Libra — A flexible toolkit supporting multiple radiology LLM backbones, covering the full pipeline from training to inference.
• TorchXRayVision — A library for chest X-ray datasets and models.
• MedSigLIP — Medical Signal–Language Image Pretraining.
• RadEval — A unified framework for radiology text evaluation.

We thank the authors for their valuable contributions to the medical AI community.

This project is licensed under the MIT License - see the LICENSE file for details.

CCD is designed to assist clinical practitioners, researchers, and medical trainees in generating and analysing chest X-ray reports, with a focus on temporal reasoning and context-aware description of radiological findings.

• 🩺 Clinical Decision Support — Produces preliminary findings or comparative analyses that can aid radiologists in drafting and reviewing reports.
• 🎓 Educational Tool — Demonstrates example interpretations and temporal progressions for teaching radiology residents and students.
• 🔬 Research Utility — Enables investigation of automated report generation, visual-language alignment, and temporal feature learning in medical imaging.