CHAPTER 14

실전: rfdetr 패키지

지금까지 13개 장에 걸쳐 RF-DETR 의 부품을 하나씩 직접 만들었습니다. 박스와 IoU, AP, 어텐션, DINOv2 백본, 헝가리안 매칭, 변형 어텐션, 윈도 어텐션, IA-BCE 손실, EMA, 가중치 공유 NAS 까지. 이 장에서는 손으로 만든 미니 모델을 내려놓고 진짜 RF-DETR, 곧 Roboflow 가 공개한 rfdetr 패키지를 씁니다. 사전 학습 모델로 추론하고, 내 데이터(도형 세상)로 미세 조정하고, 채점하고, 다른 실행 환경으로 내보내 지연 시간을 재 봅니다. 그리고 단계마다 “앞 장에서 만든 그 부품이 지금 여기서 돌고 있다” 는 것을 짚어 갑니다.

읽는 시간 약 80분난이도 ★★★☆☆코드: code/ch14_make_coco.py · ch14_finetune.py · ch14_export.py
이 장에서 배우는 것
이 장이 확인한 판(버전)

이 장의 모든 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 패키지입니다.

패키지를 쓰는 흐름은 다섯 단계입니다. 이 장의 차례도 이 순서를 따릅니다.

① 추론 RFDETRNano() .predict(그림) → Detections 7 · 8 · 10장 ② 데이터 준비 train/ valid/ test/ _annotations .coco.json 2장 ③ 미세 조정 .train( dataset_dir=…) → 체크포인트 6 · 9 · 11장 ④ 평가 .evaluate( split="test") → mAP 50:95 … 3장 ⑤ 내보내기 · 배포 .export() → ONNX onnxruntime 추론 → 지연 시간 재기 12장 상자 아래 숫자는 그 단계에서 돌고 있는 원리를 만들어 본 장
그림 14-1. 이 장의 다섯 단계. ① 은 받아 온 모델을 그대로 써 보는 것이고, ② – ⑤ 가 “내 데이터에 맞추고 내보내는” 본론입니다.

실습 파일은 세 개입니다. 차례로 실행합니다.

파일하는 일걸린 시간(이 튜토리얼의 노트북)
ch14_make_coco.py도형 세상을 COCO 형식 폴더로 내보내기CPU 약 15초
ch14_finetune.py사전 학습 모델 추론 → 미세 조정 2회 → 평가 → 추론 설정 바꿔 보기GPU 약 30분(학습 18.2분 + 8.5분, 그 밖의 단계 약 3분 반)
ch14_export.pyONNX 내보내기 → onnxruntime 추론 → 지연 시간 재기GPU + CPU 약 5분(그 가운데 3분은 추론 전용 스냅숏 두 개를 준비하는 시간)

설치와 모델 가족

설치

패키지는 Python 3.10 이상에서 pip 로 설치합니다. 기본 설치는 추론에 필요한 것만 들어 있고, 학습과 내보내기에 필요한 패키지는 “추가 묶음(extras)” 으로 나뉘어 있습니다. 이 장의 세 파일을 모두 돌리려면 train 과 onnx 묶음이 필요합니다.

$ pip install "rfdetr[train,onnx]"
설치 명령들어오는 것이 장에서 쓰는 곳
pip install rfdetrtorch · torchvision · transformers · supervision · pydantic 등. 추론(predict)만 가능사전 학습 모델로 추론
pip install "rfdetr[train]"pytorch_lightning · torchmetrics · pycocotools 를 비롯한 COCO 채점기들 · roboflow 등train(), evaluate()
pip install "rfdetr[onnx]"onnx · onnxruntimeexport() 와 ONNX 추론
pip install "rfdetr[plus]"rfdetr_plus(다른 라이선스의 모델들, 아래 참고)쓰지 않음

모델 가족과 라이선스

RF-DETR 은 모델 하나가 아니라 크기가 다른 모델들의 가족 입니다. 12장 에서 본 것처럼, 가중치 공유 NAS 로 찾은 파레토 곡선 위의 점들에 이름(Nano, Small, Medium …)을 붙인 것입니다. 패키지에서는 크기마다 클래스가 하나씩 있습니다.

과제클래스라이선스설치
객체 탐지RFDETRNano, RFDETRSmall, RFDETRMedium, RFDETRLargeApache 2.0rfdetr
객체 탐지Atto · Femto · Pico(아주 작은 것), XLarge · 2XLarge(아주 큰 것)PML 1.0rfdetr[plus]
인스턴스 분할RFDETRSegNano, …SegSmall, …SegMedium, …SegLarge, …SegXLarge, …Seg2XLargeApache 2.0rfdetr
키포인트 탐지(미리보기)RFDETRKeypointPreviewApache 2.0rfdetr

라이선스는 실무에서 가장 먼저 확인할 것입니다. 저장소 README(2026년 11월)에 따르면 이렇습니다.

라이선스는 직접 확인하세요

위 내용은 이 글을 쓴 시점의 README 를 옮긴 것이고 법률 조언이 아닙니다. 제품에 넣기 전에 그 시점의 저장소 LICENSE 와 README 의 License 절을 직접 읽으세요.

크기별 성능표

