HuggingFace Accelerate: Satu Kode PyTorch untuk CPU, Satu GPU, Multi-GPU, dan Mixed Precision

Halo temen-temen, kali ini kita bahas library yang sering dipakai diam-diam di balik layar tapi jarang dipelajari langsung, namanya Accelerate dari HuggingFace. Kalau kalian pernah nulis training loop PyTorch yang jalan mulus di laptop, terus disuruh jalanin di server dengan 4 GPU, dan tiba-tiba harus belajar DistributedDataParallel, torchrun, rank, world size, dist.initprocessgroup, sampai pusing sendiri, nah Accelerate itu obatnya.

Filosofinya sederhana dan aku suka banget: kalian tetap nulis training loop PyTorch biasa, Accelerate cuma nambahin sekitar lima baris, dan setelah itu kode yang sama bisa jalan di CPU, satu GPU, banyak GPU dalam satu mesin, banyak mesin, Apple Silicon (MPS), sampai TPU. Tanpa if bertingkat, tanpa nulis dua versi kode.

Di tutorial ini kita bakal bahas instalasi dan konfigurasi, mengubah training loop biasa jadi versi Accelerate, mixed precision, gradient accumulation, cara benar menyimpan dan memuat checkpoint di lingkungan terdistribusi, logging yang nggak dobel, sampai integrasi DeepSpeed dan FSDP untuk model besar. Ayo mulai.

Introduction

Aku mau kalian paham dulu masalah apa yang sebenarnya diselesaikan Accelerate.

Kenapa Multi-GPU Itu Menyebalkan

Waktu kalian pindah dari satu GPU ke banyak GPU dengan PyTorch murni, ada banyak hal membosankan yang harus diurus manual.

Kalian harus inisialisasi process group, menentukan backend komunikasi seperti NCCL, menentukan rank tiap proses, dan menutup process group dengan benar di akhir.

Kalian harus mengganti DataLoader biasa jadi pakai DistributedSampler, dan jangan lupa memanggil setepoch() tiap epoch supaya shuffle-nya benar antar-proses.

python -m venv venv
source venv/bin/activate   # Linux / Mac
venv\Scripts\activate    # Windows

pip install torch torchvision
pip install accelerate

accelerate config

Kalian akan ditanya beberapa hal: jalan di satu mesin atau banyak mesin, berapa GPU, mau pakai mixed precision apa (no, fp16, atau bf16), mau pakai DeepSpeed atau FSDP atau tidak. Jawabannya disimpan di file YAML di ~/.cache/huggingface/accelerate/defaultconfig.yaml.

Kalau kalian buru-buru dan cuma mau setting default yang masuk akal:

accelerate config default

Cek hasil deteksi lingkungan kalian:

accelerate env

Dari Loop Biasa ke Loop Accelerate

Ini bagian intinya. Aku tunjukin dulu versi PyTorch biasa, lalu versi Accelerate, biar kalian lihat persis apa yang berubah.

Versi PyTorch biasa:

import torch
import torch.nn as nn

device = "cuda" if torch.cuda.isavailable() else "cpu"

model = MyModel().to(device)
optimizer = torch.optim.AdamW(model.parameters(), lr=3e-4)
criterion = nn.CrossEntropyLoss()

for epoch in range(EPOCHS):
    model.train()
    for x, y in trainloader:
        x, y = x.to(device), y.to(device)
        optimizer.zerograd()

        loss = criterion(model(x), y)
        loss.backward()
        optimizer.step()

import torch
import torch.nn as nn
from accelerate import Accelerator

accelerator = Accelerator()

model = MyModel()
optimizer = torch.optim.AdamW(model.parameters(), lr=3e-4)
criterion = nn.CrossEntropyLoss()

model, optimizer, trainloader = accelerator.prepare(model, optimizer, trainloader)


for epoch in range(EPOCHS):
    model.train()
    for x, y in trainloader:
        optimizer.zerograd()

        loss = criterion(model(x), y)
        accelerator.backward(loss)
        optimizer.step()

accelerate launch train.py

# Paksa 4 GPU dengan bf16
accelerate launch --numprocesses=4 --mixedprecision=bf16 train.py


Paksa jalan di CPU untuk debugging
accelerate launch --cpu train.py

accelerator = Accelerator(mixedprecision="bf16")

Pilih bf16 kalau GPU kalian Ampere ke atas (A100, RTX 30 series, RTX 40 series, H100). Pilih fp16 untuk GPU yang lebih lama seperti V100 atau T4. bf16 lebih stabil karena rentang eksponennya sama dengan fp32, jadi jarang kena masalah overflow.

Gradient Accumulation

Kalau GPU kalian kecil tapi kalian butuh batch size besar secara efektif, gradient accumulation adalah jawabannya. Accelerate menyediakannya lewat context manager yang rapi.

from accelerate import Accelerator

accelerator = Accelerator(gradientaccumulationsteps=4)
model, optimizer, trainloader = accelerator.prepare(model, optimizer, trainloader)

for x, y in trainloader:

    with accelerator.accumulate(model):
        loss = criterion(model(x), y)
        accelerator.backward(loss)
        optimizer.step()
        scheduler.step()
        optimizer.zerograd()

Yang menyenangkan, kalian tetap menulis optimizer.step() di dalam loop seperti biasa. Accelerate yang memutuskan kapan langkah itu benar-benar dieksekusi dan kapan hanya mengakumulasi gradien. Dia juga otomatis mematikan sinkronisasi gradien antar-GPU pada langkah yang belum saatnya update, yang menghemat bandwidth komunikasi.

Logging dan Print yang Tidak Dobel

Di lingkungan multi-proses, print() biasa akan dieksekusi oleh semua proses. Kalau kalian punya 8 GPU, satu baris log jadi 8 baris.

