1 · Tokenizer + Model directly

Use Auto* classes whenever you do not know the exact architecture ahead of time — they inspect the config and load the right class automatically.

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

model_id = "distilbert-base-uncased-finetuned-sst-2-english"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model     = AutoModelForSequenceClassification.from_pretrained(model_id)

inputs  = tokenizer("Hugging Face makes ML accessible.", return_tensors="pt")
outputs = model(**inputs)
probs   = torch.softmax(outputs.logits, dim=-1)
label   = model.config.id2label[probs.argmax().item()]
print(label, probs.max().item())

2 · Loading a dataset

load_dataset downloads, caches, and memory-maps the data as Apache Arrow. Use streaming=True for datasets that do not fit in RAM.

from datasets import load_dataset, DatasetDict

ds = load_dataset("imdb")          # DatasetDict with train/test splits
print(ds["train"][0])              # {'text': '...', 'label': 1}

# Tokenize the whole split in parallel (fast Rust tokenizer)
def tokenize(batch):
    return tokenizer(batch["text"], truncation=True, padding="max_length")

tokenized = ds.map(tokenize, batched=True, num_proc=4)

3 · Fine-tuning with Trainer

Trainerhandles the training loop, gradient accumulation, evaluation, checkpointing, and logging to TensorBoard / W&B with zero boilerplate.

from transformers import TrainingArguments, Trainer
import numpy as np
from evaluate import load as load_metric

accuracy = load_metric("accuracy")

def compute_metrics(eval_pred):
    logits, labels = eval_pred
    preds = np.argmax(logits, axis=-1)
    return accuracy.compute(predictions=preds, references=labels)

args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=32,
    evaluation_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
    logging_dir="./logs",
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=tokenized["train"],
    eval_dataset=tokenized["test"],
    compute_metrics=compute_metrics,
)

trainer.train()

4 · LoRA fine-tuning with PEFT

LoRA freezes the base model and injects trainable low-rank matrices into attention layers. You typically train under 1% of parameters, making it feasible on a single GPU.

from peft import LoraConfig, get_peft_model, TaskType

lora_cfg = LoraConfig(
    task_type=TaskType.SEQ_CLS,
    r=8,               # rank of the low-rank matrices
    lora_alpha=16,     # scaling factor
    lora_dropout=0.1,
    target_modules=["q_lin", "v_lin"],
)

peft_model = get_peft_model(model, lora_cfg)
peft_model.print_trainable_parameters()
# trainable params: 294,912 || all params: 66,955,010 || trainable%: 0.44

trainer = Trainer(model=peft_model, args=args, ...)

5 · Pushing to the Hub

Share your fine-tuned model (weights + tokenizer + config + model card) in one call. The repo is versioned with Git-LFS under the hood.

# Authenticate once in terminal:  huggingface-cli login

trainer.push_to_hub("my-org/distilbert-sst2-finetuned")

# Or push individually:
model.push_to_hub("my-org/my-model")
tokenizer.push_to_hub("my-org/my-model")

6 · Multi-GPU training with Accelerate

Wrap your existing training loop with Accelerator. No conditional if cuda blocks — the same script runs on a laptop or an 8-GPU node.

from accelerate import Accelerator

accelerator = Accelerator()

model, optimizer, train_dl, eval_dl = accelerator.prepare(
    model, optimizer, train_dataloader, eval_dataloader
)

for batch in train_dl:
    outputs = model(**batch)
    loss = outputs.loss
    accelerator.backward(loss)
    optimizer.step()
    optimizer.zero_grad()

Model cards

A README.md with YAML front-matter becomes your model card. Declare language, license, tags, datasets, and metrics so the Hub can index and filter your model correctly.

huggingface_hub client

from huggingface_hub import hf_hub_download, list_models, snapshot_download

# Download a single file
path = hf_hub_download(repo_id="bert-base-uncased", filename="config.json")

# Clone the whole repo (useful for non-Transformers models)
snapshot_download(repo_id="stabilityai/stable-diffusion-2-1", local_dir="./sd21")

# Search the Hub
models = list_models(filter="text-classification", sort="downloads", limit=5)
for m in models:
    print(m.modelId, m.downloads)

Spaces (Gradio demo)

# app.py  (push this file + requirements.txt to your Space repo)
import gradio as gr
from transformers import pipeline

pipe = pipeline("sentiment-analysis")

def predict(text):
    result = pipe(text)[0]
    return f"{result['label']} ({result['score']:.2%})"

gr.Interface(fn=predict, inputs="text", outputs="text").launch()