아래 표의 왼쪽 절반(해상도 – 질의 수)은 설치판의 설정 클래스(RFDETRNanoConfig 등)에서 읽은 값이고, 오른쪽 절반은 저장소 README 의 벤치마크 표에서 옮긴 값입니다. README 는 지연 시간을 “NVIDIA T4, TensorRT, FP16, 배치 1” 로, COCO AP 를 val2017 5,000장 전체로 쟀다고 밝힙니다.

크기해상도패치윈도(한 변)디코더 층질의매개변수(M)지연(ms)COCO AP50:95AP50
Nano384162230030.52.348.467.6
Small512162330032.13.553.072.1
Medium576162430033.74.454.773.6
Large704162430033.96.856.575.1
표의 지연 시간은 내 컴퓨터의 지연 시간이 아닙니다

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)뜻만들어 본 장
resolution384모델 입력 그림의 한 변(픽셀)12장
patch_size16패치 한 변. 384 ÷ 16 = 24 → 패치 토큰 24 × 24 = 576개6장
num_windows2윈도 어텐션에서 한 변을 나누는 수 → 윈도 2 × 2 = 4개, 윈도 하나에 12 × 12 = 144 토큰9장
dec_layers2디코더 층 수7장, 12장
num_queries300객체 질의 수 = 그림 한 장에서 나오는 박스 후보 수7장
num_select300후처리가 남기는 예측 수(아래 “후처리” 절)이 장
group_detr13학습 때만 쓰는 질의 묶음 수. 추론은 첫 묶음 300개만9장
num_classes90COCO 의 범주 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 로 끌 수 있음)
maskNone탐지 모델은 비어 있음. 분할 모델이면 객체별 마스크

len(detections) 는 객체 수 $n$ 이고, detections[detections.confidence > 0.7] 처럼 불 배열로 골라낼 수 있습니다.

이 튜토리얼은 2장부터 줄곧 박스를 정규화한 중심 표현 $(c_x, c_y, w, h)$ 로 써 왔습니다. xyxy 픽셀 좌표를 우리 형식으로 바꾸는 식은 2장의 변환에 “그림 크기로 나누기” 를 더한 것입니다. 원본 그림의 너비를 $W$, 높이를 $H$ 라 하면

$$ c_x = \frac{x_0 + x_1}{2W}, \qquad c_y = \frac{y_0 + y_1}{2H}, \qquad w = \frac{x_1 - x_0}{W}, \qquad h = \frac{y_1 - y_0}{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)가 비어 있기 때문입니다. 그래서

미세 조정한 모델은 훨씬 단순합니다. 클래스 번호가 0 부터 차례로 매겨지고 model.class_names[class_id] 가 곧 이름입니다. 이 차이는 “내 데이터 준비” 절에서 다시 봅니다.

입력 형태

predict 의 첫 인자는 여러 형태를 받습니다. 위 실행의 입력 형태 check 줄이 같은 그림을 네 가지로 넣어 박스가 같은지 본 것입니다.

형태조건
파일 경로 · URL 문자열URL 은 그 자리에서 내려받으므로 믿을 수 있는 주소만
PIL.ImageRGB 로 바뀌어 쓰임
numpy 배열(H, W, 3), RGB 순서. uint8(0 – 255)이면 그대로, 실수형이면 0 – 1 범위
torch.Tensor(3, H, W), 이미 0 – 1 로 나눈 실수. (B, 3, H, W) 를 주면 그림 B 장으로 나누어 처리
위의 것들의 목록한 배치로 처리하고 Detections 의 목록 을 돌려줌

전처리: 리사이즈와 정규화

그림이 모델에 들어가기 전에 거치는 손질을 전처리preprocessing 라고 합니다. predict 안에서 일어나는 일은 세 단계입니다.

  1. 0 – 1 로. uint8 픽셀값을 255 로 나누고, 모양을 (H, W, 3) 에서 (3, H, W) 로 바꿉니다.
  2. 리사이즈. 가로세로 비율을 무시하고 resolution × resolution(Nano 는 384 × 384)으로 쌍선형 보간합니다(8장 의 그 쌍선형 보간입니다). 우리 그림은 192 × 192 이므로 가로세로 두 배로 커집니다. 길쭉한 사진은 찌그러져 들어가지만, 출력 박스는 원본 크기로 되돌려 주므로 쓰는 사람은 신경 쓸 일이 없습니다.
  3. 정규화. 채널마다 평균을 빼고 표준편차로 나눕니다. 값은 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 가 같은 전처리를 직접 구현해 이 값을 찍어 봅니다(전처리 예 줄).


  
antialias 인자

predict(…, antialias=False) 가 기본입니다. 그림을 줄일 때 계단 현상을 막는 흐림 처리(안티에일리어싱)를 할지 정하는 인자로, 문서는 “학습 때의 리사이즈 방식과 맞추라” 고 합니다. 우리처럼 192 를 384 로 키우는 경우에는 결과에 차이가 없습니다. 모델 해상도보다 훨씬 큰 사진을 다룬다면 두 값을 다 돌려 검증 AP 가 좋은 쪽을 고르세요.

후처리: 질의 곱하기 클래스에서 상위 K 고르기

모델(신경망)이 내놓는 날출력은 두 텐서입니다. 질의 수를 $Q$(= 300), 분류 머리의 출력 칸 수를 $C$(COCO 모델은 91)라 하면

