Upload README.md

README.md

@@ -1,3 +1,148 @@
 ---
-license: mit
+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