Transformers documentation
Segmentasi instance
Segmentasi instance
Segmentasi instance adalah tugas computer vision untuk mendeteksi objek dalam sebuah gambar dan melakukan segmentasi pada setiap objek di tingkat piksel. Berbeda dengan deteksi objek (yang menghasilkan bounding box), segmentasi instance menghasilkan mask yang presisi untuk setiap objek yang terdeteksi, sehingga memungkinkan Anda membedakan instance individu bahkan ketika mereka saling tumpang tindih.
Dalam panduan ini, Anda akan belajar cara:
- Muat dataset segmentasi instance dari Hugging Face Hub.
- Lakukan fine-tuning pada RF-DETR-Seg, model instance segmentation berbasis transformer, menggunakan Trainer dari Transformers.
- Evaluasi model Anda dengan mean IoU.
- Jalankan inferensi dan visualisasikan prediksi.
Kami akan menggunakan dataset satellite-building-segmentation, yang berisi sekitar 9,6k citra satelit yang dianotasi dengan mask instance bangunan.
Untuk melihat semua arsitektur dan checkpoint yang kompatibel dengan tugas ini, kami menyarankan untuk memeriksa halaman tugas.
Sebelum Anda memulai, instal semua pustaka yang diperlukan:
pip install -Uq "transformers>=5.9" datasets torchvisionKami mendorong Anda untuk membagikan model Anda kepada komunitas. Masuk ke akun Hugging Face Anda untuk mengunggahnya ke Hub setelah pelatihan selesai:
>>> from huggingface_hub import notebook_login
>>> notebook_login()Muat dataset
Dataset satellite-building-segmentation berada dalam format Hugging Face Datasets native, sehingga dapat dimuat langsung dengan load_dataset. Setiap baris berisi:
image: citra satelit (PIL)image_id: pengidentifikasi unik untuk gambarwidth/height: dimensi gambarobjects: dict anotasi per-instance denganid,category,bbox,area,segmentation(koordinat poligon), daniscrowd
>>> from datasets import load_dataset
>>> MODEL_ID = "Roboflow/rf-detr-seg-medium"
>>> DATASET_ID = "merve/satellite-building-segmentation"
>>> ds = load_dataset(DATASET_ID)
>>> train_ds = ds["train"]
>>> valid_ds = ds["validation"]
>>> print(f"Train: {len(train_ds)} images, Valid: {len(valid_ds)} images")
Train: 6764 images, Valid: 1934 images
Periksa satu contoh. Setiap rekaman memiliki image, image_id, dan dict objects yang berisi anotasi per-instan. Setiap instan memiliki bbox dalam format [x, y, width, height] dan field segmentation dengan koordinat poligon:
>>> sample = train_ds[0]
>>> print(f"Image ID: {sample['image_id']}")
Image ID: 0
>>> print(f"Image size: {sample['image'].size}")
Image size: (512, 512)
>>> print(f"Number of instances: {len(sample['objects']['id'])}")
Number of instances: 7
>>> print(f"\nObjects keys: {list(sample['objects'].keys())}")
<BLANKLINE>
Objects keys: ['id', 'area', 'bbox', 'segmentation', 'category', 'iscrowd']
>>> print(f"First bbox: {sample['objects']['bbox'][0]}")
First bbox: [80.0, 0.0, 51.0, 51.5]
>>> print(f"First category: {sample['objects']['category'][0]}")
First category: 0
Visualisasikan sebuah contoh beserta mask ground-truth-nya:
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from PIL import Image, ImageDraw
>>> sample = train_ds[0]
>>> image = sample["image"].convert("RGB")
>>> fig, axes = plt.subplots(1, 2, figsize=(14, 6))
>>> _ = axes[0].imshow(image)
>>> _ = axes[0].set_title("Original image")
>>> _ = axes[0].axis("off")
>>> overlay = image.copy()
>>> draw = ImageDraw.Draw(overlay, "RGBA")
>>> objects = sample["objects"]
>>> for seg in objects["segmentation"]:
... for poly in seg:
... coords = list(zip(poly[0::2], poly[1::2]))
... color = tuple(np.random.randint(50, 255, 3)) + (100,)
... draw.polygon(coords, fill=color, outline="red")
>>> _ = axes[1].imshow(overlay)
>>> _ = axes[1].set_title(f"Ground truth ({len(objects['id'])} buildings)")
>>> _ = axes[1].axis("off")
>>> plt.tight_layout()
>>> plt.show()
Muat model dan pemroses gambar
Gunakan AutoImageProcessor dan AutoModelForInstanceSegmentation untuk memuat model RF-DETR-Seg. Saat memuat model, berikan pemetaan id2label dan label2id untuk mengonfigurasi kepala klasifikasi untuk kelas tunggal “building”. Karena model pretrained dilatih pada COCO (91 kelas), atur ignore_mismatched_sizes=True untuk menginisialisasi ulang kepala klasifikasi dengan jumlah output yang benar.
Image processor menangani semua pra-pemrosesan: mengubah ukuran gambar sambil mempertahankan rasio aspek, menormalisasi dengan statistik ImageNet, melakukan padding ke ukuran seragam, dan — yang sangat penting untuk segmentasi instance — mengonversi anotasi poligon menjadi mask biner, mengubah ukuran mask tersebut, dan menormalisasi kotak batas ke format [cx, cy, w, h] dalam rentang [0, 1] yang diharapkan oleh model.
>>> from transformers import AutoImageProcessor, AutoModelForInstanceSegmentation
>>> id2label = {0: "building"}
>>> label2id = {"building": 0}
>>> image_processor = AutoImageProcessor.from_pretrained(MODEL_ID)
>>> model = AutoModelForInstanceSegmentation.from_pretrained(
... MODEL_ID,
... id2label=id2label,
... label2id=label2id,
... ignore_mismatched_sizes=True,
... )Praproses data
Untuk melakukan fine-tuning pada model, Anda harus memproses data terlebih dahulu agar sesuai dengan format yang diharapkan oleh model. RfDetrImageProcessor melakukan semua pekerjaan berat ketika Anda melewatkan gambar dan anotasi dalam format COCO dengan return_segmentation_masks=True:
- Merasterisasi segmentasi poligon menjadi maska biner
- Mengubah ukuran gambar, kotak pembatas, dan mask ke ukuran input model
- Menormalisasi nilai piksel dengan mean/std ImageNet
- Mengonversi kotak pembatas dari
[x, y, w, h]menjadi[cx, cy, w, h]yang dinormalisasi - Menambahkan padding pada gambar ke ukuran seragam dan membuat
pixel_mask
Transform ini merekonstruksi dict anotasi bergaya COCO yang diharapkan oleh image processor dari kolom objects dataset.
Gunakan with_transform untuk menerapkan pra-pemrosesan secara malas (on-the-fly saat sampel dimuat), yang menghindari penyimpanan seluruh dataset yang sudah diproses di memori.
>>> from functools import partial
>>> from typing import Any
>>> def transform_batch(examples: dict[str, Any], image_processor) -> dict[str, Any]:
... """Convert HF dataset rows into COCO-style dicts and pass to the processor."""
... images, targets = [], []
... for image, img_id, objects in zip(
... examples["image"], examples["image_id"], examples["objects"]
... ):
... if not objects["id"]:
... continue
... annotations = [
... {
... "id": ann_id,
... "image_id": img_id,
... "category_id": cat,
... "bbox": bbox,
... "area": area,
... "segmentation": seg,
... "iscrowd": crowd,
... }
... for ann_id, cat, bbox, area, seg, crowd in zip(
... objects["id"],
... objects["category"],
... objects["bbox"],
... objects["area"],
... objects["segmentation"],
... objects["iscrowd"],
... )
... ]
... images.append(image.convert("RGB"))
... targets.append({"image_id": img_id, "annotations": annotations})
...
... if not images:
... return {}
... return image_processor(
... images=images, annotations=targets, return_segmentation_masks=True, return_tensors="pt"
... )
>>> transform = partial(transform_batch, image_processor=image_processor)
>>> train_ds = train_ds.shuffle(seed=42).with_transform(transform)
>>> valid_ds = valid_ds.with_transform(transform)Verifikasi contoh yang telah diproses. Contoh ini berisi pixel_values (tensor gambar ternormalisasi), pixel_mask (menunjukkan piksel asli vs padding), dan labels (sebuah dict dengan class_labels, boxes dalam format pusat ternormalisasi, dan masks biner):
>>> example = train_ds[0]
>>> print(f"pixel_values shape: {example['pixel_values'].shape}")
pixel_values shape: torch.Size([3, 432, 432])
>>> print(f"pixel_mask shape: {example['pixel_mask'].shape}")
pixel_mask shape: torch.Size([432, 432])
>>> print(f"labels keys: {list(example['labels'].keys())}")
labels keys: ['size', 'image_id', 'class_labels', 'boxes', 'area', 'iscrowd', 'orig_size', 'masks']
>>> print(f" class_labels: {example['labels']['class_labels']}")
class_labels: tensor([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0])
>>> print(f" boxes shape: {example['labels']['boxes'].shape}")
boxes shape: torch.Size([26, 4])
>>> print(f" masks shape: {example['labels']['masks'].shape}")
masks shape: torch.Size([26, 432, 432])
Data collator
Karena setiap gambar memiliki jumlah instance objek yang berbeda, label berupa kamus dengan panjang yang bervariasi dan tidak dapat ditumpuk menjadi satu tensor. Definisikan fungsi collate kustom yang menumpuk pixel_values dan pixel_mask secara normal, tetapi mempertahankan labels sebagai daftar kamus per gambar:
>>> import torch
>>> def collate_fn(batch: list[dict[str, Any]]) -> dict[str, Any]:
... out = {
... "pixel_values": torch.stack([x["pixel_values"] for x in batch]),
... "labels": [x["labels"] for x in batch],
... }
... if "pixel_mask" in batch[0]:
... out["pixel_mask"] = torch.stack([x["pixel_mask"] for x in batch])
... return outDefinisikan metrik evaluasi
Untuk melacak kualitas segmentasi selama pelatihan, hitung mean IoU berbasis union pada setiap epoch evaluasi. Untuk setiap gambar:
- Gabungkan semua mask instance yang diprediksi menjadi satu peta biner “buildings” (binerkan mask logits dari setiap query dengan
sigmoid > 0.5) - Gabungkan semua mask instance ground-truth menjadi satu peta biner
- Hitung Intersection-over-Union antara dua peta
Query mask pada RF-DETR-Seg tidak di-gate oleh ambang batas skor kelas, sehingga metrik mengabaikan skor kelas dan langsung melakukan union pada logit mask per-query. Query yang tidak cocok menghasilkan mask yang hampir kosong, sehingga tidak mencemari hasil union.
Hal ini menghasilkan metrik per gambar untuk “seberapa baik model mencakup bangunan”, yang dirata-ratakan di seluruh set validasi.
Benchmark segmentasi instance (seperti COCO) biasanya melaporkan mask mean average precision (mAP), yang menilai setiap mask instance yang diprediksi terhadap ground truth pada serangkaian ambang IoU dan karenanya memberikan penghargaan untuk pemisahan objek individual yang benar. Mean IoU berbasis union yang digunakan di sini adalah proksi yang lebih sederhana dan cepat: ini mengukur cakupan piksel keseluruhan alih-alih kualitas per-instance, yang membuatnya nyaman untuk melacak kemajuan selama pelatihan. Untuk evaluasi standar yang sadar instance, hitung mask mAP sebagai gantinya, misalnya dengan
MeanAveragePrecision(iou_type="segm")daritorchmetrics.
Lewatkan ini ke Trainer sebagai fungsi compute_metrics alih-alih membuat subkelas dari trainer. Dengan eval_do_concat_batches=False (diatur di TrainingArguments di bawah), prediksi dan label yang dihasilkan oleh jalur evaluasi standar diserahkan ke compute_metrics sebagai daftar output per-batch, sehingga metrik tersebut dapat menggunakan ulang prediksi tersebut dan tidak diperlukan forward pass kedua pada set validasi. Dalam tuple output model, indeks 3 menyimpan pred_masks:
>>> import torch.nn.functional as F
>>> @torch.no_grad()
... def compute_mean_iou(pred_masks, gt_masks, target_size):
... """Union-based IoU: merge all instances per image, then compute IoU."""
... pred_masks = F.interpolate(pred_masks[None], size=target_size, mode="bilinear", align_corners=False)[0]
... pred_union = (pred_masks.sigmoid() > 0.5).any(dim=0)
...
... gt_union = gt_masks.any(dim=0).bool()
...
... intersection = (pred_union & gt_union).sum().float()
... union = (pred_union | gt_union).sum().float()
... return (intersection / union.clamp(min=1)).item()
>>> @torch.no_grad()
... def compute_metrics(evaluation_results):
... predictions, targets = evaluation_results.predictions, evaluation_results.label_ids
... ious = []
... for pred_batch, target_batch in zip(predictions, targets):
... batch_masks = pred_batch[3]
... for i, gt_label in enumerate(target_batch):
... gt_masks = torch.as_tensor(gt_label["masks"])
... if gt_masks.numel() == 0:
... continue
... target_size = gt_masks.shape[-2:]
... pred_masks = torch.as_tensor(batch_masks[i])
... ious.append(compute_mean_iou(pred_masks, gt_masks, target_size))
...
... mean_iou = sum(ious) / len(ious) if ious else 0.0
... return {"mean_iou": mean_iou}Trainer secara otomatis menambahkan awalan eval_ pada kunci yang dikembalikan, sehingga menghasilkan metrik eval_mean_iou yang digunakan di bawah ini untuk pemilihan checkpoint.
Pelatihan
Dengan data, model, dan metrik yang sudah siap, atur pelatihan. Beberapa catatan penting mengenai TrainingArguments:
remove_unused_columns=False: Diperlukan karena perilaku bawaan akan membuang kolom sebelum transform kami dijalankan.eval_do_concat_batches=False: Label instance segmentation berupa dict dengan panjang variabel, sehingga tidak dapat digabungkan antar batch. Pengaturan ini juga menjaga agar prediksi tetap dikelompokkan per batch sehinggacompute_metricsdapat mencocokkannya dengan label yang sesuai.metric_for_best_model="eval_mean_iou": Pilih checkpoint terbaik berdasarkan kualitas segmentasi, bukan hanya loss.fp16=True: Pelatihan presisi campuran secara signifikan mempercepat pelatihan pada GPU modern.
>>> from transformers import Trainer, TrainingArguments
>>> training_args = TrainingArguments(
... output_dir="rf-detr-seg-satellite-buildings",
... num_train_epochs=10,
... per_device_train_batch_size=16,
... per_device_eval_batch_size=16,
... learning_rate=1e-4,
... weight_decay=1e-4,
... lr_scheduler_type="cosine",
... warmup_steps=0.1,
... fp16=True,
... dataloader_num_workers=4,
... eval_strategy="epoch",
... save_strategy="epoch",
... save_total_limit=2,
... load_best_model_at_end=True,
... metric_for_best_model="eval_mean_iou",
... greater_is_better=True,
... remove_unused_columns=False,
... eval_do_concat_batches=False,
... push_to_hub=False,
... )
>>> trainer = Trainer(
... model=model,
... args=training_args,
... train_dataset=train_ds,
... eval_dataset=valid_ds,
... processing_class=image_processor,
... data_collator=collate_fn,
... compute_metrics=compute_metrics,
... )
>>> trainer.train()Jika Anda mengatur push_to_hub=True dalam argumen pelatihan, checkpoint pelatihan akan didorong ke Hugging Face Hub. Setelah pelatihan selesai, dorong juga model akhir ke Hub dengan memanggil metode push_to_hub().
>>> trainer.push_to_hub(
... dataset=DATASET_ID,
... tags=["instance-segmentation", "rf-detr-seg", "vision", "satellite", "building"],
... )Inferensi
Sekarang Anda memiliki model yang telah di-*fine-tune*, gunakan model tersebut untuk inferensi pada citra satelit baru. Alur kerjanya adalah:
- Praproses gambar dengan image processor
- Jalankan forward pass melalui model
- Lakukan pascapemrosesan output dengan
post_process_instance_segmentationuntuk mendapatkan mask pada tingkat piksel
Langkah pascapemrosesan mengubah keluaran kueri mentah (logits + mask beresolusi rendah) menjadi peta segmentasi instance beresolusi penuh, dengan menerapkan ambang batas skor dan binarisasi mask.
>>> from datasets import load_dataset
>>> test_ds = load_dataset(DATASET_ID, split="test")
>>> sample = test_ds[0]
>>> image = sample["image"].convert("RGB")
>>> device = next(model.parameters()).device
>>> inputs = image_processor(images=image, return_tensors="pt").to(device)
>>> with torch.no_grad():
... outputs = model(**inputs)
>>> results = image_processor.post_process_instance_segmentation(
... outputs, threshold=0.5, target_sizes=[(image.height, image.width)]
... )[0]
>>> print(f"Detected {len(results['segments_info'])} buildings")
Detected 0 buildings
>>> for seg_info in results["segments_info"][:5]:
... print(f" Building (score: {seg_info['score']:.3f})")Visualisasikan prediksi. Peta segmentasi memberikan setiap piksel sebuah ID segmen (-1 untuk latar belakang). Tampilkan setiap bangunan yang terdeteksi dengan warna acak:
>>> fig, axes = plt.subplots(1, 2, figsize=(14, 6))
>>> _ = axes[0].imshow(image)
>>> _ = axes[0].set_title("Input satellite image")
>>> _ = axes[0].axis("off")
>>> seg_map = results["segmentation"].cpu().numpy()
>>> overlay = np.array(image).copy()
>>> for seg_info in results["segments_info"]:
... mask = seg_map == seg_info["id"]
... color = np.random.randint(0, 255, 3)
... overlay[mask] = (overlay[mask] * 0.4 + color * 0.6).astype(np.uint8)
>>> _ = axes[1].imshow(overlay)
>>> _ = axes[1].set_title(f"Predicted masks ({len(results['segments_info'])} buildings)")
>>> _ = axes[1].axis("off")
>>> plt.tight_layout()
>>> plt.show()