이것을 “점수 높은 박스 몇 개” 로 바꾸는 손질이 후처리postprocessing 입니다. 7장 의 DETR 은 질의마다 소프트맥스로 클래스 하나 를 골랐습니다. RF-DETR 은 다릅니다. 4장 · 9장 에서 본 것처럼 분류 손실이 시그모이드 기반(IA-BCE)이라, 칸 하나하나가 “이 질의가 이 클래스의 객체인가” 를 따로 답하는 독립된 점수 입니다. 그래서 후처리도 질의 단위가 아니라 (질의, 클래스) 쌍 단위로 합니다. 패키지의 PostProcess(rfdetr/models/postprocess.py)가 하는 일을 순서대로 적으면 이렇습니다.

날출력에서 탐지 결과까지 (그림 한 장 기준)
$$ s_{q,c} = \sigma(z_{q,c}) = \frac{1}{1 + e^{-z_{q,c}}} \qquad (q = 0, \dots, Q-1;\ \ c = 0, \dots, C-1) $$
① 로짓 $z_{q,c}$(질의 $q$ 의 클래스 $c$ 칸)마다 시그모이드 $\sigma$ 를 씌워 점수 $s_{q,c}$ 를 만듭니다. 소프트맥스가 아니므로 한 질의의 점수들을 더해도 1 이 아닙니다.
$$ i = q \cdot C + c \qquad (i = 0, \dots, QC - 1) $$
② $(Q, C)$ 표를 한 줄로 폅니다. 쌍 $(q, c)$ 가 편 번호 $i$ 가 됩니다. COCO 모델이면 $300 \times 91 = 27{,}300$ 개의 쌍입니다.
$$ \{i_1, \dots, i_K\} = \text{점수 } s_i \text{ 가 큰 순서로 } K \text{ 개}, \qquad K = \min(\texttt{num\_select},\ QC) $$
③ 쌍 전체에서 점수 상위 $K$ 개를 고릅니다. 기본 $K = 300$. 점수가 같으면 편 번호가 작은 쪽이 먼저입니다(안정 정렬).
$$ q_k = \lfloor i_k / C \rfloor, \qquad c_k = i_k \bmod C $$
④ 편 번호를 다시 질의 번호(몫)와 클래스 번호(나머지)로 풉니다. $\lfloor \cdot \rfloor$ 는 내림입니다.
$$ (x_0, y_0, x_1, y_1)_k = \Big( (c_x - \tfrac{w}{2})\,W,\ \ (c_y - \tfrac{h}{2})\,H,\ \ (c_x + \tfrac{w}{2})\,W,\ \ (c_y + \tfrac{h}{2})\,H \Big) $$
⑤ 질의 $q_k$ 의 박스 $(c_x, c_y, w, h)$ 를 모서리 표현으로 바꾸고(2장) 원본 그림 의 너비 $W$ · 높이 $H$ 를 곱합니다. 그림 밖으로 나간 좌표는 $[0, W]$, $[0, H]$ 로 자릅니다.
$$ \text{결과} = \{\, (\text{박스}_k,\ s_{i_k},\ c_k) \ :\ s_{i_k} \gt \tau \,\} $$
⑥ 마지막으로 점수가 문턱값 $\tau$(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.00.88080.2689
1(0.25, 0.75, 0.5, 0.5)0.01.00.50000.7311
2(0.8, 0.2, 0.1, 0.1)−3.0−2.00.04740.1192
  1. 시그모이드: $\sigma(2) = 1/(1 + e^{-2}) = 1/1.1353 = 0.8808$, $\sigma(1) = 1/1.3679 = 0.7311$, $\sigma(0) = 0.5$ 등.
  2. 편 번호: 점수를 한 줄로 펴면 $[0.8808,\ 0.2689,\ 0.5000,\ 0.7311,\ 0.0474,\ 0.1192]$ (편 번호 0 – 5).
  3. 상위 3개: 편 번호 0(0.8808), 3(0.7311), 2(0.5000).
  4. 풀기: $0 \to (q, c) = (0, 0)$, $\ 3 \to (\lfloor 3/2 \rfloor,\ 3 \bmod 2) = (1, 1)$, $\ 2 \to (1, 0)$. 질의 1 이 두 번 뽑혔습니다. 한 번은 클래스 1 로, 한 번은 클래스 0 으로. 같은 박스가 서로 다른 이름표를 달고 두 번 나올 수 있다는 뜻입니다.
  5. 박스: 질의 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)$.
  6. 문턱값 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]
상위 K 개는 “질의 K 개” 가 아닙니다

num_select = 300 이라고 해서 질의 300개가 하나씩 나오는 것이 아닙니다. 27,300 개의 (질의, 클래스) 쌍 가운데 점수가 높은 300 쌍입니다. 자신 있는 질의는 여러 클래스로 여러 번 뽑힐 수 있고, 자신 없는 질의는 한 번도 안 뽑힐 수 있습니다. 다만 잘 학습된 모델에서는 둘째 클래스의 점수가 보통 문턱값보다 한참 낮아서, threshold=0.5 를 넘는 결과에서 같은 박스가 두 번 보이는 일은 드뭅니다.

COCO 모델은 도형을 모른다

이제 위 실행 출력의 아래쪽을 읽어 봅시다. COCO 로 학습된 Nano 에게 도형 세상의 시험 그림 50장을 보여 준 결과입니다.

