Hugging Face Cheat Sheet

#Pengantar

Hugging Face mengelompokkan banyak tool untuk machine learning: transformers untuk model pretrained, datasets untuk memuat data, tokenizers untuk mengubah teks jadi angka, serta peft, trl, accelerate, dan huggingface_hub untuk fine-tuning dan distribusi. Kamu tidak harus menguasai semuanya sekaligus. Mulai dari pipeline, lalu bongkar jadi tokenizer dan model ketika butuh kontrol lebih.

#Instalasi

transformers membawa tokenizers dan bergantung pada framework deep learning. Untuk tugas teks dengan PyTorch, dua baris ini biasanya cukup:

pip install transformers torch

Kalau kamu akan memakai dataset, LoRA, training terdistribusi, atau upload ke Hub, tambahkan sisanya:

pip install datasets peft trl accelerate
pip install "huggingface_hub[cli]"

#Login ke Hub

Upload model, push dataset, atau akses model gated butuh autentikasi. Token kamu simpan dengan huggingface-cli login, bukan ditulis langsung di kode.

huggingface-cli login

Di notebook atau script, login dari kode juga tersedia. Jangan commit token ini ke repository.

from huggingface_hub import login
 
login()  # meminta token lewat prompt interaktif

#Pipeline

pipeline membungkus preprocessing, inference, dan post-processing jadi satu panggilan. Ini cara tercepat memakai model pretrained tanpa menyusun tokenizer dan forward pass sendiri.

#Sentiment analysis

from transformers import pipeline
 
classifier = pipeline("sentiment-analysis")
results = classifier([
    "Produk ini bagus banget, pengiriman cepat.",
    "Barangnya rusak pas sampai.",
])
print(results)

Outputnya berupa daftar dictionary dengan label dan score. Model default untuk sentiment analysis adalah model distilbert yang dilatih pada SST-2, jadi labelnya POSITIVE dan NEGATIVE. Untuk teks bahasa Indonesia, cari model yang dilatih pada dataset Indonesia, misalnya dengan filter bahasa pada halaman model di Hub.

#Text generation

from transformers import pipeline
 
generator = pipeline("text-generation", model="HuggingFaceTB/SmolLM2-135M")
output = generator(
    "Nasi goreng adalah",
    max_new_tokens=40,
    do_sample=True,
    temperature=0.7,
    top_p=0.9,
)
print(output[0]["generated_text"])

Model dengan miliaran parameter tidak akan muat di RAM biasa. Pilih model kecil untuk eksperimen lokal, atau pakai GPU plus teknik memuat model yang lebih besar pada bagian quantization di bawah.

#Tugas lain lewat pipeline

Pipeline menyediakan pintasan untuk banyak tugas. Kamu hanya perlu memilih task yang cocok dan model yang sesuai.

from transformers import pipeline
 
ner = pipeline("ner", grouped_entities=True)
qa = pipeline("question-answering", model="distilbert/distilbert-base-cased-distilled-squad")
summarizer = pipeline("summarization")
translator = pipeline("translation", model="Helsinki-NLP/opus-mt-id-en")
zero_shot = pipeline("zero-shot-classification")

Pipeline cocok untuk prototipe. Ketika kamu butuh mengendalikan device, batch, atau output mentah, turun ke layer tokenizer dan model.

#Tokenizer dan input model

Tokenizer memecah teks menjadi token lalu memetakan token itu ke id. Model hanya membaca angka, jadi tokenizer harus cocok dengan model yang kamu muat. Itulah kenapa kamu selalu memuat keduanya lewat nama yang sama.

#Tokenisasi dasar

from transformers import AutoTokenizer
 
tokenizer = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM2-135M")
encoded = tokenizer("Halo, dunia!", return_tensors="pt")
print(encoded)

Hasilnya punya input_ids dan attention_mask. attention_mask menandai token yang benar-benar bermakna versus padding. Model causal language model (autoregressive) tidak membutuhkan token_type_ids.

#Dekode dan kosakata

text = tokenizer.decode(encoded["input_ids"][0], skip_special_tokens=True)
print(text)
 
