ruwwww/faruq-alignment-models

Faruq IndoLaw Alignment Models ⚖️🇮🇩

Koleksi checkpoint model dan LoRA adapters untuk penalaran hukum pidana Indonesia berbasis putusan peradilan tingkat pertama Mahkamah Agung Republik Indonesia. Proyek riset ini mengevaluasi adaptasi domain peradilan (Supervised Fine-Tuning & QLoRA) dari model berskala ringan (1.5B/3B) hingga skala besar (12B, 27B, dan 31B) untuk menyusun pertimbangan hukum (ratio decidendi) dan amar putusan (dictum) yang setia pada fakta persidangan dan patuh pada asas pembuktian Pasal 184 KUHAP.

Repository ini diorganisasikan sebagai satu project induk bertingkat (multi-folder model repository), di mana setiap arsitektur model, checkpoint per-epoch, dan artefak evaluasi dikelompokkan ke dalam subdirektori masing-masing.

🔗 Source Code & Research Repository: ADDI-LAW/faruq-project (GitHub)

---

🏆 Model Matrix & Benchmark Kinerja

Subfolder Model	Arsitektur Basis	Metode & Precision	Epochs	Train Loss	Eval Loss	Hasil Uji 52 Kasus
models/sft-v2-gemma4-31b-5epoch	Google Gemma 4 31B It	4-bit QLoRA (NF4)	5 ep	0.6541	0.6427 (best 0.6361)	100% Pertimbangan | 94.2% Amar
models/sft-v2-qwen38-27b-5epoch	Qwen 3.8 27B	4-bit QLoRA (NF4)	5 ep	0.7156	0.6246	Evaluated (Internal CoT Reasoning)
models/sft-v2-gemma4-12b-5epoch	Google Gemma 4 12B It	4-bit QLoRA (NF4)	5 ep	0.7632	0.6980 (best 0.6965)	98.1% Pertimbangan | 92.3% Amar
models/sft-v2-qwen35-9b-5epoch	Qwen 3.5 9B	LoRA (BF16)	5 ep	0.6865	0.6288	Checkpoints ready
models/sft-v2-3b-5epoch	Qwen 2.5 3B	LoRA (BF16)	5 ep	0.5478	0.5752	Baseline 3B Canonical
models/sft-v2-5epoch	Qwen 2.5 1.5B	LoRA (BF16)	5 ep	0.5520	0.5520	Baseline 1.5B Canonical

Catatan Checkpoint Per-Epoch:
Setiap model menyimpan checkpoint intermediate lengkap per epoch di subfolder checkpoints/epoch-1 sampai epoch-5 (termasuk bobot adapter, resep YAML, dan file metrics).

---

📊 Hasil Evaluasi Empiris (52 Test Cases Benchmark)

Evaluasi formal dilakukan terhadap 52 kasus uji yuridis yang belum pernah dilihat model (artifacts/sft_v2/test.jsonl), mencakup dakwaan lengkap dan fakta persidangan riil. Model dievaluasi kemampuannya dalam memproduksi dua komponen mutlak putusan hakim:

1. [PERTIMBANGAN HUKUM]: Telaah fakta persidangan, pemenuhan unsur dakwaan, dan pembuktian barang bukti.
2. [AMAR PUTUSAN]: Diktum putusan (Menyatakan Terdakwa terbukti/tidak, penjatuhan pidana, pengurangan masa tahanan, status barang bukti, dan beban biaya perkara).

Hasil Gemma 4 31B (4-bit QLoRA, 5 Epochs):

• Total Kasus Teruji: 52 / 52 Kasus (100.0%)
• Kelengkapan Pertimbangan Hukum: 52 / 52 Kasus (100.0%)
• Kelengkapan Amar Putusan: 49 / 52 Kasus (94.2%)
• Rata-rata Panjang Output: 1.691,4 token / putusan
• Throughput Inferensi (A100-SXM4-40GB): ~18,2 token/detik (Batched 4-bit NF4)

Distribusi Kategori Perkara yang Diuji:

• Narkotika (UU No. 35/2009): 30 kasus
• Pencurian (Pasal 362/363 KUHP): 10 kasus
• Informasi & Transaksi Elektronik / ITE: 4 kasus
• Perlindungan Anak: 2 kasus
• Penipuan (Pasal 378 KUHP): 2 kasus
• Pidana Umum Lainnya: 2 kasus
• Penggelapan (Pasal 372 KUHP): 1 kasus
• Perjudian (Pasal 303 KUHP): 1 kasus

📂 Unduh Hasil Evaluasi Gemma 4 31B:

• samples.csv (Tabel lengkap 52 kasus dengan metrik dan hasil putusan)
• samples.jsonl (Format JSON Lines untuk evaluasi otomatis)

Hasil Qwen 3.8 27B (4-bit QLoRA, 5 Epochs):

