Skip to main content

🦁 BaliNER: Named Entity Recognition untuk Teks Bahasa Bali Berbasis Transformer

Sistem ekstraksi entitas bernama (Named Entity Recognition) mutakhir untuk mendeteksi karakter dan tokoh pada sastra cerita rakyat Bali (Satua Bali) berbasis fine-tuning model Transformer (IndoBERT / Multilingual). Dilengkapi antarmuka web interaktif profesional minimalis (BaliNER Studio) serta REST API siap produksi.


📊 Hasil Evaluasi & Akurasi Model (IndoBERT Base)

Pengujian performa model dievaluasi secara ketat pada data uji buta (blind test set) dari berkas test.xlsx yang sepenuhnya terisolasi dari proses pelatihan dan validasi (mencegah data leakage). Evaluasi menggunakan standar akademik chunk-level CoNLL melalui pustaka seqeval dengan strategi first-subword alignment.

1. Laporan Klasifikasi Rinci per Kelas Entitas (Data Uji test.xlsx)

Kategori Entitas Deskripsi Karakter Precision Recall F1-Score Support (Sampel)
ADJ Penanda Sifat Karakter Tokoh 0.88 0.93 0.91 132
PNAME Tokoh Manusia (Person Name) 0.81 0.85 0.83 845
ANM Tokoh Binatang / Fabel (Animal) 0.79 0.82 0.81 872
GODS Dewa & Bhatara (Deities & Spiritual) 0.63 0.70 0.66 162
OBJ Benda Pusaka / Keramat (Sacred Object) 0.60 0.60 0.60 577
Micro Average Rata-rata Agregat Global 0.75 0.78 0.77 2.588
Macro Average Rata-rata Tak Berbobot per Kelas 0.74 0.78 0.76 2.588
Weighted Average Rata-rata Berbobot Proporsi Kelas 0.75 0.78 0.77 2.588

Catatan Analisis:

  • Kategori ADJ memperoleh skor F1 tertinggi (0.91) karena pola leksikal sifat tokoh yang sangat konsisten (ririh, sugih, lacur).
  • Kategori PNAME (0.83) dan ANM (0.81) memiliki rekognisi yang sangat kuat berkat pemanfaatan partikel budaya (I, Men, Pan, Sang, Ni) dan normalisasi batas kata (boundary snapping).
  • Kategori OBJ (0.60) dan GODS (0.66) memiliki tantangan ambiguitas konteks yang berhasil ditingkatkan melalui penyelarasan fitur POS tag.

2. Riwayat Pelatihan & Validasi per Epoch

Fine-tuning dilakukan selama 5 epoch pada model backbone serumpun Austronesia indobenchmark/indobert-base-p1 dengan learning rate 3e-5, batch size 16, dan optimizer AdamW:

Epoch Training Loss Validation Loss Precision Recall F1-Score
1 0.2262 0.2221 0.7169 0.7096 0.7133
2 0.1437 0.1908 0.7305 0.7873 0.7579
3 0.0731 0.1836 0.7174 0.7996 0.7563
4 0.0380 0.2147 0.7281 0.8160 0.7695
5 0.0191 0.2262 0.7383 0.8078 0.7715

Model terbaik pada checkpoint optimal secara otomatis diekspor ke direktori ./best_balinese_ner_model_base.


📑 Daftar Diagram Arsitektur & Rekayasa Perangkat Lunak UML

Dokumentasi lengkap analisis sistem, kebutuhan fungsional (11 use cases), kebutuhan non-fungsional, dan visualisasi arsitektur UML tersimpan dalam berkas-berkas markdown terpisah:

  • 📐 RINGKASAN_DIAGRAM.md: Versi Sederhana / Ringkasan Seluruh Diagram (Use Case, Activity, Class, Flowchart, dan Sequence) untuk pemahaman cepat.
  1. 🎯 USE_CASE_DIAGRAM.md: Diagram kasus penggunaan UML untuk 11 fungsi sistem serta matriks kepatuhan kebutuhan operasional, keamanan, informasi, dan kinerja.
  2. 🔄 ACTIVITY_DIAGRAM.md: Diagram aktivitas UML dengan jalur tanggung jawab (swimlanes) antarmodul dari input teks hingga evaluasi.
  3. 🏛️ CLASS_DIAGRAM.md: Diagram kelas berorientasi objek memodelkan modularitas pipeline inferensi, model manager, dan peladen web API.
  4. 📊 FLOWCHART.md: Diagram alur menyeluruh (end-to-end) dari verifikasi bahasa, ekstraksi entitas, hingga pencatatan riwayat.
  5. ⏱️ SEQUENCE_DIAGRAM.md: Diagram urutan waktu interaksi kronologis antarkomponen saat inferensi dan pencatatan umpan balik.
  6. 🎨 UI_UX_DOCUMENTATION.md: Dokumentasi komprehensif desain antarmuka pengguna (UI/UX), dilengkapi 19 tangkapan layar asli, pemetaan 11 kebutuhan fungsional, dan evaluasi heuristik.