tokens = tokenizer.convert_ids_to_tokens(encoded["input_ids"][0])
print(tokens)

Untuk model Indonesia, cek tokenizer terkait. Model yang dilatih pada korpus campuran biasanya membelah kata Indonesia menjadi beberapa subword, dan itu wajar. Jika kamu serius pada bahasa Indonesia, pilih atau latih tokenizer yang sesuai, karena tokenisasi buruk menghamburkan token dan memperlambat inference.

#Padding dan truncation

batch = tokenizer(
    ["Teks pendek.", "Teks yang jauh lebih panjang dan butuh dipotong."],
    padding=True,
    truncation=True,
    max_length=16,
    return_tensors="pt",
)
print(batch["input_ids"].shape)

Untuk dataset besar, dynamic padding lewat data collator lebih hemat daripada memotong semua contoh ke panjang tetap.

#Dataset

datasets memuat dan memproses dataset dalam format efisien berbasis Apache Arrow. Dataset dari Hub diunduh otomatis dengan load_dataset.

#Memuat dataset

from datasets import load_dataset
 
dataset = load_dataset("glue", "mrpc")
print(dataset)
print(dataset["train"][0])

dataset adalah DatasetDict yang biasanya punya split train, validation, dan test. Untuk file lokal, gunakan load_dataset("csv", data_files="reviews.csv") atau "json".

#Mapping dan transformasi

Dataset.map menerapkan fungsi ke setiap contoh, dan batched=True memproses sekumpulan contoh sekaligus supaya tokenizer tidak dipanggil satu per satu.

def tokenize(batch):
    return tokenizer(
        batch["text"],
        truncation=True,
        max_length=128,
        padding=False,
    )
 
tokenized = dataset.map(tokenize, batched=True)

Gunakan remove_columns untuk membuang kolom teks asli setelah tokenisasi, karena model hanya menerima input_ids dan attention_mask. Kolom yang tertinggal kadang menimbulkan error saat dibawa ke Trainer.

#Split dan iterasi

split = tokenized["train"].train_test_split(test_size=0.1, seed=42)
train_dataset = split["train"]
eval_dataset = split["test"]
 
for item in train_dataset.select(range(2)):
    print(item)

Dataset bersifat lazy di beberapa operasi. Ambil subset kecil saat prototyping supaya iterasi cepat.

#Memuat dan memakai model

AutoModelFor... memilih class model yang tepat berdasarkan checkpoint. Model causal LM dipakai untuk generate teks, sedangkan klasifikasi teks memakai class dengan head task khusus.

#Model causal LM untuk generate

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
 
model_name = "HuggingFaceTB/SmolLM2-135M"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, dtype="auto")
 
inputs = tokenizer("Sebutkan tiga bahasa pemrograman populer.", return_tensors="pt")
with torch.inference_mode():
    outputs = model.generate(
        **inputs,
        max_new_tokens=60,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
    )
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

Parameter dtype="auto" memuat bobot pada dtype aslinya. Tanpa itu, PyTorch memuat semuanya sebagai float32 dan memakai memori dua kali lipat untuk model bfloat16.

#Sequence classification

from transformers import AutoModelForSequenceClassification
 
model = AutoModelForSequenceClassification.from_pretrained(
    "distilbert/distilbert-base-uncased",
    num_labels=2,
)

Output model berupa SequenceClassifierOutput. Ambil .logits untuk dipakai bersama loss atau argmax. Untuk custom training, masukkan model ini ke Trainer atau loop PyTorch biasa seperti cheat sheet PyTorch.

#Model ke GPU

model = model.to("cuda")
inputs = {k: v.to("cuda") for k, v in inputs.items()}

Cara yang lebih mudah untuk distribusi adalah accelerator.prepare(model) dari accelerate, yang menaruh model dan input ke device yang benar secara otomatis.

#Fine-tuning dengan Trainer

Trainer menyatukan optimizer, scheduler, gradient accumulation, logging, evaluasi, dan checkpoint. Kamu cukup menyiapkan dataset, data collator, dan TrainingArguments.