미세 조정 전의 COCO 모델이 도형 세상 그림 여섯 장에 그린 박스: 대부분 그림 전체를 덮는 박스에 냉장고, TV 같은 이름이 붙는다
그림 14-2. 미세 조정하지 않은 COCO 모델의 예측. 분홍 점선은 점수가 0.1 을 넘는 박스 전부이고, 그림마다 제목에 박스 수와 점수가 가장 높은 예측의 이름 · 점수를 적었습니다.

그렇다고 이 모델이 쓸모없는 것은 아닙니다. 이름표(분류 머리)만 우리 것이 아닐 뿐, 그 아래의 백본 · 프로젝터 · 디코더는 “그림에서 물체를 찾아 박스를 두르는 법” 을 이미 알고 있습니다. 미세 조정 은 그 지식을 그대로 둔 채 이름표를 우리 클래스로 갈아 끼우고 조금 더 학습하는 일입니다. 그러려면 먼저 우리 데이터를 패키지가 읽을 수 있는 모양으로 만들어야 합니다.

추론 전용 스냅숏

위 출력에는 생략했지만, 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") 입니다. 얼마나 빨라지는지는 지연 시간 절에서 잽니다.

optimize_for_inference() 는 없어졌습니다

예전 글과 예제에는 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장의 두 가지 표현(모서리 표현 · 중심 표현) 가운데 어느 것과도 다릅니다.

이 절에서만: 같은 글자 w, h 의 두 가지 단위

우리 형식의 너비 · 높이와 COCO 의 너비 · 높이가 둘 다 흔히 $w$, $h$ 로 쓰여 헷갈립니다. 이 절에서는 정규화한 우리 형식 을 $(c_x, c_y, w, h)$, COCO 의 픽셀 값 을 $[x^{\text{px}}, y^{\text{px}}, w^{\text{px}}, h^{\text{px}}]$ 로 구별해 씁니다. 그림의 너비 · 높이(픽셀)는 대문자 $W$, $H$ 입니다.

정규화 (cx, cy, w, h) 에서 COCO [x, y, w, h] 로
$$ x_0 = c_x - \frac{w}{2}, \qquad y_0 = c_y - \frac{h}{2} $$
2장: 왼쪽 위 모서리는 중심에서 너비 · 높이의 절반만큼 왼쪽 · 위로 간 점입니다(아직 0 – 1 단위).
$$ x^{\text{px}} = x_0 \cdot W = \Big(c_x - \frac{w}{2}\Big) W, \qquad y^{\text{px}} = y_0 \cdot H = \Big(c_y - \frac{h}{2}\Big) H $$
정규화 좌표는 “그림 크기에 대한 비율” 이므로, 가로 방향 값에는 그림 너비 $W$ 를, 세로 방향 값에는 높이 $H$ 를 곱하면 픽셀이 됩니다.
$$ [x^{\text{px}},\ y^{\text{px}},\ w^{\text{px}},\ h^{\text{px}}] = \Big[ \Big(c_x - \frac{w}{2}\Big) W,\ \ \Big(c_y - \frac{h}{2}\Big) H,\ \ wW,\ \ hH \Big] $$
너비 · 높이도 같은 이유로 $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 박스로 바꾸면

같은 박스가 96 × 96 그림에서는 [36, 12, 24, 48] 입니다. 정규화 좌표는 그림 크기가 바뀌어도 그대로지만 COCO 좌표는 그림 크기에 따라 달라집니다. 그래서 그림을 리사이즈해 저장할 때는 주석도 같이 고쳐야 합니다.



  
192×192 도형 그림 위에 COCO bbox 세 개를 그린 그림: 분홍 점이 왼쪽 위 모서리 (x, y) 이고 초록 사각형이 박스
그림 14-3. 학습 세트의 한 그림과 그 주석 세 개. 분홍 점이 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

클래스 번호는 다시 매겨진다

우리 클래스는 0, 1, 2 인데 category_id 는 일부러 COCO 의 관례대로 1, 2, 3 으로 적었습니다. 그래도 됩니다. 패키지는 (기본값 dataset_file="roboflow" 일 때) 학습 세트의 categories 를 id 순으로 늘어놓고 0 부터 다시 번호를 매깁니다.

JSON 의 category_id이름모델의 class_id(학습 · 예측)
1circle0
2rectangle1
3triangle2

미세 조정을 마친 모델에서 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 로 나누어떨어져야 합니다.

