Promote handwriting-heavy hwmix adapter (QLoRA on Qwen3-VL-2B)

README.md

@@ -1,103 +1,210 @@
 ---
-license: apache-2.0
-language:
-- ar
-- fr
-- en
+base_model: unsloth/qwen3-vl-2b-instruct-unsloth-bnb-4bit
+library_name: peft
+pipeline_tag: text-generation
 tags:
-- ocr
-- arabic
-- vision-language-model
-- qwen3-vl
+- base_model:adapter:unsloth/qwen3-vl-2b-instruct-unsloth-bnb-4bit
 - lora
+- sft
+- transformers
+- trl
 - unsloth
-- text-recognition
-- handwriting-recognition
-pipeline_tag: image-to-text
-base_model: unsloth/qwen3-vl-2b-instruct-unsloth-bnb-4bit
-datasets:
-- context212/context212-alhazen-ocr
-- ahmedheakl/arocrbench_khatt
-library_name: peft
 ---
 
-# Alhazen-OCR
-
-**Alhazen-OCR** is an Arabic-first OCR vision-language model: a QLoRA adapter
-on top of **Qwen3-VL-2B-Instruct**, fine-tuned on
-[`context212/context212-alhazen-ocr`](https://huggingface.co/datasets/context212/context212-alhazen-ocr)
-— a license-clean mix of Arabic synthetic documents, invoices, and handwritten
-text (KHATT).
-
-Named after **Ibn al-Haytham (Alhazen)**, the 11th-century pioneer of optics.
-
-## Benchmark
-
-Evaluated with CER/WER (lower is better) on the held-out eval split of the
-training data and on the external
-[`ahmedheakl/arocrbench_khatt`](https://huggingface.co/datasets/ahmedheakl/arocrbench_khatt)
-benchmark (100 samples each, greedy decoding):
-
-| Model | Eval CER ↓ | Eval WER ↓ | KHATT-bench CER ↓ | KHATT-bench WER ↓ |
-|---|---|---|---|---|
-| Qwen3-VL-2B-Instruct (base) | 0.653 | 0.951 | 1.498 | 1.594 |
-| **Alhazen-OCR** | **0.368** | **0.567** | 2.761 | 1.707 |
-
-**Reading the numbers:** fine-tuning cuts character errors nearly in half on
-in-distribution documents (0.65 → 0.37 CER) and word errors from 0.95 → 0.57.
-On the external KHATT handwriting benchmark the model still struggles — this
-is a first smoke run on 20k samples; scaling data and training is expected to
-close the gap. Published as a work-in-progress baseline.
-
-## Usage
-
-```python
-import torch
-from unsloth import FastVisionModel
-
-model, tokenizer = FastVisionModel.from_pretrained(
-    "context212/alhazen-ocr",
-    load_in_4bit=True,
-)
-FastVisionModel.for_inference(model)
-
-messages = [{
-    "role": "user",
-    "content": [
-        {"type": "image", "image": image},  # a PIL.Image
-        {"type": "text", "text": "Extract all the text from this image, preserving the original reading order."},
-    ],
-}]
-inputs = tokenizer.apply_chat_template(
-    messages, tokenize=True, add_generation_prompt=True,
-    return_dict=True, return_tensors="pt",
-).to(model.device)
-
-with torch.inference_mode():
-    out = model.generate(**inputs, max_new_tokens=512, temperature=0.0, do_sample=False)
-print(tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
-```
-
-## Training
-
-- **Base:** `unsloth/Qwen3-VL-2B-Instruct` (4-bit)
-- **Method:** QLoRA via [unsloth](https://github.com/unslothai/unsloth) —
-  r=16, rsLoRA, vision + language layers (17.4M trainable params, 0.81%)
-- **Data:** 20,000 samples from `context212/context212-alhazen-ocr`
-  (60% synthetic documents, 20% invoices, 20% handwriting)
-- **Schedule:** 1 epoch, lr 2e-5, cosine, bf16, batch 16, seq 2048 —
-  single A100 80GB, ~35 min
-- **Checkpoint selection:** per-epoch eval on held-out split + external
-  benchmark; epoch 1 won (later epochs diverge — see the repo for details)
-
-## Data sources & licenses
-
-| Source | License |
-|---|---|
-| `loay/arabic-ocr-synthetic-scans-faker-300k` | CC-BY-4.0 |
-| `KhalfounMehdi/arabic-latin-invoices-synthetic` | CC-BY-4.0 |
-| `johnlockejrr/KHATT_v1.0_dataset` | MIT |
-| `sherif1313/Historical-Arabic-Handwritten-OCR` | Apache-2.0 |
-
-Eval benchmark: `ahmedheakl/arocrbench_khatt` (MIT).
+# Model Card for Model ID
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+
+
+- **Developed by:** [More Information Needed]
+- **Funded by [optional]:** [More Information Needed]
+- **Shared by [optional]:** [More Information Needed]
+- **Model type:** [More Information Needed]
+- **Language(s) (NLP):** [More Information Needed]
+- **License:** [More Information Needed]
+- **Finetuned from model [optional]:** [More Information Needed]
+
+### Model Sources [optional]
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** [More Information Needed]
+- **Paper [optional]:** [More Information Needed]
+- **Demo [optional]:** [More Information Needed]
+
+## Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+[More Information Needed]
+
+### Downstream Use [optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+[More Information Needed]
+
+### Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+
+[More Information Needed]
+
+## Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+[More Information Needed]
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+
+## How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+[More Information Needed]
+
+## Training Details
+
+### Training Data
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+[More Information Needed]
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+#### Preprocessing [optional]
+
+[More Information Needed]
+
+
+#### Training Hyperparameters
+
+- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+
+#### Speeds, Sizes, Times [optional]
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+[More Information Needed]
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+
+
+## Model Examination [optional]
+
+<!-- Relevant interpretability work for the model goes here -->
+
+[More Information Needed]
+
+## Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** [More Information Needed]
+- **Hours used:** [More Information Needed]
+- **Cloud Provider:** [More Information Needed]
+- **Compute Region:** [More Information Needed]
+- **Carbon Emitted:** [More Information Needed]
+
+## Technical Specifications [optional]
+
+### Model Architecture and Objective
+
+[More Information Needed]
+
+### Compute Infrastructure
+
+[More Information Needed]
+
+#### Hardware
+
+[More Information Needed]
+
+#### Software
+
+[More Information Needed]
+
+## Citation [optional]
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+[More Information Needed]
+
+**APA:**
+
+[More Information Needed]
+
+## Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+[More Information Needed]
+
+## More Information [optional]
+
+[More Information Needed]
+
+## Model Card Authors [optional]
+
+[More Information Needed]
+
+## Model Card Contact
+
+[More Information Needed]
+### Framework versions
 
+- PEFT 0.20.0

adapter_config.json

@@ -35,13 +35,13 @@
   "rank_pattern": {},
   "revision": null,
   "target_modules": [
-    "q_proj",
     "down_proj",
+    "q_proj",
     "k_proj",
-    "v_proj",
-    "gate_proj",
     "o_proj",
-    "up_proj"
+    "up_proj",
+    "v_proj",
+    "gate_proj"
   ],
   "target_parameters": null,
   "task_type": "CAUSAL_LM",

adapter_model.safetensors

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:033c8c8b58aa68a7e7ec2cbd0ea88a1ebac2f0dbf2bf6bc5a12482f11f8ba847
+oid sha256:cde83aede9363875edac105a90b5c7c0dc1358244792643b42eecbfc9e32bf10
 size 69788264