# Hanya dicetak oleh proses utama
accelerator.print(f"epoch {epoch} loss {loss.item():.4f}")

Blok yang hanya dijalankan proses utama
if accelerator.ismainprocess:
    kirimnotifikasitelegram("training selesai")

Tunggu semua proses sampai di titik ini
accelerator.waitforeveryone()

Menggabungkan Metrik dari Semua Proses

Waktu evaluasi, tiap proses cuma melihat sebagian data. Kalau kalian hitung akurasi lokal saja, angkanya tidak mewakili seluruh dataset. Accelerate menyediakan gatherformetrics yang juga otomatis membuang duplikat dari padding batch terakhir.

model.eval()
benar = 0
total = 0
for x, y in evalloader:

    with torch.nograd():
        pred = model(x).argmax(dim=-1)
    pred, y = accelerator.gatherformetrics((pred, y))
    benar += (pred == y).sum().item()
    total += y.numel()

accelerator.print(f"akurasi: {benar/total:.4f}")

Ini salah satu fitur yang paling menyelamatkan, karena bug metrik di lingkungan distribusi itu sunyi. Angkanya kelihatan wajar tapi salah.

Menyimpan dan Memuat Model

Ini area yang paling sering bikin orang tersandung. Model yang sudah di-prepare itu dibungkus DDP, jadi kalau kalian simpan langsung, key-nya akan punya prefix module. dan nanti susah dimuat.

Cara yang benar untuk menyimpan bobot final:

accelerator.waitforeveryone()
unwrapped = accelerator.unwrapmodel(model)

accelerator.save(unwrapped.statedict(), "modelfinal.pth")

# Daftarkan objek tambahan yang ingin ikut disimpan
accelerator.registerforcheckpointing(scheduler)


Simpan
accelerator.savestate("checkpoints/epoch5")


Muat kembali
accelerator.loadstate("checkpoints/epoch5")

import torch
import torch.nn as nn
from torch.utils.data import DataLoader, TensorDataset
from accelerate import Accelerator

EPOCHS = 5

def main():
    accelerator = Accelerator(mixedprecision="bf16", gradientaccumulationsteps=2)

    # Data dummy: 2000 sampel, 20 fitur, 3 kelas
    x = torch.randn(2000, 20)
    y = torch.randint(0, 3, (2000,))
    ds = TensorDataset(x, y)
    trainloader = DataLoader(ds, batchsize=32, shuffle=True)

    model = nn.Sequential(
        nn.Linear(20, 128), nn.ReLU(),
        nn.Linear(128, 64), nn.ReLU(),
        nn.Linear(64, 3),
    )
    optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3)
    scheduler = torch.optim.lrscheduler.CosineAnnealingLR(optimizer, Tmax=EPOCHS)
    criterion = nn.CrossEntropyLoss()

    model, optimizer, trainloader, scheduler = accelerator.prepare(

        model, optimizer, trainloader, scheduler
    )

    for epoch in range(EPOCHS):
        model.train()
        for xb, yb in trainloader:

            with accelerator.accumulate(model):
                loss = criterion(model(xb), yb)
                accelerator.backward(loss)
                optimizer.step()
                optimizer.zerograd()
        scheduler.step()
        accelerator.print(f"epoch {epoch+1}/{EPOCHS} loss {loss.item():.4f}")

    accelerator.waitforeveryone()
    unwrapped = accelerator.unwrapmodel(model)

    accelerator.save(unwrapped.statedict(), "modelfinal.pth")

    accelerator.print("selesai, model tersimpan")

if name == "main":
    main()

accelerate launch contoh.py

accelerator = Accelerator(logwith="wandb")
accelerator.inittrackers("proyek-klasifikasi", config={"lr": 1e-3, "epochs": 5})


accelerator.log({"trainloss": loss.item(), "epoch": epoch}, step=globalstep)


accelerator.endtraining()

Ganti "wandb" dengan "tensorboard", "mlflow", atau "cometml" sesuai kebutuhan, tanpa mengubah baris accelerator.log.

Dua catatan penting untuk kasus ini. Pertama, dengan DeepSpeed ZeRO-3 atau FSDP, penyimpanan checkpoint harus lewat accelerator.savestate, karena statedict biasa mungkin hanya berisi shard lokal. Kedua, unwrapmodel perlu argumen tambahan pada beberapa konfigurasi untuk mengumpulkan parameter penuh, jadi baca peringatan yang muncul di log.

Tips dan Best Practice

Selalu bungkus kode kalian dalam fungsi main() dan blok if name == "main":. Di lingkungan multi-proses, kode di level modul bisa dieksekusi berkali-kali dengan efek samping yang tidak kalian harapkan.

Jangan panggil .to(device) manual setelah prepare. Kalau kalian butuh device saat ini untuk membuat tensor baru, pakai accelerator.device.

Ingat bahwa batchsize di DataLoader adalah batch per proses. Dengan 4 GPU dan batch size 32, batch efektif kalian adalah 128. Sesuaikan learning rate kalau perlu.

Gunakan accelerator.print, ismainprocess, dan waitforeveryone supaya log dan penulisan file tidak kacau di multi-proses.

Gunakan gatherformetrics untuk evaluasi yang benar, dan savestate atau unwrap_model untuk penyimpanan yang benar.

Untuk model besar, DeepSpeed dan FSDP tinggal diaktifkan lewat konfigurasi tanpa menyentuh kode training.

Coba ambil satu skrip training lama kalian, ubah lima baris sesuai panduan di atas, lalu jalankan dengan accelerate launch. Rasanya menyenangkan waktu sadar skrip yang tadinya cuma jalan di laptop sekarang bisa langsung dipakai di server multi-GPU tanpa ditulis ulang. Selamat mencoba.