왜 patch_size × num_windows 의 배수여야 하나
$$ N = \frac{S}{P} \quad \text{가 정수} $$
그림 한 변 $S$ 픽셀을 한 변 $P$ 픽셀의 패치로 빈틈없이 자르려면(6장) $S$ 가 $P$ 의 배수여야 합니다. $N$ 은 한 변의 패치 수입니다.
$$ \frac{N}{M} \quad \text{가 정수} $$
윈도 어텐션은 $N \times N$ 패치 격자를 한 변 $M$ 등분해 $M \times M$ 개의 윈도로 나눕니다(9장). 윈도마다 패치 수가 같으려면 $N$ 이 $M$ 의 배수여야 합니다.
$$ S = P \cdot M \cdot n \qquad (n = 1, 2, 3, \dots) $$
두 조건을 합치면 $S$ 는 $P \cdot M$ 의 배수입니다. $n$ 은 윈도 한 변의 패치 수입니다.

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"체크포인트 · 기록을 쓸 폴더
epochs100학습 세트를 몇 바퀴 돌 것인가4장
batch_size4한 번에 GPU 에 올리는 그림 수. "auto" 를 주면 GPU 메모리를 재어 스스로 정함(CUDA 에서만)
grad_accum_steps1기울기를 몇 번 모아 한 번 갱신할 것인가11장
lr1e-4학습률(프로젝터 · 머리 등). 디코더는 여기에 lr_component_decay 를 곱함11장
lr_encoder1.5e-4백본(DINOv2)의 기준 학습률. 여기에 층별 감쇠가 곱해짐11장
lr_vit_layer_decay0.8층별 학습률 감쇠율11장
lr_component_decay0.7부품(디코더 · 백본)별 학습률 감쇠율이 장
weight_decay1e-4가중치 감쇠(AdamW)4장
warmup_epochs0.0학습률 워밍업 길이. 0 = 워밍업 없음11장
clip_max_norm0.1기울기 자르기의 최대 노름11장
use_ema, ema_decay, ema_tauTrue, 0.993, 100가중치의 지수 이동 평균(EMA)11장
multi_scale, expanded_scales"per-batch", True배치마다 해상도를 바꾸는 다중 스케일 학습11장
drop_path0.0드롭 패스 확률11장
early_stoppingFalse검증 AP 가 오르지 않으면 일찍 멈춤(early_stopping_patience=10, early_stopping_min_delta=0.001)이 장
checkpoint_interval10몇 에폭마다 checkpoint_<에폭>.ckpt 를 남길 것인가
resumeNone이어서 학습할 체크포인트(last.ckpt) 경로이 장
resolution(모델 기본값)학습 해상도 바꾸기. patch_size × num_windows 의 배수12장
num_workers2데이터 로더 일꾼(프로세스) 수
seedNone난수 시드
tensorboard / wandb / mlflowTrue / False / False기록 도구
run_testFalse학습이 끝나면 시험 세트도 채점할 것인가

손실의 가중치(분류 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}}$ 장이면 한 에폭의 순전파 횟수와 가중치 갱신 횟수는

$$ \text{순전파 횟수} = \frac{N_{\text{train}}}{B}, \qquad \text{갱신 횟수} = \frac{N_{\text{train}}}{B \times A} = \frac{N_{\text{train}}}{B_{\text{eff}}} $$

이번 실험에 넣어 봅니다. $N_{\text{train}} = 1000$, $B = 2$, $A = 4$ 이므로

메모리는 $B$ 만 따라갑니다. batch_size=2 일 때 이번 학습이 쓴 GPU 메모리는 최대 1.61 GiB 였습니다. 같은 실효 배치 8 을 batch_size=8, grad_accum_steps=1 로 만들면 갱신 한 번의 내용은 (거의) 같지만 메모리는 몇 배가 듭니다.

배치를 어떻게 정할까

부품마다 다른 학습률

“학습률 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}$
손으로 계산: 백본 맨 위 블록과 맨 아래 임베딩의 학습률
$$ \eta_{\text{enc}} \cdot \rho^2 = 1.5 \times 10^{-4} \times 0.7^2 = 1.5 \times 10^{-4} \times 0.49 = 7.35 \times 10^{-5} $$
백본 전체에 공통으로 곱해지는 부분입니다. 부품 감쇠 0.7 이 디코더에는 한 번, 백본에는 두 번 곱해집니다(출력에서 멀수록 작게).
$$ \text{블록 } 11:\quad 7.35 \times 10^{-5} \times 0.8^{\,13 - 11} = 7.35 \times 10^{-5} \times 0.64 = 4.70 \times 10^{-5} $$
마지막 블록($j = 11$)은 감쇠가 두 번만 곱해집니다.
$$ \text{블록 } 0:\quad 7.35 \times 10^{-5} \times 0.8^{13} = 7.35 \times 10^{-5} \times 0.05498 = 4.04 \times 10^{-6} $$
첫 블록은 13번. $0.8^{13} = 0.05498$ 입니다($0.8^2 = 0.64$, $0.8^4 = 0.4096$, $0.8^8 = 0.16777$, $0.8^{13} = 0.8^8 \cdot 0.8^4 \cdot 0.8 = 0.05498$).
$$ \text{임베딩}:\quad 7.35 \times 10^{-5} \times 0.8^{14} = 7.35 \times 10^{-5} \times 0.04398 = 3.23 \times 10^{-6} $$
패치 임베딩 · 위치 임베딩은 한 번 더 곱해져 가장 작습니다. 머리(1e-4)의 약 1/31 입니다.

이 손계산은 실제 학습 기록과 맞습니다. 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) 입니다(뒤의 실행 출력).

학습 로그의 손실 이름

에폭이 끝날 때마다 출력 폴더의 metrics.csv 에 학습 손실과 검증 지표가 한 줄씩 쌓입니다. 열 이름을 읽을 줄 알면 지금 모델의 어느 부분이 어떻게 배우고 있는지 보입니다. 기본 설정(compact_train_metrics=True)에서는 보조 손실이 loss_ce_aux 처럼 하나로 합쳐져 기록되므로, 이 실습은 그것을 끄고 층별로 받았습니다.

