RF-DETR:Tutorial
lastmod 2026-11-18created 2026-11-181 edits
RF-DETR 튜토리얼은 실시간 객체 탐지기 RF-DETR 을 머신러닝 초급자가 처음부터 끝까지 혼자 따라갈 수 있게 쓴 16개 장(00 – 15)짜리 글이다. "박스를 숫자로 어떻게 적지?" 라는 질문에서 시작해 채점 · 손실 · 어텐션 · DETR 계보를 하나씩 쌓고, 마지막에는 RF-DETR 의 구조 · 학습 · 구조 탐색 · 분할을 작은 크기로 PyTorch 로 직접 만들어 돌려 본 뒤 공개된 진짜 모델을 내 데이터에 맞춘다. 이 문서는 튜토리얼의 지도이고, 장마다 내용을 정리한 문서가 따로 있다.
- 원문: 00. 시작하기 - RF-DETR 튜토리얼 (pages.unwiki.net)
- 무대: 2장부터 13장까지의 실습은 모두 도형 세상(Shape World) 이라는 작은 탐지 데이터 하나에서 한다(96×96 그림에 원 · 사각형 · 삼각형 1 – 4개). 14장은 같은 장면을 192 픽셀로 그려 진짜 RF-DETR 을 미세 조정한다.
- 수식은 한 줄씩 풀고, 손계산과 같은 값을 코드로도 계산해 맞춰 본다. 본문의 출력 · 그래프 · 그림은 실제로 돌린 코드가 만든 결과 그대로다.
이 튜토리얼이 약속하는 것
RF-DETR 을 소개하는 글은 대개 "DINOv2 백본에 LW-DETR 디코더를 얹고 NAS 를 했다" 는 한 줄에서 시작한다. 초급자에게는 그 한 줄의 낱말 하나하나가 벽이다. 이 튜토리얼은 그 벽을 밑에서부터 쌓아 올라가며 넘으며, 약속은 네 가지다.
- 건너뛰지 않는다. 수식이 나오면 한 줄씩 풀고 각 줄 옆에 "왜 이렇게 되는지" 를 적는다. 식마다 숫자를 넣은 손계산을 곁들이고, 같은 값을 코드로도 계산해 맞춰 본다.
- 직접 만들어 본다. IoU, AP, 어텐션, 헝가리안 매칭, 변형 어텐션, 윈도 어텐션, 손실, NAS, 분할 머리를 모두 PyTorch 로 구현한다.
- 같은 세상에서 끝까지 간다. 데이터가 같으니 모델이 바뀌는 것에만 집중할 수 있고, 장마다의 결과를 서로 견줄 수 있다.
- 나온 대로 적는다. 작은 실험에서는 논문의 기법이 기대만큼 듣지 않을 때도 있다. 그런 결과도 고르거나 다듬지 않고 적고 왜 그럴 수 있는지를 따진다. 이 튜토리얼의 미니 실험에서 본 것과 논문이 COCO 에서 보고한 것을 늘 나눠 적는다.
- 그림: 그림 0-1. 도형 세상의 그림 여덟 장(
ShapesDataset(8, seed=0)) - 어두운 배경 위에 여러 색의 원 · 사각형 · 삼각형이 한 장에 두 개에서 네 개씩 놓여 있고, 도형마다 초록색 정답 박스와 클래스 이름이 붙어 있다. 탐지기가 할 일은 그림만 보고 이 초록 박스와 이름을 맞히는 것이다. 도형끼리 조금 겹치기도 하고 박스가 서로 걸치기도 한다.
- 누구를 위한 글인가
- 객체 탐지를 처음 배우는데 YOLO 사용법이 아니라 원리를 알고 싶은 사람, DETR 계열 논문을 펼쳤다가 "헝가리안 매칭", "변형 어텐션" 에서 멈춘 사람, RF-DETR 을 내 데이터에 써야 하는데 설정값 하나하나가 무슨 뜻인지 알고 쓰고 싶은 사람.
- 끝까지 읽으면 얻는 것
- 탐지 논문의 표(AP, AP50, 지연 시간)를 정의부터 읽는 눈. DETR → Deformable DETR → LW-DETR → RF-DETR 로 무엇이 왜 바뀌었는지에 대한 설명. RF-DETR 의 순전파와 손실을 텐서 모양까지 따라갈 수 있는 이해와 직접 짠 미니 구현.
rfdetr패키지로 추론 · 미세 조정 · 내보내기를 하고 그 안에서 무슨 일이 벌어지는지 아는 것.
RF-DETR 을 한 문장으로
- 핵심
- RF-DETR 은 그림을 받아 "어디에 무엇이 있는지" 를 박스 · 클래스 · 점수의 묶음으로 내놓는 실시간 객체 탐지기다. DINOv2 로 사전 학습한 ViT 백본 위에 LW-DETR 계열의 가벼운 디코더를 얹었고, 가중치 공유 NAS 로 한 번의 학습에서 빠른 모델부터 정확한 모델까지 여럿을 꺼낸다.
탐지기가 하는 일을 식으로 쓰면 다음과 같다. 그림 한 장이 들어가고 예측 \(N\) 개가 나온다.
\(\text{그림} \;\xrightarrow{\ \text{탐지기}\ }\; \{(b_i,\ c_i,\ s_i)\}_{i=1}^{N}\)
\(b_i\) 는 \(i\) 번째 예측의 박스(숫자 네 개), \(c_i\) 는 클래스(도형 세상에서는 원 · 사각형 · 삼각형 가운데 하나), \(s_i\) 는 점수(0 과 1 사이, 클수록 확신이 크다)다. 중괄호는 이 묶음이 집합, 곧 순서가 없는 모음이라는 뜻이다. 이 식을 이루는 것들을 하나씩 채워 가는 것이 튜토리얼의 줄거리다.
- 박스를 숫자로 적고 두 박스가 얼마나 겹치는지 재는 법 (2장)
- 예측 묶음이 얼마나 좋은지 숫자 하나로 채점하는 법 (3장)
- 화살표, 곧 탐지기 안의 신경망 · 어텐션 · 백본 (4 – 6장)
- "집합을 내놓도록" 학습시키는 법과 그 개량들 (7 – 9장)
- 그 모두를 조립한 RF-DETR (10 – 13장)
목차
00장을 빼면 전체는 네 단계로 나뉘고, 앞 단계가 뒤 단계의 재료가 된다(원문 그림 0-2). 3단계에서 도형 세상용 "미니 RF-DETR" 이 완성되고, 4단계에서 Roboflow 가 공개한 진짜 RF-DETR 을 만난다. 처음이라면 순서대로 읽기를 권한다.
장마다 "배우는 것" 과 "도형 세상에서 해 보는 것" 을 함께 적었다. 괄호 안의 AP 는 그 장의 본 실행이 낸 값을 0 – 1 눈금으로 적은 것이다(읽는 법은 3장).
1단계: 기초 체력 (01 – 06장)
재고, 채점하고, 보는 법. 끝나면 RF-DETR 이 왜 나왔는지 설명하고, IoU · GIoU · AP 를 손으로 계산하고, 포컬 손실의 기울기를 유도하고, 어텐션 한 번을 손으로 계산하고, ViT 의 토큰 수와 매개변수 수를 셀 수 있다.
- 01. RF-DETR 이란 무엇인가 - 객체 탐지가 어떤 문제인지, 탐지를 어렵게 만드는 다섯 가지, 2단계 · 1단계 탐지기에서 DETR 로 이어지는 계보, "실시간" 과 파레토 곡선, RF-DETR 의 문제의식 · 구조 · 기여 · 수치. 수식 없이 읽으며 코드는 없다.
- 02. 박스와 IoU - 박스의 두 표현, IoU 와 GIoU, 박스 회귀 손실(L1 · GIoU)과 그 기울기. IoU · GIoU 를 구현해 손계산과 맞추고, 경사 하강법으로 박스 하나를 정답에 맞춘다.
- 03. 탐지기 채점: AP 와 mAP - 참 양성 · 거짓 양성 · 거짓 음성, 정밀도와 재현율, PR 곡선, COCO 방식 AP, NMS. 정답을 흐트러뜨린 "가짜 탐지기" 로 AP 가 무엇에 반응하는지 본다.
- 04. 딥러닝 기초와 분류 손실 - 신경망 · 역전파 · AdamW · 정규화 층 · 합성곱을 훑고, 시그모이드 · BCE · 포컬 손실 · 사전 확률 편향 초기화를 끝까지 유도한다. 양성이 약 0.6% 뿐인 분류 문제를 세 가지 설정으로 학습해 비교한다.
- 05. 어텐션과 Transformer - 질의 · 열쇠 · 값으로 어텐션 손계산, \(\operatorname{softmax}(QK^\top/\sqrt{d_k})\,V\) 의 각 글자, 다중 머리 어텐션, 위치 인코딩, Transformer 층. 학습되는 질의가 교차 어텐션 한 층으로 정해진 색의 도형을 찾는다.
- 06. Vision Transformer 와 DINOv2 - 그림을 패치로 잘라 넣는 ViT, 위치 임베딩 보간, 라벨 없이 배우는 DINO 와 DINOv2. MiniViT 를 지도 학습하고 미니 DINO 로 자기 증류를 돌려 본다.
2단계: DETR 계보 (07 – 09장)
집합 예측에서 실시간까지. 끝나면 비용 행렬에서 헝가리안 매칭을 손으로 풀고, NMS 없는 탐지기를 처음부터 학습하고, 변형 어텐션의 표본점 하나를 손으로 읽고, LW-DETR 의 부품이 각각 무엇을 덜어 냈는지 말할 수 있다.
- 07. DETR: 탐지를 집합 예측으로 - 탐지를 집합 예측으로 보기, 헝가리안 매칭, 집합 손실, 객체 질의, 보조 손실. 미니 DETR 을 처음부터 학습하고(검증 AP 0.8375) NMS 가 필요 없는지 확인한다.
- 08. Deformable DETR: 필요한 곳만 보기 - 쌍선형 보간, 변형 어텐션, 박스 반복 정제, 2단계 질의 선택. 미니 Deformable DETR 을 7장과 같은 조건으로 학습해(검증 AP 0.8982) 견준다.
- 09. 실시간 DETR: RT-DETR 과 LW-DETR - RT-DETR 의 생각, LW-DETR 의 부품인 윈도 어텐션과 윈도 우선 배치, C2f 프로젝터, IA-BCE, Group DETR, 박스 재매개변수화. 부품을 하나씩 구현해 식 · 손계산과 맞춘다(학습은 하지 않는다).
3단계: RF-DETR (10 – 13장)
미니 RF-DETR 완성. 끝나면 그림 한 장이 박스 300개가 되기까지의 텐서 모양을 따라가고, 전체 손실을 손으로 계산하고, 한 번 학습한 모델에서 손잡이를 돌려 여러 모델을 꺼내고, 탐지기에 분할 머리를 달 수 있다.
- 10. RF-DETR 의 구조 - RF-DETR 의 순전파 여덟 단계와 텐서 모양, 매개변수 30,467,298개(RF-DETR Nano)를 부품별로 세기. 9장까지의 부품으로
MiniRFDETR을 조립하고 진짜 Nano 와 나란히 놓는다. - 11. RF-DETR 의 학습 - 전체 손실, 스케줄러 없는 학습, 기울기 자르기, EMA, 층별 학습률 감쇠, 사전 학습. 미니 RF-DETR 을 60 에폭 학습하고(EMA 모델의 검증 AP 0.9347) 절제 실험 다섯 가지를 읽는다.
- 12. 가중치 공유 NAS - 파레토 최적, 가중치 공유 NAS, 다섯 손잡이(해상도 · 패치 크기 · 윈도 수 · 디코더 층 수 · 질의 수), 지연 시간을 바르게 재는 법. 한 번 학습한 모델에서 408개 구성을 꺼내 파레토 곡선을 그린다.
- 13. RF-DETR-Seg: 인스턴스 분할 - 질의 임베딩과 픽셀 임베딩의 내적으로 만드는 마스크, 마스크 BCE 와 다이스 손실. 11장의 모델에 분할 머리를 달아 30 에폭 학습한다(마스크 AP 0.8766).
4단계: 실전 (14 – 15장)
진짜 모델, 내 데이터. 끝나면 공개된 RF-DETR 로 추론하고, 내 데이터를 COCO 형식으로 만들어 미세 조정하고, ONNX 로 내보내 지연 시간을 잴 수 있으며, 학습이 안 될 때 어디부터 볼지 안다.
- 14. 실전: rfdetr 패키지 -
rfdetr패키지로 추론, COCO 형식 데이터, 미세 조정, 평가, ONNX 내보내기. RF-DETR Nano 를 도형 세상에 5 에폭 미세 조정하고(시험 세트 AP 0.9830) ONNX 로 내보내 시간을 잰다. - 15. 부록: 디버깅 · 용어집 · 다음 걸음 - 막혔을 때의 점검표, 수식 모음, 용어집, 더 읽을 논문. 처음부터 읽기보다 필요한 절을 찾아 쓰는 참고서다.
위 목록의 AP 를 줄 세우면 안 된다. 7 · 8 · 11장의 값은 같은 검증 세트(그림 500장)에서 잰 것이지만 모델의 크기와 학습 설정이 서로 다르고, 14장은 그림 크기(192 픽셀)와 평가 세트가 다르다. "어느 기법이 얼마나 낫다" 는 결론은 조건을 맞춘 비교에서만 나온다. 또 이 값들은 모두 도형 세상의 것이므로 논문이 COCO 에서 보고한 값과 섞어 읽으면 안 된다.
읽는 방법
목적에 따라 읽는 깊이를 고를 수 있다. 어느 길을 가든 각 장의 "핵심" 상자와 그림은 꼭 본다.
| 길 | 대상 | 읽는 법 |
| A. 직관의 길 | 개념만 빨리 잡고 싶을 때 | 모든 장의 도입 · 그림 · 핵심 상자 · "이 장의 정리" 만 읽고, 풀이 상자는 결과 줄만 본다. 코드는 돌리지 않는다. |
| B. 수학의 길 | 논문을 읽을 수 있게 되고 싶을 때 | 모든 장을 순서대로, 풀이 상자를 한 줄씩 종이에 따라 쓰며 읽는다. 확인 문제를 풀어 본다. |
| C. 구현의 길 | 직접 만들어 보고 싶을 때 | B 에 더해 각 장의 실습 파일을 직접 실행하고 본문의 출력과 견주어 본다. 숫자를 바꿔 다시 돌려 본다. |
급할 때의 지름길
| 목적 | 읽을 장(순서대로) | 건너뛰어도 되는 것 |
| 내 데이터에 당장 써야 한다 | 01 → 02 앞부분(박스의 두 표현, IoU) → 03 앞부분(AP 의 뜻) → 14 | 유도 전부. 14장이 "이 설정은 몇 장의 무엇" 이라고 가리킬 때 그 절만 찾아가 읽는다. |
| RF-DETR 논문을 읽어야 한다 | 01 → 05 → 07 → 08 → 09 → 10 → 11 → 12 | 2 – 4 · 6장은 필요할 때 찾아본다. 13장은 분할에 관심이 있을 때만. |
| DETR 이 무엇인지만 알면 된다 | 01 → 02 → 05 → 07 | 8장부터는 DETR 을 빠르고 가볍게 만드는 이야기다. |
| NAS 부분만 궁금하다 | 01 → 06 의 해상도 · 패치 크기 절 → 10 → 12 | 12장은 10장의 모델과 11장의 학습 코드를 가져다 쓰지만, 읽기만 한다면 11장은 결과만 봐도 된다. |
수식에서 막히면 그 줄의 풀이("↳" 뒤의 설명)를 먼저 읽고, 앞 장의 개념이 가물가물하면 장 링크를 따라간다. 모든 용어는 15장 부록의 용어집에 모여 있다.
준비물
배경지식
- Python 기초: 변수, 함수,
for반복문, 리스트 · 사전, 클래스를 읽을 수 있는 정도. - 고등학교 수학: 함수, 지수 · 로그, 그래프, 간단한 미분("기울기"), 좌표 평면. 잊어버렸어도 필요할 때 다시 설명한다.
- 다음은 몰라도 된다. 행렬과 벡터의 곱은 5장에서 모양과 함께, 확률은 4장에서 BCE 를 유도할 때 필요한 만큼만, 딥러닝과 PyTorch 는 4장에서 뒤 장들이 쓰는 부품을 정리하며, 합성곱은 4장, 그림을 토큰으로 바꾸는 법은 6장에서 다룬다.
- 딥러닝이 완전히 처음이라 역전파 손계산이나 확률 · KL 발산의 유도를 더 느린 호흡으로 보고 싶다면 같은 양식으로 쓴 World Model 튜토리얼의 딥러닝 기초 장이 도움이 된다. 읽지 않아도 이 튜토리얼을 따라오는 데는 문제가 없다.
컴퓨터와 GPU
- Windows · macOS · Linux 어느 것이든 된다. 실습 코드는 장치를 cuda → mps → cpu 순으로 알아서 고른다.
- 2 · 3장은 GPU 를 쓰지 않으며 CPU 로 몇 초 – 1분이면 끝난다. 9 · 10장도 학습이 없어 금방 끝난다.
- 모델을 학습하는 장(4 – 8장, 11 – 14장)은 GPU 가 있으면 좋다. 튜토리얼의 수치는 모두 메모리 8GB 짜리 노트북 GPU 한 장에서 냈고, 한 번의 본 실행은 길어야 30분 안팎이다. CPU 만으로 본 실행을 했을 때의 시간은 재지 않았다.
- GPU 가 없다면
--quick으로 코드가 도는 것만 확인하고 본문의 출력과 그림을 읽거나, Google Colab 같은 무료 GPU 환경을 쓴다. - 14장의 일부(
rfdetr의 사전 학습 가중치)와 6장의 선택 실습(DINOv2 가중치 약 88MB)은 처음 실행할 때 파일을 내려받으므로 인터넷 연결이 필요하다.
설치
Python 3.10 이상이 필요하다. $ 는 입력하는 줄이라는 표시이므로 따라 치지 않는다.
$ python --version # Python 3.10 이상인지 확인 (macOS · Linux 는 python3)
$ mkdir rf-detr && cd rf-detr # 실습 폴더. 실습 파일을 모두 여기에 둡니다
$ python -m venv .venv # 이 폴더 전용 Python 환경 만들기
$ source .venv/bin/activate # Windows 는: .venv\Scripts\activate
$ pip install -r requirements.txt # torch · numpy · matplotlib · scipy
venv(가상 환경)는 이 실습 전용 Python 방을 하나 만드는 것으로, 여기에 설치한 패키지는 다른 프로젝트와 섞이지 않는다. requirements.txt 에는 2 – 13장이 쓰는 패키지 네 개가 최소 버전과 함께 적혀 있다.
| 패키지 | 최소 버전 | 어디에 쓰나 |
| | 2.2 | 모든 모델과 학습 |
| | 1.26 | 도형 세상 그림 그리기, 수치 계산 |
| | 3.8 | 본문의 그림 |
| | 1.11 | 헝가리안 매칭의 풀이( |
NVIDIA GPU 를 쓰려면 requirements.txt 를 설치하기 전에 PyTorch 설치 안내에서 자기 환경을 고르고 나오는 명령으로 CUDA 판 torch 를 먼저 설치한다. torchvision 은 2 – 13장에서 쓰지 않는다. 원리를 직접 구현하는 것이 목적이기 때문이다.
버전 숫자가 나오면 성공이다. 두 번째 값은 NVIDIA GPU 를 쓸 수 있으면 True, 아니면 False 이며 어느 쪽이든 실습을 시작할 수 있다.
14장만 패키지가 더 필요하며, 14장에 이르렀을 때 설치하면 된다.
-
rfdetr: Roboflow 가 공개한 RF-DETR 패키지. 튜토리얼은 1.12.1 판에서 확인했다. -
[train]:train()과evaluate()에 필요한 패키지 묶음. -
[onnx]: ONNX 로 내보내고 그 파일로 추론하는 데 필요한 패키지(onnx·onnxruntime). - 선택: 6장의 선택 실습
ch06_dinov2_features.py는transformers가 필요하다(pip install transformers). 10 · 13장의 실습 파일은rfdetr가 설치되어 있으면 진짜 RF-DETR Nano 와 대조하는 부분까지 돌고, 없으면 그 부분만 건너뛴다.
실습 코드
각 장의 코드는 원문의 code/ 폴더에 있다(rf_shapes.py 처럼 https://pages.unwiki.net/rf-detr/code/ 아래에서 받는다). 원문 본문의 코드 상자는 그 파일의 일부를 그대로 불러온 것이라 본문과 파일이 어긋나지 않는다. 공용 파일은 requirements.txt(필요한 패키지 목록)와 rf_shapes.py(도형 세상 데이터) 둘이며, 2 – 14장의 실습 파일이 rf_shapes.py 를 직접 또는 앞 장의 파일을 거쳐 불러온다.
받은 파일은 모두 같은 폴더에 두고 그 폴더에서 실행한다. 뒤 장의 파일이 앞 장의 파일에서 함수와 클래스를 가져다 쓰기 때문이다(예: 11장의 학습 코드는 2 · 3 · 7 · 8 · 9 · 10장의 파일을 불러온다). 그림은 그 폴더 아래 figures/ 에, 체크포인트(*.pt)와 기록(*.json)은 실행한 폴더에 저장된다.
먼저 도형 세상 파일만 실행해 설치를 확인한다.
$ python rf_shapes.py
그림 (3, 96, 96) torch.float32 값 범위 0.0 1.0
박스 (cx, cy, w, h) [[0.14, 0.753, 0.216, 0.151], [0.528, 0.768, 0.31, 0.344], [0.384, 0.448, 0.382, 0.292], [0.854, 0.843, 0.247, 0.247]]
클래스 [1, 2, 2, 0] → ['사각형', '삼각형', '삼각형', '원']
마스크 (4, 96, 96) torch.bool
그림마다의 객체 수 [4, 3, 4, 3, 2, 3, 2, 4]
shapes_world.png 저장
1초 남짓이면 끝나고 실행한 폴더에 shapes_world.png 가 생긴다. 그림 0-1 이 바로 이 그림이다. 출력의 박스 네 개는 그림 0-1 맨 왼쪽 그림의 것으로, 첫 박스 [0.14, 0.753, 0.216, 0.151] 은 왼쪽 아래의 파란 사각형이고 마지막 박스는 오른쪽 아래의 초록 원이다.
실습 파일과 걸린 시간
시간은 튜토리얼을 쓴 컴퓨터(메모리 8GB 노트북 GPU 한 장)에서 잰 값이다. "GPU" 라고 적힌 시간은 대부분 GPU 를 다른 작업과 나눠 쓰는 상태에서 잰 것이라 혼자 쓰면 더 짧을 수 있으므로 대략의 크기로만 읽는다.
| 파일 | 장 | 본 실행에 걸린 시간 | | 만들어지는 것 |
| | 00 | 1초 남짓 | - | |
| | 02 | CPU 8 – 15초 | 약 3초 | 그림 |
| | 03 | CPU 1분 남짓 | 10 – 20초 | 그림 |
| | 04 | GPU 5분 40초 | 약 20초 | 그림 |
| | 05 | GPU 약 2분 | CPU 40초 안쪽 | 그림 |
| | 06 | GPU 10분 30초 | GPU 약 12초 / CPU 약 30초 | 그림 |
| | 06 | GPU 약 1분 30초 | 있음(시간은 재지 않음) | 그림 |
| | 07 | GPU 약 15분 | CPU 약 15초 | 그림 |
| | 08 | GPU 약 27분 | CPU 약 30초 | 그림 |
| | 09 | GPU 약 32초 | CPU 약 7초 | 그림 |
| | 10 | GPU 약 35초 | CPU 약 15초 | 그림 |
| | 11 | GPU 약 17분 | CPU 약 20초 | 그림 |
| | 12 | GPU 약 18분 | CPU 약 20초 | 그림 |
| | 13 | GPU 약 10분 | CPU 약 30초 | 그림 |
| | 14 | CPU 약 15초 | 1초 남짓 | COCO 형식 폴더 |
| | 14 | GPU 약 30분 | 약 35초(학습 없이 추론만) | 학습 결과 폴더 |
| | 14 | GPU + CPU 약 5분 | 1 – 2분 | ONNX 파일( |
대부분은 어느 장부터 돌려도 되지만, 다음 넷은 앞의 실행이 남긴 결과 파일을 쓴다.
-
ch08_deformable.py: 같은 폴더에ch07_history.json이 있으면 7장의 학습 곡선을 겹쳐 그린다. 없어도 돈다. -
ch12_nas.py --search와--finetune: 먼저python ch12_nas.py가 만든ch12_nas.pt가 있어야 한다. -
ch13_seg.py: 11장의ch11_rfdetr.pt에서 출발한다. 없으면 무작위 초기화에서 시작하므로 본문과 다른 결과가 나온다. - 14장:
ch14_make_coco.py→ch14_finetune.py→ch14_export.py순서로 돌린다.
빠른 확인 모드
장별 실습 파일(ch02 – ch14)에는 모두 --quick 이 있다. 그림 수 · 에폭 수 · 반복 횟수를 줄여 몇 초 – 2분 안에 끝나는 축소판이다.
- 쓰임새: 설치가 맞는지, 코드가 끝까지 도는지 확인하는 것이다. GPU 가 없어도 된다.
- 주의:
--quick이 내는 수치와 그림에는 의미가 없다. 모델이 거의 학습되지 않은 상태이기 때문이며, 본문의 값과 견주려면 본 실행을 해야 한다. - 함께 쓰는 인자:
--fig-dir(그림을 저장할 폴더, 기본figures)와--seed(난수 시드, 기본 0). - 시드를 고정했으므로 같은 컴퓨터에서는 같은 결과가 나온다. 하지만 GPU 의 종류나 PyTorch 판이 다르면 소수 셋째 – 넷째 자리가 달라질 수 있고, 학습이 길수록 그 차이가 쌓인다. AP 가 본문과 비슷한 수준이면 제대로 돈 것이다.
도형 세상
실제 탐지 데이터셋인 COCO 로 RF-DETR 을 학습하려면 GPU 여러 대가 필요하지만, 도형 세상의 미니 모델은 노트북 GPU 한 장으로 십여 분이면 학습된다. 작아도 탐지 문제의 뼈대는 그대로 들어 있다. 객체의 수가 그림마다 다르고, 크기와 위치가 제각각이고, 서로 겹치기도 한다.
- 그림: 96×96 픽셀의 RGB 그림. 텐서 모양은
(3, 96, 96), 값은 0 – 1 이다. 배경은 어두운 회색이고 약한 잡음이 섞여 있다. - 객체: 한 장에 1 – 4개. 크기는 그림 한 변의 0.14 – 0.42 배이고 그림 밖으로 나가지 않는다.
- 클래스: 세 가지. 번호 0 은 원(circle), 1 은 사각형(rectangle), 2 는 삼각형(triangle).
- 색: 여덟 가지 가운데 무작위로 칠한다. 색은 클래스와 관계가 없으므로 모델은 색이 아니라 모양으로 클래스를 가려야 한다.
- 겹침: 조금 겹치는 것은 허용하며 나중에 그린 도형이 먼저 그린 도형을 덮는다. 다만 다른 도형에 묻혀 거의 안 보이는 객체는 만들지 않는다.
- 정답: 객체마다 박스
(cx, cy, w, h)와 클래스 번호. 13장에서는 객체가 차지한 픽셀을 표시한 마스크도 쓴다.
CLASS_NAMES = ["circle", "rectangle", "triangle"] # 클래스 번호 0, 1, 2
CLASS_NAMES_KO = ["원", "사각형", "삼각형"]
NUM_CLASSES = len(CLASS_NAMES)
장면 하나를 뽑는 함수 sample_scene 은 클래스 · 크기 · 중심을 차례로 뽑고, 이미 놓인 도형과 너무 많이 겹치면(IoU 가 0.2 를 넘거나 작은 쪽이 35% 넘게 가려지면) 다시 뽑는다. 장면은 0 – 1 로 정규화한 좌표로 적어 두므로 같은 장면을 96 픽셀로도, 더 크게도 그릴 수 있다. 2 – 13장은 96 픽셀을 기본으로 쓰고, 12장의 NAS 는 해상도를 바꿔 가며 그리고, 14장은 192 픽셀로 그린다. 실습 파일은 장면을 하나씩 뽑지 않고 ShapesDataset 으로 한꺼번에 만들어 쓴다.
기억해 둘 약속은 세 가지다.
- 정답의 형식: 그림 한 장의 정답은 사전 하나다.
"boxes"는 모양(객체 수, 4)의 정규화(cx, cy, w, h),"labels"는 모양(객체 수,)의 클래스 번호다. - 배치: 그림은 한 텐서
(B, 3, 96, 96)로 쌓지만, 정답은 그림마다 객체 수가 달라 쌓을 수 없으므로 목록으로 둔다(collate). "개수가 그림마다 다르다" 는 탐지의 어려움이 데이터를 읽는 자리에서부터 드러난다. - 시드:
seed가 같으면 언제나 같은 데이터가 나온다. 학습용에seed=0, 검증용에seed=1, 시험용에seed=2를 쓴다.
def collate(batch):
"""그림은 한 텐서로 쌓고, 정답은 그림마다 객체 수가 달라 목록으로 둔다."""
images = torch.stack([image for image, _ in batch])
targets = [target for _, target in batch]
return images, targets
도형 세상은 원리를 손에 익히기 위한 장난감이다. 실제 사진에는 질감 · 조명 · 가림 · 수십 – 수백 개의 클래스가 있고 객체가 훨씬 작거나 많다. 도형 세상에서 어떤 기법이 효과가 없었다고 해서 COCO 에서도 그렇다는 뜻이 아니고, 그 반대도 마찬가지다. 실제 데이터에서의 성능은 논문이 보고한 값을 출처와 함께 따로 적는다.
표기 규칙
튜토리얼 전체와 장별 문서에서 같은 기호와 용어를 쓴다.
박스를 적는 두 가지 방법
같은 박스를 숫자 네 개로 적는 방법이 둘 있고, 쓰임새에 따라 둘을 오간다. 자세한 것은 2장에서 다룬다.
| 이름 | 기호 | 코드에서의 이름 | 뜻 | 주로 쓰는 곳 |
| 중심 표현 | \((c_x, c_y, w, h)\) | | 중심의 가로 · 세로 좌표, 너비, 높이 | 데이터의 정답, 모델의 출력, L1 손실 |
| 모서리 표현 | \((x_0, y_0, x_1, y_1)\) | | 왼쪽 위 모서리와 오른쪽 아래 모서리의 좌표 | 넓이 · IoU · GIoU 계산, 그림 위에 그리기 |
- 정규화 좌표: 따로 말하지 않으면 좌표는 그림의 너비 · 높이로 나눈 0 – 1 의 값이다. 96 픽셀 그림에서 픽셀로 바꾸려면 96 을 곱한다. 예를 들어 \((0.5,\ 0.5,\ 0.25,\ 0.5)\) 인 박스의 왼쪽 끝은 \(x_0 = c_x - w/2 = 0.5 - 0.125 = 0.375\), 곧 \(0.375 \times 96 = 36\) 픽셀이고, 오른쪽 끝은 \(x_1 = c_x + w/2 = 0.625\), 곧 60 픽셀이다. 두 끝의 차이 24 픽셀이 너비 \(0.25 \times 96 = 24\) 픽셀과 같다. 이 박스의 넓이 \(24 \times 48 = 1152\) 픽셀은 그림 전체 9216 픽셀의 12.5% 이며, 정규화 좌표에서 바로 \(0.25 \times 0.5 = 0.125\) 로 구해도 같다. 정규화 좌표의 넓이는 "그림에서 차지하는 비율" 이다.
- 원점과 방향: 원점은 그림의 왼쪽 위이고, 가로 좌표는 오른쪽으로, 세로 좌표는 아래로 갈수록 커진다. 수학 시간의 좌표 평면과 세로 방향이 반대다.
- 번호는 0 부터: 클래스 번호, 층 번호 같은 코드의 번호는 0 부터 센다. 본문에서 1 부터 셀 때는 그렇다고 밝힌다.
- COCO 형식은 또 다르다: 14장에서 만나는 COCO 형식은 픽셀 단위의
[x, y, w, h]이고, 앞의 두 수가 중심이 아니라 왼쪽 위 모서리다.
텐서 모양과 수치
- 텐서 모양:
(B, N, D)처럼 괄호 안에 축의 길이를 적는다.B는 배치 크기(한 번에 넣는 그림 수),N은 토큰이나 질의의 수,D는 벡터의 차원이다. 모양이 바뀌는 자리마다 새 모양을 밝힌다. - AP 의 눈금: 튜토리얼의 실험 출력은 AP 를 0.9347 처럼 0 – 1 로 적는다. 논문은 여기에 100 을 곱해 48.0 처럼 적는다. "48.0 AP" 는 0.480 이다.
- 출처의 구별: 수치 앞에 "이 튜토리얼의 실험에서는" 과 "논문(표 N)에서는" 을 구별해 적는다. 논문과 공개 코드가 서로 다를 때는 둘을 나란히 적는다.
- 로그: 수식의 \(\log\) 는 모두 자연로그다.
그리스 문자
"자세히" 칸은 그 뜻으로 처음 쓰는 장이다.
| 기호 | 읽는 법 | 주로 쓰는 뜻 | 자세히 |
| \(\alpha\) | 알파 | 포컬 손실의 균형 가중치(0.25). 9장부터는 IA-BCE 의 지수로도 쓴다 | 4장 |
| \(\gamma\) | 감마 | 포컬 손실에서 쉬운 칸을 얼마나 세게 깎을지 정하는 지수(2) | 4장 |
| \(\eta\) | 에타 | 학습률(한 스텝에 얼마나 고칠지) | 4장 |
| \(\theta\) | 세타 | 신경망의 매개변수 전체(가중치와 편향) | 4장 |
| \(\sigma(z)\) | 시그마 | 시그모이드 함수. 실수 \(z\) 를 0 과 1 사이의 값으로 바꾼다. 7장에서만은 \(\sigma\) 가 매칭의 배정을 뜻한다 | 4장 |
| \(\lambda\) | 람다 | 손실의 항들을 섞는 계수. 그 밖에 가중치 감쇠의 세기(4장), 층별 학습률 감쇠율(11장)로도 쓴다 | 2장 |
| \(\tau\) | 타우 | IoU 문턱값. 그 밖에 소프트맥스의 온도(6장), EMA 감쇠가 올라가는 빠르기(11장), 점수 문턱값(14장)으로도 쓴다 | 3장 |
| \(\delta\) | 델타 | 박스 머리가 내는 변화량. 기준 박스를 얼마나 옮기고 키울지 | 9장 |
| \(\textstyle\sum\) | 시그마 (대문자) | 합. 아래 · 위에 적힌 범위에 걸쳐 더한다 | - |
| \(\textstyle\prod\) | 파이 (대문자) | 곱. 아래 · 위에 적힌 범위에 걸쳐 곱한다 | - |
자주 쓰는 기호
| 기호 | 뜻 | 자세히 |
| \(b\), \(\hat{b}\) | \(b\) 는 정답 박스, 모자(^)를 쓴 \(\hat{b}\) 는 모델이 예측한 박스. 모자는 늘 "예측값" 이라는 표시다 | 2장 |
| \(\operatorname{IoU}(\hat{b}, b)\) | 두 박스의 교집합 넓이 ÷ 합집합 넓이. 0(안 겹침) – 1(똑같음) | 2장 |
| \(\operatorname{GIoU}(\hat{b}, b)\) | 겹치지 않는 박스끼리도 얼마나 먼지 말해 주도록 고친 IoU. −1 – 1 | 2장 |
| \(\mathrm{AP}\) | 평균 정밀도. 탐지기의 성적표에 쓰는 숫자 하나 | 3장 |
| \(z\), \(p\) | \(z\) 는 로짓(시그모이드에 넣기 전의 실수), \(p = \sigma(z)\) 는 그것을 확률로 바꾼 값 | 4장 |
| \(\theta \leftarrow \theta - \eta \nabla_\theta L\) | 경사 하강법 한 스텝. 화살표는 "오른쪽을 계산해 왼쪽에 새로 넣는다", \(\nabla_\theta L\) 은 손실 \(L\) 의 기울기 | 4장 |
| \(\frac{\partial L}{\partial z}\) | 다른 것은 그대로 두고 \(z\) 만 조금 바꿀 때 \(L\) 이 바뀌는 비율(편미분) | 4장 |
| \(\operatorname{softmax}(QK^\top / \sqrt{d_k})\,V\) | 어텐션 한 번. \(Q\) · \(K\) · \(V\) 는 질의 · 열쇠 · 값을 행으로 쌓은 행렬, \(^\top\) 은 행과 열을 바꾸는 전치 | 5장 |
| \(\operatorname*{arg\,min}\), \(\operatorname*{arg\,max}\) | 뒤의 값을 가장 작게(크게) 만드는 입력. 최솟값 자체가 아니라 그때의 입력이다. 7장의 매칭이 "비용이 가장 작은 배정" 을 이렇게 적는다 | 7장 |
| \(\varnothing\) | "객체 없음" 클래스. 객체를 맡지 않은 질의가 내야 하는 답 | 7장 |
| \(\operatorname{sg}(\hat{b})\) | 기울기 차단(stop-gradient). 값은 그대로 쓰되 이 부분으로는 기울기를 흘리지 않는다 | 8장 |
| \(\approx\) | 근사적으로 같다 | - |
| \(:=\) | 왼쪽 이름을 오른쪽 식으로 정의한다 | - |
같은 글자가 장마다 다른 뜻으로 쓰이는 곳이 있다. 널리 쓰이는 관례를 따르느라 그렇고, 한 장 안에서 두 뜻으로 쓸 수밖에 없는 곳은 본문에서 밝힌다.
- \(p\): 4장부터의 손실에서는 확률, 6 · 10 · 12장의 구조 이야기에서는 패치 크기(픽셀).
- \(N\): 5 · 6 · 9장에서는 토큰의 수, 7장부터의 디코더 이야기에서는 객체 질의의 수.
- \(K\): 4 · 7 · 11장에서는 클래스의 수, 8 · 10장에서는 변형 어텐션의 표본점 수.
- \(L\): 4장에서는 손실, 6장부터는 층의 수로도 쓴다. 7장부터 손실은 주로 \(\mathcal{L}\) 로 적는다.
용어
탐지 분야의 글은 영어 낱말을 소리 나는 대로 옮겨 쓰는 일이 많아 같은 것을 두세 가지 이름으로 부르곤 한다. 튜토리얼은 다음 원칙을 지킨다.
- 한 개념에는 한 이름만 쓴다.
- 뜻이 드러나는 우리말을 고르고, 처음 나올 때 영어 원어를 한 번 함께 적는다.
- 모델 · 논문 · 데이터셋의 이름은 영어 그대로 쓴다. DETR, Deformable DETR, LW-DETR, RF-DETR, DINOv2, ViT, Transformer, COCO 가 그렇다.
- 코드의 이름은 코드 글꼴로 그대로 쓴다.
num_queries,class_embed처럼 공식 구현의 식별자는 바꾸지 않는다.
| 영어 | 튜토리얼의 말 | 메모 |
| bounding box | 박스 | "경계 상자" 라고도 한다 |
| ground truth | 정답 | 정답 박스, 정답 클래스 |
| score, confidence | 점수 | "신뢰도" 라고도 한다 |
| threshold | 문턱값 | IoU 문턱값, 점수 문턱값 |
| backbone / projector / head | 백본 / 프로젝터 / 머리 | 분류 머리, 박스 머리, 분할 머리. multi-head attention 은 다중 머리 어텐션 |
| query / key / value | 질의 / 열쇠 / 값 | object query 는 객체 질의 |
| self- / cross-attention | 자기 어텐션 / 교차 어텐션 | |
| deformable attention | 변형 어텐션 | reference point 는 기준점, sampling point 는 표본점 |
| Hungarian matching | 헝가리안 매칭 | cost 는 비용, assignment 는 배정 |
| weight / parameter | 가중치 / 매개변수 | hyperparameter 만은 하이퍼파라미터 |
| gradient | 기울기 | stop-gradient 는 기울기 차단 |
| sample / noise | 표본 / 잡음 | sampling 은 표본 추출, 또는 "뽑기" |
| pre-training / fine-tuning | 사전 학습 / 미세 조정 | |
| latency / throughput | 지연 시간 / 처리량 | |
| layer / shape / hidden | 층 / 모양 / 은닉 | 텐서의 shape 가 "모양" |
| knob (NAS) | 손잡이 | 해상도 · 패치 크기 · 윈도 수 · 디코더 층 수 · 질의 수 |
띄어쓰기도 하나 약속한다. 영어 낱말이나 숫자 · 기호 뒤의 조사는 띄어 쓴다("DETR 은", "IoU 가", "0.5 를"). 조사가 어디서 시작하는지 한눈에 보이게 하기 위해서다.
다루지 않는 것
- COCO · Objects365 같은 큰 데이터셋에서의 실제 학습. GPU 여러 대가 필요한 규모라 직접 하지 않고, 논문이 보고한 값을 출처와 함께 읽는다.
- YOLO 계열 · D-FINE 등 다른 탐지기의 내부. RF-DETR 과 견주는 데 필요한 만큼만 1 · 9장에서 짚는다.
- TensorRT 엔진 만들기와 NVIDIA T4 에서의 지연 시간 재현. 논문의 측정 절차는 12장에서 설명하고, 14장에서는 ONNX 까지 내보내 튜토리얼의 컴퓨터에서 잰다.
- 열린 어휘 탐지, 키포인트 탐지, 영상에서의 추적. RF-DETR 과의 관계만 1장에서 짚는다.
- 데이터 모으기와 라벨 붙이기의 실무. 14장은 이미 정답이 있는 데이터를 COCO 형식으로 바꾸는 데서 시작한다.
See also
- RF-DETR
- RF-DETR:Review
- Object detection
- DINOv2
- Vision Transformer
- Transformer
- Instance segmentation
- Roboflow
- WorldModels:Tutorial - 같은 양식으로 쓴 World Model 튜토리얼
Favorite site
- RF-DETR
- RF-DETR:Tutorial:01-WhatIsRFDETR
- RF-DETR:Tutorial:02-BoxesIoU
- RF-DETR:Tutorial:03-EvaluationMAP
- RF-DETR:Tutorial:04-DeepLearningBasics
- RF-DETR:Tutorial:05-AttentionTransformer
- RF-DETR:Tutorial:06-ViT-DINOv2
- RF-DETR:Tutorial:07-DETR
- RF-DETR:Tutorial:08-DeformableDETR
- RF-DETR:Tutorial:09-RT-DETR-LW-DETR
- RF-DETR:Tutorial:10-Architecture
- RF-DETR:Tutorial:11-Training
- RF-DETR:Tutorial:12-NAS
- RF-DETR:Tutorial:13-Segmentation
- RF-DETR:Tutorial:14-Practice
- RF-DETR:Tutorial:15-Appendix