Klinexa EL1.md

README_KLINEXA_EL1.md

@@ -0,0 +1,352 @@
+---
+license: apache-2.0
+language:
+  - id
+tags:
+  - health
+  - medical
+  - indonesia
+  - native-llm
+  - from-scratch
+  - klinexa
+pipeline_tag: text-generation
+---
+
+# KLINEXA-EL1 — Kei Local Intelligence for Nexus Expert Analysis (Edition Level 1)
+
+> **Native Indonesian Medical LLM — dibangun dari NOL (from scratch)**
+> Dibuat oleh **Emylton Leunufna** di Kota Langgur, Kabupaten Maluku Tenggara, Provinsi Maluku, Indonesia.
+
+---
+
+## Tentang KLINEXA
+
+**KLINEXA** (**K**ei **L**ocal **I**ntelligence for **N**exus **Ex**pert **A**nalysis) adalah proyek LLM native Indonesia yang dibangun sepenuhnya dari nol — bukan fine-tune dari model lain. Seluruh arsitektur, tokenizer, dan training pipeline dirancang sendiri oleh Emylton Leunufna.
+
+### Varian KLINEXA
+
+| Model | Domain | Deskripsi |
+|-------|--------|-----------|
+| **KLINEXA-EL1** | Kesehatan Indonesia (umum) | Model utama. Dilatih dengan 500K+ data medis Indonesia: clinical reasoning, diagnosis, tatalaksana, farmakologi, SOAP, interaksi obat, dll. |
+| **KLINEXA-EL1-Malra** | Kesehatan Kabupaten Maluku Tenggara | Versi spesialis untuk Kabupaten Maluku Tenggara (Malra). Berisi data puskesmas, rumah sakit, penyakit endemik, statistik kesehatan, SDM kesehatan, dan geografi spesifik Malra. |
+| **KLINEXA-EL2** *(dalam pengembangan)* | Multi-domain + Crystal Architecture | Arsitektur lanjutan dengan Crystal ARM (modular knowledge storage). Target 1.55B parameters. |
+
+> **Catatan penting:** KLINEXA-EL1 awalnya hanya untuk domain kesehatan Kabupaten Maluku Tenggara. Pada versi v10, cakupan **ditingkatkan menjadi domain kesehatan Indonesia secara umum** menggunakan dataset 500K clinical reasoning. Versi spesifik Maluku Tenggara sekarang menjadi **KLINEXA-EL1-Malra**.
+
+---
+
+## Spesifikasi Model
+
+| Parameter | Nilai |
+|-----------|-------|
+| **Nama** | KLINEXA-EL1 |
+| **Versi** | v10 (Full Fix) |
+| **Total Parameters** | 271.1M |
+| **Layers** | 16 |
+| **Hidden Dimension** | 1024 |
+| **Attention Heads** | 16 |
+| **Head Dimension** | 64 |
+| **FFN Dimension** | 2816 |
+| **Vocabulary** | 32,000 (BPE) |
+| **Context Length** | 1,024 tokens |
+| **Activation** | SwiGLU |
+| **Normalization** | RMSNorm |
+| **Position Encoding** | RoPE (Rotary Position Embedding) |
+| **Weight Tying** | Ya (tok_emb = lm_head) |
+| **Dropout** | 0.1 |
+| **Gradient Checkpointing** | Ya |
+| **Precision** | FP16 (training), FP32 (inference) |
+| **Built From** | Scratch (bukan fine-tune) |
+
+---
+
+## Arsitektur
+
+```
+Input Tokens
+    ↓
+[Embedding] (tok_emb: 32000 × 1024) + Dropout(0.1)
+    ↓
+[Transformer Block × 16]
+    ├── RMSNorm → CausalSelfAttention (16 heads, RoPE) → Dropout
+    └── RMSNorm → SwiGLU FFN (1024 → 2816 → 1024) → Dropout
+    ↓
+[RMSNorm]
+    ↓
+[LM Head] (1024 → 32000, weight tied with embedding)
+    ↓
+Output Logits
+```
+
+Setiap Transformer Block menggunakan **gradient checkpointing** untuk menghemat VRAM saat training.
+
+### Komponen Kunci
+
+- **RMSNorm**: Normalisasi yang lebih efisien dari LayerNorm
+- **RoPE**: Rotary Position Embedding — encoding posisi tanpa learned parameters
+- **SwiGLU**: `SiLU(W1·x) * W3·x` → `W2·...` — FFN dengan gating
+- **Weight Tying**: Embedding dan LM head berbagi weight matrix yang sama
+- **Causal Mask**: Lower-triangular mask untuk autoregressive generation
+
+---
+
+## Format Token (KRITIS — Harus Diikuti!)
+
+### Format Training
+
+```
+[BOS][USER] question_tokens [ASST] answer_tokens [EOS] [PAD...]
+```
+
+Dengan token ID:
+| Token | ID | Keterangan |
+|-------|-----|------------|
+| `<pad>` | 0 | Padding |
+| `<bos>` | 2 | Begin of Sequence |
+| `<eos>` | 3 | End of Sequence |
+| `<user>` | 5 | Awal pertanyaan user (SINGLE TOKEN) |
+| `<assistant>` | 6 | Awal jawaban assistant (SINGLE TOKEN) |
+
+### Label Masking
+
+```
+Input:  [BOS][USER] q1 q2 q3 [ASST] a1 a2 a3 [EOS] [PAD] [PAD]
+Labels: [-100][-100][-100][-100][-100][-100] a1 a2 a3 [EOS] [-100] [-100]
+                   ^^^^^^^^^^^^^^^^^^^^^^^^         ^^^^^^^^^^^^^^^^
+                   prompt (di-mask, tidak di-train)  answer (di-train)
+```
+
+- **Prompt** (BOS + USER + question + ASST) → di-mask dengan `-100`
+- **Answer** (answer tokens + EOS) → yang di-train
+- **Padding** → di-mask dengan `-100`
+
+### Format Inference
+
+```python
+# BENAR:
+input_ids = [BOS_ID, USER_ID] + tokenize(question) + [ASST_ID]
+
+# SALAH (JANGAN PAKAI):
+# "<user>\nquestion\n</user>\n<assistant>\n"  ← format ini TIDAK DIKENALI model
+# "[BOS][SYS]system_prompt[USER]..."          ← model tidak dilatih dengan [SYS]
+```
+
+> **PERINGATAN**: Model HANYA mengenal format `[BOS][USER]...[ASST]`. Menggunakan format lain (termasuk `<user>...</user><assistant>` sebagai teks, atau menambahkan system prompt) akan menghasilkan output yang rusak/acak.
+
+---
+
+## Tokenizer
+
+- **Tipe**: BPE (Byte-Pair Encoding)
+- **Library**: `tokenizers` (HuggingFace tokenizers, BUKAN `transformers.PreTrainedTokenizerFast`)
+- **Vocab size**: 32,000
+- **File**: `klinexa_tokenizer.json`
+
+### Cara Load
+
+```python
+from tokenizers import Tokenizer as TokLoader
+
+tok = TokLoader.from_file("klinexa_tokenizer.json")
+PAD_ID = tok.token_to_id("<pad>")    # 0
+BOS_ID = tok.token_to_id("<bos>")    # 2
+EOS_ID = tok.token_to_id("<eos>")    # 3
+USER_ID = tok.token_to_id("<user>")  # 5
+ASST_ID = tok.token_to_id("<assistant>")  # 6
+```
+
+> **PENTING**: Gunakan `tokenizers.Tokenizer`, BUKAN `transformers.PreTrainedTokenizerFast`. Alasan: `PreTrainedTokenizerFast` meng-encode `</user>` menjadi 3 token `[10587, 7722, 37]` (bukan special token), yang akan merusak label masking.
+
+---
+
+## Dataset Training
+
+### KLINEXA-EL1 v10 (Domain Kesehatan Indonesia)
+
+| Sumber | Jumlah | Deskripsi |
+|--------|--------|-----------|
+| **combined_dataset_v4** | 500,000 | Clinical reasoning, SOAP, diagnosis, tatalaksana, farmakologi, interaksi obat, skenario kompleks |
+
+Kategori data:
+- **Clinical Reasoning**: analisis kasus, diagnosis banding, tatalaksana berbasis evidence
+- **SOAP Notes**: dokumentasi klinis terstruktur (Subjective, Objective, Assessment, Plan)
+- **Drug Interactions**: mekanisme interaksi obat, severity, rekomendasi
+- **Complex Scenarios**: multi-disease management, kasus menantang (HIV+TB, geriatri, pediatri)
+- **Disease Knowledge**: patofisiologi, epidemiologi, pencegahan
+- **Integrated Clinical**: kasus dari diagnosis hingga tatalaksana terintegrasi
+
+### KLINEXA-EL1-Malra (Domain Maluku Tenggara)
+
+| Sumber | Jumlah | Deskripsi |
+|--------|--------|-----------|
+| malra_llm_training_v5 | 5,667 | Reasoning + 26 modul kesehatan Malra |
+| natural_qa_12k | 12,000 | Fakta paten, identity, refusal |
+| engine_training_qa | 452 | Analytical, recommendation, prediction |
+| v5_augmented_4k | 3,170 | Reasoning reinforcement |
+| sft_v8_rebalance | 7,622 | Behavior fixes |
+
+---
+
+## Cara Menggunakan
+
+### 1. Load Model
+
+```python
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import math
+
+# Definisi arsitektur (WAJIB — model ini native, bukan HuggingFace format)
+class KlinexaConfig:
+    vocab_size = 32000
+    max_seq_len = 1024
+    n_layers = 16
+    n_heads = 16
+    d_model = 1024
+    d_ff = 2816
+    dropout = 0.1
+    pad_id = 0
+    bos_id = 2
+    eos_id = 3
+    @property
+    def head_dim(self):
+        return self.d_model // self.n_heads
+
+# ... (definisi class RMSNorm, CausalSelfAttention, SwiGLUFFN,
+#      TransformerBlock, KlinexaEL1 — lihat notebook atau source code)
+
+cfg = KlinexaConfig()
+model = KlinexaEL1(cfg)
+
+ckpt = torch.load("klinexa_el1_model.pt", map_location="cpu")
+model.load_state_dict(ckpt["model_state_dict"])
+model.eval()
+```
+
+### 2. Chat / Inference
+
+```python
+from tokenizers import Tokenizer as TokLoader
+
+tok = TokLoader.from_file("klinexa_tokenizer.json")
+BOS_ID = tok.token_to_id("<bos>")
+USER_ID = tok.token_to_id("<user>")
+ASST_ID = tok.token_to_id("<assistant>")
+EOS_ID = tok.token_to_id("<eos>")
+PAD_ID = tok.token_to_id("<pad>")
+
+def chat(question, max_tokens=300, temperature=0.7):
+    u_ids = tok.encode(question).ids
+    inp = [BOS_ID, USER_ID] + u_ids + [ASST_ID]
+    inp_t = torch.tensor([inp], dtype=torch.long)
+
+    with torch.no_grad():
+        out = model.generate(inp_t, max_new_tokens=max_tokens,
+                             temperature=temperature)
+
+    gen = out[0].tolist()[len(inp):]
+    clean = [t for t in gen if t not in (EOS_ID, PAD_ID)]
+    # Potong di EOS
+    for i, t in enumerate(gen):
+        if t in (EOS_ID, PAD_ID):
+            clean = gen[:i]
+            break
+
+    return tok.decode(clean)
+
+# Contoh
+print(chat("Apa gejala demam berdarah dengue?"))
+print(chat("Jelaskan mekanisme kerja metformin"))
+```
+
+---
+
+## Loss & Training
+
+### Causal Language Modeling dengan Shift
+
+```python
+logits, _ = model(input_ids)
+
+# KRITIS: Causal shift — logits[i] predicts token[i+1]
+shift_logits = logits[:, :-1, :].contiguous()
+shift_labels = labels[:, 1:].contiguous()
+
+loss = F.cross_entropy(
+    shift_logits.view(-1, shift_logits.size(-1)),
+    shift_labels.view(-1),
+    ignore_index=-100
+)
+```
+
+> **JANGAN** compute loss tanpa shift. Tanpa shift, model belajar "copy task" (memprediksi token yang sama, bukan token berikutnya), menghasilkan loss artifisial rendah dan output yang rusak.
+
+### Hyperparameters Training
+
+| Parameter | Nilai |
+|-----------|-------|
+| Optimizer | AdamW (β1=0.9, β2=0.95) |
+| Learning Rate | 2e-5 → 1e-6 (cosine decay) |
+| Warmup | 200 steps |
+| Weight Decay | 0.01 |
+| Gradient Clipping | 1.0 |
+| Batch Size | 4 × 8 = 32 (effective) |
+| AMP | FP16 |
+| Epochs | 1 |
+
+---
+
+## File dalam Repository
+
+| File | Ukuran | Deskripsi |
+|------|--------|-----------|
+| `klinexa_el1_model.pt` | ~1 GB | Model weights (PyTorch state_dict + config + training info) |
+| `klinexa_tokenizer.json` | ~1 MB | BPE tokenizer (tokenizers library format) |
+| `config.json` | ~1 KB | Model configuration |
+| `README.md` | - | Dokumentasi ini |
+
+---
+
+## Riwayat Versi
+
+| Versi | Tanggal | Perubahan |
+|-------|---------|-----------|
+| v1-v7 | 2026 | Iterasi awal, domain Maluku Tenggara only |
+| v8 | Mar 2026 | Rebalanced dataset + behavior fixes |
+| v9 | Mar 2026 | Causal shift fix, single GPU |
+| **v10** | **Mar 2026** | **Full fix**: arsitektur exact match, format token benar, dataset 500K kesehatan Indonesia, label masking benar, tokenizer benar |
+
+### Bug yang Diperbaiki di v10
+
+1. **Arsitektur mismatch** — Nama layer `embed` → `tok_emb` (sesuai checkpoint). Dropout dan gradient checkpointing yang hilang dikembalikan.
+2. **Format token salah** — `<user>...\n</user>\n<assistant>` → `[BOS][USER]...[ASST]...[EOS]` (sesuai training).
+3. **Loss tanpa causal shift** — Ditambahkan `logits[:, :-1]` vs `labels[:, 1:]`.
+4. **Tokenizer salah** — `PreTrainedTokenizerFast` → `tokenizers.Tokenizer` (agar special tokens dikenali dengan benar).
+5. **Dual GPU bugs** — Dihapus, single GPU only.
+
+---
+
+## Batasan & Peringatan
+
+- Model ini **BUKAN** model HuggingFace standar. Tidak bisa di-load dengan `AutoModelForCausalLM`. Harus menggunakan class `KlinexaEL1` custom.
+- Context length terbatas **1,024 tokens**. Input + output harus muat dalam limit ini.
+- Model dilatih untuk **domain kesehatan**. Untuk pertanyaan di luar domain, model akan berusaha menolak atau memberikan disclaimer.
+- Model **TIDAK** boleh digunakan sebagai pengganti diagnosis medis profesional.
+- Output model **HARUS** diverifikasi oleh tenaga medis yang kompeten.
+
+---
+
+## Lisensi
+
+Apache 2.0
+
+---
+
+## Kredit
+
+**Dibuat oleh:** Emylton Leunufna
+**Lokasi:** Kota Langgur, Kabupaten Maluku Tenggara, Provinsi Maluku, Indonesia
+**Proyek:** KLINEXA — Kei Local Intelligence for Nexus Expert Analysis
+
+*Seluruh arsitektur, tokenizer, dataset pipeline, dan training code dirancang dan dibangun dari nol oleh Emylton Leunufna.*