README.md

---
base_model: Qwen/Qwen2.5-1.5B-Instruct
library_name: peft
pipeline_tag: text-generation
tags:
- base_model:adapter:Qwen/Qwen2.5-1.5B-Instruct
- lora
- qlora
- transformers
- peft
- medical
---

# MediGuide QLoRA

MediGuide is a fine-tuned medical conversational assistant based on `Qwen/Qwen2.5-1.5B-Instruct`.

This repository contains the **QLoRA adapter weights** trained for the MediGuide project. The base Qwen model is not included and must be loaded separately.

## Model Details

- **Base model:** `Qwen/Qwen2.5-1.5B-Instruct`
- **Fine-tuning method:** QLoRA
- **PEFT method:** LoRA
- **LoRA rank:** 16
- **LoRA alpha:** 32
- **LoRA dropout:** 0.05
- **Task:** Medical dialogue generation
- **Framework:** Hugging Face Transformers + PEFT
- **PEFT version:** 0.20.0
- **License:** See the base model's license and the MediGuide project repository for applicable terms.

## Intended Use

This adapter is intended for research and educational experimentation with medical dialogue generation and parameter-efficient fine-tuning.

It is not intended to replace a qualified healthcare professional, provide definitive diagnoses, or make medical decisions.

## Out-of-Scope Use

Do not use this model as an autonomous clinical decision-maker, for emergency medical guidance, or as a substitute for professional medical advice.

## Training

The adapter was trained on the cleaned MediDialog-derived MediGuide dataset used in the project.

The project uses an 80/10/10 train/validation/test split and compares multiple parameter-efficient fine-tuning approaches, including LoRA, QLoRA, and Prompt Tuning.

### QLoRA Configuration

The adapter targets:

- `q_proj`
- `k_proj`
- `v_proj`
- `o_proj`
- `gate_proj`
- `up_proj`
- `down_proj`

The adapter configuration uses `r=16`, `alpha=32`, and `dropout=0.05`.

## Evaluation

On the MediGuide evaluation setup, QLoRA achieved:

| Metric | QLoRA |
|---|---:|
| ROUGE-1 | 0.1319 |
| ROUGE-2 | 0.0269 |
| ROUGE-L | 0.1319 |
| BLEU | 2.40 |
| Perplexity | 14.65 |

These results come from the project's current evaluation setup and should not be interpreted as clinical performance benchmarks.

## How to Use

Install the required packages:

```bash
pip install transformers peft torch
```

Load the base model and adapter:

```python
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

base_model_id = "Qwen/Qwen2.5-1.5B-Instruct"
adapter_id = "rolmaxx/MediGuide-QLoRA"

tokenizer = AutoTokenizer.from_pretrained(base_model_id)

model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    torch_dtype=torch.float16,
    device_map="auto"
)

model = PeftModel.from_pretrained(model, adapter_id)

prompt = "What are common symptoms of the flu?"

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=256,
        temperature=0.7,
        do_sample=True
    )

print(tokenizer.decode(outputs[0], skip_special_tokens=True))
```

## Repository

GitHub: https://github.com/lxzy8/MediGuide

## Files

- `adapter_config.json` — PEFT/LoRA adapter configuration
- `adapter_model.safetensors` — trained adapter weights

The base Qwen model is not included in this repository.

## Limitations

The model was trained on a relatively small dataset and evaluated using automated text-generation metrics. Automated metrics such as ROUGE and BLEU do not establish medical correctness, safety, or clinical usefulness.

Model outputs may contain incorrect, incomplete, or unsafe medical information. Human review is required for any real-world medical application.

## Citation

If you use this adapter in your work, please cite the MediGuide project repository:

```text
MediGuide — QLoRA fine-tuned medical conversational assistant.
https://github.com/lxzy8/MediGuide
```

## Framework Versions

- PEFT: 0.20.0