열 이름(train/ 뒤)무엇인가가중치앞 장
loss_ce분류 손실. 이름은 ce(cross-entropy)지만 실제로는 IA-BCE(ia_bce_loss=True). 마지막 디코더 층의 출력에 대한 것19장, 11장
loss_bbox매칭된 예측 박스와 정답 박스의 L1 거리(정규화 좌표)52장, 7장
loss_giou$1 - \GIoU$22장, 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_enc2단계 질의 선택에서 인코더(프로젝터) 출력이 낸 제안 에 건 손실. 디코더를 거치기 전의 예측입니다같음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.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

사전 학습의 힘

이렇게 쉽게 되는 것이 모델 구조 덕분일까요, 사전 학습 덕분일까요? 가려내는 방법은 하나입니다. 똑같은 설정으로, 사전 학습 가중치만 빼고 학습해 보는 것입니다. 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 곡선. 오른쪽: 사전 학습 시작의 손실 항목별 곡선
그림 14-4. 왼쪽: 에폭별 검증 AP@[.50:.95]. 파랑은 사전 학습 가중치에서 시작, 주황은 무작위 초기화. 실선은 EMA 가중치, 점선은 일반 가중치. 오른쪽: 사전 학습 시작 실행의 손실 항목(가중치를 곱하기 전, 세로축 로그 눈금).

두 실행을 같은 에폭끼리 나란히 놓으면 이렇습니다(검증 AP@[.50:.95], EMA 가중치).

에폭(갱신 횟수)(a) 사전 학습에서 시작(b) 무작위 초기화에서 시작(b) 의 AP50
1 (125)0.94760.32440.5972
2 (250)0.97920.63420.8311
3 (375)0.98160.77490.8902
5 (625)0.9839(돌리지 않음)
시험 그림 여섯 장에 대한 두 모델의 예측: 위는 사전 학습 시작, 아래는 무작위 초기화
그림 14-5. 시험 그림 여섯 장(그림 14-2 와 같은 그림). 흰 점선이 정답, 초록 실선이 점수 0.5 를 넘는 예측. 위: 사전 학습 가중치에서 시작한 모델, 아래: 무작위 초기화에서 시작한 모델.

출력 폴더와 체크포인트

학습이 끝나면 output_dir 에 파일이 여럿 남습니다. 학습 도중이나 끝의 가중치를 저장한 파일을 체크포인트checkpoint 라고 합니다. 위 출력의 출력 폴더 줄에 나온 파일들을 열어 보고 정리한 것이 아래 표입니다.

파일크기들어 있는 것쓰임
checkpoint_best_total.pth121 MB검증 AP 가 가장 좋았던 가중치. 일반과 EMA 가운데 더 나은 쪽(이번에는 EMA) + 모델 설정 · 클래스 이름추론 · 내보내기용. 보통 이것만 있으면 됩니다
checkpoint_best_ema.pth121 MBEMA 가중치의 검증 AP 가 가장 좋았던 에폭의 EMA 가중치위 파일의 재료
checkpoint_best_regular.pth242 MB일반 가중치의 검증 AP 가 가장 좋았던 에폭의 일반 가중치(EMA 사본도 함께 들어 있어 큼)위 파일의 재료. eval_base_model=True 일 때만 생김
last.ckpt483 MB마지막 에폭의 일반 가중치(121) + EMA 가중치(121) + 옵티마이저 상태(241)학습 재개용
last_ema.pth121 MB마지막 에폭의 EMA 가중치
metrics.csv에폭별 손실 · 검증 지표학습 곡선 그리기
training_config.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)

평가

패키지의 evaluate

검증 세트의 AP 는 가장 좋은 체크포인트를 고르는 데 이미 썼으므로, 최종 성적은 한 번도 보지 않은 시험 세트 로 매깁니다(3장). 패키지에서는 model.evaluate(dataset_dir=…, split="test") 한 줄이고, 지표의 사전을 돌려줍니다.

돌려주는 키뜻3장의 이름
test/mAP_50_95IoU 문턱값 0.50, 0.55, …, 0.95 의 AP 를 평균하고 클래스에 대해 평균한 값. COCO 의 대표 지표AP(= AP@[.50:.95], mAP)
test/mAP_50IoU 문턱값 0.5 하나만 쓴 APAP50
test/mAP_75IoU 문턱값 0.75 하나만 쓴 APAP75
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:95AP50AP75
(a) 사전 학습에서 시작패키지 evaluate()0.98281.00000.9900
우리 evaluate_ap0.98301.00000.9900
(b) 무작위 초기화패키지 evaluate()0.77220.88270.8582
우리 evaluate_ap0.77380.88340.8569

추론 설정 바꿔 보기

학습이 끝난 모델도 쓰는 방법 에 따라 결과가 달라집니다. 가중치는 그대로 두고 추론 설정 세 가지를 바꿔 봅니다. 모두 미세 조정한 모델 (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).
왼쪽: 점수 문턱값에 따른 정밀도와 재현율. 오른쪽: 추론 해상도에 따른 AP, AP50, AP75
그림 14-6. 왼쪽: 점수 문턱값을 올릴 때의 정밀도(파랑 실선)와 재현율(주황 점선), IoU 0.5 기준. 오른쪽: predict(shape=(S, S)) 로 추론 해상도만 바꿨을 때의 시험 AP. 회색 세로선이 학습 해상도 384.

점수 문턱값

predict(threshold=…) 는 점수가 그 값보다 큰 예측만 남깁니다. 문턱값을 올리면 틀린 예측이 줄고(정밀도 ↑) 놓치는 객체가 늘어납니다(재현율 ↓). 3장 의 그 맞바꿈입니다.