#Tokenisasi dataset

from datasets import load_dataset
from transformers import AutoTokenizer
 
model_name = "distilbert/distilbert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
 
dataset = load_dataset("imdb")
small_train = dataset["train"].select(range(2000))
small_test = dataset["test"].select(range(500))
 
def tokenize(batch):
    return tokenizer(
        batch["text"],
        truncation=True,
        max_length=256,
        padding=False,
    )
 
train_dataset = small_train.map(tokenize, batched=True, remove_columns=["text"])
eval_dataset = small_test.map(tokenize, batched=True, remove_columns=["text"])

#Data collator

DataCollatorWithPadding memberi padding pada setiap batch secara dinamis, mengikuti panjang contoh terpanjang di batch itu, bukan seluruh dataset.

from transformers import DataCollatorWithPadding
 
data_collator = DataCollatorWithPadding(tokenizer=tokenizer)

#TrainingArguments dan Trainer

from transformers import (
    AutoModelForSequenceClassification,
    TrainingArguments,
    Trainer,
)
 
model = AutoModelForSequenceClassification.from_pretrained(
    model_name,
    num_labels=2,
)
 
training_args = TrainingArguments(
    output_dir="./imdb-finetuned",
    num_train_epochs=2,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    learning_rate=2e-5,
    weight_decay=0.01,
    eval_strategy="epoch",
    save_strategy="epoch",
    logging_steps=50,
    load_best_model_at_end=True,
)
 
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    processing_class=tokenizer,
    data_collator=data_collator,
)
 
trainer.train()

Pada transformers versi baru, Trainer menerima processing_class sebagai pengganti parameter tokenizer lama. Kalau versi library kamu lebih tua dan processing_class tidak dikenali, gunakan tokenizer=tokenizer.

#Evaluasi dan push ke Hub

metrics = trainer.evaluate()
print(metrics)
 
trainer.push_to_hub("nama-akun/imdb-finetuned")

push_to_hub mengunggah bobot, konfigurasi, dan tokenizer ke Hub selama kamu sudah login. Hasil upload jadi repository Git yang bisa kamu lihat di huggingface.co.

#Parameter efisien dengan LoRA dan PEFT

Full fine-tuning mengubah semua bobot dan butuh banyak memori. LoRA membekukan bobot asli dan melatih matriks rank rendah yang lebih kecil. Hasilnya jauh lebih ringan untuk LLM.

from peft import LoraConfig, get_peft_model
from transformers import AutoModelForCausalLM
 
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-1B",
    dtype="auto",
)
 
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "v_proj"],
    task_type="CAUSAL_LM",
)
 
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

target_modules bergantung pada arsitektur model. Modul attention pada llama adalah q_proj, k_proj, v_proj, o_proj. Untuk model lain, cetak model.named_modules() dan cari nama layer linear pada attention. r mengontrol ukuran rank, lora_alpha menskalakan update.

Simpan adapter secara terpisah, bukan seluruh model.

model.save_pretrained("lora-adapter")
 
from peft import PeftModel
from transformers import AutoModelForCausalLM
 
base = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B", dtype="auto")
model = PeftModel.from_pretrained(base, "lora-adapter")

Untuk fine-tuning supervised pada LLM, trl menyediakan SFTTrainer yang membungkus proses ini untuk dataset instruksi. DPOTrainer dipakai untuk preference tuning.

#Quantization dan memuat model besar

Model besar tidak muat di satu GPU. Quantization menurunkan presisi bobot, dan accelerate menyebar bobot ke beberapa device.

#Quantization 4-bit dengan bitsandbytes

from transformers import AutoModelForCausalLM, BitsAndBytesConfig
 
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
)
 
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-1B",
    quantization_config=bnb_config,
    dtype="auto",
)

Quantization 4-bit butuh GPU dengan dukungan yang sesuai, biasanya NVIDIA dengan CUDA dan library bitsandbytes. Model yang di-quantize dipakai untuk inference; untuk fine-tuning LoRA di atas model 4-bit, gabungkan konfigurasi di atas dengan LoraConfig.

