Arsitektur Repository

Repository ini adalah harness finetuning yang tipis. Dua skrip di akar repository menjadi entry point — main.py untuk training dan evaluasi, predict.py untuk prediksi ulang — dan keduanya mengimpor fungsi dari utils/ secara langsung tanpa lapisan paket perantara (main.py:14-15¹, predict.py:13-15²). Halaman ini memetakan siapa bergantung pada siapa; rincian tiap tahap dibahas di halaman masing-masing.

Peta ketergantungan antar modul

Arah impor konsisten: entry point bergantung pada utils/, dan hanya utils/functions.py yang mengimpor modules/ (utils/functions.py:6-7³). utils/args_helper.py menjadi tempat ketiga lapisan bertemu karena ia mengimpor kelas dataset, fungsi metrik, dan forward function sekaligus (utils/args_helper.py:1-14⁴).

graph TD
  m_main["main.py<br/>training + evaluation"]
  p_pred["predict.py<br/>prediction"]
  a_helper["utils/args_helper.py<br/>parser + dataset dispatch"]
  f_utils["utils/functions.py<br/>model loading"]
  d_utils["utils/data_utils.py<br/>Dataset + DataLoader"]
  fwd["utils/forward_fn.py"]
  mets["utils/metrics.py"]
  w_cls["modules/word_classification.py"]
  m_cls["modules/multi_label_classification.py"]
  dset[("dataset/")]
  saved[("save/ artefacts")]
  m_main --> a_helper
  m_main --> f_utils
  m_main -.-> d_utils
  m_main -.-> fwd
  p_pred --> a_helper
  p_pred --> f_utils
  p_pred --> mets
  p_pred -.-> fwd
  a_helper --> d_utils
  a_helper --> fwd
  a_helper --> mets
  f_utils --> w_cls
  f_utils --> m_cls
  d_utils -.-> dset
  f_utils -.-> saved
  style m_main fill:#2d7d46,color:#fff
  style p_pred fill:#2d7d46,color:#fff
  style a_helper fill:#f59e0b,color:#000
  style dset fill:#336791,color:#fff
  style saved fill:#8b5cf6,color:#fff
%% fig: Peta ketergantungan modul IndoNLU
%% desc: Dua entry point memakai utils/, args_helper menyatukan data, forward dan metrik, sementara functions memuat bobot dari save/ dan memilih kepala di modules/.

Garis putus-putus menandai pemanggilan saat runtime, bukan impor. main.py tidak mengimpor utils/forward_fn.py; ia memakai fungsi yang sudah diisi append_dataset_args lewat args['forward_fn'] saat memanggil train(...) (main.py:185⁵). Pola yang sama berlaku untuk bobot: berkasnya dibaca dari model_dir yang disusun dari args['model_dir'], args['dataset'], dan args['experiment_name'] (utils/functions.py:222-225⁶).

Dua entry point dan pembagian tugas

Keduanya memakai parser dan pemuat model yang berbeda, tetapi berbagi append_dataset_args dan model_dir yang sama.

⚠️ main.py membuat folder model_dir sendiri dan menolak menimpanya kecuali diberi --force (main.py:144-151¹⁸), sedangkan predict.py hanya membaca folder itu dan mencetak Model doesn't exist in {model_dir} bila best_model_0.th tidak ada (predict.py:99-107¹⁷). Menjalankan prediksi sebelum training selesai hanya menghasilkan pesan itu, bukan berkas submission.

Alur training lengkap ada di Alur Training dan Evaluasi, dan pemilihan model_checkpoint di Konfigurasi Argumen dan Pemilihan Model.

append_dataset_args sebagai titik sambung

Setiap nama dataset punya satu cabang di append_dataset_args yang mengisi set kunci yang sama: task, num_labels, dataset_class, dataloader_class, forward_fn, metrics_fn, valid_criterion, jalur berkas, dan word_tokenizer_class (utils/args_helper.py:85-90¹⁹).