🏷️ Taksonomi Label Entitas Karakter (11 Kelas BIO)

Sistem mengidentifikasi 5 kategori utama karakter budaya Bali dengan skema anotasi Beginning-Inside-Outside (BIO):

Tag BIO Kategori Karakter Penjelasan & Contoh
B-PNAME / I-PNAME Person Name Tokoh manusia (contoh: I Pekak Dukuh, Men Sugih, I Tiwas).
B-ANM / I-ANM Animal Tokoh binatang / fabel (contoh: Sang Lutung, I Kekua, I Macan).
B-OBJ / I-OBJ Object Benda magis / pusaka bertuah (contoh: Gada, Pecut Sakti).
B-GODS / I-GODS Gods & Deities Dewa, bhatara, atau entitas spiritual (contoh: Bhatara Guru).
B-ADJ / I-ADJ Adjective Modifier Penanda sifat karakter tokoh (contoh: anak ririh, tualen).
O Outside Kata umum non-entitas.

📂 Struktur Direktori Proyek

Proyek ini telah ditata secara modular dan rapi sesuai standar rekayasa perangkat lunak dan pembelajaran mesin (Machine Learning):

BaliNER/
├── data/                                 # Dataset anotasi aksara/teks Latin Satua Bali
│   ├── train.xlsx                        # Dataset latih (60.627 token, 4.398 kalimat)
│   ├── test.xlsx                         # Dataset uji blind test (28.986 token, 2.052 kalimat)
│   └── all.xlsx                          # Dataset gabungan lengkap
├── docs/                                 # Dokumentasi arsitektur sistem & rekayasa perangkat lunak
│   ├── images/                           # Tangkapan layar antarmuka & aset visual sistem
│   ├── ACTIVITY_DIAGRAM.md               # Activity diagram & alur swimlanes
│   ├── CLASS_DIAGRAM.md                  # Class diagram & pemodelan komponen OOP
│   ├── FLOWCHART.md                      # Flowchart alur inferensi & verifikasi bahasa
│   ├── GITHUB_SETUP.md                   # Panduan unggah & konfigurasi Git LFS
│   ├── RINGKASAN_DIAGRAM.md              # Rangkuman komprehensif diagram sistem
│   ├── SEQUENCE_DIAGRAM.md               # Sequence diagram interaksi inferensi & umpan balik
│   ├── UI_UX_DOCUMENTATION.md            # Dokumentasi UI/UX & evaluasi heuristik
│   └── USE_CASE_DIAGRAM.md               # Use case diagram 11 kebutuhan fungsional
├── tests/                                # Pengujian unit & integrasi otomatis
│   ├── __init__.py                       # Inisialisasi paket tes
│   ├── test_venv_imports.py              # Pengujian kompatibilitas environment & dependensi
│   └── test_web_ui.py                    # Suite 9 unit test Flask & pipeline inferensi
├── notebooks/                            # Koleksi Jupyter Notebook varian model Transformer
│   ├── README.md                         # Panduan lengkap tiap model eksperimen
│   ├── BaliNER_IndoBERT_base.ipynb       # Model IndoBERT Base (IndoBenchmark)
│   ├── BaliNER_IndoBERT_large.ipynb      # Model IndoBERT Large (IndoBenchmark)
│   ├── BaliNER_NusaBERT.ipynb            # Model NusaBERT Base (LazarusNLP)
│   ├── BaliNER_IndoRoBERTa.ipynb         # Model IndoRoBERTa Base (Cahya)
│   ├── BaliNER_RoBERTa.ipynb             # Model RoBERTa Base standar
│   ├── BaliNER_XLM_RoBERTa.ipynb         # Model XLM-RoBERTa Base multilingual
│   ├── BaliNER_mDeBERTa_v3.ipynb         # Model mDeBERTa-v3 Base (Disentangled Attention)
│   └── BaliNER_mBERT.ipynb               # Model mBERT Base (Google Multilingual)
├── reports/                               # Hasil komparasi performa model (CSV, JSON, Markdown, PNG)
│   ├── MODEL_COMPARISON.md               # Laporan analisis komparatif publikasi
│   ├── model_comparison_summary.csv      # Ringkasan matriks leaderboard
│   ├── model_comparison_per_class.csv    # Rincian metrik per kategori entitas
│   ├── model_comparison_overall_f1.png   # Grafik bar chart F1-score keseluruhan
│   ├── model_comparison_per_class.png    # Grafik grouped bar chart 5 kategori entitas
│   └── model_comparison_latency_vs_f1.png# Scatter plot trade-off akurasi vs latensi
├── submission/                           # Arsip berkas pengumpulan tugas akademik (diabaikan Git)
│   ├── 2408561071_Kelompok_BaliNER.pdf   # Laporan dokumentasi tugas
│   ├── 2408561071_Kelompok_BaliNER.zip   # Arsip penyerahan mandiri
│   └── 2408561071_Kelompok_BaliNER/      # Folder build penyerahan
├── best_balinese_ner_model_base/         # Model IndoBERT Base terlatih (konfigurasi & tokenizer)
├── static/                               # Aset antarmuka web (CSS & JS)
│   ├── css/style.css                     # Gaya CSS profesional minimalis
│   └── js/app.js                         # Logika interaktif antarmuka klien
├── templates/                            # Template Jinja2 Flask
│   └── index.html                        # Template HTML BaliNER Studio
├── app.py                                # Peladen web Flask & backend REST API
├── infer_ner.py                          # Utilitas CLI inferensi teks kustom
├── train_ner.py                          # Skrip CLI pelatihan & evaluasi Transformer
├── compare_models.py                     # Program evaluasi & komparasi benchmark seluruh model
├── BaliNER.ipynb                         # Jupyter Notebook eksperimen & analisis data
├── run_web_ui.bat                        # Launcher 1-klik untuk sistem operasi Windows
├── run_web_ui.sh                         # Launcher 1-klik untuk Linux / macOS
├── requirements.txt                      # Daftar dependensi Python
├── CONTRIBUTING.md                       # Panduan kontribusi pengembangan
├── LICENSE                               # Lisensi proyek (MIT)
└── README.md                             # Dokumentasi utama proyek