• Karakteristik Generasi: Sebagai model berbasis arsitektur reasoning / thinking, Qwen 3.8 27B menghasilkan analisis penalaran beruntun mendalam (Chain-of-Thought) secara ekstensif sebelum menyusun formulasi putusan akhir.
• Panjang Output: Rata-rata 2.048 token per kasus (mencapai batas budget konteks generasi per batch).
• 📂 Unduh Hasil Evaluasi Qwen 3.8 27B: samples.csv | samples.jsonl

Hasil Gemma 4 12B IT (4-bit QLoRA, 5 Epochs):

• Total Kasus Teruji: 52 / 52 Kasus (100.0%)
• Kelengkapan Pertimbangan Hukum: 51 / 52 Kasus (98.1%)
• Kelengkapan Amar Putusan: 48 / 52 Kasus (92.3%)
• Rata-rata Panjang Output: 1.680,2 token / putusan
• Throughput Inferensi (A100-SXM4-40GB): ~30,3 token/detik (Batched 4-bit NF4, Batch Size 4, Selesai dalam 48 menit)
• 📂 Unduh Hasil Evaluasi Gemma 4 12B: samples.csv | samples.jsonl

---

🚀 Panduan Penggunaan & Contoh Kode

Gunakan library transformers dan peft dengan menyertakan argumen subfolder:

Contoh 1: Inferensi Gemma 4 31B (4-bit NF4)

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import PeftModel

repo_id = "ruwwww/faruq-alignment-models"
base_model_id = "google/gemma-4-31B-it"
subfolder = "models/sft-v2-gemma4-31b-5epoch"

# 1. Kuantisasi 4-bit BitsAndBytes (Hanya butuh ~18 GB VRAM)
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16
)

tokenizer = AutoTokenizer.from_pretrained(base_model_id, padding_side="left")
base_model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    quantization_config=bnb_config,
    device_map="auto"
)

# 2. Pasang LoRA Adapter dari Subfolder HF
model = PeftModel.from_pretrained(base_model, repo_id, subfolder=subfolder)
model.eval()

# 3. Format Prompt Hukum
messages = [
    {
        "role": "system",
        "content": (
            "Anda adalah asisten hukum Indonesia. Gunakan hanya dakwaan dan fakta persidangan yang diberikan. "
            "Susun pertimbangan hukum yang ringkas dan amar putusan secara setia pada sumber."
        ),
    },
    {
        "role": "user",
        "content": (
            "[SURAT DAKWAAN]\n"
            "Bahwa terdakwa didakwa melanggar Pasal 372 KUHP tentang Penggelapan karena telah memindahtangankan "
            "sepeda motor sewaan tanpa seizin pemiliknya.\n\n"
            "[FAKTA PERSIDANGAN & ALAT BUKTI]\n"
            "Saksi korban menerangkan terdakwa menyewa motor selama 3 hari namun tidak dikembalikan dan digadaikan. "
            "Terdakwa mengakui uang gadai digunakan untuk kepentingan pribadi."
        ),
    },
]

chat_prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(chat_prompt, return_tensors="pt").to(model.device)

# 4. Generate Pertimbangan & Amar Putusan
with torch.inference_mode():
    outputs = model.generate(
        **inputs,
        max_new_tokens=1536,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
        repetition_penalty=1.05,
        pad_token_id=tokenizer.pad_token_id,
        eos_token_id=[tokenizer.eos_token_id, 106],  # ID 106 = <turn|>
    )

completion = tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(completion)

---

Contoh 2: Inferensi Qwen 3.8 27B / Qwen 2.5 3B

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

repo_id = "ruwwww/faruq-alignment-models"
base_model_id = "Qwen/Qwen3.8-27B"
subfolder = "models/sft-v2-qwen38-27b-5epoch"

tokenizer = AutoTokenizer.from_pretrained(repo_id, subfolder=subfolder)
base_model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto"
)
model = PeftModel.from_pretrained(base_model, repo_id, subfolder=subfolder)
model.eval()

---

🛠️ Konfigurasi Pelatihan & Dataset

Pelatihan dilaksanakan di atas GPU cluster NVIDIA A100-SXM4-40GB:

• Dataset: 1.125 putusan pidana inkrah (Train), 64 validasi, 52 kasus uji riil Mahkamah Agung RI.
• Panjang Konteks Maksimum: 4.096 token (mencegah terpotongnya telaah dakwaan dan saksi).
• Completion-Only Loss Masking: Gradien hanya dihitung pada segmen jawaban asisten ([PERTIMBANGAN HUKUM] dan [AMAR PUTUSAN]), tidak menghafal teks prompt.
• LoRA Setup:
  • Rank ($r$): 16, Alpha ($\alpha$): 32, Dropout: 0.05
  • Target Modules: [q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj]
  • Optimizer: AdamW dengan learning rate $1\times 10^{-4}$ (cosine scheduler).

---

📜 Sitasi

@misc{faruq2026indolaw,
  author    = {Faruq and contributors},
  title     = {IndoLaw Alignment: Supervised Fine-Tuning and Preference Alignment on Indonesian Supreme Court Decisions},
  year      = {2026},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/ruwwww/faruq-alignment-models}}
}