실제 데이터에서는 이렇게 넓고 평평한 구간이 나오지 않습니다. 검증 세트에서 이런 표를 만들어 “거짓 경보가 더 나쁜가, 놓치는 것이 더 나쁜가” 에 따라 문턱값을 정하세요. 문턱값은 AP 에는 영향을 주지 않습니다(AP 는 모든 문턱값을 훑어 계산한 값입니다). 설명문에 따르면 threshold 에 ClassThresholds 를 주어 클래스마다 다른 문턱값을 쓸 수도 있습니다(돌려 보지는 않았습니다).

남기는 예측 수 num_select

후처리가 남기는 (질의, 클래스) 쌍의 수입니다. 만든 뒤에도 model.model.postprocess.num_select = K 로 바꿀 수 있습니다.

num_select 를 줄여도 신경망의 계산량은 줄지 않습니다(질의 300개는 그대로 디코더를 지납니다). 줄어드는 것은 후처리와 결과의 크기뿐입니다. 계산량까지 줄이는 것은 12장 의 “질의 수” 손잡이인데, 그것은 모델 구조를 바꾸는 일이라 이 장에서는 다루지 않았습니다.

추론 해상도

predict(shape=(H, W)) 는 이번 호출에서만 입력 해상도를 바꿉니다. 가중치도 모델 설정도 그대로입니다.

해상도를 바꿀 수 없는 경우

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}
출력은 모양이 아니라 이름으로 구별하세요

우리 모델의 두 출력은 모양이 똑같이 [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 두 줄을 차례로 읽습니다.

내보낸 모델을 검증할 때

날출력 텐서를 통째로 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개 가운데)

지연 시간 재기

12장 에서 지연 시간은 NAS 의 한 축이었습니다. 그런데 지연 시간은 AP 와 달리 재는 방법에 따라 값이 몇 배씩 달라지는 숫자입니다. RF-DETR 논문(4절, 부록 K)이 측정 방법을 따로 공들여 적은 까닭입니다. 먼저 무엇을 재는지부터 정해야 합니다.

그리고 재는 요령이 있습니다. 아래 measure 함수가 그것을 담고 있습니다.


  
  1. 예열 실행을 버린다. 처음 몇 번은 메모리 할당, 연산 구현 고르기, 캐시 채우기 같은 준비 때문에 훨씬 느립니다. 이 값을 평균에 넣으면 안 됩니다. 이 실습은 구성을 바꿀 때마다 몇 번을 헛돌린 뒤 잽니다.
  2. GPU 를 기다린다. PyTorch 의 GPU 연산은 “일을 맡기고 바로 돌아오는” 방식입니다. torch.cuda.synchronize() 로 일이 끝나기를 기다리지 않고 시계를 보면, 맡기는 데 걸린 시간만 재게 되어 터무니없이 빠른 값이 나옵니다.
  3. 여러 번 재서 분포를 본다. 한 번의 값은 그 순간 다른 프로그램이 무엇을 했는지에 흔들립니다. 구성마다 200번(CPU 구성은 40번)을 재서 중앙값 을 대푯값으로 쓰고, 10% · 90% 분위수로 퍼진 정도를 함께 적습니다(평균은 가끔 튀는 큰 값에 끌려갑니다).
  4. 배치 1. 실시간 탐지의 지연 시간은 그림 한 장이 들어와 결과가 나올 때까지의 시간이므로 배치 크기 1 로 잽니다.
  5. 견줄 구성들은 번갈아 잰다. 기계를 다른 작업과 나눠 쓰면 부하가 시시각각 변합니다. 구성 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
구성별 지연 시간 분포의 상자 그림: GPU 구성은 수 – 수십 ms, CPU 구성은 그보다 훨씬 오른쪽에 있고 상자가 넓게 퍼져 있다
그림 14-7. 같은 모델 · 같은 그림 한 장을 구성만 바꿔 잰 지연 시간(가로축은 로그 눈금). 상자는 25 – 75%, 수염은 10 – 90%, 상자 안의 선이 전체 중앙값이고, 검은 마름모는 기계가 가장 한가했던 라운드의 중앙값입니다. 파랑은 GPU, 주황은 CPU.

출력의 위쪽 표는 라운드마다의 중앙값입니다. 행(구성)마다 열 방향으로 값이 고르면 재는 동안 기계의 사정이 크게 변하지 않았다는 뜻이고, 이번 실행이 그랬습니다. 아래쪽 표를 정리하면 이렇습니다.

구성잰 범위중앙값(ms)10% – 90%
PyTorch GPU, FP32순전파만16.914.9 – 17.6
PyTorch GPU, FP16 자동 혼합 정밀도순전파만13.811.3 – 17.0
PyTorch GPU, FP32, 사이에 200 ms 쉬기순전파만19.717.1 – 21.9
model.predict(), GPU FP32처음부터 끝까지20.417.5 – 24.3
model.inference() 스냅숏, GPU FP32처음부터 끝까지14.612.3 – 17.8
model.inference(dtype="float16") 스냅숏, GPU FP16처음부터 끝까지10.17.8 – 12.9
onnxruntime CPU, FP32, 8 스레드순전파만112.3111.7 – 115.6
PyTorch CPU, FP32, 8 스레드순전파만148.0146.5 – 160.5
PyTorch CPU, FP32, 16 스레드(기본값)순전파만3,0772,935 – 3,173
이 숫자들을 논문 · README 의 2.3 ms 와 견주면 안 됩니다

