Transformers documentation

객체 감지

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

객체 감지

Object detection은 이미지에서 인스턴스(예: 사람, 건물, 자동차)를 감지하는 컴퓨터 비전 작업입니다. Object detection 모델은 이미지를 입력으로 받아 감지된 객체의 bounding box 좌표와 관련 라벨을 출력합니다. 하나의 이미지에는 각자 고유한 bounding box와 라벨(예: 자동차와 건물)을 가진 여러 객체가 포함될 수 있으며, 각 객체는 이미지의 서로 다른 영역에 존재할 수 있습니다(예: 여러 대의 자동차). 이 작업은 보행자, 도로 표지판, 신호등과 같은 객체를 감지하기 위해 자율 주행에 널리 사용됩니다. 기타 응용 분야로는 이미지 내 객체 카운팅, 이미지 검색 등이 있습니다.

이 가이드에서는 다음 내용을 배웁니다:

  1. mobile-ui-design 데이터셋에서 RF-DETR을 파인튜닝하여 모바일 앱 스크린샷의 UI 요소를 감지합니다.
  2. 파인튜닝한 모델을 추론에 사용하세요.

이 작업과 호환되는 모든 아키텍처와 체크포인트를 확인하려면 task-page를 확인하는 것을 권장합니다.

시작하기 전에 필요한 라이브러리가 모두 설치되어 있는지 확인하세요:

pip install -q datasets transformers accelerate timm trackio torchmetrics pycocotools

🤗 Datasets를 사용하여 Hugging Face Hub에서 데이터셋을 로드하고, 🤗 Transformers를 사용하여 모델을 학습시킵니다.

모델을 커뮤니티와 공유하시도록 권장합니다. Hub에 업로드하려면 Hugging Face 계정에 로그인하세요. 프롬프트가 표시되면 로그인할 토큰을 입력하세요:

>>> from huggingface_hub import notebook_login

>>> notebook_login()

전역 상수, 즉 모델 이름과 이미지 크기를 정의합니다. 이 튜토리얼에서는 RF-DETR를 사용하지만, Transformers의 어떤 객체 감지 모델이든 선택할 수 있습니다.

>>> MODEL_NAME = "Roboflow/rf-detr-medium"

mobile-ui-design 데이터셋을 로드합니다

mobile-ui-design 데이터셋에는 텍스트, 이미지, 사각형, 그룹과 같은 UI 요소를 감지하기 위한 주석이 포함된 모바일 앱 스크린샷이 포함되어 있습니다.

데이터셋을 로드하고 카테고리 라벨을 추출하는 것으로 시작합니다. 데이터셋에는 이미 스플릿이 포함되어 있습니다.

>>> from datasets import load_dataset

>>> ds = load_dataset("merve/mobile-ui-design")

>>> CATEGORIES = sorted(set(
...     cat for split in ds.values() for example in split for cat in example["objects"]["category"]
... ))
>>> label2id = {label: i for i, label in enumerate(CATEGORIES)}
>>> id2label = {i: label for label, i in label2id.items()}
>>> print(f"Categories ({len(CATEGORIES)}): {CATEGORIES}")
Categories (4): ['group', 'image', 'rectangle', 'text']

데이터셋은 문자열 범주 이름과 COCO 형식의 바운딩 박스 (x, y, w, h)를 사용합니다. 학습 전에 범주를 정수 ID로 변환하고, 면적을 계산하며, 퇴화한 바운딩 박스를 필터링하세요:

