CCD

CCD (Clinical Contrastive Decoding) is a training-free framework designed to mitigate hallucinations in radiology-capable large language models by integrating structured clinical signals from radiology expert models. The server exposes a CLI-style and programmatic interface to run CCD-enabled inference on chest X-rays and related radiology tasks. You can run inference directly from the command line using the provided Python module (python -m ccd.run_ccd) or invoke it programmatically via the ccd_eval interface, selecting an expert model (DenseNet, MedSiglip, View, or Device) and tuning the clinical guidance weight (alpha), expert token weight (beta), and token bias (gamma). The system is designed to reduce unsupported or incorrect clinical details while preserving the base model’s capabilities. In addition to CLI inference, CCD also offers a script-based evaluation workflow (ccd_eval) and a Gradio web interface for interactive exploration. When using the CLI, you can specify the image path, model-path for the radiology LLM, and a physician-style question; the configurable parameters let you balance clinical guidance with model tokens to tailor outputs to clinical contexts.

Prerequisites:

• Python 3.9 or later
• CUDA-enabled GPU (recommended) for acceleration
• Internet access to install dependencies

Option A: Quick setup (recommended)

1. Install directly from GitHub using uv (faster installation for Python projects):

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

2. Verify installation and run a sample: you can start by running the CLI module (see Quick Start in the README for exact usage).

Option B: Editable development install (for contributing)

1. Clone the repository and install in editable mode:

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

2. Create and activate a conda environment (optional but recommended):

conda create -n CCD python=3.10 -y
conda activate CCD

3. Install uv fast-path support and install the package in editable mode:

pip install uv  # enable uv support
uv pip install -e .

Upgrade to the latest code base when needed:

uv pip install -e .

Note: The README recommends uv as the installation method for speed and reliability.

Tips and caveats:

• Prerequisites emphasize a CUDA-capable GPU for best performance.
• The CCD CLI uses python -m ccd.run_ccd with options for model-path, image, and question; you can tune alpha (clinical guidance weight), beta (expert token weight), and gamma (token bias magnitude) to adjust the balance between clinical signals and base model outputs.
• Available expert models include DenseNet, MedSiglip, View, and Device. You can choose among these when launching the inference to influence hallucination mitigation.
• If you plan to modify or contribute, install in editable mode and use the provided ccd_eval and run_ccd entry points for integration tests.
• Gradio demo is available locally via python -m ccd.app or through Hugging Face Spaces for quick experimentation.
• Ensure appropriate CUDA drivers and libraries are installed on the host to leverage GPU acceleration.
• When using the MCP server configuration, you can set environment variables (e.g., CUDA_VISIBLE_DEVICES) to control device visibility and other runtime options.