Create README.md

README.md

@@ -0,0 +1,319 @@
+---
+license: apache-2.0
+base_model:
+- deepseek-ai/DeepSeek-R1-Distill-Qwen-32B
+pipeline_tag: text-generation
+library_name: transformers
+tags:
+- medical
+---
+
+
+## Overview
+
+**RaDaR (Rare Disease navigatoR)** is a 32B-parameter reasoning large language model specialized for rare-disease differential diagnosis from free-text clinical narratives.
+
+RaDaR was initialized from [DeepSeek-R1-Distill-Qwen-32B](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-32B) and further trained using real-world rare-disease case reports and phenotype-anchored synthetic clinical cases, followed by supervised fine-tuning (SFT) and direct preference optimization (DPO).
+
+RaDaR is designed to process **free-text clinical records directly**, without requiring users to first convert the clinical narrative into Human Phenotype Ontology (HPO) terms.
+
+One motivation for releasing RaDaR as an open-weight model is to support **local deployment**, including settings in which sensitive clinical data should remain within an institution's own computing environment.
+
+## Resources
+
+* **Training and synthetic-data construction code:** https://github.com/sczzz3/RaDaR
+* **Paper:** https://arxiv.org/abs/2606.24510
+* **Web application:** https://raredx.datummed.com
+
+## Clinical-use notice
+
+RaDaR is a research and clinical decision-support model. It is not intended to replace qualified healthcare professionals or to provide autonomous diagnosis or treatment decisions. Model outputs may be incorrect, incomplete, or overconfident and should always be independently reviewed by qualified clinicians.
+
+
+## Quick start
+
+This section provides step-by-step instructions for downloading RaDaR and running it locally.
+
+### 1. Hardware and storage
+
+The released RaDaR-32B checkpoint is stored in BF16 format and occupies approximately **65.5 GB** of disk space. We recommend reserving at least **70 GB of free disk space** for the model files, plus additional space for the Python environment and model cache. Because the BF16 model weights alone occupy approximately 65.5 GB, GPU inference requires additional memory beyond the raw model size for runtime overhead and the key-value cache. Depending on the available hardware, users can run RaDaR on:
+
+- a single high-memory GPU;
+- multiple GPUs using automatic model sharding; or
+- multiple GPUs using tensor parallelism with an inference engine such as vLLM.
+
+Actual memory requirements depend on the input length, output length, inference backend, and number of concurrent requests. For users with limited GPU memory, shorter context lengths can substantially reduce runtime memory requirements.
+
+
+### 2. Create a Python environment
+
+We recommend Python 3.11.
+
+```bash
+conda create -n radar python=3.11 -y
+conda activate radar
+```
+
+Install the required packages:
+
+```bash
+pip install torch
+pip install transformers accelerate safetensors huggingface_hub
+```
+
+The released checkpoint was saved with Transformers 4.45.2. If you encounter version-related compatibility issues, you can use:
+
+```bash
+pip install transformers==4.45.2
+```
+
+### 3. Download RaDaR
+
+Install or update the Hugging Face Hub command-line utility:
+
+```bash
+pip install -U huggingface_hub
+```
+
+Download the complete model to a local directory:
+
+```bash
+hf download sczzz/RaDaR-32B \
+    --local-dir ./RaDaR-32B
+```
+
+After the download completes, the local directory should contain the model weights, tokenizer files, configuration files, and generation configuration. You can also skip this manual download step and use the Hugging Face repository name directly in `from_pretrained()`. However, explicitly downloading the checkpoint is recommended when preparing a fully offline clinical environment.
+
+
+### 4. Local inference with Transformers
+
+Create a file called `run_radar.py`:
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# Path to the locally downloaded checkpoint.
+MODEL_PATH = "./RaDaR-32B"
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH)
+
+model = AutoModelForCausalLM.from_pretrained(
+    MODEL_PATH,
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+)
+
+model.eval()
+
+# ---------------------------------------------------------------------
+# Replace the example text below with your own de-identified or locally
+# governed clinical narrative.
+# ---------------------------------------------------------------------
+
+case_text = """
+A 38-year-old male visited the surgery clinic with a year-long history of upper abdominal pain. The pain was described as dull and aching, with episodes of increased intensity lasting 1 to 2 hours...
+"""
+
+prompt = f"""
+As a medical expert, enumerate the top 10 most likely diagnoses for the following patient in descending order of likelihood, with the most likely disease listed first. Ensure that each diagnosis is as specific as possible, avoiding vague terms like "rare genetic disease".
+
+Here is the case: 
+{case_text}
+
+Only output the diagnosis in numeric order, one per line. For example:
+1. Disease A;
+2. Disease B;
+...
+
+Do not output anything else!
+"""
+
+# For the DeepSeek-R1-Distill model family, instructions are placed
+# directly in the user message rather than in a separate system prompt.
+messages = [
+    {"role": "user", "content": prompt}
+]
+
+formatted_prompt = tokenizer.apply_chat_template(
+    messages,
+    tokenize=False,
+    add_generation_prompt=True,
+)
+
+inputs = tokenizer(
+    formatted_prompt,
+    return_tensors="pt",
+).to(model.device)
+
+with torch.no_grad():
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=32768,
+        do_sample=True,
+        temperature=0.6,
+        top_p=0.95,
+        pad_token_id=tokenizer.eos_token_id,
+    )
+
+generated_tokens = outputs[0][inputs["input_ids"].shape[-1]:]
+
+response = tokenizer.decode(
+    generated_tokens,
+    skip_special_tokens=True,
+)
+
+print(response)
+```
+
+Run the script:
+
+```bash
+python run_radar.py
+```
+
+The first model load may take several minutes depending on disk and GPU speed.
+
+
+### Optional: local API deployment with vLLM
+
+RaDaR can also be served as a local API for integration with an institutional interface or clinical research application.
+
+Install vLLM:
+
+```bash
+pip install vllm
+```
+
+For example, to serve RaDaR using two GPUs:
+
+```bash
+vllm serve ./RaDaR-32B \
+    --dtype bfloat16 \
+    --tensor-parallel-size 2 \
+    --max-model-len 32768 \
+    --served-model-name RaDaR-32B
+```
+
+Adjust `--tensor-parallel-size` to match the number of GPUs available. The maximum model length can also be reduced if GPU memory is limited. The server listens locally on port 8000 by default.
+
+An example request is:
+
+```bash
+curl http://127.0.0.1:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "RaDaR-32B",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Based on the following clinical information, provide a ranked differential diagnosis of up to five rare diseases.\n\nClinical information:\n[CLINICAL RECORD]"
+      }
+    ],
+    "temperature": 0.6,
+    "top_p": 0.95,
+    "max_tokens": 32768
+  }'
+```
+
+For a fully offline deployment, start the server from the local checkpoint after enabling offline mode:
+
+```bash
+export HF_HUB_OFFLINE=1
+
+vllm serve ./RaDaR-32B \
+    --dtype bfloat16 \
+    --tensor-parallel-size 2 \
+    --max-model-len 32768 \
+    --served-model-name RaDaR-32B
+```
+
+This allows a local application to interact with RaDaR without sending clinical records to an external LLM API.
+
+
+## Input format
+
+RaDaR is primarily designed for **free-text clinical narratives**.
+
+Useful information may include:
+
+* age, sex, and age of symptom onset;
+* major symptoms and physical examination findings;
+* relevant past medical and family history;
+* laboratory results;
+* imaging findings;
+* pathology or procedural findings;
+* previous diagnostic investigations;
+* treatment history and treatment response;
+* genetic or genomic findings, when available.
+
+
+## Output
+
+RaDaR generates diagnostic reasoning and candidate rare-disease diagnoses. For clinical decision support, the output should be interpreted as a **differential diagnosis list**, not as a definitive diagnosis. The primary diagnostic evaluation in our study used a top-5 differential-diagnosis setting, reflecting the intended use of RaDaR as a tool for prioritizing a short list of diseases for clinician review.
+
+
+## Model development
+
+RaDaR was initialized from:
+
+```text
+DeepSeek-R1-Distill-Qwen-32B
+```
+
+The training corpus included:
+
+* **49,170** publicly available real-world rare-disease cases; and
+* **104,666** phenotype-anchored synthetic rare-disease cases.
+
+Training consisted of two reasoning-enhancement stages:
+
+1. **Supervised Fine-Tuning (SFT)** using rare-disease clinical narratives paired with diagnostic reasoning trajectories; and
+2. **Direct Preference Optimization (DPO)** using preferred and dispreferred diagnostic reasoning outputs.
+
+The full methodology is described in the accompanying paper. Code for phenotype sampling, synthetic-case construction, SFT, and DPO is available at: https://github.com/sczzz3/RaDaR
+
+
+## Citation
+
+If you use RaDaR in your research, please cite:
+
+```bibtex
+@article{chen2026radar,
+  title   = {A specialized reasoning large language model for accelerating rare disease diagnosis: a randomized AI physician-assistance trial},
+  author  = {Chen, Haichao and
+             Zhou, Songchi and
+             Zhao, Zhengyun and
+             Hu, Shikai and
+             Jin, Xianghong and
+             Ji, Hongwei and
+             He, Li and
+             Li, Shuli and
+             Qin, Yiming and
+             Tan, Xin and
+             Shi, Runfeng and
+             Tham, Yih Chung and
+             Zhu, Jiaye and
+             Li, Ye and
+             Jin, Ye and
+             Cao, Longhao and
+             Li, Dawei and
+             Wu, Honghan and
+             Gu, Hongqiu and
+             Li, Guanqiao and
+             Groza, Tudor and
+             Li, Chunying and
+             Zeng, Dian and
+             Yu, Weihong and
+             Baynam, Gareth and
+             Jamuar, Saumya Shekhar and
+             Shen, Min and
+             Zhang, Shuyang and
+             Sheng, Bin and
+             Yu, Sheng and
+             Wong, Tien Yin},
+  journal = {arXiv preprint arXiv:2606.24510},
+  year    = {2026},
+  url     = {https://arxiv.org/abs/2606.24510}
+}
+```