논문 표 2 와 README 의 “Nano 2.3 ms” 는 NVIDIA T4 + TensorRT + FP16, 순전파만, 배치 1 의 값입니다. 위 표와는 다음이 모두 다릅니다.

지연 시간은 같은 기계에서 같은 방법으로 잰 것끼리만 비교할 수 있습니다. 내 서비스에 필요한 숫자는 내 하드웨어에서, 실제로 쓸 실행기와 정밀도로, 처음부터 끝까지 재야 합니다.

그 밖의 내보내기 형식

export(format=…) 은 ONNX 말고도 여러 형식을 받습니다. 아래 표는 설치판의 export() 설명문(docstring)과 패키지의 추가 묶음 목록, 공식 문서를 정리한 것입니다. 이 튜토리얼에서 직접 돌려 본 것은 ONNX 뿐 이고, 나머지는 문서 기준입니다.

format산출물추가 설치어디에 쓰나(문서 기준)
"onnx"(기본).onnxrfdetr[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".tfliterfdetr[litert]위와 같은 파일 형식을 ONNX · TensorFlow 없이 PyTorch 에서 바로
"executorch"("pte").pterfdetr[executorch]기기 위의 PyTorch 실행기. backend= 로 대상(xnnpack · coreml · qnn)을 정해야 한다
"coreml".mlpackagerfdetr[coreml]Apple 기기(Xcode)
"coreai".aimodelrfdetr[coreai]Apple Core AI(문서: iOS · iPadOS · macOS 27 이상)

분할과 키포인트 모델

13장 에서 만든 분할 머리를 단 모델 RF-DETR-Seg, 그리고 사람의 관절 같은 점들을 찾는 키포인트 모델(미리보기)도 같은 패키지에 있습니다. 이 절은 공식 문서와 설치판의 소스를 읽고 정리한 것이며 직접 돌려 보지는 않았습니다.

탐지인스턴스 분할키포인트(미리보기)
클래스RFDETRNano … RFDETRLargeRFDETRSegNano … RFDETRSeg2XLargeRFDETRKeypointPreview
쓰는 법같습니다: predict(), train(dataset_dir=…), evaluate(), export()
predict 가 돌려주는 것sv.Detectionssv.Detections + mask: 객체마다의 불 마스크 (n, H, W)(원본 그림 크기)sv.KeyPoints: xy 가 (n, K, 2), 박스는 data["xyxy"]
데이터셋 주석bboxbbox + segmentation(다각형 꼭짓점 목록). YOLO 형식이면 다각형 좌표bbox + keypoints(점마다 x, y, 보임 여부)
설정(설치판)Nano: 384 / 패치 16 / 질의 300SegNano: 312 / 패치 12 / 윈도 1 / 디코더 4층 / 질의 100576 / 패치 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장 에서 직접 만들어 보았습니다.

실전 요령과 흔한 문제

이 장의 실험과 설치판의 소스 · 문서에서 확인한 것만 모았습니다.

메모리가 모자랄 때 (CUDA out of memory)
작은 객체가 안 잡힐 때

해상도를 올리는 것이 첫 번째 처방입니다. Nano 의 384 에서 패치 하나는 16 × 16 픽셀이므로, 원본에서 그보다 한참 작은 객체는 패치 하나의 일부에 지나지 않습니다. model.train(resolution=512, …) 처럼 patch_size × num_windows 의 배수로 올리거나, 처음부터 해상도가 높은 크기(Small 512, Medium 576, Large 704)를 고릅니다. 12장 에서 본 것처럼 정확도는 해상도와 패치 크기 각각보다 “한 변의 패치 수” 와 더 관계가 깊었습니다.

자주 걸리는 곳
어디서부터 시작할까
  1. 사전 학습 모델로 내 그림 몇 장을 predict 해 본다(이미 되는 일이라면 학습이 필요 없다).
  2. 데이터를 COCO 형식으로 만들고, 저장한 주석을 다시 읽어 그림 위에 그려 본다(그림 14-3 처럼). 주석이 틀리면 뒤의 모든 것이 헛일이다.
  3. 가장 작은 모델(Nano)로, 기본 설정으로, 몇 에폭만 돌려 검증 AP 가 오르는지 본다.
  4. 시험 세트로 채점하고 예측을 눈으로 본다. 모자라면 그때 해상도 · 모델 크기 · 에폭 수를 올린다.
  5. 내보내고, 원래 모델과 출력을 비교하고, 실제 쓸 기계에서 지연 시간을 잰다.
이 장의 정리

확인 문제

문제 1

너비 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

학습 그림이 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 번 그대로입니다. 메모리는 줄고 시간은 줄지 않습니다.

문제 3

(가) 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$ 배인데 토큰은 그 제곱만큼 늡니다.

문제 4

클래스 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 으로 올리면 하나만 남습니다.

문제 5

기본 설정(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 가 그것을 막아 줍니다.

문제 6

동료가 “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장(부록) 에는 학습이 잘 안 될 때 살펴볼 점검표, 이 튜토리얼에 나온 용어와 기호를 한데 모은 용어집, 그리고 여기서 더 나아가려는 분을 위한 읽을거리를 모아 두었습니다.