#Big model inference

device_map="auto" membuat accelerate memilih penempatan tiap layer. Layer yang tidak muat di GPU diturunkan ke CPU atau disk.

from transformers import AutoModelForCausalLM
 
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-1B",
    dtype="auto",
    device_map="auto",
)

Cara manual lewat accelerate memberi kontrol lebih pada checkpoint shard.

from accelerate import load_checkpoint_and_dispatch
 
model = load_checkpoint_and_dispatch(
    model,
    checkpoint="path/to/checkpoint",
    device_map="auto",
    no_split_module_classes=["LlamaDecoderLayer"],
)

no_split_module_classes mencegah layer dengan residual connection terpecah ke beberapa device, karena itu akan mengubah hasil komputasi.

#Accelerate untuk training terdistribusi

accelerate menyesuaikan kode PyTorch biasa agar berjalan di satu GPU, banyak GPU, atau TPU tanpa menulis ulang loop training. Siapkan konfigurasi sekali, lalu jalankan script lewat accelerate launch.

accelerate config
accelerate launch train.py --epochs 3

Di dalam script, bungkus objek training dengan Accelerator.

from accelerate import Accelerator
 
accelerator = Accelerator()
model, optimizer, train_dataloader, scheduler = accelerator.prepare(
    model, optimizer, train_dataloader, scheduler
)
 
for batch in train_dataloader:
    optimizer.zero_grad()
    outputs = model(**batch)
    loss = outputs.loss
    accelerator.backward(loss)
    optimizer.step()
    scheduler.step()

accelerator.prepare menaruh objek ke device yang tepat, dan accelerator.backward menangani gradient pada setup terdistribusi. Jangan lagi memanggil .to(device) atau loss.backward() secara manual di dalam loop seperti ini.

#Upload dan berbagi di Hub

Model dan dataset di Hub adalah repository Git. Kamu bisa upload lewat API Python, CLI, atau Git biasa.

#Push model dari kode

from transformers import AutoModelForSequenceClassification
 
model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased", num_labels=2)
model.push_to_hub("nama-akun/model-ku")

Token yang disimpan lewat huggingface-cli login dipakai otomatis. Repository privat dibuat dengan private=True, dan file yang tidak diinginkan bisa dicegah dengan pola pada .gitignore atau parameter ignore_patterns.

#Upload model PyTorch custom

Kalau modelmu nn.Module biasa, PyTorchModelHubMixin memberi method from_pretrained dan push_to_hub seperti model di transformers.

import torch.nn as nn
from huggingface_hub import PyTorchModelHubMixin
 
class MyModel(nn.Module, PyTorchModelHubMixin):
    def __init__(self, config):
        super().__init__()
        self.linear = nn.Linear(config["in_features"], config["out_features"])
 
    def forward(self, x):
        return self.linear(x)
 
model = MyModel({"in_features": 4, "out_features": 2})
model.push_to_hub("nama-akun/my-custom-model")

Bobot disimpan sebagai model.safetensors atau pytorch_model.bin, plus config.json. Format safetensors disarankan karena lebih aman dan cepat dimuat daripada pickle.

#Dataset push

from datasets import load_dataset
 
dataset = load_dataset("json", data_files="data.json")
dataset.push_to_hub("nama-akun/dataset-ku")

Tambahkan model card dan dataset card. Metadata yang jelas, misalnya task, bahasa, lisensi, dan cara memakai, membuat asetmu ditemukan orang lain dan tidak dianggap spam.

#Pemilihan model

Model di Hub sangat banyak. Jangan pilih hanya dari jumlah download atau nama yang terlihat besar. Urutkan prioritasmu: lisensi, bahasa, ukuran, tugas, dan apakah kamu boleh memakainya untuk produk komersial.

Untuk produksi bahasa Indonesia, model multibahasa atau model yang dilatih komunitas Indonesia sering jadi titik awal. Selalu ukur pada data kamu sendiri. Benchmark pihak ketiga jarang mewakili distribusi data produkmu.

#Debugging cepat

#Glossary