실전: rfdetr 패키지
지금까지 13개 장에 걸쳐 RF-DETR 의 부품을 하나씩 직접 만들었습니다. 박스와 IoU, AP, 어텐션, DINOv2 백본, 헝가리안 매칭, 변형 어텐션, 윈도 어텐션, IA-BCE 손실, EMA, 가중치 공유 NAS 까지.
이 장에서는 손으로 만든 미니 모델을 내려놓고 진짜 RF-DETR, 곧 Roboflow 가 공개한 rfdetr 패키지를 씁니다.
사전 학습 모델로 추론하고, 내 데이터(도형 세상)로 미세 조정하고, 채점하고, 다른 실행 환경으로 내보내 지연 시간을 재 봅니다.
그리고 단계마다 “앞 장에서 만든 그 부품이 지금 여기서 돌고 있다” 는 것을 짚어 갑니다.
rfdetr패키지의 설치, 모델 가족(크기 · 해상도 · 지연 시간 · AP)과 라이선스predict()가 돌려주는supervision.Detections의 구조, 그리고 그 앞뒤의 전처리 · 후처리(질의 × 클래스 전체에서 상위 K 개 고르기)- 내 데이터를 COCO 형식 폴더로 만드는 법과, 2장의 정규화
(cx, cy, w, h)와 COCO 의 픽셀[x, y, w, h]사이의 변환 train()의 주요 인자, 실효 배치 크기, 학습 로그의 손실 이름 읽기, 체크포인트 파일의 뜻- RF-DETR Nano 를 도형 세상에 실제로 미세 조정한 결과와, 사전 학습 가중치에서 시작할 때와 무작위 초기화에서 시작할 때의 차이
- 패키지의 평가 지표를 3장의 AP 와 맞대어 보기, 문턱값 ·
num_select· 해상도 바꿔 보기 - ONNX 로 내보내 onnxruntime 으로 돌리고, 날출력을 직접 후처리하고, 지연 시간을 바르게 재는 법
이 장의 모든 API · 인자 이름 · 기본값 · 출력은 rfdetr 1.12.1(2026년 11월 기준 설치판; torch 2.15.0, supervision 0.31.7, onnx 1.23.2, onnxruntime 1.32.0)에서 실제로 돌려 확인한 것 입니다.
패키지는 빠르게 바뀌므로(예를 들어 예전 글에 자주 나오는 optimize_for_inference() 는 이 판에 없습니다) 다른 판을 쓴다면 이름이 조금 다를 수 있습니다.
돌려 보지 못하고 공식 문서 · 소스의 설명만 옮긴 곳은 “문서에 따르면” 이라고 따로 밝혔습니다.
원리에서 도구로
앞 장들의 미니 구현은 원리를 보이려고 일부러 작게 만든 것입니다. 96×96 그림, 수십만 개의 매개변수, 몇 분의 학습.
진짜 RF-DETR Nano 는 매개변수가 약 3,050만 개이고, DINOv2 로 사전 학습된 백본 위에서 Objects365 와 COCO 로 학습된 가중치를 가지고 있습니다.
그 가중치와, 학습 · 추론 · 내보내기에 필요한 모든 코드를 묶어 놓은 것이 rfdetr 패키지입니다.
패키지를 쓰는 흐름은 다섯 단계입니다. 이 장의 차례도 이 순서를 따릅니다.
실습 파일은 세 개입니다. 차례로 실행합니다.
| 파일 | 하는 일 | 걸린 시간(이 튜토리얼의 노트북) |
|---|---|---|
ch14_make_coco.py | 도형 세상을 COCO 형식 폴더로 내보내기 | CPU 약 15초 |
ch14_finetune.py | 사전 학습 모델 추론 → 미세 조정 2회 → 평가 → 추론 설정 바꿔 보기 | GPU 약 30분(학습 18.2분 + 8.5분, 그 밖의 단계 약 3분 반) |
ch14_export.py | ONNX 내보내기 → onnxruntime 추론 → 지연 시간 재기 | GPU + CPU 약 5분(그 가운데 3분은 추론 전용 스냅숏 두 개를 준비하는 시간) |
설치와 모델 가족
설치
패키지는 Python 3.10 이상에서 pip 로 설치합니다. 기본 설치는 추론에 필요한 것만 들어 있고, 학습과 내보내기에 필요한 패키지는 “추가 묶음(extras)” 으로 나뉘어 있습니다.
이 장의 세 파일을 모두 돌리려면 train 과 onnx 묶음이 필요합니다.
$ pip install "rfdetr[train,onnx]"
| 설치 명령 | 들어오는 것 | 이 장에서 쓰는 곳 |
|---|---|---|
pip install rfdetr | torch · torchvision · transformers · supervision · pydantic 등. 추론(predict)만 가능 | 사전 학습 모델로 추론 |
pip install "rfdetr[train]" | pytorch_lightning · torchmetrics · pycocotools 를 비롯한 COCO 채점기들 · roboflow 등 | train(), evaluate() |
pip install "rfdetr[onnx]" | onnx · onnxruntime | export() 와 ONNX 추론 |
pip install "rfdetr[plus]" | rfdetr_plus(다른 라이선스의 모델들, 아래 참고) | 쓰지 않음 |
-
학습 묶음을 빼먹으면
train()을 부를 때RF-DETR training dependencies are missing. Install them with `pip install "rfdetr[train,loggers]"`라는ImportError가 납니다. (loggers묶음은 TensorBoard · wandb · mlflow 같은 기록 도구입니다. 이 장은 쓰지 않습니다.) - GPU. 추론은 CPU 로도 되지만 학습은 NVIDIA GPU 가 사실상 필요합니다. 이 장의 실험은 8GB 노트북 GPU(NVIDIA RTX PRO 2000 Blackwell) 한 장으로 했습니다. GPU 가 있다면 0장 의 안내대로 CUDA 판 torch 를 먼저 설치해 두세요.
-
가중치 파일. 모델 클래스를 처음 만들 때 사전 학습 가중치를 내려받아
~/.roboflow/models/에 둡니다(환경 변수RF_HOME으로 바꿀 수 있습니다). Nano 의rf-detr-nano.pth는 366 MB 였습니다. 열어 보면 모델 가중치(116 MB)와 함께 옵티마이저의 상태가 들어 있어서 큽니다(미세 조정 뒤에 생기는 추론용 체크포인트는 약 120 MB 입니다). -
이 튜토리얼의 다른 장은 torch · numpy · matplotlib · scipy 만 쓰지만(
requirements.txt), 이 장의 코드만은 rfdetr · supervision · pillow · onnx · onnxruntime 을 씁니다.
모델 가족과 라이선스
RF-DETR 은 모델 하나가 아니라 크기가 다른 모델들의 가족 입니다. 12장 에서 본 것처럼, 가중치 공유 NAS 로 찾은 파레토 곡선 위의 점들에 이름(Nano, Small, Medium …)을 붙인 것입니다. 패키지에서는 크기마다 클래스가 하나씩 있습니다.
| 과제 | 클래스 | 라이선스 | 설치 |
|---|---|---|---|
| 객체 탐지 | RFDETRNano, RFDETRSmall, RFDETRMedium, RFDETRLarge | Apache 2.0 | rfdetr |
| 객체 탐지 | Atto · Femto · Pico(아주 작은 것), XLarge · 2XLarge(아주 큰 것) | PML 1.0 | rfdetr[plus] |
| 인스턴스 분할 | RFDETRSegNano, …SegSmall, …SegMedium, …SegLarge, …SegXLarge, …Seg2XLarge | Apache 2.0 | rfdetr |
| 키포인트 탐지(미리보기) | RFDETRKeypointPreview | Apache 2.0 | rfdetr |
라이선스는 실무에서 가장 먼저 확인할 것입니다. 저장소 README(2026년 11월)에 따르면 이렇습니다.
- Apache 2.0:
rfdetr패키지 자체, 탐지 Nano · Small · Medium · Large, 분할 전 크기, 키포인트 모델. 소스를 공개하지 않는 상용 제품에 넣어도 되고 사용료가 없습니다. -
PML 1.0(Roboflow Platform Model License): 탐지 Atto · Femto · Pico · XLarge · 2XLarge.
rfdetr[plus]로 따로 설치합니다. README 는 “Roboflow 에 배포하면 상업적 이용이 포함되고, 직접 운영하는 상업적 이용에는 Enterprise 추가 계약이 필요하다” 고 적고 있습니다. pip install rfdetr만으로는 Apache 2.0 인 코드와 모델만 들어옵니다. 이 장은 Apache 2.0 인 Nano 만 씁니다.
위 내용은 이 글을 쓴 시점의 README 를 옮긴 것이고 법률 조언이 아닙니다. 제품에 넣기 전에 그 시점의 저장소 LICENSE 와 README 의 License 절을 직접 읽으세요.
크기별 성능표
아래 표의 왼쪽 절반(해상도 – 질의 수)은 설치판의 설정 클래스(RFDETRNanoConfig 등)에서 읽은 값이고, 오른쪽 절반은 저장소 README 의 벤치마크 표에서 옮긴 값입니다.
README 는 지연 시간을 “NVIDIA T4, TensorRT, FP16, 배치 1” 로, COCO AP 를 val2017 5,000장 전체로 쟀다고 밝힙니다.
| 크기 | 해상도 | 패치 | 윈도(한 변) | 디코더 층 | 질의 | 매개변수(M) | 지연(ms) | COCO AP50:95 | AP50 |
|---|---|---|---|---|---|---|---|---|---|
| Nano | 384 | 16 | 2 | 2 | 300 | 30.5 | 2.3 | 48.4 | 67.6 |
| Small | 512 | 16 | 2 | 3 | 300 | 32.1 | 3.5 | 53.0 | 72.1 |
| Medium | 576 | 16 | 2 | 4 | 300 | 33.7 | 4.4 | 54.7 | 73.6 |
| Large | 704 | 16 | 2 | 4 | 300 | 33.9 | 6.8 | 56.5 | 75.1 |
-
네 크기의 백본은 모두 같습니다(DINOv2-S 에 윈도 어텐션을 넣은
dinov2_windowed_small, 은닉 차원 256). 달라지는 것은 12장 의 손잡이 가운데 해상도 와 디코더 층 수 뿐입니다. 그래서 매개변수는 30.5M → 33.9M 으로 조금만 늘고(디코더 층과, 해상도를 따라 늘어나는 위치 임베딩만큼), 지연 시간은 해상도를 따라 2.3 → 6.8 ms 로 늘어납니다. - 설치판에서 직접 센 Nano 의 매개변수는 30,467,298개로 표의 30.5M 과 맞습니다(아래 실행 출력).
- 같은 Nano 의 COCO AP 가 README 에는 48.4, 논문 표 2 에는 48.0 으로 적혀 있습니다(1장). 측정 시점 · 방법이 다른 두 출처이므로 섞어 쓰지 않습니다. 이 표는 README 값입니다.
- README 의 같은 표에서 PML 1.0 모델은 Atto 30.5 AP / 1.0 ms(380×380)부터 2XLarge 60.1 AP / 17.2 ms(880×880)까지입니다.
2.3 ms 는 서버용 GPU T4 에서 TensorRT 로 변환하고 FP16 으로 잰, 모델 순전파만의 시간입니다. 같은 Nano 를 이 튜토리얼의 노트북에서 PyTorch 로 돌리면 전혀 다른 값이 나옵니다. 무엇이 왜 다른지는 이 장 뒤쪽의 지연 시간 재기 에서 직접 재 봅니다.
사전 학습 모델로 추론
모델 만들기와 predict
가장 짧은 사용법은 세 줄입니다. 클래스를 만들면 가중치를 내려받아 읽고, predict 에 그림을 주면 결과가 돌아옵니다.
from rfdetr import RFDETRNano
model = RFDETRNano() # COCO 로 학습된 가중치를 내려받아 읽는다
detections = model.predict("my_photo.jpg", threshold=0.5)
print(detections.xyxy, detections.confidence, detections.class_id)
my_photo.jpg 자리에 여러분의 사진을 넣어 꼭 직접 해 보세요. 사람 · 자동차 · 개 같은 COCO 의 80가지 물체가 찍힌 사진이면 박스가 잘 나옵니다.
이 튜토리얼은 남의 사진을 싣지 않으므로, 아래 실행 예는 모두 우리의 도형 세상 그림으로 합니다.
COCO 에는 “원 · 사각형 · 삼각형” 이라는 클래스가 없으니 잘 될 리가 없습니다. 그 “안 되는 모습” 이 미세 조정이 왜 필요한지를 보여 주는 출발점입니다.
ch14_finetune.py 의 첫 단계가 이 일을 합니다. 모델을 만들고, 설정을 찍고, 입력 형태를 바꿔 가며 같은 결과가 나오는지 확인합니다.
$ python ch14_finetune.py --quick # 학습 없이 이 단계만
[0] 환경: rfdetr 1.12.1, torch 2.15.0+cu132, supervision 0.31.7, 장치 NVIDIA RTX PRO 2000 Blackwell Generation Laptop GPU
[1] COCO 로 사전 학습된 RF-DETR Nano 를 도형 세상에 그대로 써 보기
모델 준비 8.7초 | 매개변수 30,467,298개
설정: resolution=384, patch_size=16, num_windows=2, dec_layers=2, num_queries=300, num_select=300, group_detr=13, num_classes=90
분류 머리: Linear(in_features=256, out_features=91, bias=True)
COCO_CLASSES: 이름 80개, id 범위 1 – 90, 예: 'person', 'dog'
입력 형태 check (경로 기준 박스 최대 차이, 픽셀): PIL 0.0e+00, numpy 0.0e+00, 텐서 0.0e+00, 배치 5.6e-03
predict 가 돌려준 것: supervision.detection.core.Detections, 객체 21개 (threshold=0.05)
xyxy [0.0, 0.0, 192.0, 192.0] confidence 0.390 class_id 82 → 'refrigerator'
xyxy [0.0, 0.0, 192.0, 192.0] confidence 0.110 class_id 85 → 'clock'
xyxy [0.0, 0.0, 192.0, 192.0] confidence 0.102 class_id 61 → 'cake'
xyxy [0.0, 0.0, 192.0, 192.0] confidence 0.083 class_id 13 → 'stop sign'
시험 그림 50장, threshold=0.5: 탐지 3개
시험 그림 50장, threshold=0.3: 탐지 18개
시험 그림 50장, threshold=0.1: 탐지 412개
시험 그림 50장, threshold=0.05: 탐지 2500개
threshold=0.1 에서 붙인 이름 (많은 순): person 48, tv 46, clock 33, refrigerator 32, apple 24, laptop 22
그림 저장: figures/ch14-coco-model-on-shapes.png출력의 둘째 줄이 반갑습니다. 10장 에서 직접 만든 구조의 손잡이들이 그대로 보입니다.
| 설정 | 값(Nano) | 뜻 | 만들어 본 장 |
|---|---|---|---|
resolution | 384 | 모델 입력 그림의 한 변(픽셀) | 12장 |
patch_size | 16 | 패치 한 변. 384 ÷ 16 = 24 → 패치 토큰 24 × 24 = 576개 | 6장 |
num_windows | 2 | 윈도 어텐션에서 한 변을 나누는 수 → 윈도 2 × 2 = 4개, 윈도 하나에 12 × 12 = 144 토큰 | 9장 |
dec_layers | 2 | 디코더 층 수 | 7장, 12장 |
num_queries | 300 | 객체 질의 수 = 그림 한 장에서 나오는 박스 후보 수 | 7장 |
num_select | 300 | 후처리가 남기는 예측 수(아래 “후처리” 절) | 이 장 |
group_detr | 13 | 학습 때만 쓰는 질의 묶음 수. 추론은 첫 묶음 300개만 | 9장 |
num_classes | 90 | COCO 의 범주 id 가 1 – 90 이라 90. 분류 머리의 출력은 그보다 하나 많은 91칸 | 이 장 |
Detections 읽는 법
predict 가 돌려주는 것은 Detectionssupervision.Detections 입니다.
Roboflow 의 시각화 · 후처리 라이브러리 supervision 이 정의한, 탐지 결과를 담는 그릇입니다. 객체가 $n$ 개 탐지되었다면 필드의 모양은 이렇습니다.
| 필드 | 모양 · 자료형 | 내용 |
|---|---|---|
xyxy | (n, 4) float32 | 박스의 두 모서리 $(x_0, y_0, x_1, y_1)$. 원본 그림의 픽셀 좌표(모델 입력 384 의 좌표가 아님) |
confidence | (n,) float32 | 점수(신뢰도). 시그모이드를 거친 0 – 1 의 값이고 내림차순 으로 정렬되어 있음 |
class_id | (n,) int64 | 클래스 번호 |
data["class_name"] | (n,) 문자열 | 클래스 이름 |
data["source_shape"] | (n, 2) int64 | 원본 그림의 (높이, 너비) |
metadata["source_image"] | (H, W, 3) uint8 | 원본 그림(include_source_image=False 로 끌 수 있음) |
mask | None | 탐지 모델은 비어 있음. 분할 모델이면 객체별 마스크 |
len(detections) 는 객체 수 $n$ 이고, detections[detections.confidence > 0.7] 처럼 불 배열로 골라낼 수 있습니다.
이 튜토리얼은 2장부터 줄곧 박스를 정규화한 중심 표현 $(c_x, c_y, w, h)$ 로 써 왔습니다. xyxy 픽셀 좌표를 우리 형식으로 바꾸는 식은 2장의 변환에 “그림 크기로 나누기” 를 더한 것입니다.
원본 그림의 너비를 $W$, 높이를 $H$ 라 하면
예를 들어 192 × 192 그림에서 xyxy = [72, 24, 120, 120] 이면
$c_x = (72 + 120)/(2 \cdot 192) = 0.5$, $c_y = (24 + 120)/384 = 0.375$, $w = 48/192 = 0.25$, $h = 96/192 = 0.5$ 입니다.
3장의 evaluate_ap 에 넣을 수 있게 바꿔 주는 함수가 아래입니다. 이 장의 채점은 모두 이 함수를 거칩니다.
클래스 번호와 이름
위 출력에서 class_id 82 → 'refrigerator' 를 보세요. COCO 의 클래스는 80가지인데 번호가 82 입니다.
COCO 의 범주 id 는 1 부터 90 까지이고 그 가운데 10개(12, 26, 29, 30, 45, 66, 68, 69, 71, 83)가 비어 있기 때문입니다. 그래서
- 사전 학습 모델의
num_classes는 80 이 아니라 90 이고, 분류 머리는Linear(256 → 91)입니다. -
class_id는 COCO 범주 id 그대로입니다. 이름은rfdetr.assets.coco_classes.COCO_CLASSES사전으로 찾습니다(COCO_CLASSES[1]은"person",COCO_CLASSES[18]은"dog").data["class_name"]에는 이 이름이 이미 들어 있습니다. -
model.class_names는 이름 80개의 목록인데, 번호로 바로 찾으면 틀립니다(class_names[18]은 개가 아니라 양(sheep)입니다). 사전 학습 모델에서는 꼭COCO_CLASSES나data["class_name"]을 쓰세요.
미세 조정한 모델은 훨씬 단순합니다. 클래스 번호가 0 부터 차례로 매겨지고 model.class_names[class_id] 가 곧 이름입니다. 이 차이는 “내 데이터 준비” 절에서 다시 봅니다.
입력 형태
predict 의 첫 인자는 여러 형태를 받습니다. 위 실행의 입력 형태 check 줄이 같은 그림을 네 가지로 넣어 박스가 같은지 본 것입니다.
| 형태 | 조건 |
|---|---|
| 파일 경로 · URL 문자열 | URL 은 그 자리에서 내려받으므로 믿을 수 있는 주소만 |
PIL.Image | RGB 로 바뀌어 쓰임 |
| numpy 배열 | (H, W, 3), RGB 순서. uint8(0 – 255)이면 그대로, 실수형이면 0 – 1 범위 |
torch.Tensor | (3, H, W), 이미 0 – 1 로 나눈 실수. (B, 3, H, W) 를 주면 그림 B 장으로 나누어 처리 |
| 위의 것들의 목록 | 한 배치로 처리하고 Detections 의 목록 을 돌려줌 |
- 경로 · PIL · numpy · 텐서 넷은 박스가 완전히 같았습니다(차이 0). 두 장을 한 배치로 넣었을 때만 0.006 픽셀쯤 달라졌는데, 배치 크기가 바뀌면 GPU 의 연산 순서가 달라져 생기는 부동소수점 오차입니다.
-
OpenCV 로 읽은 그림은 BGR 순서 입니다. 그대로 넣으면 빨강과 파랑이 뒤바뀐 그림을 보게 됩니다.
image[:, :, ::-1]로 뒤집어 넣으세요. - 동영상 · 폴더 · 웹캠은
predict가 받지 않습니다. 문서에 따르면RFDETRInference(model).predict(…)가 그런 입력을 다룹니다(이 장에서는 돌려 보지 않았습니다).
전처리: 리사이즈와 정규화
그림이 모델에 들어가기 전에 거치는 손질을 전처리preprocessing 라고 합니다. predict 안에서 일어나는 일은 세 단계입니다.
- 0 – 1 로. uint8 픽셀값을 255 로 나누고, 모양을
(H, W, 3)에서(3, H, W)로 바꿉니다. -
리사이즈. 가로세로 비율을 무시하고
resolution × resolution(Nano 는 384 × 384)으로 쌍선형 보간합니다(8장 의 그 쌍선형 보간입니다). 우리 그림은 192 × 192 이므로 가로세로 두 배로 커집니다. 길쭉한 사진은 찌그러져 들어가지만, 출력 박스는 원본 크기로 되돌려 주므로 쓰는 사람은 신경 쓸 일이 없습니다. - 정규화. 채널마다 평균을 빼고 표준편차로 나눕니다. 값은 ImageNet 의 통계로, DINOv2 가 사전 학습될 때 쓴 것과 같습니다. $$ \tilde{x}_c = \frac{x_c - \text{mean}_c}{\text{std}_c}, \qquad \text{mean} = (0.485,\ 0.456,\ 0.406), \quad \text{std} = (0.229,\ 0.224,\ 0.225) $$ 여기서 $x_c$ 는 채널 $c$(R, G, B)의 0 – 1 픽셀값, $\text{mean}_c$ · $\text{std}_c$ 는 그 채널의 평균 · 표준편차, $\tilde{x}_c$ 는 모델에 들어가는 값입니다.
숫자로 확인합니다. 시험 그림 0번의 왼쪽 위 픽셀은 RGB (30, 17, 39) 입니다(어두운 회색 배경에 잡음이 섞인 값). R 채널은
$$ \tilde{x}_R = \frac{30/255 - 0.485}{0.229} = \frac{0.1176 - 0.485}{0.229} = -1.6042 $$
입니다. 뒤에 나올 ch14_export.py 가 같은 전처리를 직접 구현해 이 값을 찍어 봅니다(전처리 예 줄).
predict(…, antialias=False) 가 기본입니다. 그림을 줄일 때 계단 현상을 막는 흐림 처리(안티에일리어싱)를 할지 정하는 인자로, 문서는 “학습 때의 리사이즈 방식과 맞추라” 고 합니다.
우리처럼 192 를 384 로 키우는 경우에는 결과에 차이가 없습니다. 모델 해상도보다 훨씬 큰 사진을 다룬다면 두 값을 다 돌려 검증 AP 가 좋은 쪽을 고르세요.
후처리: 질의 곱하기 클래스에서 상위 K 고르기
모델(신경망)이 내놓는 날출력은 두 텐서입니다. 질의 수를 $Q$(= 300), 분류 머리의 출력 칸 수를 $C$(COCO 모델은 91)라 하면
pred_boxes: 모양(B, Q, 4). 질의마다의 박스, 정규화 $(c_x, c_y, w, h)$pred_logits: 모양(B, Q, C). 질의마다 · 클래스마다의 로짓(시그모이드를 거치기 전의 값)
이것을 “점수 높은 박스 몇 개” 로 바꾸는 손질이 후처리postprocessing 입니다.
7장 의 DETR 은 질의마다 소프트맥스로 클래스 하나 를 골랐습니다. RF-DETR 은 다릅니다.
4장 · 9장 에서 본 것처럼 분류 손실이 시그모이드 기반(IA-BCE)이라, 칸 하나하나가 “이 질의가 이 클래스의 객체인가” 를 따로 답하는 독립된 점수 입니다.
그래서 후처리도 질의 단위가 아니라 (질의, 클래스) 쌍 단위로 합니다. 패키지의 PostProcess(rfdetr/models/postprocess.py)가 하는 일을 순서대로 적으면 이렇습니다.
threshold, 기본 0.5)보다 큰 것만 남깁니다. NMS 는 어디에도 없습니다(7장: 헝가리안 매칭으로 학습한 모델은 중복 예측을 스스로 억제합니다).
작은 숫자로 따라가 봅니다. 질의 3개($Q = 3$), 클래스 2개($C = 2$), num_select $= 3$, 그림은 너비 200 · 높이 100 이라 하고 로짓이 다음과 같다고 합시다.
| 질의 $q$ | 박스 $(c_x, c_y, w, h)$ | 로짓 $z_{q,0}$ | 로짓 $z_{q,1}$ | 점수 $s_{q,0}$ | 점수 $s_{q,1}$ |
|---|---|---|---|---|---|
| 0 | (0.5, 0.5, 0.2, 0.4) | 2.0 | −1.0 | 0.8808 | 0.2689 |
| 1 | (0.25, 0.75, 0.5, 0.5) | 0.0 | 1.0 | 0.5000 | 0.7311 |
| 2 | (0.8, 0.2, 0.1, 0.1) | −3.0 | −2.0 | 0.0474 | 0.1192 |
- 시그모이드: $\sigma(2) = 1/(1 + e^{-2}) = 1/1.1353 = 0.8808$, $\sigma(1) = 1/1.3679 = 0.7311$, $\sigma(0) = 0.5$ 등.
- 편 번호: 점수를 한 줄로 펴면 $[0.8808,\ 0.2689,\ 0.5000,\ 0.7311,\ 0.0474,\ 0.1192]$ (편 번호 0 – 5).
- 상위 3개: 편 번호 0(0.8808), 3(0.7311), 2(0.5000).
- 풀기: $0 \to (q, c) = (0, 0)$, $\ 3 \to (\lfloor 3/2 \rfloor,\ 3 \bmod 2) = (1, 1)$, $\ 2 \to (1, 0)$. 질의 1 이 두 번 뽑혔습니다. 한 번은 클래스 1 로, 한 번은 클래스 0 으로. 같은 박스가 서로 다른 이름표를 달고 두 번 나올 수 있다는 뜻입니다.
- 박스: 질의 0 은 $((0.5 - 0.1) \cdot 200,\ (0.5 - 0.2) \cdot 100,\ (0.5 + 0.1) \cdot 200,\ (0.5 + 0.2) \cdot 100) = (80, 30, 120, 70)$, 질의 1 은 $((0.25 - 0.25) \cdot 200,\ (0.75 - 0.25) \cdot 100,\ 0.5 \cdot 200,\ 1.0 \cdot 100) = (0, 50, 100, 100)$.
- 문턱값 0.5: 0.8808 과 0.7311 은 남고, 0.5000 은 0.5 보다 크지 않으므로 빠집니다. 결과는 두 개입니다.
같은 계산을 코드로 한 것이 아래입니다(ch14_export.py). 이 함수는 뒤에서 ONNX 모델의 날출력을 직접 후처리하는 데 그대로 쓰입니다.
손계산 예: 시그모이드 점수 (질의 3 × 클래스 2) = [[0.8808, 0.2689], [0.5, 0.7311], [0.0474, 0.1192]]
편 번호 상위 3개 [0, 3, 2] → 질의 [0, 1, 1], 클래스 [0, 1, 0], 점수 [0.8808, 0.7311, 0.5]
문턱값 0.5 통과: 질의 0, 클래스 0, 점수 0.8808, xyxy [80.0, 30.0, 120.0, 70.0]
문턱값 0.5 통과: 질의 1, 클래스 1, 점수 0.7311, xyxy [0.0, 50.0, 100.0, 100.0]
num_select = 300 이라고 해서 질의 300개가 하나씩 나오는 것이 아닙니다. 27,300 개의 (질의, 클래스) 쌍 가운데 점수가 높은 300 쌍입니다.
자신 있는 질의는 여러 클래스로 여러 번 뽑힐 수 있고, 자신 없는 질의는 한 번도 안 뽑힐 수 있습니다.
다만 잘 학습된 모델에서는 둘째 클래스의 점수가 보통 문턱값보다 한참 낮아서, threshold=0.5 를 넘는 결과에서 같은 박스가 두 번 보이는 일은 드뭅니다.
COCO 모델은 도형을 모른다
이제 위 실행 출력의 아래쪽을 읽어 봅시다. COCO 로 학습된 Nano 에게 도형 세상의 시험 그림 50장을 보여 준 결과입니다.
- 기본 문턱값 0.5 에서는 거의 아무것도 나오지 않습니다. 50장(정답 객체 123개)에서 탐지 3개. 모델은 “내가 아는 물체가 없다” 고 꽤 정직하게 답하고 있습니다.
- 문턱값을 낮추면 엉뚱한 이름이 쏟아집니다. 0.1 에서 412개, 0.05 에서는 2,500개(그림당 50개). 붙인 이름은 person 48, tv 46, clock 33, refrigerator 32, apple 24, laptop 22 순입니다. 네모난 것(TV · 냉장고 · 노트북)과 둥근 것(시계 · 사과)의 이름이 많은 것을 보면, 처음 보는 도형을 “아는 것 가운데 가장 비슷한 것” 에 끼워 맞추고 있는 듯합니다.
-
박스의 위치도 맞지 않습니다. 시험 그림 0번에서 점수가 가장 높은 예측은 그림 전체(
[0, 0, 192, 192])를 냉장고(0.39)라고 한 것입니다. 그림 14-2 에서도 분홍 박스는 대부분 그림 전체나 도형 여러 개를 한꺼번에 감싸고 있습니다. 다만 도형 하나에 꼭 맞는 박스도 가끔 보입니다 — 클래스 이름은 몰라도 “무언가 덩어리가 있다” 는 것은 느끼고 있다는 뜻입니다.
그렇다고 이 모델이 쓸모없는 것은 아닙니다. 이름표(분류 머리)만 우리 것이 아닐 뿐, 그 아래의 백본 · 프로젝터 · 디코더는 “그림에서 물체를 찾아 박스를 두르는 법” 을 이미 알고 있습니다. 미세 조정 은 그 지식을 그대로 둔 채 이름표를 우리 클래스로 갈아 끼우고 조금 더 학습하는 일입니다. 그러려면 먼저 우리 데이터를 패키지가 읽을 수 있는 모양으로 만들어야 합니다.
추론 전용 스냅숏
위 출력에는 생략했지만, predict 를 처음 부르면 패키지가 이런 경고를 한 번 냅니다.
[WARNING] rf-detr - Model is not optimized for inference. Latency may be higher than expected. Create predictor = native_model.inference(...) and use predictor.predict(...).
model.predict() 는 학습할 때와 같은 일반 PyTorch 모듈로 추론합니다. 편하지만 가장 빠른 길은 아닙니다.
predictor = model.inference() 는 지금의 가중치를 복사해 배치 크기와 해상도를 고정한 추론 전용 사본을 만들어 돌려주고(GPU 에서는 연산 순서를 미리 기록해 두었다가 재생하는 CUDA 그래프를 씁니다),
그 뒤로는 predictor.predict(그림) 을 씁니다. 반정밀도로 만들려면 model.inference(dtype="float16") 입니다. 얼마나 빨라지는지는 지연 시간 절에서 잽니다.
예전 글과 예제에는 model.optimize_for_inference() 가 자주 나옵니다. 1.12.1 에서 부르면 AttributeError: 'RFDETRNano' object has no attribute 'optimize_for_inference' 가 납니다.
저장소의 변경 기록(CHANGELOG)에 따르면 이 이름은 1.9 부터 inference() 로 바뀌었고 그 뒤 지워졌습니다. 또 예전에는 모델 자체를 바꿔 놓았지만, 지금의 inference() 는 원래 모델을 건드리지 않고 새 추론기를 돌려줍니다.
내 데이터 준비: COCO 형식
패키지가 받는 폴더 구조
train(dataset_dir=…) 에는 폴더 하나를 줍니다. 패키지는 그 안을 보고 형식을 스스로 알아냅니다. 문서와 소스에 따르면 두 가지를 받습니다.
| 형식 | 알아보는 기준 | 주석이 담긴 곳 | 박스 표기 |
|---|---|---|---|
| COCO 형식COCO format | train/_annotations.coco.json 이 있다 |
분할(train · valid · test)마다 JSON 파일 하나 | 픽셀 [x, y, w, h], (x, y) 는 왼쪽 위 모서리 |
| YOLO 형식YOLO format | data.yaml(또는 data.yml)과 학습 그림 폴더가 있다 |
그림마다 .txt 파일 하나(labels/), 클래스 이름은 data.yaml |
정규화 클래스 cx cy w h — 2장의 우리 형식과 같음 |
둘 다 있으면 COCO 가 우선입니다. 이 장은 COCO 형식을 씁니다(직접 돌려 확인한 것도 COCO 형식뿐입니다). 폴더는 이렇게 생겼습니다.
ch14_shapes_coco/
├── train/
│ ├── _annotations.coco.json ← 학습용 주석 (이 이름 그대로여야 한다)
│ ├── 000000.png
│ ├── 000001.png
│ └── …
├── valid/ ← 검증용. "val" 이 아니라 "valid"
│ ├── _annotations.coco.json
│ └── …
└── test/ ← 시험용. evaluate(split="test") 가 읽는다
├── _annotations.coco.json
└── …
세 분할의 역할은 3장 에서 본 그대로입니다. 학습 세트로 가중치를 고치고, 검증 세트로 에폭마다 채점해 가장 좋은 체크포인트를 고르고, 시험 세트는 마지막에 한 번만 봅니다.
이 폴더 구조는 Roboflow 서비스에서 데이터셋을 “COCO” 로 내려받았을 때의 구조와 같습니다. 그래서 train() 의 dataset_file 인자의 기본값 이름이 "roboflow" 입니다.
주석 JSON 의 세 목록
_annotations.coco.json 은 큰 사전 하나이고, 그 안의 목록 세 개가 핵심입니다.
| 목록 | 원소 하나 | 필드 |
|---|---|---|
images | 그림 한 장 | id(그림 번호), file_name, width, height(픽셀) |
categories | 클래스 하나 | id(범주 번호), name, supercategory(상위 분류, 없어도 됨) |
annotations | 객체 하나 | id, image_id(어느 그림), category_id(어느 클래스), bbox, area, iscrowd |
그림과 객체가 따로 적혀 있고 image_id 로 이어진다는 점이 처음에는 낯섭니다. 객체가 없는 그림은 images 에만 있고 annotations 에는 한 줄도 없습니다.
iscrowd 는 “사람 무리” 처럼 낱개로 셀 수 없는 영역을 표시하는 값입니다. 보통은 0 이고, 문서에 따르면 1 인 주석은 학습 정답으로 쓰이지 않습니다.
박스 좌표 바꾸기
COCO 의 bbox 는 네 숫자 [x, y, w, h] 입니다. 2장의 두 가지 표현(모서리 표현 · 중심 표현) 가운데 어느 것과도 다릅니다.
- 앞의 두 숫자
(x, y)는 박스의 왼쪽 위 모서리(중심이 아님), 뒤의 두 숫자는 너비 · 높이 - 단위는 픽셀(0 – 1 로 정규화하지 않음). 원점은 그림의 왼쪽 위이고 세로 좌표는 아래로 갈수록 커집니다
우리 형식의 너비 · 높이와 COCO 의 너비 · 높이가 둘 다 흔히 $w$, $h$ 로 쓰여 헷갈립니다. 이 절에서는 정규화한 우리 형식 을 $(c_x, c_y, w, h)$, COCO 의 픽셀 값 을 $[x^{\text{px}}, y^{\text{px}}, w^{\text{px}}, h^{\text{px}}]$ 로 구별해 씁니다. 그림의 너비 · 높이(픽셀)는 대문자 $W$, $H$ 입니다.
거꾸로는 각 식을 뒤집으면 됩니다. 모서리에 너비의 절반을 더해 중심으로 옮기고, 그림 크기로 나눕니다.
$$ c_x = \frac{x^{\text{px}} + w^{\text{px}}/2}{W}, \qquad c_y = \frac{y^{\text{px}} + h^{\text{px}}/2}{H}, \qquad w = \frac{w^{\text{px}}}{W}, \qquad h = \frac{h^{\text{px}}}{H} $$손으로 해 봅니다. 정규화 박스 $(c_x, c_y, w, h) = (0.5,\ 0.375,\ 0.25,\ 0.5)$ 를 192 × 192 그림의 COCO 박스로 바꾸면
- $x^{\text{px}} = (0.5 - 0.125) \times 192 = 0.375 \times 192 = 72$
- $y^{\text{px}} = (0.375 - 0.25) \times 192 = 0.125 \times 192 = 24$
- $w^{\text{px}} = 0.25 \times 192 = 48$, $\ h^{\text{px}} = 0.5 \times 192 = 96$ →
[72, 24, 48, 96], 넓이 $48 \times 96 = 4608$ - 되돌리기: $c_x = (72 + 24)/192 = 0.5$, $c_y = (24 + 48)/192 = 0.375$ ✓
같은 박스가 96 × 96 그림에서는 [36, 12, 24, 48] 입니다. 정규화 좌표는 그림 크기가 바뀌어도 그대로지만 COCO 좌표는 그림 크기에 따라 달라집니다.
그래서 그림을 리사이즈해 저장할 때는 주석도 같이 고쳐야 합니다.
bbox 의 앞 두 숫자 $(x^{\text{px}}, y^{\text{px}})$, 곧 왼쪽 위 모서리입니다. 축의 눈금은 픽셀이고 세로축이 아래로 자랍니다.
그림 14-3 에서 읽을 것은 두 가지입니다. 첫째, 분홍 점은 늘 박스의 왼쪽 위 에 있습니다(중심이 아닙니다). 둘째, 오른쪽에 적힌 bbox 의 뒤 두 숫자는 오른쪽 아래 모서리의 좌표가 아니라 너비와 높이 입니다.
원 B 는 너비와 높이가 같고(69.23), 삼각형 A 는 높이(69.94)가 너비(56.83)보다 큽니다. 2장의 모서리 표현 $(x_0, y_0, x_1, y_1)$ 과 가장 자주 헷갈리는 부분이니 눈에 익혀 두세요.
도형 세상 내보내기
이제 ShapesDataset 을 COCO 형식 폴더로 저장합니다. 장면은 앞 장들과 같은 시드(학습 0, 검증 1, 시험 2)로 만들되, 그림은 96 대신 192 픽셀 로 그립니다.
0장 에서 본 것처럼 장면은 정규화 좌표로 적혀 있어 어떤 해상도로도 그릴 수 있습니다. 학습 1,000장 · 검증 200장 · 시험 200장입니다.
저장한 폴더를 다시 읽어 우리 형식의 정답으로 되돌리는 함수도 만듭니다. 뒤에서 시험 세트를 3장의 evaluate_ap 로 채점할 때 씁니다.
그리고 “저장 → 다시 읽기” 를 거친 박스가 원래와 같은지 확인합니다.
$ python ch14_make_coco.py
[1] 손계산 예: 정규화 (cx, cy, w, h) = (0.5, 0.375, 0.25, 0.5)
96×96 그림 → COCO bbox [x, y, w, h] = [36.0, 12.0, 24.0, 48.0] (넓이 1152) → 되돌리면 (0.5, 0.375, 0.25, 0.5)
192×192 그림 → COCO bbox [x, y, w, h] = [72.0, 24.0, 48.0, 96.0] (넓이 4608) → 되돌리면 (0.5, 0.375, 0.25, 0.5)
[2] 도형 세상을 COCO 형식으로 내보내기 → ch14_shapes_coco/ (그림 192×192)
train: 그림 1000장, 객체 2442개 (circle 807, rectangle 863, triangle 772) | 되읽기 check: 박스 최대 차이 3.8e-05
valid: 그림 200장, 객체 501개 (circle 169, rectangle 183, triangle 149) | 되읽기 check: 박스 최대 차이 3.8e-05
test : 그림 200장, 객체 483개 (circle 161, rectangle 163, triangle 159) | 되읽기 check: 박스 최대 차이 3.8e-05
걸린 시간 15.1초
[3] 주석 파일 들여다보기 (train/_annotations.coco.json)
images[0] = {"id": 0, "file_name": "000000.png", "width": 192, "height": 192}
categories = [{"id": 1, "name": "circle", "supercategory": "shape"}, {"id": 2, "name": "rectangle", "supercategory": "shape"}, {"id": 3, "name": "triangle", "supercategory": "shape"}]
annotations[0] = {"id": 1, "image_id": 0, "category_id": 2, "bbox": [6.2, 130.09, 41.38, 29.08], "area": 1203.33, "iscrowd": 0}
2장 형식의 같은 박스 (cx, cy, w, h) = [0.1401, 0.7533, 0.2155, 0.1515]
그림 저장: figures/ch14-coco-bbox.png- 되읽기 check. 박스 좌표의 최대 차이가 $3.8 \times 10^{-5}$(정규화 단위)입니다. 주석을 소수 둘째 자리 픽셀로 반올림해 저장했기 때문에 생기는 차이입니다. 반올림 오차는 숫자마다 최대 0.005 픽셀이므로 중심 $x^{\text{px}} + w^{\text{px}}/2$ 의 오차는 최대 $0.005 + 0.0025 = 0.0075$ 픽셀, 192 로 나누면 $3.9 \times 10^{-5}$ 로 관측값과 맞습니다. 무시해도 되는 크기입니다.
-
주석 한 줄 읽기.
annotations[0]은 0번 그림의 사각형(category_id2)이고bbox는[6.2, 130.09, 41.38, 29.08]입니다. 되돌리면 $c_x = (6.2 + 41.38/2)/192 = 26.89/192 = 0.1401$, $c_y = (130.09 + 29.08/2)/192 = 144.63/192 = 0.7533$, $w = 41.38/192 = 0.2155$, $h = 29.08/192 = 0.1515$. 마지막 줄의 2장 형식 값과 같습니다. - 세 클래스가 고르게 들어 있습니다(학습 세트에 원 807, 사각형 863, 삼각형 772).
클래스 번호는 다시 매겨진다
우리 클래스는 0, 1, 2 인데 category_id 는 일부러 COCO 의 관례대로 1, 2, 3 으로 적었습니다. 그래도 됩니다.
패키지는 (기본값 dataset_file="roboflow" 일 때) 학습 세트의 categories 를 id 순으로 늘어놓고 0 부터 다시 번호를 매깁니다.
JSON 의 category_id | 이름 | 모델의 class_id(학습 · 예측) |
|---|---|---|
| 1 | circle | 0 |
| 2 | rectangle | 1 |
| 3 | triangle | 2 |
미세 조정을 마친 모델에서 model.class_names 는 ['circle', 'rectangle', 'triangle'] 이었고, predict 의 class_id 는 0, 1, 2 로 나왔습니다(뒤의 실행 출력).
범주 id 가 0 부터든 1 부터든, 중간에 빈 번호가 있든 결과는 같습니다. 예측의 class_id 는 JSON 의 category_id 가 아니라 “id 순서로 몇 번째 범주인가” 입니다.
우리 load_coco_split 도 같은 방식으로 번호를 매겨 두었으므로 모델의 예측과 그대로 비교할 수 있습니다.
그리고 클래스 수를 따로 알려 줄 필요가 없습니다. train() 이 categories 를 세어 분류 머리를 알맞은 크기로 다시 만듭니다. 이때 나오는 경고와 그 뜻은 다음 절에서 봅니다.
해상도와 나누어떨어짐 제약
우리 그림은 192 픽셀인데 Nano 의 입력은 384 입니다. 문제없습니다. 학습 때도 추론 때도 패키지가 그림을 모델 해상도로 리사이즈합니다(주석의 박스도 함께). 데이터셋의 그림 크기는 제각각이어도 됩니다.
모델 해상도를 바꾸고 싶다면 제약이 하나 있습니다. 한 변의 길이가 patch_size × num_windows 로 나누어떨어져야 합니다.
Nano 는 $P = 16$, $M = 2$ 이므로 $S$ 는 32 의 배수 여야 합니다. 기본 384 는 $32 \times 12$ 로, 패치 $24 \times 24$ 개가 $12 \times 12$ 짜리 윈도 4개로 나뉩니다. 320, 352, 416, 448 은 되고 400 은 안 됩니다($400/32 = 12.5$). 실제로 넣어 보면 이렇게 거절됩니다.
shape=(400, 400) 은 거절된다: shape must have both dimensions divisible by 32 (patch_size=16 * num_windows=2), got (400, 400).
이 제약은 학습(train(resolution=…)), 추론(predict(shape=…)), 내보내기(export(shape=…)) 모두에 똑같이 적용됩니다.
분할 모델은 패치가 12 라서 배수가 다릅니다(대부분 24, SegNano 는 12).
11장 의 다중 스케일 학습이 기본으로 켜져 있습니다(multi_scale="per-batch", expanded_scales=True).
설치판의 함수로 Nano(384)의 후보 크기를 계산해 보면 224, 256, 288, …, 544 의 11가지, 곧 384 를 가운데 두고 32 씩 다섯 칸 아래위입니다(384 의 0.58 – 1.42 배; 논문의 “0.5 – 1.5 배” 에 해당).
배치마다 이 가운데 하나를 무작위로 골라 그 크기로 학습합니다. 검증과 추론은 늘 384 입니다.
미세 조정
train 한 번 부르기
미세 조정은 메서드 하나입니다. 모델을 만들고(사전 학습 가중치가 읽힙니다) train() 에 데이터셋 폴더와 출력 폴더를 알려 줍니다.
11장에서 손으로 짠 학습 고리, 곧 다중 스케일, Group DETR, 헝가리안 매칭, IA-BCE · L1 · GIoU 손실, 보조 손실, 기울기 누적, 기울기 자르기, AdamW, EMA, 에폭마다의 검증이 모두 이 한 줄 안에서 돕니다.
(안쪽은 PyTorch Lightning 으로 짜여 있습니다.)
설치판의 TrainConfig 기본값은 wandb=False, mlflow=False, clearml=False 이고 tensorboard=True 뿐입니다.
TensorBoard 는 출력 폴더에 파일을 쓸 뿐 어디로도 보내지 않습니다. 곧 따로 켜지 않는 한 학습 기록이 외부 서비스로 올라가지 않습니다.
이 실습은 tensorboard=False 로 그것마저 끄고, 늘 기록되는 metrics.csv 만 읽습니다.
(네트워크를 쓰는 것은 처음에 사전 학습 가중치를 내려받을 때뿐입니다.)
주요 인자와 기본값
train() 의 키워드 인자는 그대로 TrainConfig 의 필드가 됩니다. 아래 기본값은 설치판(1.12.1)의 rfdetr/config.py 에서 읽은 것입니다.
이름을 틀리게 쓰면(예: epoch=10) 조용히 무시되지 않고 오류가 납니다.
| 인자 | 기본값 | 뜻 | 앞 장 |
|---|---|---|---|
dataset_dir | (필수) | COCO · YOLO 형식 데이터셋 폴더 | 이 장 |
output_dir | "output" | 체크포인트 · 기록을 쓸 폴더 | |
epochs | 100 | 학습 세트를 몇 바퀴 돌 것인가 | 4장 |
batch_size | 4 | 한 번에 GPU 에 올리는 그림 수. "auto" 를 주면 GPU 메모리를 재어 스스로 정함(CUDA 에서만) | |
grad_accum_steps | 1 | 기울기를 몇 번 모아 한 번 갱신할 것인가 | 11장 |
lr | 1e-4 | 학습률(프로젝터 · 머리 등). 디코더는 여기에 lr_component_decay 를 곱함 | 11장 |
lr_encoder | 1.5e-4 | 백본(DINOv2)의 기준 학습률. 여기에 층별 감쇠가 곱해짐 | 11장 |
lr_vit_layer_decay | 0.8 | 층별 학습률 감쇠율 | 11장 |
lr_component_decay | 0.7 | 부품(디코더 · 백본)별 학습률 감쇠율 | 이 장 |
weight_decay | 1e-4 | 가중치 감쇠(AdamW) | 4장 |
warmup_epochs | 0.0 | 학습률 워밍업 길이. 0 = 워밍업 없음 | 11장 |
clip_max_norm | 0.1 | 기울기 자르기의 최대 노름 | 11장 |
use_ema, ema_decay, ema_tau | True, 0.993, 100 | 가중치의 지수 이동 평균(EMA) | 11장 |
multi_scale, expanded_scales | "per-batch", True | 배치마다 해상도를 바꾸는 다중 스케일 학습 | 11장 |
drop_path | 0.0 | 드롭 패스 확률 | 11장 |
early_stopping | False | 검증 AP 가 오르지 않으면 일찍 멈춤(early_stopping_patience=10, early_stopping_min_delta=0.001) | 이 장 |
checkpoint_interval | 10 | 몇 에폭마다 checkpoint_<에폭>.ckpt 를 남길 것인가 | |
resume | None | 이어서 학습할 체크포인트(last.ckpt) 경로 | 이 장 |
resolution | (모델 기본값) | 학습 해상도 바꾸기. patch_size × num_windows 의 배수 | 12장 |
num_workers | 2 | 데이터 로더 일꾼(프로세스) 수 | |
seed | None | 난수 시드 | |
tensorboard / wandb / mlflow | True / False / False | 기록 도구 | |
run_test | False | 학습이 끝나면 시험 세트도 채점할 것인가 |
손실의 가중치(분류 1, L1 5, GIoU 2), 질의 묶음 수(group_detr=13), IA-BCE 사용 여부(ia_bce_loss=True) 같은 것은 학습 인자가 아니라 모델 설정 쪽에 있고, 보통은 건드리지 않습니다.
기본값들을 한 줄로 요약하면 “학습률 1e-4, 워밍업 없음, 기울기 0.1 로 자르기, 층별 감쇠 0.8, EMA 0.993” 으로, 11장 에서 본 논문 부록 A 의 설정과 같습니다.
학습률 스케줄도 논문의 “스케줄러 없는 학습” 그대로입니다. 설치판의 기본 스케줄(lr_scheduler="step")은 100 에폭 뒤에야 학습률을 1/10 로 내리는데, 기본 에폭 수가 100 이므로 학습 내내 학습률이 일정합니다(이번 실험의 metrics.csv 에서도 일정했습니다).
실효 배치 크기
GPU 메모리가 작으면 한 번에 올릴 수 있는 그림 수가 적습니다. 그런데 배치가 너무 작으면 기울기가 그림 몇 장의 사정에 휘둘려 들쭉날쭉해집니다. 11장 의 기울기 누적이 이 둘을 떼어 놓습니다. 작은 배치로 순전파 · 역전파를 여러 번 하면서 기울기를 더해 두었다가, 한 번에 가중치를 고칩니다. 가중치를 한 번 고칠 때 본 그림의 수를 실효 배치 크기effective batch size 라고 합니다.
$$ B_{\text{eff}} = B \times A $$
$B$ 는 batch_size(한 번에 GPU 에 올리는 그림 수), $A$ 는 grad_accum_steps(기울기를 모으는 횟수), $B_{\text{eff}}$ 가 실효 배치 크기입니다.
학습 그림이 $N_{\text{train}}$ 장이면 한 에폭의 순전파 횟수와 가중치 갱신 횟수는
이번 실험에 넣어 봅니다. $N_{\text{train}} = 1000$, $B = 2$, $A = 4$ 이므로
- 실효 배치 크기 $B_{\text{eff}} = 2 \times 4 = 8$
- 한 에폭에 순전파 $1000 / 2 = 500$ 번, 가중치 갱신 $1000 / 8 = 125$ 번
- 5 에폭이면 갱신은 모두 $5 \times 125 = 625$ 번. 실제
metrics.csv의 마지막 줄의step이 624 입니다(0 부터 세므로 625 번째).
메모리는 $B$ 만 따라갑니다. batch_size=2 일 때 이번 학습이 쓴 GPU 메모리는 최대 1.61 GiB 였습니다.
같은 실효 배치 8 을 batch_size=8, grad_accum_steps=1 로 만들면 갱신 한 번의 내용은 (거의) 같지만 메모리는 몇 배가 듭니다.
- 문서의 권고는 “먼저
batch_size를 GPU 에 들어가는 만큼 키우고, 그래도 모자랄 때만grad_accum_steps를 올리라” 입니다. 누적은 메모리를 아껴 줄 뿐 시간을 아껴 주지는 않습니다. batch_size="auto"(CUDA 전용)는 GPU 를 시험해 들어가는 배치를 찾고, 실효 배치가 16(auto_batch_target_effective의 기본값)에 닿도록 누적 횟수를 정합니다. 이 장에서는 GPU 를 다른 작업과 나눠 쓰느라 쓰지 않았습니다.- RF-DETR 이 누적에 잘 견디는 것은 10장 에서 본 선택 덕분입니다. 프로젝터의 배치 정규화를 층 정규화 로 바꿨기 때문에, 배치가 2장뿐이어도 정규화 통계가 흔들리지 않습니다.
부품마다 다른 학습률
“학습률 1e-4” 라고 했지만 모든 가중치가 그 값으로 배우는 것은 아닙니다. 설치판의 training/param_groups.py 와 models/backbone/backbone.py 를 읽어 보면 부품마다 이렇게 정해집니다.
$\eta$ 는 lr, $\eta_{\text{enc}}$ 는 lr_encoder, $\rho$ 는 lr_component_decay(0.7), $\lambda$ 는 lr_vit_layer_decay(0.8), $L$ 은 백본에서 쓰는 블록 수에 1 을 더한 값(Nano 는 13), $j$ 는 백본 블록 번호(0 – 11)입니다.
| 부품 | 학습률 | Nano 기본값에서 |
|---|---|---|
| 프로젝터, 분류 · 박스 머리, 질의 임베딩 등 | $\eta$ | $1.0 \times 10^{-4}$ |
| 디코더 | $\eta \cdot \rho$ | $10^{-4} \times 0.7 = 7.0 \times 10^{-5}$ |
| 백본의 블록 $j$ | $\eta_{\text{enc}} \cdot \lambda^{\,L - j} \cdot \rho^2$ | 블록 11: $4.70 \times 10^{-5}$ … 블록 0: $4.04 \times 10^{-6}$ |
| 백본의 패치 · 위치 임베딩 | $\eta_{\text{enc}} \cdot \lambda^{\,L + 1} \cdot \rho^2$ | $3.23 \times 10^{-6}$ |
이 손계산은 실제 학습 기록과 맞습니다. metrics.csv 에는 옵티마이저의 매개변수 묶음 가운데 가장 큰 학습률과 가장 작은 학습률이 기록되는데, 이번 실행에서
lr_max 0.0001, lr_min 3.233e-06 이었습니다(뒤의 실행 출력). 위 표의 맨 윗줄과 맨 아랫줄입니다.
왜 이렇게 할까요? 11장 의 층별 학습률 감쇠 그대로입니다. 백본의 아래층은 DINOv2 가 1억 장이 넘는 그림에서 배운 “모서리 · 질감 · 모양” 같은 일반 지식을 담고 있어 조금만 고치는 것이 안전하고, 새로 만든 머리는 우리 데이터에 맞게 크게 고쳐야 합니다. 미세 조정에서 사전 학습의 지식을 지키는 장치입니다.
머리 재초기화 경고
학습을 시작하면 로그에 이런 경고가 한 줄 지나갑니다.
[WARNING] rf-detr - Checkpoint has 90 classes but model is configured for 3. The detection head will be re-initialized to 3 classes.
오류가 아니라 바라던 일이 일어났다는 알림 입니다. 사전 학습 가중치의 분류 머리는 COCO 용 91칸인데 우리 데이터의 클래스는 3개입니다.
패키지는 데이터셋의 categories 를 세어 num_classes 를 3 으로 맞추고, 분류 머리를 클래스 수 + 1 = 4칸 짜리로 새로 만듭니다(reinitialize_detection_head).
미세 조정을 마친 모델의 머리를 찍어 보면 Linear(in_features=256, out_features=4, bias=True) 입니다(뒤의 실행 출력).
-
“다시 초기화” 의 실제 내용. 경고문만 보면 새 머리가 무작위 값으로 채워질 것 같지만, 설치판의 소스(
_resize_linear)는 그렇게 하지 않습니다. 원래 머리의 91개 행 가운데 앞의 4개 행을 잘라 와 새 머리로 씁니다(클래스가 91개보다 많으면 반대로 행을 되풀이해 이어 붙입니다). 직접 확인해 보면RFDETRNano(num_classes=3)의 분류 머리 가중치는 COCO 모델 머리의 0 – 3번 행과 차이가 정확히 0 이었고, 편향은 −4.4 ~ −4.7 로 10장 에서 본 “사전 확률 0.01” 초기화값 $-\log(0.99/0.01) = -4.595$ 근처였습니다. 곧 우리의 “원” 은 COCO 의 쓰이지 않는 0번 칸에서, “사각형” 은 person 칸에서, “삼각형” 은 bicycle 칸에서 출발합니다. 도형과 아무 상관 없는 값이므로 실질적으로는 새로 배워야 하는 머리 라는 점은 같습니다. 머리 아래의 모든 것(백본 · 프로젝터 · 디코더 · 박스 머리)은 사전 학습 가중치 그대로입니다. -
남는 한 칸(마지막 칸)은 쓰이지 않는 자리입니다. 정답이 그 칸을 가리키는 일이 없으므로 학습하면서 점수가 0 에 가까워집니다.
다만
predict(threshold=0.0)처럼 문턱값을 아예 없애면 그 칸의 예측(class_id= 3)도 딸려 나옵니다. 그래서detections_to_prediction에num_classes로 걸러 내는 줄을 두었습니다. -
모델을 만들 때
RFDETRNano(num_classes=5)처럼 클래스 수를 직접 주면, 데이터셋과 달라도 내가 준 값이 유지 되고 경고만 나옵니다(소스의_align_num_classes_from_dataset). 특별한 이유가 없으면 주지 말고 패키지가 세게 두세요.
학습 로그의 손실 이름
에폭이 끝날 때마다 출력 폴더의 metrics.csv 에 학습 손실과 검증 지표가 한 줄씩 쌓입니다. 열 이름을 읽을 줄 알면 지금 모델의 어느 부분이 어떻게 배우고 있는지 보입니다.
기본 설정(compact_train_metrics=True)에서는 보조 손실이 loss_ce_aux 처럼 하나로 합쳐져 기록되므로, 이 실습은 그것을 끄고 층별로 받았습니다.
열 이름(train/ 뒤) | 무엇인가 | 가중치 | 앞 장 |
|---|---|---|---|
loss_ce | 분류 손실. 이름은 ce(cross-entropy)지만 실제로는 IA-BCE(ia_bce_loss=True). 마지막 디코더 층의 출력에 대한 것 | 1 | 9장, 11장 |
loss_bbox | 매칭된 예측 박스와 정답 박스의 L1 거리(정규화 좌표) | 5 | 2장, 7장 |
loss_giou | $1 - \GIoU$ | 2 | 2장, 7장 |
loss_ce_0, loss_bbox_0, loss_giou_0 | 보조 손실: 디코더의 0번째(첫) 층 출력에 같은 손실을 건 것. Nano 는 디코더가 2층이라 _0 하나뿐이고, 3층인 Small 이면 _0, _1 이 생깁니다 | 같음 | 7장, 12장 |
loss_ce_enc, loss_bbox_enc, loss_giou_enc | 2단계 질의 선택에서 인코더(프로젝터) 출력이 낸 제안 에 건 손실. 디코더를 거치기 전의 예측입니다 | 같음 | 8장, 10장 |
loss | 위 9개를 가중치를 곱해 모두 더한 값. 역전파되는 것은 이 숫자 하나 | 11장 | |
class_error, cardinality_error(_0, _enc) | 참고용 지표(손실에 들어가지 않음). 매칭된 질의의 클래스 오답률(%), 그리고 “점수 0.5 를 넘는 질의 수 − 정답 객체 수” 의 절댓값 | – | |
lr, lr_max, lr_min | 학습률(앞 절) | – |
전체 손실은 식으로 쓰면 다음과 같습니다. $\ell$ 은 손실을 거는 자리(마지막 디코더 층, 디코더 0층, 인코더 제안)를 가리키는 첨자입니다.
$$ \mathcal{L} = \sum_{\ell \,\in\, \{\text{마지막},\ 0,\ \text{enc}\}} \Big( 1 \cdot \mathcal{L}^{(\ell)}_{\text{ce}} + 5 \cdot \mathcal{L}^{(\ell)}_{\text{bbox}} + 2 \cdot \mathcal{L}^{(\ell)}_{\text{giou}} \Big) $$$\mathcal{L}^{(\ell)}_{\text{ce}}$, $\mathcal{L}^{(\ell)}_{\text{bbox}}$, $\mathcal{L}^{(\ell)}_{\text{giou}}$ 가 자리 $\ell$ 의 분류 · L1 · GIoU 손실입니다. 기록된 값으로 이 식이 맞는지 확인할 수 있습니다. 첫 에폭의 값을 넣어 보면
- 분류: $0.4325 + 0.7244 + 0.6895 = 1.8464$
- L1: $5 \times (0.0181 + 0.0198 + 0.0558) = 5 \times 0.0937 = 0.4685$
- GIoU: $2 \times (0.0515 + 0.0556 + 0.1499) = 2 \times 0.2570 = 0.5140$
- 합: $1.8464 + 0.4685 + 0.5140 = 2.8289$. 기록된
loss는 2.8288 입니다(넷째 자리의 차이는 반올림). ✓
세 자리의 손실을 나란히 보는 것만으로도 구조가 읽힙니다. 같은 에폭에서 분류 손실은 인코더 제안(0.6895)과 디코더 0층(0.7244)보다 마지막 층(0.4325)이 작고, 박스 손실은 인코더 제안(0.0558)이 디코더 층들(0.0198, 0.0181)의 약 세 배입니다. 인코더의 거친 제안을 디코더가 층을 거치며 다듬는다는 8장 · 10장 의 그림 그대로입니다.
에폭별 결과
이제 실제로 돌린 결과입니다. 사전 학습 가중치에서 시작해 도형 세상 1,000장으로 5 에폭 학습했습니다.
아래는 metrics.csv 를 읽어 에폭마다 한 줄로 정리한 것입니다(패키지가 화면에 찍는 긴 로그는 생략했습니다).
학습을 마친 뒤 그림을 다시 그리려고 한 번 더 실행한 출력이라 “건너뜀” 줄이 보입니다. 처음 실행할 때는 그 자리에서 학습이 돌고 학습 끝: 18.2분, GPU 메모리 최대 1.61 GiB 가 찍힙니다.
$ python ch14_finetune.py
[2] 미세 조정 (a) 사전 학습 가중치에서 시작 → ch14_out_pretrained/
설정: epochs=5, batch_size=2, grad_accum_steps=4, lr=0.0001, num_workers=2, seed=0, tensorboard=False, eval_base_model=True, compact_train_metrics=False, progress_bar=None
ch14_out_pretrained/ 에 학습 결과가 있어 건너뜀 (--retrain 으로 다시 학습).
그때의 기록: 18.2분, GPU 메모리 최대 1.61 GiB (torch 가 할당한 양)
metrics.csv 의 손실 열: loss, loss_bbox, loss_bbox_0, loss_bbox_enc, loss_ce, loss_ce_0, loss_ce_enc, loss_giou, loss_giou_0, loss_giou_enc
에폭 | loss | loss_ce loss_bbox loss_giou | loss_ce_0 loss_ce_enc | val AP(일반) AP(EMA) AP50(EMA)
1 | 2.829 | 0.433 0.0181 0.0515 | 0.724 0.689 | 0.9417 0.9476 0.9998
2 | 2.072 | 0.243 0.0177 0.0524 | 0.464 0.440 | 0.9772 0.9792 1.0000
3 | 1.530 | 0.189 0.0138 0.0419 | 0.349 0.328 | 0.9754 0.9816 0.9999
4 | 1.425 | 0.182 0.0136 0.0409 | 0.278 0.321 | 0.9808 0.9832 0.9999
5 | 1.513 | 0.178 0.0131 0.0394 | 0.348 0.327 | 0.9822 0.9839 0.9999
첫 에폭의 손실 항목: loss 2.8288, loss_bbox 0.0181, loss_bbox_0 0.0198, loss_bbox_enc 0.0558, loss_ce 0.4325, loss_ce_0 0.7244, loss_ce_enc 0.6895, loss_giou 0.0515, loss_giou_0 0.0556, loss_giou_enc 0.1499
cardinality_error (에폭별): 25.09, 28.98, 29.23, 29.03, 29.19 | lr_max 0.0001 lr_min 3.233e-06
check: 1·Σloss_ce + 5·Σloss_bbox + 2·Σloss_giou = 1.513 vs 기록된 loss = 1.513
출력 폴더: checkpoint_best_ema.pth (121 MB), checkpoint_best_regular.pth (242 MB), checkpoint_best_total.pth (121 MB), last.ckpt (483 MB), last_ema.pth (121 MB), metrics.csv, train_info.json, training_config.json- 첫 에폭에 이미 끝나 있습니다. 가중치를 125번 고친 뒤의 검증 AP 가 0.9417(일반 가중치), 0.9476(EMA 가중치)이고 AP50 은 0.9998 입니다. 미세 조정 전에는 도형을 냉장고라 부르던 모델입니다. 5 에폭 뒤에는 0.9822 / 0.9839 입니다.
-
AP50 은 1 에 붙어 있고 AP 는 0.98 근처에서 천천히 오릅니다. 3장 에서 본 것처럼 AP@[.50:.95] 는 IoU 문턱값 0.95 까지 평균한 값입니다.
“대충 맞는 박스”(IoU 0.5)는 첫 에폭부터 거의 전부 맞고, 남은 차이는 “IoU 0.9 를 넘길 만큼 꼭 맞는가” 에서 납니다. 박스 손실(
loss_bbox0.0181 → 0.0131,loss_giou0.0515 → 0.0394)이 조금씩 줄어드는 것이 그 과정입니다. - EMA 가중치가 매번 조금 더 좋습니다(0.9476 대 0.9417, 0.9792 대 0.9772, …, 0.9839 대 0.9822). 차이는 0.002 – 0.006 으로 작지만 다섯 에폭 모두 같은 방향입니다. 11장 에서 본 대로, 여러 스텝의 가중치를 평균하면 한 스텝 한 스텝의 흔들림이 지워집니다. 일반 가중치의 AP 는 3 에폭에서 한 번 내려갔지만(0.9772 → 0.9754) EMA 쪽은 내려간 적이 없습니다.
-
전체 손실은 4 → 5 에폭에서 오히려 올랐습니다(1.425 → 1.513). 보조 손실
loss_ce_0이 0.278 → 0.348 로 튄 탓입니다. 그런데 검증 AP 는 계속 올랐습니다. 학습 손실은 배치마다 해상도가 바뀌는 다중 스케일 · 증강이 걸린 값이고, 에폭 하나의 평균이 조금 오르내리는 것은 흔한 일입니다. 모델을 고르는 기준은 학습 손실이 아니라 검증 AP 입니다. -
cardinality_error 가 29 근처인 까닭. 출력에는 싣지 않았지만
metrics.csv의 이 열은 2 에폭부터 29.0 – 29.2 에 머뭅니다. 고장이 아닙니다. 학습 때는 9장 의 Group DETR 로 질의 묶음 13개가 함께 돌고, 묶음마다 객체 하나에 예측 하나씩을 냅니다. 그림 한 장의 객체가 평균 $2442/1000 = 2.44$ 개이므로 점수 0.5 를 넘는 질의는 약 $13 \times 2.44$ 개, 정답 수와의 차이는 $12 \times 2.44 = 29.3$ 입니다. 관측값과 맞습니다. Group DETR 이 실제로 돌고 있다는 것을 로그 숫자 하나로 확인한 셈입니다.
사전 학습의 힘
이렇게 쉽게 되는 것이 모델 구조 덕분일까요, 사전 학습 덕분일까요? 가려내는 방법은 하나입니다. 똑같은 설정으로, 사전 학습 가중치만 빼고 학습해 보는 것입니다.
RFDETRNano(pretrain_weights=None) 으로 만들면 가중치 파일을 읽지 않습니다.
이때 패키지는 “Using patch size 16 instead of 14, which means we're not loading DINOv2 backbone weights and the backbone starts from random initialization” 이라고 알려 줍니다.
Nano 는 패치가 16 이라 DINOv2 원본(패치 14)을 그대로 읽을 수도 없어서, 백본부터 머리까지 전부 무작위 초기화 로 시작합니다.
GPU 시간을 아끼려고 이 실행은 3 에폭만 돌렸습니다. 에폭 수 말고는 설정이 모두 같고 학습률도 내내 일정하므로, 같은 에폭끼리 견주면 공정한 비교입니다.
[3] 미세 조정 (b) 무작위 초기화에서 시작 (epochs=3, 나머지 설정은 같음) → ch14_out_scratch/
ch14_out_scratch/ 에 학습 결과가 있어 건너뜀 (--retrain 으로 다시 학습).
그때의 기록: 8.5분, GPU 메모리 최대 1.61 GiB (torch 가 할당한 양)
metrics.csv 의 손실 열: loss, loss_bbox, loss_bbox_0, loss_bbox_enc, loss_ce, loss_ce_0, loss_ce_enc, loss_giou, loss_giou_0, loss_giou_enc
에폭 | loss | loss_ce loss_bbox loss_giou | loss_ce_0 loss_ce_enc | val AP(일반) AP(EMA) AP50(EMA)
1 | 9.972 | 0.776 0.2797 0.5711 | 0.760 0.733 | 0.3384 0.3244 0.5972
2 | 6.901 | 0.848 0.1534 0.3076 | 0.875 1.018 | 0.6059 0.6342 0.8311
3 | 5.782 | 0.758 0.1173 0.2154 | 0.804 0.988 | 0.7532 0.7749 0.8902
첫 에폭의 손실 항목: loss 9.9724, loss_bbox 0.2797, loss_bbox_0 0.2865, loss_bbox_enc 0.2747, loss_ce 0.7758, loss_ce_0 0.7599, loss_ce_enc 0.7331, loss_giou 0.5711, loss_giou_0 0.5793, loss_giou_enc 0.5989
cardinality_error (에폭별): 2.52, 9.58, 18.62 | lr_max 0.0001 lr_min 3.233e-06
check: 1·Σloss_ce + 5·Σloss_bbox + 2·Σloss_giou = 5.782 vs 기록된 loss = 5.782
두 실행을 같은 에폭끼리 나란히 놓으면 이렇습니다(검증 AP@[.50:.95], EMA 가중치).
| 에폭(갱신 횟수) | (a) 사전 학습에서 시작 | (b) 무작위 초기화에서 시작 | (b) 의 AP50 |
|---|---|---|---|
| 1 (125) | 0.9476 | 0.3244 | 0.5972 |
| 2 (250) | 0.9792 | 0.6342 | 0.8311 |
| 3 (375) | 0.9816 | 0.7749 | 0.8902 |
| 5 (625) | 0.9839 | (돌리지 않음) |
- 사전 학습 모델의 1 에폭이 무작위 초기화의 3 에폭을 크게 앞섭니다(0.948 대 0.775). 그림 14-4 왼쪽에서 파란 선은 처음부터 천장에 붙어 있고 주황 선은 바닥에서 올라오는 중입니다.
-
차이는 박스에서 가장 큽니다. 첫 에폭의
loss_bbox가 (a) 0.0181, (b) 0.2797 로 15배,loss_giou가 0.0515 대 0.5711 로 11배입니다. (a) 는 “물체에 박스를 두르는 법” 을 이미 알고 시작해 이름표만 새로 배우면 되고, (b) 는 모서리가 무엇인지부터 배워야 합니다. (b) 의 AP50(0.89)과 AP(0.77)의 틈이 (a) 보다 훨씬 큰 것도 같은 이야기입니다 — 찾기는 하지만 꼭 맞게 두르지는 못합니다. - 그래도 (b) 가 꽤 올라온다는 점도 정직하게 봐야 합니다. 3 에폭, 가중치 갱신 375번 만에 0.77 이고 아직 오르는 중입니다. 더 돌리면 틈은 더 좁혀질 것입니다. 도형 세상이 그만큼 쉬운 데이터이기 때문입니다(단색 배경, 뚜렷한 색, 세 클래스). 사진처럼 복잡한 데이터에서는 이야기가 다릅니다. LW-DETR 논문은 Objects365 사전 학습이 COCO 에서 +8.7 mAP 를 준다고 보고했고, RF-DETR 논문이 백본을 DINOv2 로 바꾼 이유도 “작은 데이터셋에서의 정확도” 였습니다(6장, 10장). 이 실험이 보여 주는 것은 그 크기가 아니라 방향입니다: 같은 데이터 · 같은 시간이면 사전 학습에서 시작하는 쪽이 훨씬 멀리 갑니다.
-
EMA 가 늘 이기는 것은 아닙니다. (b) 의 첫 에폭에서는 EMA 가중치(0.3244)가 일반 가중치(0.3384)보다 나쁩니다. 모델이 빠르게 좋아지는 중에는 “지난 가중치들의 평균” 이 지금의 가중치보다 뒤처지기 때문입니다.
2 · 3 에폭에서는 다시 EMA 가 앞섭니다(0.6342 대 0.6059, 0.7749 대 0.7532). 패키지가
checkpoint_best_total.pth를 만들 때 둘 가운데 나은 쪽을 고르는 이유입니다. -
(b) 의 분류 손실
loss_ce는 0.776 → 0.848 → 0.758 로 거의 줄지 않는데 AP 는 오릅니다. 9장 의 IA-BCE 는 분류의 목표값을 예측 박스의 IoU 에 묶어 두므로, 박스가 좋아질수록 목표도 함께 높아집니다. 손실 값 하나만으로 학습이 잘되는지 판단하기 어렵다는 점을 다시 보여 줍니다. - 학습 시간은 (a) 5 에폭에 18.2분, (b) 3 에폭에 8.5분이었고 GPU 메모리는 둘 다 최대 1.61 GiB 였습니다. 이 GPU 는 다른 학습 작업 여럿과 나눠 쓰는 중이었으므로 시간은 참고만 하세요. 혼자 쓰면 더 빠릅니다.
- 위 줄(사전 학습에서 시작). 여섯 장의 모든 도형에 박스가 하나씩, 정답(흰 점선)과 거의 겹쳐 그려졌고 점수는 0.89 – 0.98 입니다. 서로 겹친 도형(넷째 · 다섯째 그림)도 따로따로 잡았습니다. 그림 14-2 에서 같은 그림들에 냉장고 · TV 라고 답하던 모델이 1,000장 · 18분의 미세 조정으로 여기까지 왔습니다.
- 아래 줄(무작위 초기화). 점수가 0.5 를 넘는 예측이 적고(다섯째 그림에는 하나도 없습니다) 넘더라도 0.5 – 0.8 사이로 낮습니다. 첫째 그림의 흰 사각형과 둘째 그림의 삼각형에는 박스가 두 개씩 겹쳐 그려졌습니다. “객체 하나에 예측 하나” 라는, 헝가리안 매칭이 가르치는 규칙(7장)을 아직 다 배우지 못한 모습입니다. 여섯째 그림에서는 원의 박스가 옆의 사각형 쪽으로 넓게 퍼졌습니다.
- 아래 줄의 모델도 시험 AP 는 0.77 입니다(다음 절). AP 는 점수의 순서 만 보기 때문에 점수가 전체적으로 낮아도 높게 나올 수 있습니다. 문턱값 0.5 로 잘라 쓰는 실제 사용에서는 그림처럼 많이 놓칩니다. 지표와 눈으로 본 결과를 함께 봐야 하는 이유입니다.
출력 폴더와 체크포인트
학습이 끝나면 output_dir 에 파일이 여럿 남습니다. 학습 도중이나 끝의 가중치를 저장한 파일을 체크포인트checkpoint 라고 합니다.
위 출력의 출력 폴더 줄에 나온 파일들을 열어 보고 정리한 것이 아래 표입니다.
| 파일 | 크기 | 들어 있는 것 | 쓰임 |
|---|---|---|---|
checkpoint_best_total.pth | 121 MB | 검증 AP 가 가장 좋았던 가중치. 일반과 EMA 가운데 더 나은 쪽(이번에는 EMA) + 모델 설정 · 클래스 이름 | 추론 · 내보내기용. 보통 이것만 있으면 됩니다 |
checkpoint_best_ema.pth | 121 MB | EMA 가중치의 검증 AP 가 가장 좋았던 에폭의 EMA 가중치 | 위 파일의 재료 |
checkpoint_best_regular.pth | 242 MB | 일반 가중치의 검증 AP 가 가장 좋았던 에폭의 일반 가중치(EMA 사본도 함께 들어 있어 큼) | 위 파일의 재료. eval_base_model=True 일 때만 생김 |
last.ckpt | 483 MB | 마지막 에폭의 일반 가중치(121) + EMA 가중치(121) + 옵티마이저 상태(241) | 학습 재개용 |
last_ema.pth | 121 MB | 마지막 에폭의 EMA 가중치 | |
metrics.csv | 에폭별 손실 · 검증 지표 | 학습 곡선 그리기 | |
training_config.json | 이번 학습의 모든 설정과 클래스 이름 | 재현 · 기록 |
-
크기가 말해 주는 것. 가중치 한 벌이 121 MB 입니다(매개변수 약 3,015만 개 × 4바이트).
last.ckpt가 그 네 배인 것은 AdamW 가 매개변수마다 값 두 개(기울기의 이동 평균과 기울기 제곱의 이동 평균, 4장)를 기억하기 때문입니다. 옵티마이저 상태가 가중치의 두 배(241 MB)입니다. -
학습이 끝난 뒤에는
rfdetr.from_checkpoint("…/checkpoint_best_total.pth")로 읽습니다. 체크포인트에 모델 종류가 적혀 있어 알맞은 클래스(RFDETRNano)를 스스로 골라 주고, 클래스 이름도 복원됩니다.train()을 부른 그model객체로도 바로predict할 수 있지만, 다른 프로그램 · 다른 날에 다시 쓰려면 이 방법이 기본입니다. checkpoint_<에폭>.ckpt는checkpoint_interval(기본 10) 에폭마다 남습니다. 5 에폭짜리 이번 실행에는 없습니다.train_info.json은 패키지가 아니라 이 실습 코드가 걸린 시간과 메모리를 적어 둔 파일입니다.
“EMA 가중치” 가 어떻게 만들어지는지도 설치판의 소스에서 확인할 수 있습니다. 가중치를 한 번 갱신할 때마다
$$ \theta_{\text{EMA}} \leftarrow d_t\, \theta_{\text{EMA}} + (1 - d_t)\, \theta, \qquad d_t = d \cdot \big(1 - e^{-t/\tau_{\text{EMA}}}\big) $$
$\theta$ 는 지금의 (일반) 가중치, $\theta_{\text{EMA}}$ 는 EMA 가중치, $t$ 는 지금까지의 갱신 횟수, $d$ 는 ema_decay(0.993), $\tau_{\text{EMA}}$ 는 ema_tau(100), $d_t$ 는 $t$ 번째 갱신의 실효 감쇠율입니다.
11장 의 EMA 에 “처음에는 빨리 따라가게 하는” 보정이 붙은 꼴입니다.
$t = 100$ 이면 $d_t = 0.993 \times (1 - e^{-1}) = 0.993 \times 0.632 = 0.628$, 이번 실험의 마지막인 $t = 625$ 이면 $d_t = 0.993 \times (1 - e^{-6.25}) = 0.993 \times 0.998 = 0.991$ 입니다.
$d_t$ 가 0.993 에 다가가면 EMA 는 대략 최근 $1/(1 - 0.993) \approx 143$ 번의 갱신을 평균한 가중치가 됩니다. 이번 실험의 한 에폭(125번)보다 조금 긴 길이입니다.
조기 종료와 학습 재개
에폭 수를 넉넉히 잡아 두면 어느 순간부터 검증 AP 가 오르지 않습니다. 그때 학습을 멈춰 시간을 아끼는 것이 조기 종료early stopping 입니다.
설치판에서는 train(…, early_stopping=True) 로 켭니다(기본은 꺼져 있습니다). 문서에 따르면 검증 AP(탐지는 val/mAP_50_95)가 early_stopping_patience(기본 10) 에폭 동안 early_stopping_min_delta(기본 0.001) 넘게 오르지 않으면 멈춥니다.
이번 실험처럼 5 에폭짜리 학습에서는 쓸 일이 없어 돌려 보지는 않았습니다. 조기 종료를 쓰든 안 쓰든 checkpoint_best_total.pth 에는 검증 AP 가 가장 좋았던 가중치가 남으므로, “너무 오래 학습해서 나빠진 모델” 을 쓰게 될 걱정은 없습니다.
학습이 중간에 끊겼거나 에폭을 더 돌리고 싶으면 resume 에 last.ckpt 를 줍니다.
model = RFDETRNano()
model.train(dataset_dir="ch14_shapes_coco", output_dir="ch14_out_pretrained",
epochs=8, # 전체 에폭 수 (이미 돈 5 에폭 포함)
resume="ch14_out_pretrained/last.ckpt", # 가중치 · 옵티마이저 상태 · 에폭 번호를 이어받는다
batch_size=2, grad_accum_steps=4)
-
epochs는 “더 돌릴 에폭 수” 가 아니라 전체 에폭 수 입니다. 작은 데이터셋(60장)으로 확인해 보았습니다.epochs=1로 학습한 뒤 같은 출력 폴더에서resume=…/last.ckpt, epochs=2로 다시 부르니 둘째 에폭만 더 돌았고,metrics.csv에는 에폭 0(스텝 14)과 에폭 1(스텝 29)이 이어서 남았습니다. -
이어받을 수 있는 것은 옵티마이저 상태까지 든
last.ckpt(와checkpoint_<에폭>.ckpt)입니다. 문서에 따르면 가벼운.pth파일들은 옵티마이저 상태가 없어, 그것으로 재개하면 가중치만 이어받습니다. -
resume없이 학습을 마친model로train()을 또 부르면 이어서 학습하는 것이 아닙니다. 소스에 따르면 처음의 사전 학습 가중치에서 다시 시작하고, 그렇다는 경고를 냅니다.
평가
패키지의 evaluate
검증 세트의 AP 는 가장 좋은 체크포인트를 고르는 데 이미 썼으므로, 최종 성적은 한 번도 보지 않은 시험 세트 로 매깁니다(3장).
패키지에서는 model.evaluate(dataset_dir=…, split="test") 한 줄이고, 지표의 사전을 돌려줍니다.
| 돌려주는 키 | 뜻 | 3장의 이름 |
|---|---|---|
test/mAP_50_95 | IoU 문턱값 0.50, 0.55, …, 0.95 의 AP 를 평균하고 클래스에 대해 평균한 값. COCO 의 대표 지표 | AP(= AP@[.50:.95], mAP) |
test/mAP_50 | IoU 문턱값 0.5 하나만 쓴 AP | AP50 |
test/mAP_75 | IoU 문턱값 0.75 하나만 쓴 AP | AP75 |
test/mAR | 그림당 예측을 500개(eval_max_dets)까지 썼을 때의 평균 재현율 | 재현율의 평균 |
test/F1, test/precision, test/recall | 점수 문턱값을 여러 값으로 훑어(sweep) F1 이 가장 좋은 지점에서의 F1 · 정밀도 · 재현율 | 정밀도 · 재현율 |
test/loss | 시험 세트에서의 손실 |
이름은 mAP 지만 정의는 3장에서 손으로 계산한 것과 같습니다. 클래스마다 예측을 점수순으로 늘어놓아 정밀도 – 재현율 곡선을 그리고, 재현율 101개 지점에서 보간한 정밀도를 평균하고, 그것을 IoU 문턱값 10개와 클래스에 대해 평균합니다. 계산은 COCO 공식 채점기(pycocotools)와 같은 결과를 내는 채점 라이브러리가 맡습니다.
3장의 채점기와 맞대어 보기
패키지가 내놓는 숫자를 그냥 믿지 않고, 같은 모델의 예측을 우리 evaluate_ap 로 직접 채점해 견주어 봅니다.
predict(threshold=0.0) 으로 그림마다 예측을 모두 받아 2장 형식으로 바꾸고(detections_to_prediction), load_coco_split 으로 읽은 정답과 함께 넣습니다.
[4] 시험 세트 채점: 패키지의 evaluate() 와 3장의 evaluate_ap
from_checkpoint → RFDETRNano, class_names=['circle', 'rectangle', 'triangle'], 분류 머리 Linear(in_features=256, out_features=4, bias=True)
(pretrained) 패키지 evaluate(): mAP50:95 0.9828, mAP50 1.0000, mAP75 0.9900, mAR 0.9864
(pretrained) 우리 evaluate_ap : AP 0.9830, AP50 1.0000, AP75 0.9900 | max_dets=500 이면 AP 0.9830 | 클래스별 AP circle 0.989, rectangle 0.996, triangle 0.965
예측 예 (시험 그림 0, 점수 상위 4개 / 돌려받은 277개):
rectangle 점수 0.980 (cx, cy, w, h) = [0.225, 0.326, 0.34, 0.193]
rectangle 점수 0.977 (cx, cy, w, h) = [0.618, 0.44, 0.315, 0.408]
circle 점수 0.975 (cx, cy, w, h) = [0.732, 0.194, 0.225, 0.215]
rectangle 점수 0.962 (cx, cy, w, h) = [0.456, 0.633, 0.296, 0.183]
정답: ['circle', 'rectangle', 'rectangle', 'rectangle'] [[0.731, 0.2, 0.224, 0.224], [0.226, 0.327, 0.344, 0.193], [0.455, 0.632, 0.297, 0.182], [0.618, 0.44, 0.317, 0.411]]
(scratch) 패키지 evaluate(): mAP50:95 0.7722, mAP50 0.8827, mAP75 0.8582, mAR 0.9132
(scratch) 우리 evaluate_ap : AP 0.7738, AP50 0.8834, AP75 0.8569 | max_dets=500 이면 AP 0.7738 | 클래스별 AP circle 0.814, rectangle 0.752, triangle 0.754| 모델 | 채점기 | AP50:95 | AP50 | AP75 |
|---|---|---|---|---|
| (a) 사전 학습에서 시작 | 패키지 evaluate() | 0.9828 | 1.0000 | 0.9900 |
우리 evaluate_ap | 0.9830 | 1.0000 | 0.9900 | |
| (b) 무작위 초기화 | 패키지 evaluate() | 0.7722 | 0.8827 | 0.8582 |
우리 evaluate_ap | 0.7738 | 0.8834 | 0.8569 |
- 두 채점기가 맞습니다. (a) 는 0.0002, (b) 는 0.0016 차이입니다. 3장에서 손으로 만든 채점기가 실제 패키지의 채점과 같은 것을 재고 있다는 뜻입니다. 시험 세트의 AP(0.983)는 검증 세트의 AP(0.984)와도 거의 같아, 검증 세트에 맞춰 고른 체크포인트가 처음 보는 그림에서도 그대로 통했습니다.
-
완전히 같지 않은 까닭. 채점 규칙이 아니라 채점한 예측이 조금 다르기 때문으로 보입니다.
evaluate()는 학습 때와 같은 경로로 순전파하는데, 로그의Using bfloat16 Automatic Mixed Precision (AMP)가 말하듯 16비트 혼합 정밀도로 계산합니다. 우리 쪽 예측은predict()가 FP32 로 계산한 것입니다. 박스 좌표가 소수 몇째 자리에서 달라지면 IoU 가 문턱값(특히 0.90, 0.95)을 아슬아슬하게 넘거나 못 넘는 예측이 몇 개 생기고, AP 의 끝자리가 움직입니다. 박스가 덜 정확한 (b) 에서 차이가 더 큰 것도 그렇게 설명됩니다. (이 설명은 따로 실험해 확인하지는 않았습니다.) -
그림당 예측 수 제한은 영향이 없었습니다. 패키지는 그림당 500개까지(
eval_max_dets), 3장의 기본값은 100개까지 채점에 넣는데, 우리 채점기를 500 으로 바꿔도 AP 가 같았습니다(0.9830). 객체가 그림당 많아야 4개라 상위 100개 밖에는 쓸모 있는 예측이 없기 때문입니다. - 클래스별로 보면 (a) 는 사각형 0.996, 원 0.989, 삼각형 0.965 입니다. AP50 이 1.0 이니 놓치거나 잘못 부른 것은 거의 없고, 차이는 높은 IoU 문턱값에서 박스가 얼마나 꼭 맞는가에서 납니다. 삼각형의 박스가 조금 덜 꼭 맞는 셈입니다.
-
예측을 직접 보면 시험 그림 0번에서 점수 상위 네 개가 정답 네 개와 하나씩 대응합니다. 예를 들어 예측
(0.225, 0.326, 0.34, 0.193)과 정답(0.226, 0.327, 0.344, 0.193)은 좌표가 0.004 안쪽으로 같습니다. 돌려받은 예측은 277개인데,num_select300개 가운데 쓰이지 않는 넷째 칸의 예측 23개를 걸러 낸 수입니다.
추론 설정 바꿔 보기
학습이 끝난 모델도 쓰는 방법 에 따라 결과가 달라집니다. 가중치는 그대로 두고 추론 설정 세 가지를 바꿔 봅니다. 모두 미세 조정한 모델 (a) 와 시험 세트 200장으로 잰 것입니다.
[5] 추론 설정 바꿔 보기 (미세 조정한 모델 (a), 시험 세트 200장)
문턱값 | 남는 예측 수 | 정밀도 | 재현율 (IoU 0.5 기준, 정답 483개)
0.05 | 517 | 0.9342 | 1.0000
0.10 | 489 | 0.9877 | 1.0000
0.20 | 484 | 0.9979 | 1.0000
0.30 | 483 | 1.0000 | 1.0000
0.40 | 483 | 1.0000 | 1.0000
0.50 | 483 | 1.0000 | 1.0000
0.60 | 481 | 1.0000 | 0.9959
0.70 | 481 | 1.0000 | 0.9959
0.80 | 480 | 1.0000 | 0.9938
0.90 | 476 | 1.0000 | 0.9855
0.95 | 463 | 1.0000 | 0.9586
num_select | 그림당 돌려받은 예측 수(평균) | AP | AP50
300 | 250.7 | 0.9830 | 1.0000
100 | 87.0 | 0.9830 | 1.0000
20 | 18.0 | 0.9830 | 1.0000
5 | 4.6 | 0.9819 | 1.0000
2 | 2.0 | 0.7116 | 0.7129
predict(shape=(S, S)) | AP | AP50 | AP75 | 그림당 시간(ms, 파일 읽기 포함 · 참고용)
128 | 0.8921 | 0.9973 | 0.9652 | 11.5
192 | 0.9566 | 0.9997 | 0.9864 | 12.1
256 | 0.9810 | 1.0000 | 0.9900 | 15.8
320 | 0.9835 | 1.0000 | 0.9899 | 15.1
384 | 0.9830 | 1.0000 | 0.9900 | 24.9
448 | 0.9825 | 1.0000 | 0.9869 | 40.9
512 | 0.9826 | 1.0000 | 0.9899 | 46.7
640 | 0.9833 | 1.0000 | 0.9867 | 42.3
shape=(400, 400) 은 거절된다: shape must have both dimensions divisible by 32 (patch_size=16 * num_windows=2), got (400, 400).
predict(shape=(S, S)) 로 추론 해상도만 바꿨을 때의 시험 AP. 회색 세로선이 학습 해상도 384.
점수 문턱값
predict(threshold=…) 는 점수가 그 값보다 큰 예측만 남깁니다. 문턱값을 올리면 틀린 예측이 줄고(정밀도 ↑) 놓치는 객체가 늘어납니다(재현율 ↓). 3장 의 그 맞바꿈입니다.
- 0.3 – 0.5 에서는 완벽합니다. 남는 예측이 정확히 483개로 정답 객체 수와 같고, 정밀도와 재현율이 모두 1.0000 입니다(IoU 0.5 기준). 기본값 0.5 가 이 데이터에서는 잘 맞습니다.
- 낮추면 거짓 양성이 섞입니다. 0.05 에서는 예측이 517개로 늘고 그 가운데 34개가 틀려 정밀도가 $483/517 = 0.934$ 입니다. 재현율은 이미 1 이라 더 얻을 것이 없습니다.
- 올리면 놓칩니다. 0.9 에서 476개(재현율 0.986), 0.95 에서 463개(재현율 0.959). 모델이 맞게 찾고도 점수를 0.95 까지는 주지 않은 객체가 20개 있다는 뜻입니다.
- 점수가 양 끝으로 갈려 있다는 것도 읽을 수 있습니다. 그림 200장에서 나온 수만 개의 예측 가운데 0.05 를 넘는 것이 517개뿐이고, 0.2 와 0.8 사이에서는 수가 거의 변하지 않습니다(484 → 480). 그림 14-6 왼쪽의 두 선이 넓은 구간에서 1 에 붙어 있는 까닭입니다.
실제 데이터에서는 이렇게 넓고 평평한 구간이 나오지 않습니다. 검증 세트에서 이런 표를 만들어 “거짓 경보가 더 나쁜가, 놓치는 것이 더 나쁜가” 에 따라 문턱값을 정하세요.
문턱값은 AP 에는 영향을 주지 않습니다(AP 는 모든 문턱값을 훑어 계산한 값입니다). 설명문에 따르면 threshold 에 ClassThresholds 를 주어 클래스마다 다른 문턱값을 쓸 수도 있습니다(돌려 보지는 않았습니다).
남기는 예측 수 num_select
후처리가 남기는 (질의, 클래스) 쌍의 수입니다. 만든 뒤에도 model.model.postprocess.num_select = K 로 바꿀 수 있습니다.
- 300 → 20 으로 줄여도 AP 가 그대로입니다(0.9830). 그림마다 객체가 많아야 4개이고, 그 예측들이 점수 순위의 맨 앞에 있기 때문입니다. 5 로 줄여도 0.9819 입니다.
-
2 로 줄이면 무너집니다(AP 0.7116). 객체가 3 – 4개인 그림에서 두 개밖에 답하지 못하니 당연합니다.
num_select는 “그림 한 장에 나올 수 있는 객체 수의 상한” 보다 넉넉히 커야 합니다. -
300개를 달라고 했는데 평균 250.7개가 돌아온 것 은 우리
detections_to_prediction이 쓰이지 않는 넷째 칸의 예측을 걸러 냈기 때문입니다. 상위 300 쌍 가운데 평균 49개쯤이 그 칸이었습니다.
num_select 를 줄여도 신경망의 계산량은 줄지 않습니다(질의 300개는 그대로 디코더를 지납니다). 줄어드는 것은 후처리와 결과의 크기뿐입니다.
계산량까지 줄이는 것은 12장 의 “질의 수” 손잡이인데, 그것은 모델 구조를 바꾸는 일이라 이 장에서는 다루지 않았습니다.
추론 해상도
predict(shape=(H, W)) 는 이번 호출에서만 입력 해상도를 바꿉니다. 가중치도 모델 설정도 그대로입니다.
- 256 부터 640 까지 AP 가 거의 같습니다(0.981 – 0.9835, 차이 0.003 안쪽). 모델은 “384 로 학습” 했지만 실제로는 다중 스케일 학습으로 224 – 544 의 여러 크기를 보았고, 위치 임베딩은 크기에 맞춰 보간됩니다. 학습 때 본 적 없는 640 에서도 0.9833 입니다. 12장 에서 해상도를 “학습 뒤에 돌릴 수 있는 손잡이” 로 다룬 것이 실제 모델에서도 통합니다.
- 너무 낮추면 떨어집니다. 192 에서 0.957, 128 에서 0.892. 그런데 128 에서도 AP50 은 0.997 입니다. 객체를 놓치는 것이 아니라 박스가 덜 정밀해지는 것입니다(AP75 0.965). 128 에서는 패치가 $8 \times 8 = 64$ 개뿐이라, 384 의 576개에 견주어 한 변의 눈금이 세 배 거칩니다.
- 올린다고 좋아지지도 않습니다. 원본 그림이 192 픽셀이라 384 넘게 키워 봐야 새 정보가 없습니다. 작은 객체가 많은 큰 사진이라면 결과가 다를 것입니다.
- 오른쪽 끝 열의 시간은 파일 읽기가 섞이고 GPU 를 나눠 쓰는 중에 잰 값이라 참고용입니다(512 가 640 보다 느리게 나올 만큼 흔들립니다). 그래도 해상도를 따라 커지는 경향(128 에서 11.5 ms, 384 에서 24.9 ms, 640 에서 42.3 ms)은 보입니다. 낮은 해상도는 “조금 덜 정확하고 더 빠른” 선택지입니다.
- 32 의 배수가 아닌 400 은 앞에서 본 대로 거절됩니다(출력의 마지막 줄).
model.inference() 로 만든 추론 전용 스냅숏과 내보낸 ONNX 파일은 해상도가 고정됩니다. 다른 해상도로 쓰려면 그 해상도로 다시 만들거나 내보내야 합니다.
내보내기와 배포
학습을 마친 모델은 PyTorch 안에서만 돕니다. 실제 서비스나 기기에서는 PyTorch 없이, 그 하드웨어에 맞게 다듬은 실행기로 돌리는 일이 많습니다.
모델을 다른 실행기가 읽을 수 있는 파일로 바꾸는 일을 내보내기export 라고 합니다.
ch14_export.py 가 미세 조정한 Nano 를 내보내고, 다른 실행기로 돌려 보고, 속도를 잽니다.
ONNX 로 내보내기
ONNXOpen Neural Network Exchange 는 신경망을 “표준 연산들이 이어진 그래프” 로 적어 두는 파일 형식입니다. PyTorch 로 만든 모델을 ONNX 파일로 써 두면, ONNX 를 읽을 줄 아는 여러 실행기(ONNX Runtime, TensorRT, OpenVINO …)가 그것을 돌릴 수 있습니다. 서로 다른 도구 사이의 공용어인 셈입니다. 표준 연산의 목록은 판(버전)마다 조금씩 늘어나는데, 그 판 번호를 opsetoperator set version 이라고 합니다.
패키지에서는 model.export() 한 줄입니다. 설치판의 기본 인자는 format="onnx", opset_version=17, batch_size=1, output_dir="output" 이고, 내보낸 파일의 경로를 돌려줍니다.
$ python ch14_export.py
[0] 환경: rfdetr 1.12.1, torch 2.15.0+cu132, onnx 1.23.2, onnxruntime 1.32.0 (실행 제공자 ['AzureExecutionProvider', 'CPUExecutionProvider'])
GPU: NVIDIA RTX PRO 2000 Blackwell Generation Laptop GPU | CPU: Intel(R) Core(TM) Ultra 7 255H (코어 16개)
[1] 모델: fine-tuned Nano (Shape World, 3 classes), 입력 해상도 384×384
[2] ONNX 로 내보내기 → ch14_export/
model.export() 가 돌려준 경로: ch14_export/rfdetr-nano.onnx (8.6초, 102.7 MB)
opset 17, 노드 1422개
입력 'input': 모양 [1, 3, 384, 384], tensor(float)
출력 'dets': 모양 [1, 300, 4], tensor(float)
출력 'labels': 모양 [1, 300, 4], tensor(float)
파일에 함께 적힌 메타데이터(일부): {"input_shape": [1, 3, 384, 384], "means": [0.485, 0.456, 0.406], "stds": [0.229, 0.224, 0.225], "channel_order": "RGB", "resize_interpolation": "bilinear", "resize_antialias": false, "outputs": {"pred_boxes": "dets", "pred_logits": "labels"}, "box_format": "cxcywh_normalized", "class_names": ["circle", "rectangle", "triangle"], "num_select": 300}-
산출물. 파일 하나,
rfdetr-nano.onnx(102.7 MB)입니다. 저장소의 문서(개발판)에는inference_model.onnx라는 이름이 나오지만 1.12.1 은 모델 종류를 따서 이름을 지었습니다. 이름을 미리 짐작하지 말고export()가 돌려준 경로를 쓰세요. -
입력 은 이름
input, 모양[1, 3, 384, 384], float32. 배치 크기 1 과 해상도 384 가 그래프에 고정 되어 있습니다. 설명문(docstring)에 따르면 다른 배치 크기는export(batch_size=4)나export(dynamic_batch=True), 다른 해상도는export(shape=(H, W))로 다시 내보냅니다(나누어떨어짐 제약은 같습니다). -
출력 은 두 개,
dets(박스,[1, 300, 4])와labels(클래스 로짓,[1, 300, 4])입니다. 앞에서 본 날출력pred_boxes·pred_logits그대로이고, 전처리도 후처리도 그래프 안에 들어 있지 않습니다. 리사이즈 · 정규화 · 상위 K 고르기는 쓰는 쪽이 해야 합니다. -
메타데이터. 그래서 패키지는 전처리 · 후처리에 필요한 정보(평균 · 표준편차, 채널 순서, 보간 방식, 출력 이름, 박스 형식, 클래스 이름,
num_select)를 ONNX 파일 안에 함께 적어 둡니다. 파일 하나만 건네받아도 어떻게 써야 하는지 알 수 있습니다.
우리 모델의 두 출력은 모양이 똑같이 [1, 300, 4] 입니다. 박스는 좌표가 4개라서, 로짓은 클래스 3개 + 1칸이라서 4 입니다.
“마지막 차원이 4 인 것이 박스” 라는 식으로 모양을 보고 고르는 코드는 클래스가 정확히 3개일 때만 조용히 틀립니다(공식 문서도 이 함정을 경고합니다).
session.run(["dets", "labels"], …) 처럼 이름으로 꺼내세요.
onnxruntime 으로 돌려 PyTorch 와 비교
ONNX Runtimeonnxruntime 은 ONNX 그래프를 실행하는 엔진입니다. 어떤 하드웨어로 계산할지는 “실행 제공자(execution provider)” 로 고릅니다.
rfdetr[onnx] 로 설치되는 기본판 onnxruntime 에는 GPU 제공자가 없습니다(위 출력 첫 줄의 제공자 목록에 CUDA 가 없습니다). GPU 로 돌리려면 onnxruntime-gpu 가 따로 필요합니다. 이 장은 CPU 제공자만 썼습니다.
내보낸 모델이 원래 모델과 같은 계산 을 하는지부터 확인해야 합니다. 같은 입력 텐서를 PyTorch 모델과 ONNX 모델에 넣고 날출력을 수치로 비교합니다.
전처리는 앞에서 본 preprocess 함수로 직접 합니다.
[3] onnxruntime 추론 vs PyTorch 순전파 (같은 입력 텐서) 전처리 예: 왼쪽 위 픽셀 RGB (30, 17, 39) → 정규화 뒤 [-1.6042, -1.7381, -1.1247] (R 채널 손계산: (30/255 − 0.485)/0.229 = -1.6042) 입력 (1, 3, 384, 384) → dets (1, 300, 4), labels (1, 300, 4) check (점수 0.05 초과 질의 4개): 박스 최대 차이 7.8e-05, 로짓 최대 차이 1.3e-02 (PyTorch cuda vs onnxruntime CPU) 질의 300개 전체: 박스 최대 차이 1.0e+00, 로짓 최대 차이 2.3e+00 | 박스 차이가 1e-3 을 넘는 질의 185개, 그 질의들의 최고 점수 0.013
출력의 check 두 줄을 차례로 읽습니다.
- 객체를 잡은 질의에서는 같습니다. 점수가 0.05 를 넘는 질의 4개(이 그림의 객체 4개)에서 박스의 최대 차이는 $7.8 \times 10^{-5}$(정규화 단위; 192 픽셀 그림에서 0.015 픽셀), 로짓의 최대 차이는 0.013 입니다. 완전히 0 이 아닌 것은 정상입니다. 한쪽은 GPU 의 PyTorch, 한쪽은 CPU 의 ONNX Runtime 이라 같은 수식을 서로 다른 순서 · 다른 라이브러리로 계산하고, float32 는 유효 숫자가 7자리쯤이라 층을 수십 개 거치며 끝자리가 조금씩 달라집니다. 로짓 0.013 의 차이는 점수 0.98 근처에서 0.0003 쯤의 차이입니다.
- 그런데 300개 전체를 비교하면 크게 다릅니다. 박스 최대 차이 1.0, 로짓 최대 차이 2.3. 차이가 $10^{-3}$ 을 넘는 질의가 185개나 됩니다. 내보내기가 잘못된 것일까요? 아닙니다. 그 185개 질의의 점수는 가장 높은 것도 0.013 입니다. 모두 “아무것도 없다” 고 답한 배경 질의입니다.
- 왜 배경 질의만 달라지나. 10장 의 2단계 질의 선택을 떠올리면 짐작할 수 있습니다. 인코더 출력의 576개 위치(24 × 24)가 낸 제안 가운데 점수 상위 300개가 질의의 기준 박스가 됩니다. 도형 세상의 배경은 어디나 비슷해서 배경 위치들의 제안 점수가 서로 거의 같고, 계산 순서가 달라 끝자리가 조금만 바뀌어도 그 순위가 뒤바뀝니다. 그러면 같은 번호의 질의가 서로 다른 제안을 받아 출력이 통째로 달라집니다. 객체 위의 제안은 점수가 뚜렷이 높아 순위가 바뀌지 않습니다. (이 설명은 관측과 맞는 추정이고, 제안의 순위를 직접 비교해 확인한 것은 아닙니다.)
날출력 텐서를 통째로 np.allclose 로 비교하면 멀쩡한 모델도 “다르다” 고 나올 수 있습니다. 쓸모 있는 예측끼리(점수가 문턱값을 넘는 것) 비교하거나, 다음 절처럼 후처리를 마친 탐지 결과를 비교하세요.
가장 확실한 것은 내보낸 모델로 검증 세트 전체의 AP 를 다시 재는 것입니다. 쓸모 있는 예측에서도 차이가 0.1 처럼 크다면 전처리(RGB 순서, 정규화, 보간 방식)가 다르거나 eval() 을 빠뜨린 것입니다.
날출력을 직접 후처리하기
이제 ONNX 가 준 dets · labels 를 앞에서 만든 postprocess 함수에 넣어 탐지 결과로 바꾸고, model.predict() 가 준 결과와 비교합니다.
전처리 → ONNX 순전파 → 후처리의 세 토막을 모두 우리 손으로 한 것이므로, 이것이 맞으면 PyTorch 도 rfdetr 패키지도 없는 곳에서(예를 들어 다른 언어로 짠 서버에서) 같은 결과를 낼 수 있다는 뜻입니다.
[4] 날출력을 직접 후처리 vs model.predict()
로짓 (Q, C) = (300, 4) → 쌍 1200개 가운데 상위 300개 → 문턱값 0.5 를 넘는 것 4개
질의 1 · 클래스 1 (rectangle): 점수 0.9796, xyxy [10.5, 44.1, 75.8, 81.1]
질의 0 · 클래스 1 (rectangle): 점수 0.9768, xyxy [88.4, 45.3, 148.8, 123.6]
질의 2 · 클래스 0 (circle): 점수 0.9751, xyxy [118.9, 16.7, 162.1, 58.0]
질의 3 · 클래스 1 (rectangle): 점수 0.9624, xyxy [59.2, 103.9, 116.1, 139.1]
check: predict() 와 개수 같음 True, 클래스 같음 True, 박스 최대 차이 9.0e-03 픽셀, 점수 최대 차이 3.7e-05
질의마다 가장 높은 점수의 분포: 0.5 초과 4개, 0.05 이하 296개 (질의 300개 가운데)- 직접 한 후처리가
predict()와 같습니다. 탐지 4개, 클래스가 같고, 박스의 최대 차이 0.009 픽셀, 점수의 최대 차이 $3.7 \times 10^{-5}$. 앞 절에서 본 PyTorch(GPU)와 ONNX Runtime(CPU)의 계산 차이가 그대로 넘어온 크기입니다. 1,200개의 (질의, 클래스) 쌍에서 300개를 고르고, 그 가운데 문턱값 0.5 를 넘는 것이 4개였습니다. - 점수는 양 끝으로 갈려 있습니다. 질의 300개 가운데 최고 점수가 0.5 를 넘는 것이 4개, 0.05 이하가 296개이고 그 사이에는 하나도 없습니다. NMS 없이도 중복이 없고(7장) 문턱값을 0.3 으로 하든 0.5 로 하든 결과가 같았던 까닭입니다. 또 객체를 잡은 질의의 번호가 0, 1, 2, 3 인 것은 우연이 아닙니다. 2단계 질의 선택이 인코더 제안을 점수가 높은 순으로 뽑아 질의 0, 1, 2 … 에 차례로 배정하기 때문에(10장), 객체가 있는 자리의 제안이 맨 앞 번호를 받습니다.
-
더 편한 길도 있습니다.
RFDETRInference("…/rfdetr-nano.onnx").predict(그림)처럼 ONNX 파일을 패키지의 추론기로 읽으면, 파일에 적힌 메타데이터로 전처리 · 후처리를 알아서 하고Detections를 돌려줍니다 (1.12.1 에서 같은 박스가 나오는 것을 확인했습니다). rfdetr 패키지를 설치할 수 있는 환경이라면 이쪽이 안전합니다.
지연 시간 재기
12장 에서 지연 시간은 NAS 의 한 축이었습니다. 그런데 지연 시간은 AP 와 달리 재는 방법에 따라 값이 몇 배씩 달라지는 숫자입니다. RF-DETR 논문(4절, 부록 K)이 측정 방법을 따로 공들여 적은 까닭입니다. 먼저 무엇을 재는지부터 정해야 합니다.
- 순전파만(model only): 전처리된 텐서가 GPU 에 올라가 있는 상태에서 신경망을 한 번 통과시키는 시간. 논문과 README 의 표가 이 값입니다.
- 처음부터 끝까지(end to end): 그림을 받아 전처리 → 순전파 → 후처리해 결과를 돌려주기까지. 쓰는 사람이 실제로 기다리는 시간입니다.
그리고 재는 요령이 있습니다. 아래 measure 함수가 그것을 담고 있습니다.
- 예열 실행을 버린다. 처음 몇 번은 메모리 할당, 연산 구현 고르기, 캐시 채우기 같은 준비 때문에 훨씬 느립니다. 이 값을 평균에 넣으면 안 됩니다. 이 실습은 구성을 바꿀 때마다 몇 번을 헛돌린 뒤 잽니다.
-
GPU 를 기다린다. PyTorch 의 GPU 연산은 “일을 맡기고 바로 돌아오는” 방식입니다.
torch.cuda.synchronize()로 일이 끝나기를 기다리지 않고 시계를 보면, 맡기는 데 걸린 시간만 재게 되어 터무니없이 빠른 값이 나옵니다. - 여러 번 재서 분포를 본다. 한 번의 값은 그 순간 다른 프로그램이 무엇을 했는지에 흔들립니다. 구성마다 200번(CPU 구성은 40번)을 재서 중앙값 을 대푯값으로 쓰고, 10% · 90% 분위수로 퍼진 정도를 함께 적습니다(평균은 가끔 튀는 큰 값에 끌려갑니다).
- 배치 1. 실시간 탐지의 지연 시간은 그림 한 장이 들어와 결과가 나올 때까지의 시간이므로 배치 크기 1 로 잽니다.
- 견줄 구성들은 번갈아 잰다. 기계를 다른 작업과 나눠 쓰면 부하가 시시각각 변합니다. 구성 A 를 다 재고 나서 B 를 재면 “그때 기계가 한가했는가” 가 결과에 섞입니다. 이 실습은 모든 구성을 조금씩(GPU 구성 20번, CPU 구성 4번) 재는 것을 한 라운드로 삼아 10 라운드를 돌립니다. 그러면 부하의 변화가 모든 구성에 고르게 묻습니다. 물론 가장 좋은 것은 아무것도 돌지 않는 기계에서 재는 것입니다.
논문이 지적한 측정의 함정은 세 가지입니다. 다른 사람의 지연 시간 숫자를 읽을 때 늘 확인할 것들이기도 합니다.
| 함정 | 무슨 일인가 | 논문의 처방 |
|---|---|---|
| 전력 제한(스로틀링) | 쉬지 않고 순전파를 돌리면 GPU 가 뜨거워져 스스로 속도를 낮추고, 측정값이 흔들린다 | 순전파 사이에 200 ms 쉬기. 200 ms 넘게 쉬어도 차이가 없었다고 한다 |
| 정밀도 섞어 보고하기 | 정확도는 FP32 모델로, 지연 시간은 FP16half precision, 16-bit floating point 엔진으로 재서 한 표에 적는다. 그런데 FP16 으로 바꾸면 정확도가 달라질 수 있다 — 논문은 D-FINE 을 그대로 FP16 으로 바꾸면 AP 가 0.5 로 무너졌다고 적는다 | 정확도와 지연 시간을 같은 산출물(같은 FP16 엔진)로 재서 보고 |
| NMS 빼고 재기 | YOLO 계열은 신경망 뒤에 NMS 가 꼭 필요한데, 그 시간을 빼고 재는 경우가 많다 | NMS 가 필요한 모델은 그 시간을 넣어 비교. DETR 계열은 NMS 가 없다 |
여기서 FP16 은 수 하나를 16비트로 적는 부동소수점(반정밀도)입니다. 보통 쓰는 FP32(32비트, 유효 숫자 약 7자리)에 견주어 유효 숫자가 3 – 4자리로 줄지만, 메모리가 절반이고 GPU 에서 더 빨리 계산됩니다. 가중치와 중간 계산값을 이렇게 더 적은 비트의 수로 바꿔 모델을 작고 빠르게 만드는 일을 통틀어 양자화quantization 라고 합니다(FP32 → FP16, 더 나아가 8비트 정수 INT8). 그리고 표의 “엔진” 은 TensorRTNVIDIA TensorRT 가 만든 것입니다. TensorRT 는 NVIDIA 의 추론 최적화 도구로, ONNX 그래프를 받아 특정 GPU 에 맞게 연산을 합치고 정밀도를 고르고 가장 빠른 구현을 골라 “엔진” 파일로 컴파일합니다. 논문의 지연 시간은 모두 T4 GPU 에서 TensorRT 10.4 로 만든 FP16 엔진으로 잰 것입니다.
이 노트북에서 잰 결과
미세 조정한 Nano(384 × 384)를 이 튜토리얼의 노트북(NVIDIA RTX PRO 2000 Blackwell 노트북 GPU 8GB, Intel Core Ultra 7 255H 16코어)에서 쟀습니다. 먼저 밝혀 둘 것이 있습니다. 이 측정은 다른 학습 작업들이 같은 GPU 와 CPU 를 쓰고 있는 중에 했습니다. 지연 시간을 재기에는 나쁜 조건이지만, 덕분에 “측정값이 조건에 얼마나 흔들리는가” 를 숫자로 볼 수 있습니다.
[5] 지연 시간 (배치 1, 그림 1장당 ms)
FP16 과 FP32 의 출력 차이 (점수 0.05 초과 질의): 박스 최대 3.4e-05, 로짓 최대 4.7e-03
model.inference(dtype='float32') 준비 85.6초
model.inference(dtype='float16') 준비 88.7초
FP16 스냅숏의 예측: 4개, predict() 와 박스 최대 차이 0.07 픽셀
라운드 10번 · 구성 9개를 번갈아 잰다. 시작할 때: load average 4.8 (CPU 코어 16개), GPU 사용률 · 메모리 97 %, 3472 MiB
끝났을 때: load average 13.7, GPU 사용률 · 메모리 70 %, 3474 MiB
라운드별 중앙값 (ms): R1 R2 R3 R4 R5 R6 R7 R8 R9 R10
torch_gpu_fp32 15.2 16.9 17.5 16.9 16.7 16.9 16.7 16.9 17.2 17.3
torch_gpu_fp16 14.1 12.0 14.0 11.3 15.5 14.8 14.1 12.6 15.9 11.7
torch_gpu_fp32_sleep 18.1 18.6 20.8 19.7 20.4 19.4 19.5 20.9 21.2 18.1
torch_gpu_predict 19.5 21.6 23.9 19.6 19.4 19.5 21.8 21.8 19.5 19.8
torch_gpu_predictor_fp32 16.9 16.3 14.5 14.2 14.2 14.8 15.8 11.6 15.2 14.7
torch_gpu_predictor_fp16 10.1 10.1 7.0 10.4 10.4 9.6 10.1 11.0 10.0 10.1
ort_cpu_fp32 113.6 113.1 112.5 111.9 112.1 112.1 112.1 112.5 112.0 111.7
torch_cpu_fp32 154.7 147.6 147.0 151.8 146.2 148.1 148.1 146.7 147.5 154.9
torch_cpu_fp32_default 3428.0 3072.9 3082.1 2900.0 2939.1 3110.0 2940.0 3144.9 3007.1 3109.0
가장 한가했던 라운드: R4
구성 전체 중앙값 | 10% | 90% | R4 의 중앙값 | n
PyTorch GPU FP32, forward only 16.91 | 14.87 | 17.61 | 16.86 | 200
PyTorch GPU FP16 autocast, forward only 13.83 | 11.31 | 17.02 | 11.32 | 200
PyTorch GPU FP32, forward only, 200 ms sleep between 19.67 | 17.09 | 21.94 | 19.71 | 50
PyTorch GPU FP32, model.predict() end to end 20.35 | 17.50 | 24.32 | 19.63 | 200
PyTorch GPU FP32, model.inference() predictor end to end 14.61 | 12.28 | 17.77 | 14.24 | 200
PyTorch GPU FP16, model.inference() predictor end to end 10.13 | 7.84 | 12.85 | 10.35 | 200
onnxruntime CPU FP32 (8 threads), forward only 112.29 | 111.67 | 115.56 | 111.95 | 40
PyTorch CPU FP32 (8 threads), forward only 147.96 | 146.46 | 160.51 | 151.78 | 40
PyTorch CPU FP32 (16 threads = default), forward only 3077.49 | 2935.22 | 3173.22 | 2899.97 | 10
출력의 위쪽 표는 라운드마다의 중앙값입니다. 행(구성)마다 열 방향으로 값이 고르면 재는 동안 기계의 사정이 크게 변하지 않았다는 뜻이고, 이번 실행이 그랬습니다. 아래쪽 표를 정리하면 이렇습니다.
| 구성 | 잰 범위 | 중앙값(ms) | 10% – 90% |
|---|---|---|---|
| PyTorch GPU, FP32 | 순전파만 | 16.9 | 14.9 – 17.6 |
| PyTorch GPU, FP16 자동 혼합 정밀도 | 순전파만 | 13.8 | 11.3 – 17.0 |
| PyTorch GPU, FP32, 사이에 200 ms 쉬기 | 순전파만 | 19.7 | 17.1 – 21.9 |
model.predict(), GPU FP32 | 처음부터 끝까지 | 20.4 | 17.5 – 24.3 |
model.inference() 스냅숏, GPU FP32 | 처음부터 끝까지 | 14.6 | 12.3 – 17.8 |
model.inference(dtype="float16") 스냅숏, GPU FP16 | 처음부터 끝까지 | 10.1 | 7.8 – 12.9 |
| onnxruntime CPU, FP32, 8 스레드 | 순전파만 | 112.3 | 111.7 – 115.6 |
| PyTorch CPU, FP32, 8 스레드 | 순전파만 | 148.0 | 146.5 – 160.5 |
| PyTorch CPU, FP32, 16 스레드(기본값) | 순전파만 | 3,077 | 2,935 – 3,173 |
-
무엇을 재느냐에 따라 3.4 ms 가 다릅니다. 같은 FP32 모델인데 순전파만 재면 16.9 ms,
predict()전체를 재면 20.4 ms 입니다. 전처리 · 후처리 · 결과를 CPU 로 가져오는 일이 전체의 17% 입니다. “지연 시간 몇 ms” 라는 말에는 늘 “어디서 어디까지” 가 따라붙어야 합니다. - FP16 은 빠르고, 출력은 조금 달라집니다. 자동 혼합 정밀도만 켜도 순전파가 16.9 → 13.8 ms 로 18% 줄었습니다. 그 대신 출력이 달라집니다. 객체를 잡은 질의에서 박스 최대 $3.4 \times 10^{-5}$, 로짓 최대 0.0047. 이 모델에서는 무시할 크기지만, 논문의 D-FINE 사례처럼 FP16 에서 정확도가 무너지는 모델도 있습니다. FP16 으로 쓸 것이면 FP16 으로 AP 를 다시 재야 하는 이유입니다.
-
추론 전용 스냅숏이 가장 빠릅니다.
model.inference()로 만든 추론기는 전처리 · 후처리를 다 넣고도 14.6 ms 로, 일반 모듈의 순전파만(16.9 ms)보다 빠릅니다. FP16 스냅숏은 10.1 ms 로predict()의 절반입니다. 결과는predict()와 박스 최대 0.07 픽셀 차이였습니다. 값은 준비 시간(이번 실행에서 85.6초와 88.7초; GPU 가 한가할 때는 12.7초, 붐빌 때는 3분까지 걸렸습니다)과, 배치 크기 · 해상도가 고정된다는 것입니다. - 200 ms 를 쉬었더니 오히려 느려졌습니다(16.9 → 19.7 ms). 논문의 T4 에서는 쉬지 않고 돌릴 때 전력 제한에 걸려 측정이 흔들렸기 때문에 쉬었습니다. 이 노트북에서는 반대로, 쉬는 사이에 GPU 가 절전 상태로 내려가거나 다른 작업이 그 틈을 차지해 다음 순전파가 느려진 것으로 보입니다(원인을 따로 확인하지는 않았습니다). 어느 쪽이 “맞는” 값인지는 쓰임새가 정합니다. 동영상처럼 쉬지 않고 들어오면 앞의 값, 가끔 한 장씩 들어오면 뒤의 값이 실제에 가깝습니다. 그래서 측정 방법을 함께 적어야 합니다.
- CPU 는 GPU 보다 한 자릿수 느리고, 실행기에 따라 다릅니다. 같은 8 스레드에서 onnxruntime 112 ms, PyTorch 148 ms 로 onnxruntime 이 1.3배 빠릅니다. GPU 순전파(16.9 ms)의 6.6배입니다.
-
스레드 수의 함정. PyTorch 는 기본으로 코어 수(16)만큼 스레드를 씁니다. 그 기본값으로 재면 한 장에 3.1초, 8 스레드(148 ms)의 21배가 걸렸습니다. 열 라운드 모두 2.9 – 3.4초였습니다.
다른 작업이 코어 몇 개를 쓰고 있었고(load average 5 – 14), 이 CPU 는 성능이 다른 코어가 섞여 있어, 16개 스레드가 서로를 기다리며 헛도는 것으로 보입니다. 아무것도 돌지 않는 기계에서는 이렇게까지 되지 않을 수 있지만(확인하지 못했습니다),
“스레드가 많을수록 빠르다” 는 믿을 수 없습니다. CPU 로 배포한다면
torch.set_num_threads나 onnxruntime 의intra_op_num_threads를 직접 정하고 재 보세요. - 기계가 붐비면 모든 것이 흔들립니다. 같은 스크립트를 다른 작업이 한창일 때(load average 25) 돌린 앞선 실행에서는, GPU FP32 순전파의 라운드별 중앙값이 8.7 ms 에서 58.4 ms 까지, onnxruntime CPU 가 113 ms 에서 634 ms 까지 움직였습니다. 그때 가장 빨랐던 라운드의 8.7 ms 가 GPU 를 혼자 쓸 때의 값에 가까울 것이고, 위 표의 16.9 ms 는 GPU 를 다른 학습과 나눠 쓴 값입니다. 논문이 전용 T4 에서 편차 0.1 ms 를 이야기하는 것과 견주면, 이 표의 숫자는 첫 자리 정도만 믿을 수 있습니다.
논문 표 2 와 README 의 “Nano 2.3 ms” 는 NVIDIA T4 + TensorRT + FP16, 순전파만, 배치 1 의 값입니다. 위 표와는 다음이 모두 다릅니다.
- 하드웨어: 서버용 T4 와 노트북 GPU 는 다른 기계입니다. 게다가 이 측정은 GPU 를 다른 학습 작업과 나눠 쓰는 중에 했습니다.
- 실행기: 컴파일된 TensorRT 엔진과 일반 PyTorch 모듈(또는 CPU 의 ONNX Runtime)은 같은 모델도 전혀 다른 속도로 돌립니다. 이 튜토리얼은 TensorRT 엔진을 만들어 보지 않았습니다.
- 정밀도: FP16 엔진과 FP32 순전파.
- 범위: 순전파만 잰 값과, 전처리 · 후처리까지 넣은 값.
지연 시간은 같은 기계에서 같은 방법으로 잰 것끼리만 비교할 수 있습니다. 내 서비스에 필요한 숫자는 내 하드웨어에서, 실제로 쓸 실행기와 정밀도로, 처음부터 끝까지 재야 합니다.
그 밖의 내보내기 형식
export(format=…) 은 ONNX 말고도 여러 형식을 받습니다. 아래 표는 설치판의 export() 설명문(docstring)과 패키지의 추가 묶음 목록, 공식 문서를 정리한 것입니다.
이 튜토리얼에서 직접 돌려 본 것은 ONNX 뿐 이고, 나머지는 문서 기준입니다.
format | 산출물 | 추가 설치 | 어디에 쓰나(문서 기준) |
|---|---|---|---|
"onnx"(기본) | .onnx | rfdetr[onnx] | ONNX Runtime 등 여러 실행기. 직접 확인 |
"tensorrt"("trt") | .trt 엔진 | rfdetr[tensorrt] | NVIDIA GPU 에서 가장 낮은 지연 시간. ONNX 를 거쳐 변환하고 기본이 FP16(fp16=True). 엔진은 기본적으로 만든 기계의 GPU 와 TensorRT 판에 묶인다 |
"openvino" | OpenVINO IR(.xml + .bin) | rfdetr[openvino] | Intel CPU · GPU · NPU |
"tflite" | .tflite(FP32 · FP16, 선택하면 INT8) | rfdetr[tflite] | 모바일 · 에지. ONNX → TensorFlow → TFLite 로 변환 |
"litert" | .tflite | rfdetr[litert] | 위와 같은 파일 형식을 ONNX · TensorFlow 없이 PyTorch 에서 바로 |
"executorch"("pte") | .pte | rfdetr[executorch] | 기기 위의 PyTorch 실행기. backend= 로 대상(xnnpack · coreml · qnn)을 정해야 한다 |
"coreml" | .mlpackage | rfdetr[coreml] | Apple 기기(Xcode) |
"coreai" | .aimodel | rfdetr[coreai] | Apple Core AI(문서: iOS · iPadOS · macOS 27 이상) |
- 설명문은 TFLite · ExecuTorch · CoreML · LiteRT 내보내기가 실험적 이며 바뀔 수 있다고 경고합니다.
-
INT8 양자화는
export(quantization="int8", calibration_data=…)로 합니다(ONNX · OpenVINO · TensorRT). 8비트로 바꾸려면 중간 계산값이 어느 범위에 있는지 알아야 해서, 실제 쓰일 그림과 비슷한 보정용 그림 이 꼭 필요합니다. 문서는 ONNX INT8 이 COCO 일부(500장)에서 Nano 의 mAP 를 2.65 떨어뜨렸다고 적고 “배포 전에 자기 데이터로 재 보라” 고 합니다. - 어느 형식이든 원칙은 이 절에서 한 것과 같습니다. 내보낸 뒤에는 꼭 원래 모델과 출력을 비교하고, 내보낸 그 산출물로 정확도와 지연 시간을 함께 잽니다.
분할과 키포인트 모델
13장 에서 만든 분할 머리를 단 모델 RF-DETR-Seg, 그리고 사람의 관절 같은 점들을 찾는 키포인트 모델(미리보기)도 같은 패키지에 있습니다. 이 절은 공식 문서와 설치판의 소스를 읽고 정리한 것이며 직접 돌려 보지는 않았습니다.
| 탐지 | 인스턴스 분할 | 키포인트(미리보기) | |
|---|---|---|---|
| 클래스 | RFDETRNano … RFDETRLarge | RFDETRSegNano … RFDETRSeg2XLarge | RFDETRKeypointPreview |
| 쓰는 법 | 같습니다: predict(), train(dataset_dir=…), evaluate(), export() | ||
predict 가 돌려주는 것 | sv.Detections | sv.Detections + mask: 객체마다의 불 마스크 (n, H, W)(원본 그림 크기) | sv.KeyPoints: xy 가 (n, K, 2), 박스는 data["xyxy"] |
| 데이터셋 주석 | bbox | bbox + segmentation(다각형 꼭짓점 목록). YOLO 형식이면 다각형 좌표 | bbox + keypoints(점마다 x, y, 보임 여부) |
| 설정(설치판) | Nano: 384 / 패치 16 / 질의 300 | SegNano: 312 / 패치 12 / 윈도 1 / 디코더 4층 / 질의 100 | 576 / 패치 12 / 디코더 4층 / 질의 100 |
| 더해지는 손실 | – | 마스크 BCE · 다이스 손실(mask_ce_loss_coef=5, mask_dice_loss_coef=5) | 키포인트 손실 |
| 가장 좋은 체크포인트를 고르는 기준 | 박스 mAP | 마스크 mAP | 키포인트 AP(OKS 기준) |
분할 모델을 쓸 때 탐지와 달라지는 것은 사실상 두 가지입니다. 데이터셋 주석에 segmentation 이 있어야 하고, 결과에 detections.mask 가 더 들어 있다는 것.
패치가 12 라서 해상도는 24 의 배수(SegNano 는 12 의 배수)여야 한다는 점도 기억해 두세요.
마스크가 어떻게 만들어지는지(질의 임베딩과 픽셀 임베딩의 내적), 왜 해상도의 1/4 크기로 계산하는지는 13장 에서 직접 만들어 보았습니다.
실전 요령과 흔한 문제
이 장의 실험과 설치판의 소스 · 문서에서 확인한 것만 모았습니다.
batch_size를 줄이고 그만큼grad_accum_steps를 늘려 실효 배치 크기를 지킵니다(4 × 4 → 2 × 8). 이 장의batch_size=2학습은 Nano 에서 최대 1.61 GiB 를 썼습니다.- 더 작은 모델(Nano)이나 더 낮은
resolution을 씁니다. 토큰 수는 해상도의 제곱에 비례합니다(384 → 576개, 512 → 1,024개). - 문서는
gradient_checkpointing=True(모델을 만들 때 주는 설정)도 메모리를 줄이는 방법으로 듭니다. 속도와 맞바꾸는 방법이고, 이 장에서는 써 보지 않았습니다. num_workers가 크면 GPU 가 아니라 주 메모리(RAM) 가 모자랄 수 있습니다.
해상도를 올리는 것이 첫 번째 처방입니다. Nano 의 384 에서 패치 하나는 16 × 16 픽셀이므로, 원본에서 그보다 한참 작은 객체는 패치 하나의 일부에 지나지 않습니다.
model.train(resolution=512, …) 처럼 patch_size × num_windows 의 배수로 올리거나, 처음부터 해상도가 높은 크기(Small 512, Medium 576, Large 704)를 고릅니다.
12장 에서 본 것처럼 정확도는 해상도와 패치 크기 각각보다 “한 변의 패치 수” 와 더 관계가 깊었습니다.
- 해상도가 거절된다. 한 변이
patch_size × num_windows(Nano 32)의 배수가 아니면ValueError입니다. 학습 · 추론 · 내보내기 모두 같습니다. - 클래스 번호가 하나씩 밀린 것 같다. 미세 조정한 모델의
class_id는 JSON 의category_id가 아니라 id 순으로 0 부터 다시 매긴 번호입니다. COCO 사전 학습 모델만 1 – 90 의 범주 id 를 그대로 씁니다. - 클래스 수가 안 맞는다는 경고. “Checkpoint has 90 classes but model is configured for 3” 은 정상입니다. 반대로 모델에
num_classes를 직접 줬다면 데이터셋과 맞는지 확인하세요. - 색이 이상한 결과. numpy 배열은 RGB 순서여야 합니다. OpenCV 로 읽었다면 BGR 을 뒤집어 넣습니다.
- 검증 폴더 이름.
val/이 아니라valid/, 주석 파일은_annotations.coco.json입니다. -
같은 모델로 train() 을 또 부르면. 소스에 따르면 이어서 학습하는 것이 아니라 처음의 사전 학습 가중치에서 다시 시작 하고, 그렇다는 경고를 냅니다. 이어서 하려면
resume=을 씁니다. - ONNX 출력을 모양으로 구별. 클래스가 3개면 박스와 로짓의 모양이 같습니다. 이름(
dets,labels)으로 꺼냅니다. - 직접 순전파할 때 eval().
model.model.model(실제nn.Module)을 꺼내 쓸 때는.eval()을 직접 불러야 합니다.predict()는 알아서 합니다. - 남의 지연 시간 표. 하드웨어 · 실행기 · 정밀도 · 측정 범위가 적혀 있지 않은 지연 시간은 비교에 쓸 수 없습니다.
- 사전 학습 모델로 내 그림 몇 장을
predict해 본다(이미 되는 일이라면 학습이 필요 없다). - 데이터를 COCO 형식으로 만들고, 저장한 주석을 다시 읽어 그림 위에 그려 본다(그림 14-3 처럼). 주석이 틀리면 뒤의 모든 것이 헛일이다.
- 가장 작은 모델(Nano)로, 기본 설정으로, 몇 에폭만 돌려 검증 AP 가 오르는지 본다.
- 시험 세트로 채점하고 예측을 눈으로 본다. 모자라면 그때 해상도 · 모델 크기 · 에폭 수를 올린다.
- 내보내고, 원래 모델과 출력을 비교하고, 실제 쓸 기계에서 지연 시간을 잰다.
rfdetr패키지(이 장은 1.12.1)는 크기별 클래스(RFDETRNano…)와 네 메서드predict·train·evaluate·export로 쓰입니다. 학습에는rfdetr[train], ONNX 에는rfdetr[onnx]가 더 필요합니다. 탐지 Nano – Large 와 분할 모델은 Apache 2.0, Atto · Femto · Pico · XLarge · 2XLarge 탐지는 PML 1.0(rfdetr[plus])입니다.predict는 그림을 모델 해상도로 리사이즈 · 정규화해 넣고, 날출력을 시그모이드 → (질의 × 클래스) 쌍 전체에서 상위num_select개 → 문턱값 순으로 후처리해supervision.Detections(원본 픽셀의xyxy,confidence,class_id)로 돌려줍니다. NMS 는 없습니다.- 데이터는
train/ valid/ test/폴더마다_annotations.coco.json을 둔 COCO 형식으로 준비합니다.bbox는 픽셀[x, y, w, h](왼쪽 위 모서리 기준)이고, 정규화 $(c_x, c_y, w, h)$ 와는 $x^{\text{px}} = (c_x - w/2)W$, $y^{\text{px}} = (c_y - h/2)H$ 로 오갑니다. 클래스 번호는 범주 id 순서대로 0 부터 다시 매겨집니다. - 미세 조정은
model.train(dataset_dir=…)한 줄이고, 그 안에서 11장의 학습 고리가 돕니다. 실효 배치 크기는batch_size × grad_accum_steps, 학습률은 머리 1e-4 에서 백본 맨 아래 3.2e-6 까지 부품 · 층마다 다릅니다. 로그의loss_ce·loss_bbox·loss_giou는 마지막 디코더 층,_0은 보조 손실,_enc는 인코더 제안의 손실입니다. - 이 튜토리얼의 실험에서 사전 학습 가중치에서 시작한 Nano 는 도형 세상 1,000장으로 첫 에폭에 검증 AP 0.95, 5 에폭에 0.984(시험 0.983)에 이르렀고, 같은 조건의 무작위 초기화는 3 에폭에 0.77(시험 0.772) 이었습니다. 미세 조정의 힘은 사전 학습에서 옵니다.
- 패키지의
mAP_50_95는 3장의 AP@[.50:.95] 와 같은 정의입니다. 같은 예측을 우리evaluate_ap로 채점한 값과 0.002 안쪽으로 맞았습니다(0.9828 대 0.9830, 0.7722 대 0.7738). - 내보낸 ONNX 는 전처리 · 후처리가 빠진 날출력(
dets,labels)을 냅니다. 내보낸 뒤에는 원래 모델과 출력을 수치로 비교하고, 지연 시간은 예열 · 동기화 · 여러 번 측정의 중앙값으로, 같은 기계 · 같은 실행기 · 같은 정밀도 · 같은 범위 끼리만 비교합니다.
확인 문제
너비 640, 높이 480 인 그림에서 정규화 박스 $(c_x, c_y, w, h) = (0.25,\ 0.5,\ 0.5,\ 0.25)$ 를 COCO 의 bbox 로 바꾸세요. 그리고 그 bbox 를 2장의 모서리 표현 $(x_0, y_0, x_1, y_1)$ 픽셀로도 적어 보세요.
답 보기
$x^{\text{px}} = (0.25 - 0.25) \times 640 = 0$, $y^{\text{px}} = (0.5 - 0.125) \times 480 = 180$, $w^{\text{px}} = 0.5 \times 640 = 320$, $h^{\text{px}} = 0.25 \times 480 = 120$.
따라서 bbox = [0, 180, 320, 120] 이고, 모서리 표현은 $(0,\ 180,\ 0 + 320,\ 180 + 120) = (0, 180, 320, 300)$ 입니다.
COCO 의 뒤 두 숫자는 모서리 좌표가 아니라 너비 · 높이라는 점, 가로 값에는 너비 640 을 세로 값에는 높이 480 을 곱한다는 점이 요점입니다.
학습 그림이 2,400장이고 batch_size=4, grad_accum_steps=4, epochs=20 으로 학습합니다. 실효 배치 크기, 한 에폭의 순전파 횟수와 가중치 갱신 횟수, 전체 갱신 횟수를 구하세요. GPU 메모리가 모자라 batch_size 를 2 로 줄여야 한다면 같은 실효 배치 크기를 지키려면 무엇을 어떻게 바꾸나요?
답 보기
실효 배치 크기 $4 \times 4 = 16$. 한 에폭에 순전파 $2400/4 = 600$ 번, 갱신 $2400/16 = 150$ 번. 전체 갱신 $20 \times 150 = 3{,}000$ 번.
batch_size=2 로 줄이면 grad_accum_steps=8 로 올려 $2 \times 8 = 16$ 을 지킵니다. 한 에폭의 순전파는 1,200 번으로 늘지만 갱신 횟수는 150 번 그대로입니다. 메모리는 줄고 시간은 줄지 않습니다.
(가) RF-DETR Nano(patch_size=16, num_windows=2)에 쓸 수 있는 해상도를 400, 416, 500, 640 가운데서 고르세요. (나) 분할 모델 RFDETRSegSmall(patch_size=12, num_windows=2)에는 384, 400, 432 가운데 어느 것을 쓸 수 있나요? (다) Nano 를 640 으로 돌리면 패치 토큰은 몇 개이고 384 일 때의 몇 배인가요?
답 보기
(가) $16 \times 2 = 32$ 의 배수여야 합니다. $416 = 32 \times 13$, $640 = 32 \times 20$ 은 되고, $400/32 = 12.5$, $500/32 = 15.625$ 는 안 됩니다. (나) $12 \times 2 = 24$ 의 배수: $384 = 24 \times 16$, $432 = 24 \times 18$ 은 되고 $400/24 = 16.67$ 은 안 됩니다. (다) $640/16 = 40$ 이므로 $40 \times 40 = 1{,}600$ 개. 384 일 때는 $24 \times 24 = 576$ 개이므로 $1600/576 \approx 2.78$ 배입니다. 해상도는 $640/384 = 1.67$ 배인데 토큰은 그 제곱만큼 늡니다.
클래스 3개로 미세 조정한 Nano 의 날출력 labels 는 모양이 (300, 4) 입니다. (가) 후처리가 순위를 매기는 (질의, 클래스) 쌍은 모두 몇 개인가요? (나) 편 번호 $i = 1001$ 은 몇 번 질의의 몇 번 클래스인가요? (다) 질의 7 의 로짓이 $(3.0,\ 0.2,\ -4.0,\ -6.0)$ 이고 다른 질의의 점수는 모두 0.1 아래라면, threshold=0.5 에서 질의 7 로부터 나오는 탐지는 몇 개이고 무엇인가요?
답 보기
(가) $300 \times 4 = 1{,}200$ 개. 이 가운데 상위 300개가 뽑힙니다. (나) $q = \lfloor 1001/4 \rfloor = 250$, $c = 1001 \bmod 4 = 1$. 질의 250 의 클래스 1(사각형). (다) 점수는 $\sigma(3.0) = 0.953$, $\sigma(0.2) = 0.550$, $\sigma(-4.0) = 0.018$, $\sigma(-6.0) = 0.002$. 0.5 를 넘는 것이 둘이므로 같은 박스가 두 번 나옵니다: 클래스 0(원) 점수 0.953, 클래스 1(사각형) 점수 0.550. 질의마다 클래스 하나만 고르는 소프트맥스 방식과 달리, 시그모이드 점수는 칸마다 독립이라 이런 일이 생길 수 있습니다. 문턱값을 0.6 으로 올리면 하나만 남습니다.
기본 설정(lr_encoder=1.5e-4, lr_vit_layer_decay=0.8, lr_component_decay=0.7)의 Nano 에서 백본 블록 6 의 학습률을 구하세요. 그리고 EMA 의 실효 감쇠율 $d_t = 0.993\,(1 - e^{-t/100})$ 를 $t = 50$ 과 $t = 500$ 에서 계산해, 학습 초반과 후반에 EMA 가 어떻게 다르게 움직이는지 설명하세요.
답 보기
학습률: $1.5 \times 10^{-4} \times 0.7^2 \times 0.8^{13 - 6} = 7.35 \times 10^{-5} \times 0.8^7 = 7.35 \times 10^{-5} \times 0.2097 = 1.54 \times 10^{-5}$.
EMA: $t = 50$ 이면 $1 - e^{-0.5} = 0.3935$ 이므로 $d = 0.993 \times 0.3935 = 0.391$. $t = 500$ 이면 $1 - e^{-5} = 0.9933$ 이므로 $d = 0.986$.
초반($d \approx 0.39$)에는 새 가중치를 61% 나 받아들여 EMA 가 빠르게 따라가고, 후반($d \approx 0.99$)에는 1% 남짓만 받아들여 천천히, 매끄럽게 움직입니다.
처음부터 $d = 0.993$ 이면 EMA 가 쓸모없는 초기 가중치에 오래 붙들려 있게 되는데, ema_tau 가 그것을 막아 줍니다.
동료가 “README 에는 Nano 가 2.3 ms 라는데, 내 노트북에서 model.predict() 를 재 보니 수십 ms 가 나온다. 뭔가 잘못 설치한 것 같다” 고 합니다. 잘못 설치한 것이 아닐 수 있는 이유를 네 가지 이상 들고, 동료의 측정에서 확인해 볼 것을 적어 보세요.
답 보기
두 숫자는 재는 조건이 다릅니다. ① 하드웨어: README 는 NVIDIA T4, 동료는 노트북 GPU(또는 CPU). ② 실행기: README 는 TensorRT 로 컴파일한 엔진, 동료는 일반 PyTorch 모듈(model.inference() 도 쓰지 않은 상태).
③ 정밀도: README 는 FP16, predict() 는 FP32. ④ 범위: README 는 순전파만, predict() 는 그림 읽기 · 전처리 · 후처리 · 결과 복사까지.
확인할 것: 예열 실행을 버렸는가, GPU 라면 torch.cuda.synchronize() 로 끝나기를 기다렸는가, 한 번이 아니라 여러 번 재서 중앙값을 봤는가, 정말 GPU 에서 돌고 있는가(model.model.device), 다른 프로그램이 GPU 를 쓰고 있지 않은가, 파일을 읽는 시간이 섞이지 않았는가.
여기까지가 본론입니다. 박스 하나의 좌표에서 출발해, 직접 만든 부품들로 RF-DETR 을 조립하고, 마지막으로 진짜 RF-DETR 을 내 데이터에 맞춰 내보내 보았습니다. 마지막 15장(부록) 에는 학습이 잘 안 될 때 살펴볼 점검표, 이 튜토리얼에 나온 용어와 기호를 한데 모은 용어집, 그리고 여기서 더 나아가려는 분을 위한 읽을거리를 모아 두었습니다.