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

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 Sahabat-AI Gemma 2 9B (LoRA BF16, 5 Epochs) — 🥇 Top Performer:

• Total Kasus Teruji: 52 / 52 Kasus (100.0%)
• Kelengkapan Pertimbangan Hukum: 51 / 52 Kasus (98.1%)
• Kelengkapan Amar Putusan: 51 / 52 Kasus (98.1%)
• Kesesuaian Vonis Yuridis (Verdict Alignment): 82.7% (43 dari 52 kasus vonisnya selaras dengan putusan riil)
• Skor ROUGE:
  • ROUGE-1: 0.658
  • ROUGE-2: 0.448
  • ROUGE-L: 0.471
  • ROUGE-L [AMAR PUTUSAN]: 0.693
• 📂 Unduh Hasil Evaluasi Sahabat-AI Gemma 2 9B:
  • samples.csv
  • samples.jsonl

Hasil Qwen 2.5 7B-Instruct (LoRA BF16, 5 Epochs):

• Total Kasus Teruji: 52 / 52 Kasus (100.0%)
• Kelengkapan Pertimbangan Hukum: 47 / 52 Kasus (90.4%)
• Kelengkapan Amar Putusan: 47 / 52 Kasus (90.4%)
• Kesesuaian Vonis Yuridis: 69.2% (36/52 cocok)
• Skor ROUGE: ROUGE-1 0.567, ROUGE-2 0.342, ROUGE-L 0.355
• 📂 Unduh Hasil Evaluasi Qwen 2.5 7B:
  • samples.csv
  • samples.jsonl

Hasil Qwen 3.5 9B (LLaMA-Factory Format, 5 Epochs):

• Total Kasus Teruji: 52 / 52 Kasus (100.0%)
• Kelengkapan Format Putusan: 82.7%
• Kesesuaian Vonis Yuridis: 44.2% (23/52 cocok)
• Skor ROUGE: ROUGE-1 0.384, ROUGE-2 0.182, ROUGE-L 0.200
• 📂 Unduh Hasil Evaluasi Qwen 3.5 9B:
  • 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}}
}