[Ultralytics] 캘리브레이션 데이터셋이 배치보다 작을 때 에러 대신 자동 조정

PR 링크: ultralytics/ultralytics#23899 상태: Merged | 변경: +13 / -23

들어가며

TensorRT INT8 양자화의 캘리브레이션 과정에서, 데이터셋의 이미지 수가 지정된 배치 크기보다 적으면 기존에는 ValueError가 발생하여 export 전체가 중단되었습니다. 이는 사용자에게 불친절한 동작입니다. 소량의 샘플로도 캘리브레이션은 가능하며(정확도가 다소 떨어질 수 있지만), 사용자가 이를 인지한 상태에서 진행할 수 있어야 합니다. 이번 PR은 에러를 경고로 전환하고 배치 크기를 자동으로 조정합니다.

핵심 코드 분석

캘리브레이션 배치 크기 자동 조정

Before:

n = len(dataset)
if n < self.args.batch:
    raise ValueError(
        f"The calibration dataset ({n} images) must have at least as many images "
        f"as the batch size ('batch={self.args.batch}')."
    )
elif self.args.format == "axelera" and n < 100:
    LOGGER.warning(f"{prefix} >100 images required for Axelera calibration, found {n} images.")
elif self.args.format != "axelera" and n < 300:
    LOGGER.warning(f"{prefix} >300 images recommended for INT8 calibration, found {n} images.")
return build_dataloader(dataset, batch=self.args.batch, workers=0, drop_last=True)

After:

n = len(dataset)
if n < 1:
    raise ValueError(f"The calibration dataset must have at least 1 image, but found {n} images.")
batch = min(self.args.batch, n)
if n < self.args.batch:
    LOGGER.warning(
        f"{prefix} calibration dataset has only {n} images, reducing calibration batch size to {batch}."
    )
if self.args.format == "axelera" and n < 100:
    LOGGER.warning(f"{prefix} >100 images required for Axelera calibration, found {n} images.")
elif self.args.format != "axelera" and n < 300:
    LOGGER.warning(f"{prefix} >300 images recommended for INT8 calibration, found {n} images.")
return build_dataloader(dataset, batch=batch, workers=0, drop_last=True)

변경 포인트:

1. 에러 기준 변경: n < batch에서 n < 1로 — 최소 1장이면 진행 가능
2. 자동 조정: batch = min(self.args.batch, n)으로 배치 크기를 데이터셋 크기에 맞춤
3. 경고 분리: elif에서 if로 변경하여 배치 조정 경고와 권장 이미지 수 경고가 독립적으로 표시

또한 build_dataloader 호출에서 self.args.batch 대신 조정된 batch를 사용합니다.

왜 이게 좋은가

1. 사용자 경험 개선: export 파이프라인이 중간에 에러로 중단되는 대신 자동 조정되어, 사용자가 배치 크기를 수동으로 맞출 필요가 없습니다.

2. 정보의 투명성: 경고 메시지로 실제 적용된 배치 크기를 알려주어, 캘리브레이션 품질에 대한 판단을 사용자에게 맡깁니다.

3. 방어적 프로그래밍: 진짜 에러(데이터셋이 비어있음)만 에러로 처리하고, 나머지는 graceful degradation으로 처리하는 원칙을 따릅니다.

정리

INT8 캘리브레이션에서 ValueError를 LOGGER.warning으로 전환하고 배치 크기를 자동 조정하는 사용자 친화적 개선입니다. 에러보다 경고를, 중단보다 적응을 선택하는 좋은 설계 판단입니다.

참고 자료

• ultralytics/ultralytics#23899
• TensorRT INT8 캘리브레이션 가이드

---

이 글은 AI(Claude)의 도움을 받아 작성되었으며, 실제 PR의 코드 변경 사항을 기반으로 분석한 내용입니다.