graph LR
  darg["--dataset"] --> br["append_dataset_args"]
  marg["--model_checkpoint / --model_type"] --> gmc["get_model_class"]
  br --> tsk["task: sequence / token / multi_label"]
  br --> dcls["dataset_class + dataloader_class"]
  br --> ffn["forward_fn"]
  br --> mfn["metrics_fn"]
  tsk --> gmc
  gmc --> hcls["pred_cls: Bert / Albert / XLM / XLMRoberta"]
  dcls --> batch["batch tensor + label"]
  ffn --> outp["loss, list_hyp, list_label"]
  mfn --> outp
  style br fill:#f59e0b,color:#000
  style gmc fill:#8b5cf6,color:#fff
  style outp fill:#2d7d46,color:#fff
%% fig: Dispatch argumen ke fungsi dan kelas model
%% desc: append_dataset_args mengisi task, kelas dataset, forward_fn dan metrics_fn, lalu get_model_class memilih pred_cls dari task dan model_checkpoint.

get_model_class memilih pred_cls dari pasangan model_type dan task (utils/functions.py:145-178²²), sedangkan load_model memilih kelas Transformers bawaan untuk sequence_classification (utils/functions.py:300-305²³). Nama dataset di luar daftar cabang berhenti dengan ValueError (utils/args_helper.py:300-301²⁴).

Ketiga forward function mengembalikan bentuk yang sama, loss, list_hyp, list_label, tetapi isi list_hyp berbeda: satu label per sekuens (utils/forward_fn.py:8-40²⁵), daftar label per kata yang berhenti pada nilai -100 (utils/forward_fn.py:43-85²⁶), dan satu daftar per kelas untuk multi-label (utils/forward_fn.py:88-117). Perbedaan itu yang menentukan pilihan metrics_fn: akurasi dan F1 macro untuk klasifikasi sekuens (utils/metrics.py:5-11), conll_evaluation untuk tugas tingkat kata (utils/metrics.py:13-20), dan pemerataan daftar label untuk ABSA (utils/metrics.py:74-84). Rincian tiap fungsi ada di Forward Pass dan Metrik Evaluasi.

Paket modules: dua keluarga kepala klasifikasi

modules/ hanya berisi kepala untuk klasifikasi tingkat kata dan multi-label; untuk sequence_classification kode memakai kelas bawaan transformers (utils/functions.py:300-305²³).

Pemilihan kelas di antara kedelapan kelas itu dan perilaku forward masing-masing dibahas di Modul Kepala Klasifikasi.

Direktori pendukung

Direktori dataset/ berisi satu folder per task, dan append_dataset_args menuliskan jalur berkasnya secara eksplisit, misalnya ./dataset/emot_emotion-twitter/train_preprocess.csv (utils/args_helper.py:92-95³⁵). Setiap Dataset menyimpan peta label sebagai konstanta kelas — LABEL2INDEX, INDEX2LABEL, NUM_LABELS (utils/data_utils.py:12-16³⁶) — dan setiap DataLoader menimpa collate_fn dengan _collate_fn untuk menyusun batch beserta padding (utils/data_utils.py:67-96³⁷). Rincian bentuk berkas ada di Struktur Berkas Dataset dan Submission, dan perilaku loader di Data Utils dan Dataloader.

Dua skrip shell menyambungkan entry point ke eksperimen massal. run_single_task.sh menjalankan main.py dengan kombinasi --model_checkpoint, --dataset, dan --num_layers (run_single_task.sh:2³⁸), sedangkan predict.sh menyusuri ./save/* dan menurunkan --model_type dari potongan pertama nama eksperimen (predict.sh:1-14³⁹).

Direktori examples/ dan tutorial/ berisi notebook finetune, di antaranya finetune_casa.ipynb dan finetune_smsa_tutorial.ipynb, yang dijelaskan di Contoh Finetune dan Tutorial.