>>> def prepare_example(example, idx):
...     objects = example["objects"]
...     in_bboxes = objects["bbox"]
...     categories = objects["category"]
...     img_w, img_h = example["width"], example["height"]
...     bboxes, cats, areas, ids = [], [], [], []
...     for i, (bbox, cat) in enumerate(zip(in_bboxes, categories)):
...         x, y, w, h = bbox
...         if w <= 0 or h <= 0:
...             continue
...         x = max(0.0, min(x, img_w))
...         y = max(0.0, min(y, img_h))
...         w = min(w, img_w - x)
...         h = min(h, img_h - y)
...         if w <= 0 or h <= 0:
...             continue
...         bboxes.append([x, y, w, h])
...         cats.append(label2id[cat])
...         areas.append(w * h)
...         ids.append(i)
...     return {
...         "image_id": idx, "image": example["image"],
...         "width": example["width"], "height": example["height"],
...         "objects": {"id": ids, "bbox": bboxes, "category": cats, "area": areas},
...     }

>>> ds_prepared = ds["train"].map(prepare_example, with_indices=True, remove_columns=ds["train"].column_names)
>>> ds_prepared = ds_prepared.filter(lambda x: len(x["objects"]["bbox"]) > 0)

>>> split = ds_prepared.train_test_split(test_size=0.15, seed=1337)
>>> train_ds = split["train"]
>>> val_ds = split["test"]
>>> print(f"Train: {len(train_ds)}, Validation: {len(val_ds)}")
Train: 6669, Validation: 1177

데이터 전처리

AutoImageProcessor는 모델이 학습할 수 있는 pixel_values, pixel_mask, labels를 생성하도록 이미지 데이터를 처리합니다. 이미지 프로세서가 리사이징, 패딩, 정규화를 담당합니다. 이 외에도 일반화 성능을 높이기 위해 임의의 데이터 증강을 선택적으로 추가할 수 있습니다(아래 참조).

>>> import numpy as np
>>> from functools import partial
>>> from transformers import AutoImageProcessor

>>> image_processor = AutoImageProcessor.from_pretrained(MODEL_NAME)

image_processor는 COCO 형식의 어노테이션을 기대합니다: {'image_id': int, 'annotations': list[Dict]}. 각 예시의 어노테이션을 해당 형식으로 정리하고 나머지는 프로세서가 처리하도록 하세요:

>>> def format_image_annotations_as_coco(image_id, categories, areas, bboxes):
...     annotations = []
...     for category, area, bbox in zip(categories, areas, bboxes):
...         annotations.append({
...             "image_id": image_id,
...             "category_id": category,
...             "iscrowd": 0,
...             "area": area,
...             "bbox": list(bbox),
...         })
...     return {"image_id": image_id, "annotations": annotations}

>>> def transform_batch(examples, image_processor):
...     images = []
...     annotations = []
...     for image_id, image, objects in zip(examples["image_id"], examples["image"], examples["objects"]):
...         images.append(np.array(image.convert("RGB")))
...         formatted = format_image_annotations_as_coco(
...             image_id, objects["category"], objects["area"], objects["bbox"]
...         )
...         annotations.append(formatted)
...     result = image_processor(images=images, annotations=annotations, return_tensors="pt")
...     result.pop("pixel_mask", None)
...     return result

>>> transform_fn = partial(transform_batch, image_processor=image_processor)
>>> train_ds = train_ds.with_transform(transform_fn)
>>> val_ds = val_ds.with_transform(transform_fn)

데이터 증강

위 변환은 이미지를 리사이즈하고 정규화하는 것만 수행합니다. training 스플릿에 적용되는 랜덤 증강은 일반적으로 일반화 성능을 향상시키지만, 평가가 결정론적으로 유지되도록 validation 스플릿에는 증강을 적용하지 않는 것이 좋습니다. 일반적인 선택지는 이미지와 바운딩 박스를 함께 증강하는 Albumentations입니다. bbox_params를 사용하여 파이프라인을 정의하면 박스가 이미지와 일관되게 변환되며, 증강된 박스로부터 면적을 다시 계산합니다:

>>> import albumentations as A

>>> train_augment = A.Compose(
...     [
...         A.Perspective(p=0.1),
...         A.HorizontalFlip(p=0.5),
...         A.RandomBrightnessContrast(p=0.5),
...         A.HueSaturationValue(p=0.1),
...     ],
...     bbox_params=A.BboxParams(format="coco", label_fields=["category"], clip=True, min_area=25),
... )

