zidanmubarak/jawi-qwen25-vl-qlora

Jawi OCR & Transliteration Model (Qwen2.5-VL-3B QLoRA)

Model Details

Model Description

Model ini adalah model Vision-Language (VLM) yang telah di- fine-tune secara khusus untuk melakukan dua tugas utama secara berurutan pada gambar teks cetak berbahasa Melayu/Indonesia:

1. Ekstraksi Teks (OCR): Membaca aksara Jawi (huruf Arab gundul/berharkat) dari sebuah gambar dengan tingkat akurasi tinggi.
2. Transliterasi: Mengonversi teks Jawi hasil ekstraksi tersebut menjadi huruf Latin (Rumi) berdasarkan standar Pedoman Ejaan Jawi Yang Disempurnakan (PEJYD) oleh Dewan Bahasa dan Pustaka.

Model ini dilatih menggunakan metode QLoRA (Parameter-Efficient Fine-Tuning) di atas arsitektur dasar Qwen2.5-VL-3B-Instruct. Pelatihan (Ablation Study Skenario C) menggunakan kombinasi dataset sintetik dan data manuskrip/dokumen autentik, menjadikannya sangat tangguh dalam menangani berbagai variasi font Jawi cetak.

• Developed by: Zidan Mubarak (sebagai bagian dari penelitian Skripsi)
• Model type: Vision-Language Causal LM (Qwen2.5-VL) + LoRA Adapter
• Language(s) (NLP): Melayu (ms), Indonesia (id), Arab (ar - khusus aksara Jawi)
• License: Apache 2.0
• Finetuned from model: Qwen/Qwen2.5-VL-3B-Instruct

Model Sources

• Demo (Hugging Face Space): Jawi Transliterasi Demo
• Repository: zidanmubarak/jawi-qwen25-vl-qlora

Uses

Direct Use

Model ini dirancang untuk langsung digunakan oleh:

• Peneliti linguistik, sejarawan, atau filolog yang ingin mendigitalisasi dokumen Jawi klasik/modern.
• Pengembang aplikasi edukasi atau penerjemah otomatis dokumen Jawi ke Rumi.
• Masyarakat umum yang ingin membaca literatur cetak Jawi kuno ke dalam tulisan Latin yang lebih familier.

Pengguna cukup memberikan gambar berisi teks Jawi beserta prompt instruksi standar, dan model akan mengembalikan teks Jawi sekaligus hasil transliterasinya.

Out-of-Scope Use

• Tulisan Tangan (Handwritten): Model ini dioptimalkan untuk Jawi Cetak (Printed/Typeset). Performa pada manuskrip tulisan tangan kursif yang sangat usang mungkin mengalami penurunan (meskipun sebagian data autentik telah disertakan).
• Penerjemahan Makna: Model ini melakukan transliterasi (konversi karakter/fonetis), bukan penerjemahan makna antar bahasa. Jika teks aslinya adalah bahasa Melayu klasik, hasil Rumi-nya tetap bahasa Melayu klasik.

Bias, Risks, and Limitations

• Akurasi model sangat bergantung pada kualitas resolusi gambar yang diberikan. Gambar yang buram, terpotong, atau memiliki noise latar belakang yang parah dapat meningkatkan rasio Character Error Rate (CER).
• Aturan PEJYD memiliki beberapa pengecualian linguistik yang kompleks (seperti kata serapan Arab vs kata dasar Melayu). Model mungkin sesekali melakukan kesalahan ejaan Rumi pada kata-kata serapan yang sangat jarang (Out-of-Vocabulary).

Recommendations

Pengguna disarankan untuk memproses gambar dengan pencahayaan dan kontras yang baik. Untuk digitalisasi dokumen arsip resmi, hasil keluaran Rumi dari model ini sebaiknya tetap ditinjau ulang oleh ahli bahasa (Human-in-the-loop) sebelum dipublikasikan.

How to Get Started with the Model

Untuk menjalankan model ini, Anda membutuhkan pustaka transformers, peft, dan qwen-vl-utils. Sangat disarankan untuk menjalankan model ini dalam format bfloat16 atau 4-bit menggunakan GPU.

import torch
from PIL import Image
from peft import PeftModel
from qwen_vl_utils import process_vision_info
from transformers import AutoProcessor, Qwen2_5_VLForConditionalGeneration

BASE_MODEL = "Qwen/Qwen2.5-VL-3B-Instruct"
ADAPTER_ID = "zidanmubarak/jawi-qwen25-vl-qlora"

# 1. Load Base Model dan Processor
base = Qwen2_5_VLForConditionalGeneration.from_pretrained(
    BASE_MODEL,
    device_map="auto",
    torch_dtype=torch.bfloat16,
)
model = PeftModel.from_pretrained(base, ADAPTER_ID)
model.eval()
processor = AutoProcessor.from_pretrained(ADAPTER_ID)