💻 Panduan Penggunaan Sistem

Opsi 0: Python Package Hybrid (balinese-ner) — Untuk Integrasi Developer & Redundansi Server

Paket Python yang dapat di-pip install dengan dukungan cache lokal/VPS, Hugging Face Hub (Dramaniako/BaliBERT), Hugging Face Inference API, backup mirror fallback (GitHub Releases), serta Constrained Viterbi BIO Decoding (0 pelanggaran BIO):

pip install git+https://github.com/Dramaniako/BaliNER.git
from balinese_ner import PretrainedModelNER

# Mode Hybrid (Default): cek cache lokal/VPS -> unduh HF Hub -> fallback mirror jika HF down
ner = PretrainedModelNER.load("BaliBERT", mode="hybrid")
print(ner.predict("I Pekak Dukuh lantas ngaukin Sang Lutung ane sedeng ngamah biu."))

# Mode API dengan Fallback Lokal (hemat RAM VPS, otomatis fallback ke lokal jika API HF gangguan)
ner_api = PretrainedModelNER.load("BaliBERT", mode="api_fallback")

# Mode Offline Murni (menggunakan cache/bobot lokal tanpa internet)
ner_offline = PretrainedModelNER.load("BaliBERT", mode="local")

Untuk mengisi cache pada server VPS sebelum demo (pre-warming):

balinese-ner --prewarm --model BaliBERT

Opsi 1: Antarmuka Web Interaktif (BaliNER Studio Web UI) — Direkomendasikan