>>> def augment_and_transform_batch(examples, image_processor, transform):
...     images = []
...     annotations = []
...     for image_id, image, objects in zip(examples["image_id"], examples["image"], examples["objects"]):
...         image = np.array(image.convert("RGB"))
...         output = transform(image=image, bboxes=objects["bbox"], category=objects["category"])
...         images.append(output["image"])
...         areas = [w * h for (_, _, w, h) in output["bboxes"]]
...         formatted = format_image_annotations_as_coco(
...             image_id, output["category"], areas, output["bboxes"]
...         )
...         annotations.append(formatted)
...     result = image_processor(images=images, annotations=annotations, return_tensors="pt")
...     result.pop("pixel_mask", None)
...     return result

훈련 분할에만 증강 변환을 적용하고, 검증에는 일반 transform_fn을 유지합니다:

>>> train_augment_fn = partial(augment_and_transform_batch, image_processor=image_processor, transform=train_augment)
>>> train_ds = train_ds.with_transform(train_augment_fn)
>>> val_ds = val_ds.with_transform(transform_fn)

이미지를 배치로 묶기 위해 사용자 정의 collate_fn을 만듭니다:

>>> import torch

>>> def collate_fn(batch):
...     data = {}
...     data["pixel_values"] = torch.stack([x["pixel_values"] for x in batch])
...     data["labels"] = [x["labels"] for x in batch]
...     if "pixel_mask" in batch[0]:
...         data["pixel_mask"] = torch.stack([x["pixel_mask"] for x in batch])
...     return data

mAP을 계산하는 함수 준비

Object detection 모델은 일반적으로 COCO 스타일 지표 세트로 평가됩니다. torchmetrics를 사용하여 mAP(mean average precision)와 mAR(mean average recall) 지표를 계산하고, 이를 compute_metrics 함수로 감싸서 Trainer에서 평가 시 사용할 수 있도록 합니다.

학습에 사용되는 박스의 중간 형식은 YOLO(정규화)이지만, 박스 면적을 올바르게 처리하기 위해 Pascal VOC(절대) 형식의 박스에 대해 메트릭을 계산합니다. 바운딩 박스를 Pascal VOC 형식으로 변환하는 함수를 정의해 보겠습니다:

>>> from transformers.image_transforms import center_to_corners_format

>>> def convert_bbox_yolo_to_pascal(boxes, image_size):
...     """
...     Convert bounding boxes from YOLO format (x_center, y_center, width, height) in range [0, 1]
...     to Pascal VOC format (x_min, y_min, x_max, y_max) in absolute coordinates.

...     Args:
...         boxes (torch.Tensor): Bounding boxes in YOLO format
...         image_size (tuple[int, int]): Image size in format (height, width)

...     Returns:
...         torch.Tensor: Bounding boxes in Pascal VOC format (x_min, y_min, x_max, y_max)
...     """
...     # convert center to corners format
...     boxes = center_to_corners_format(boxes)

...     # convert to absolute coordinates
...     height, width = image_size
...     boxes = boxes * torch.tensor([[width, height, width, height]])

...     return boxes

그런 다음 compute_metrics 함수에서 평가 루프 결과에서 predicted 및 target 바운딩 박스, 점수, 라벨을 수집하여 스코어링 함수에 전달합니다.

>>> import numpy as np
>>> from dataclasses import dataclass
>>> from torchmetrics.detection.mean_ap import MeanAveragePrecision


>>> @dataclass
>>> class ModelOutput:
...     logits: torch.Tensor
...     pred_boxes: torch.Tensor


>>> def _get_orig_size(image_target):
...     """Robust orig_size extraction - Trainer serialization can truncate to 1 element."""
...     orig = np.atleast_1d(np.asarray(image_target["orig_size"])).flatten()
...     if len(orig) >= 2:
...         return (int(orig[0]), int(orig[1]))
...     return (int(orig[0]), int(orig[0]))