# 2. Siapkan Gambar dan Prompt
SYSTEM_PROMPT = (
    "Anda adalah sistem multimodal untuk ekstraksi dan transliterasi aksara Jawi cetak. "
    "Tugas Anda terdiri dari dua langkah yang harus dilakukan secara berurutan:\\n"
    "1. Ekstraksi: Baca gambar dan ekstrak teks aksara Jawi (huruf Arab) yang tertulis "
    "pada gambar secara akurat, persis seperti yang tertulis.\\n"
    "2. Transliterasi: Konversi teks Jawi yang telah diekstrak ke huruf Latin (Rumi) "
    "sesuai pedoman Ejaan Jawi Yang Disempurnakan (PEJYD) oleh Dewan Bahasa dan Pustaka Malaysia.\\n\\n"
    "ATURAN OUTPUT:\\n"
    "- Keluarkan hasil dalam format berikut secara tepat:\\n"
    "  Jawi: [teks aksara Arab hasil ekstraksi]\\n"
    "  Rumi: [teks Latin hasil transliterasi]\\n"
    "- Jangan menambahkan penjelasan, komentar, atau teks lain di luar format tersebut.\\n"
    "- Transliterasi bersifat karakter ke karakter, bukan penerjemahan makna."
)

image = Image.open("contoh_jawi.jpg").convert("RGB")
messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": [
        {"type": "image", "image": image},
        {"type": "text", "text": "Ekstrak teks aksara Jawi dari gambar ini, kemudian transliterasikan ke huruf Latin (Rumi)."},
    ]},
]

# 3. Proses Inferensi
text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
image_inputs, _ = process_vision_info(messages)
inputs = processor(text=[text], images=image_inputs, padding=True, return_tensors="pt").to("cuda")

with torch.no_grad():
    generated = model.generate(**inputs, max_new_tokens=1024, do_sample=False)

trimmed = [out[len(inp):] for inp, out in zip(inputs.input_ids, generated)]
output_text = processor.batch_decode(trimmed, skip_special_tokens=True)[0].strip()
print(output_text)

Training Details

Training Data

Model ini dilatih menggunakan dua jenis dataset yang dikurasi secara manual dan di- generate secara komputasional:

1. Data Sintetik: Teks Jawi yang di- generate menggunakan berbagai macam font Arab/Jawi standar komputer (seperti font Jawi Uthman Taha, Arabic Typesetting, dll) untuk memperkaya pemahaman dasar karakter.
2. Data Autentik (Real-world): Potongan gambar dari buku, koran, dan dokumen sejarah berbahasa Melayu beraksara Jawi asli.

Pelatihan Ablation Study membuktikan bahwa pencampuran data sintetik dan autentik (Skenario C) memberikan generalisasi terbaik dibandingkan hanya dilatih pada satu jenis data saja.

Training Procedure

Pelatihan dilakukan menggunakan pustaka Unsloth untuk mempercepat proses kalkulasi dan mengurangi penggunaan memori VRAM secara signifikan.

Training Hyperparameters

• Training regime: QLoRA (4-bit NF4 Quantization pada Base Model) dengan mixed precision bfloat16.
• Optimizer: AdamW (8-bit paged optimizer)
• Gradient Checkpointing: Unsloth optimized

Evaluation

Testing Data, Factors & Metrics

Evaluasi akhir (Mega Evaluasi) dilakukan pada subset 10% Data Autentik yang sama sekali tidak pernah dilihat oleh model selama proses training (Unseen Data).

Metrics

Tiga metrik utama digunakan untuk mengukur keandalan sistem:

1. CER Jawi (Character Error Rate): Mengukur ketepatan ejaan saat mengekstrak aksara Arab/Jawi dari gambar.
2. CER Rumi: Mengukur ketepatan ejaan hasil transliterasi huruf Latin per karakter.
3. WER Rumi (Word Error Rate): Mengukur tingkat pemahaman kata secara utuh pada hasil transliterasi.

Results

Ablation Study membuktikan bahwa integrasi LoRA berhasil menurunkan tingkat kesalahan secara drastis dibandingkan dengan kemampuan dasar (Zero-Shot) dari Qwen2.5-VL asli.

Skenario Model	CER Jawi	CER Rumi	WER Rumi
Baseline (Qwen Asli Zero-Shot)	82.51%	90.59%	107.08%
Model Final (Skenario C - Epoch 3)	17.35%	16.48%	39.36%
Persentase Penurunan Error	↓ 79%	↓ 82%	↓ 63%

Summary

Performa model dalam mengekstrak dan mentransliterasi Jawi cetak mengalami lompatan raksasa. Model mampu menekan Character Error Rate untuk ekstraksi maupun transliterasi hingga di bawah batas ambang wajar (berkisar ~16%), menandakan bahwa model sudah sangat adaptif dalam membaca font Jawi nyata.

Environmental Impact

Pelatihan model dijalankan dengan optimasi tingkat tinggi menggunakan pustaka Unsloth yang memangkas waktu komputasi hingga 2x lebih cepat, secara signifikan mengurangi jejak karbon dibandingkan pelatihan full-parameter tradisional.

• Hardware Type: NVIDIA Tesla T4 / A100 (Google Colab)
• Cloud Provider: Google Cloud (via Colab)
• Compute Region: Dinamis (Global)

Framework versions

• PEFT 0.19.1
• Transformers 4.56.2
• Unsloth 2026.6.7
• Torch 2.11.0+cu128