Aplikasi web modern bergaya profesional minimalis yang terhubung langsung ke model best_balinese_ner_model_base:

  • Cara 1 (Windows 1-Click Launcher): Cukup klik ganda berkas run_web_ui.bat.
  • Cara 2 (Terminal CLI):
    .\.venv\Scripts\python.exe app.py
    
    Kemudian buka peramban web di: 👉 http://127.0.0.1:5000

✨ Rangkuman Fitur Web UI:

  • Deteksi Bahasa Otomatis: Mendeteksi kecocokan teks bahasa Bali secara instan dengan indikator persentase.
  • Visualisasi Teks Beranotasi: Penandaan entitas interaktif dengan badge warna BIO dan tooltip popover detail (Skor, Kategori, Rentang Span).
  • Preset Contoh Satua Bali: 5 kutipan sastra rakyat klasik siap uji dalam 1-klik.
  • Tabel Rincian Entitas & Bilah Keyakinan: Tabel data lengkap dengan bilah progres keyakinan dan tombol salin per entitas.
  • Evaluasi & Penilaian Kualitas: Fitur umpan balik (👍 Akurat / 👎 Perlu Koreksi) untuk mencatat hasil penilaian linguis.
  • Riwayat Analisis & Pemulihan Instan: Histori deteksi tersimpan lokal di browser dengan kemampuan restore ke layar utama.
  • Mode Gelap & Terang: Tema professional minimalist elegan dengan persistensi preferensi.
  • REST API Terbuka: Endpoint /api/predict, /api/info, /api/examples, /api/detect-language, dan /api/feedback.

Opsi 2: Menjalankan via Jupyter Notebook (Interaktif)

Anda dapat menjalankan notebook baseline utama: 👉 BaliNER.ipynb (IndoBERT Base)

Atau memilih notebook spesifik per model pada direktori notebooks/ untuk eksperimen komparatif:

Opsi 3: Pelatihan Cepat via Terminal (CLI)

python train_ner.py --epochs 5 --batch_size 16 --learning_rate 3e-5

Opsi 4: Menjalankan Inferensi pada Kalimat Baru via CLI

python infer_ner.py --text "I Pekak Dukuh lantas ngaukin Sang Lutung ane sedeng ngamah biu di duur punyane."

Opsi 5: Menjalankan Pengujian Otomatis (Unit & Integration Tests)

python tests/test_web_ui.py
# Atau menggunakan discovery:
python -m unittest discover tests

Opsi 6: Melakukan Komparasi Performa Seluruh Model Terlatih (Benchmark CLI)

Untuk mengevaluasi seluruh model yang telah dilatih dan menghasilkan laporan perbandingan lengkap (tabel leaderboard terminal, berkas CSV, JSON, Markdown, serta visualisasi grafik PNG):

python compare_models.py

Argumen opsional:

  • --test_file: Lokasi berkas data uji (default: data/test.xlsx)
  • --batch_size: Ukuran batch evaluasi (default: 32)
  • --output_dir: Direktori penyimpanan laporan (default: reports/)
  • --no_plots: Lewati pembuatan grafik gambar PNG

Metadata

Release files for balinese-ner 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for balinese-ner 0.1.0
File Size Uploaded Provenance Actions
balinese_ner-0.1.0.tar.gz 57.8 kB Without provenance Details for balinese_ner-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for balinese-ner 0.1.0
File Interpreter ABI Platform Actions
balinese_ner-0.1.0-py3-none-any.whl Python 3 none any Details for balinese_ner-0.1.0-py3-none-any.whl

Total release size: 79.2 kB

Release files / balinese_ner-0.1.0.tar.gz

Download URL balinese_ner-0.1.0.tar.gz
Size 57.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5517b34ac26e293ef68acbe41332c9af35775d94dcc564e5d7f9ea77b8a980ac
BLAKE2b-256 checksum
How to use checksums
390d469ba052f794b601585cb82acfef8fb587267d67f58f094bd6ffa63625e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / balinese_ner-0.1.0-py3-none-any.whl

Download URL balinese_ner-0.1.0-py3-none-any.whl
Size 21.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
50734401d2658dd31f3f570d93d7963a7484d271c3966c51e78ad81b2726993f
BLAKE2b-256 checksum
How to use checksums
15cac8ad524664eb25452284b7701b905dd97187008f5711ed8e1d11f07d5003
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for balinese-ner 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page