>>> @torch.no_grad()
>>> def compute_metrics(evaluation_results, image_processor, threshold=0.0, id2label=None):
...     predictions, targets = evaluation_results.predictions, evaluation_results.label_ids
...     image_sizes = []
...     post_processed_targets = []
...     post_processed_predictions = []
...
...     for batch in targets:
...         batch_sizes = []
...         for image_target in batch:
...             h, w = _get_orig_size(image_target)
...             batch_sizes.append([h, w])
...             boxes = torch.tensor(image_target["boxes"])
...             boxes = convert_bbox_yolo_to_pascal(boxes, (h, w))
...             labels = torch.tensor(image_target["class_labels"])
...             post_processed_targets.append({"boxes": boxes, "labels": labels})
...         image_sizes.append(torch.tensor(batch_sizes))
...
...     for batch, target_sizes in zip(predictions, image_sizes):
...         batch_logits, batch_boxes = batch[1], batch[2]
...         output = ModelOutput(logits=torch.tensor(batch_logits), pred_boxes=torch.tensor(batch_boxes))
...         post_processed_output = image_processor.post_process_object_detection(
...             output, threshold=threshold, target_sizes=target_sizes
...         )
...         post_processed_predictions.extend(post_processed_output)
...
...     metric = MeanAveragePrecision(box_format="xyxy", class_metrics=True)
...     metric.update(post_processed_predictions, post_processed_targets)
...     metrics = metric.compute()
...
...     classes = metrics.pop("classes")
...     map_per_class = metrics.pop("map_per_class")
...     mar_100_per_class = metrics.pop("mar_100_per_class")
...     for class_id, class_map, class_mar in zip(classes, map_per_class, mar_100_per_class):
...         class_name = id2label[class_id.item()] if id2label is not None else class_id.item()
...         metrics[f"map_{class_name}"] = class_map
...         metrics[f"mar_100_{class_name}"] = class_mar
...
...     metrics = {k: round(v.item(), 4) for k, v in metrics.items()}
...     return metrics

>>> eval_compute_metrics_fn = partial(
...     compute_metrics, image_processor=image_processor, id2label=id2label, threshold=0.0
... )

탐지 모델 학습

이전 섹션에서 대부분의 핵심 작업을 완료했으므로 이제 모델을 학습시킬 준비가 되었습니다! 이 데이터셋의 이미지는 리사이즈를 거쳤음에도 여전히 상당히 큽니다. 이는 이 모델을 파인튜닝하려면 최소 하나의 GPU가 필요하다는 것을 의미합니다.

학습에는 다음 단계가 포함됩니다:

  1. 전처리에서 사용한 것과 동일한 체크포인트를 사용하여 AutoModelForObjectDetection로 모델을 로드합니다.
  2. TrainingArguments에서 학습 하이퍼파라미터를 정의합니다.
  3. 모델, 데이터셋, 이미지 프로세서, 데이터 콜레이터와 함께 학습 인수를 Trainer에 전달합니다.
  4. 모델을 파인튜닝하려면 train()을 호출하세요.

사전 처리에 사용한 동일한 체크포인트에서 모델을 로드할 때, 데이터셋의 메타데이터에서 이전에 생성한 label2id와 id2label 매핑을 전달하는 것을 잊지 마세요. 또한, 기존 분류 헤드를 새로운 헤드로 교체하기 위해 ignore_mismatched_sizes=True를 지정합니다.

>>> from transformers import AutoModelForObjectDetection

>>> model = AutoModelForObjectDetection.from_pretrained(
...     MODEL_NAME,
...     id2label=id2label,
...     label2id=label2id,
...     ignore_mismatched_sizes=True,
... )

TrainingArguments에서 output_dir를 사용하여 모델을 저장할 위치를 지정하고, 필요에 따라 하이퍼파라미터를 설정합니다. num_train_epochs=5로 학습하면 A100 GPU에서 약 35분이 소요되며, 더 나은 결과를 얻으려면 에포크 수를 늘리세요.

중요한 참고 사항:

  • 이미지 컬럼이 제거되므로 사용하지 않는 컬럼을 삭제하지 마세요. 이미지 컬럼이 없으면 pixel_values를 생성할 수 없습니다. 이 때문에 remove_unused_columns를 False로 설정하세요.
  • eval_do_concat_batches=False를 설정하면 올바른 평가 결과를 얻을 수 있습니다. 이미지마다 대상 박스의 수가 다르기 때문에, 배치들을 연결하면 특정 이미지에 속하는 박스를 구별할 수 없습니다.

모델을 Hub에 푸시하여 공유하려면 push_to_hub를 True(모델을 업로드하려면 Hugging Face에 로그인되어 있어야 함)로 설정하세요.

>>> from transformers import TrainingArguments

>>> training_args = TrainingArguments(
...     output_dir="rf_detr_finetuned_mobile_ui",
...     num_train_epochs=5,
...     bf16=True,
...     per_device_train_batch_size=8,
...     dataloader_num_workers=4,
...     learning_rate=5e-5,
...     lr_scheduler_type="cosine",
...     weight_decay=1e-4,
...     max_grad_norm=0.01,
...     metric_for_best_model="eval_map",
...     greater_is_better=True,
...     load_best_model_at_end=True,
...     eval_strategy="epoch",
...     save_strategy="epoch",
...     save_total_limit=2,
...     remove_unused_columns=False,
...     report_to="trackio",
...     run_name="mobile-ui-detection",
...     eval_do_concat_batches=False,
...     push_to_hub=True,
... )

마지막으로 모든 것을 통합하고 train()을 호출합니다:

>>> from transformers import Trainer

>>> trainer = Trainer(
...     model=model,
...     args=training_args,
...     train_dataset=train_ds,
...     eval_dataset=val_ds,
...     processing_class=image_processor,
...     data_collator=collate_fn,
...     compute_metrics=eval_compute_metrics_fn,
... )

>>> trainer.train()
[2085/2085 38:39, Epoch 5/5]
Epoch학습 손실검증 손실맵Map 50Map 75Small을 매핑Map Medium대형 매핑3월 1일3월 10일3월 100일3월 Small3월 중간Mar LargeMap GroupMar 100 그룹이미지 매핑Mar 100 이미지사각형 매핑Mar 100 사각형텍스트 매핑Mar 100 Text
1로그 없음9.92340.13030.22360.14780.09090.20300.25240.04210.25200.46830.31130.56070.67820.12440.51220.09580.50350.12850.43280.17250.4413
2로그 없음9.84720.18930.30170.21240.13470.27890.30380.05490.29610.51400.34330.59410.74060.13050.54230.19790.55780.19640.46480.23240.4437
3로그 없음9.64010.22750.35470.26570.16980.33360.38920.06110.32040.52700.36250.61430.74960.16020.56840.26170.57630.22490.46840.26310.4692
4로그 없음9.57700.27330.40680.31330.21000.38670.43430.06680.34560.55930.38750.63930.77250.20130.59410.31580.60650.27330.49980.30280.4756
510.370011.05000.28270.41930.29130.20210.28140.37630.06090.34030.56680.41380.56690.73170.20920.59790.33340.62950.27930.52450.30890.5151

training_args에서 push_to_hub를 True로 설정한 경우, 학습 체크포인트가 Hugging Face Hub에 업로드됩니다. 학습이 완료되면 push_to_hub() 메서드를 호출하여 최종 모델도 Hub에 업로드하세요.

>>> trainer.push_to_hub()

평가

>>> from pprint import pprint

>>> metrics = trainer.evaluate(eval_dataset=val_ds, metric_key_prefix="test")
>>> pprint(metrics)
{'test_loss': 11.05,
 'test_map': 0.2827,
 'test_map_50': 0.4193,
 'test_map_75': 0.2913,
 'test_map_group': 0.2092,
 'test_map_image': 0.3334,
 'test_map_large': 0.3763,
 'test_map_medium': 0.2814,
 'test_map_rectangle': 0.2793,
 'test_map_small': 0.2021,
 'test_map_text': 0.3089,
 'test_mar_1': 0.0609,
 'test_mar_10': 0.3403,
 'test_mar_100': 0.5668,
 'test_mar_100_group': 0.5979,
 'test_mar_100_image': 0.6295,
 'test_mar_100_rectangle': 0.5245,
 'test_mar_100_text': 0.5151,
 'test_mar_large': 0.7317,
 'test_mar_medium': 0.5669,
 'test_mar_small': 0.4138}

TrainingArguments에서 에포크 수를 늘리거나 다른 하이퍼파라미터를 조정하면 이러한 결과를 더 개선할 수 있습니다. 직접 시도해 보세요!

추론

모델을 파인튜닝하고 평가한 후 Hugging Face Hub에 업로드했으므로 이제 추론에 사용할 수 있습니다.

>>> import torch
>>> from PIL import Image, ImageDraw
>>> from transformers import AutoImageProcessor, AutoModelForObjectDetection
>>> from datasets import load_dataset

>>> ds = load_dataset("merve/mobile-ui-design", split="train")
>>> image = ds[5]["image"].convert("RGB")

…

>>> model_repo = "merve/rf_detr_finetuned_mobile_ui"

>>> image_processor = AutoImageProcessor.from_pretrained(model_repo)
>>> model = AutoModelForObjectDetection.from_pretrained(model_repo)
>>> model.eval()

그리고 바운딩 박스를 감지합니다:

>>> with torch.no_grad():
...     inputs = image_processor(images=[image], return_tensors="pt")
...     outputs = model(**inputs)
...     target_sizes = torch.tensor([[image.size[1], image.size[0]]])
...     results = image_processor.post_process_object_detection(outputs, threshold=0.5, target_sizes=target_sizes)[0]

>>> for score, label, box in zip(results["scores"], results["labels"], results["boxes"]):
...     box = [round(i, 2) for i in box.tolist()]
...     print(
...         f"Detected {model.config.id2label[label.item()]} with confidence "
...         f"{round(score.item(), 3)} at location {box}"
...     )
Detected text with confidence 0.727 at location [324.02, 340.55, 339.52, 359.12]
Detected rectangle with confidence 0.717 at location [39.97, 705.14, 335.93, 753.54]
Detected text with confidence 0.702 at location [199.94, 473.66, 213.41, 490.6]
Detected text with confidence 0.678 at location [153.14, 474.81, 165.33, 491.0]
Detected text with confidence 0.675 at location [262.67, 718.28, 281.44, 740.81]
Detected rectangle with confidence 0.655 at location [143.57, 242.51, 214.32, 274.26]
Detected text with confidence 0.653 at location [298.68, 637.77, 345.68, 656.26]

결과를 그래프로 그려 보겠습니다:

>>> draw = ImageDraw.Draw(image)

>>> colors = {"group": "blue", "image": "green", "rectangle": "red", "text": "orange"}
>>> for score, label, box in zip(results["scores"], results["labels"], results["boxes"]):
...     box = [round(i, 2) for i in box.tolist()]
...     x, y, x2, y2 = tuple(box)
...     label_name = model.config.id2label[label.item()]
...     color = colors.get(label_name, "red")
...     draw.rectangle((x, y, x2, y2), outline=color, width=2)
...     draw.text((x, y), f"{label_name} {score:.2f}", fill=color)

>>> image
Object detection result on a cart screen
Object detection result on a followers screen
Update on GitHub