[CV] Ultralytics YOLOV3

조치연·2025년 5월 31일

CV Ultralytics yolov3

CV

목록 보기

7/8

권철민님의 강의를 보며 공부하다가 Ultralytics를 공부하게 되어 나중에 다시 보려고 만든 게시물입니다.

📚 Ultralytics YOLOV3

Yolo(You Only Look One)라는 딥러닝 모델이 있습니다.
Object Detection에서 매우 뛰어난 성능을 보여주며 Real time detection의 대명사라고 할 수 있습니다.

Ultralytics yolo는 yolo를 쉽게 구현할 수 있게 해주는 tool이라고 생각하시면 됩니다.
Ultralytics yolov3는 yolov3모델을 구현할 수 있게 해주는 tool입니다.

Ultralytics는 Command Line Interface (CLI)기반 tool입니다. 저도 이 tool을 사용하면서 처음으로 제대로 CLI기반 tool을 사용해봤고 공부해봤습니다.(많은 도움이 된 것 같습니다.😊)

📚 File format

앞에서 MMDetection을 공부하면서 custom dataset을 만들 때 middle format으로 만들어줘야 한다고 말한 바가 있습니다.

Ultralytics에서도 특정 format을 원하는데 형태는 다음과 같습니다.

Ultralytics에서는 내부에서 images를 labels로 바꿔서 image와 label을 구별하기 때문에 꼭 위 형식으로 맞춰주어야 합니다. Ultralytics에서 data는 yaml확장자를 가진 config file입니다.
dataset config file은 다음처럼 이루어져 있습니다.

train : 학습 이미지가 있는 디렉토리
val : 검증 이미지가 있는 디렉토리
test : 테스트 이미지가 있는 디렉토리
nc : class 갯수
names : class 이름

Ultralytics에서 dataset yaml파일을 인자로 받고 작동하는 메커니즘을 살펴보면 다음처럼 표현할 수 있습니다.

labels에 있는 각 file의 각 행은 다음과 같은 형태를 나타냅니다. "class x_center y_center width height"
bbox 좌표는 normalize되어 있으므로 마지막엔 원본 이미지를 곱해줘야 합니다.

📚 Architecture

Ultralytics의 구조를 살펴보겠습니다.
대부분의 tool에서 그렇듯이 Ultralytics의 구조도 비슷합니다. 원하는 모델을 가져오고, 모델을 학습시킨 후 추론하는 것 입니다. Ultralytics는 yolo 모델만 가지고 올 수 있다는 차이가 있습니다.

큰 메커니즘은 아래와 같습니다.

이제부터 각 CLI에 대해 알아볼 것입니다.

하지만, 그 전에 Ultralytics는 단 몇 줄로 모델을 완성하고 추론하는 것까지 가능하게 하는 편리한 tool이지만, 이를 가능하게 하기 위해 tool에서 원하는 형식으로 dataset을 바꾸는 것이 번거롭습니다.
즉, train.py, detect.py, val.py와 같은 명령어보다 tool에서 원하는 format으로 file을 변경해 주는 것이 더 중요하다고 할 수 있습니다.

✅ !python train.py

모델을 불러오고 학습하는 명령어 입니다.
Ultralytics yolov3에서 제공하는 train.py의 인자는 굉장히 많지만 주요한 인자 몇 가지를 다뤄보겠습니다.
(사실 하다보니 거의 다 다뤘습니다. ㅎㅎ)

최종적으로 사용하는 형태는 마지막에 있으니 참고 바랍니다.

1. --weights

불러올 모델의 초기 weight 경로입니다.
인자 값으로는 pt확장자를 가지는 경로가 들어오게 됩니다. Ultralytics yolov3의 경우 'yolov3.pt', 'yolov3-tiny.pt', 'yolov3-spp.pt' 등 여러가지 yolo weight값을 입력으로 받을 수 있습니다.

이렇게 인자에 값을 넣어주면 모델이 학습 시 관련 weight를 알아서 다운로드 해줍니다.(아래 사진에는 yolov5를 다운받았는데 yolov5도 어느정도 지원이 되는 것 같습니다.)

강의를 들을 당시에는 3가지 정도 모델을 소개해 주셨는데 찾아보니까 여러 모델들을 가져올 수 있는 것 같았습니다.
추측이지만, Ultralytics yolov3 github에 있는 model.yaml이 있는 것들은 모두 가능한 것 같습니다.
(한 4개정도 테스트 해봤습니다.)

그리고 이렇게 해서 다운받은 weight file은 yolov3 디렉터리 밑에 pt확장자로 다운이 됩니다. 따라서 다시 모델을 학습하거나 가져올 때 다운받을 필요가 없어집니다.

2. --cfg

모델 config파일입니다.
yaml확장자로 되어있습니다. 앞에 사진이 cfg에 인자로 들어가는 파일 경로 입니다.
(yolov11 모델을 다운받아 cfg의 인자로 넣어줬는데 "anchor key error"가 뜨면서 호환이 안되는 모습을 보여줬습니다.)

cfg에 인자를 넣을 때 yaml 파일의 내용중 nc(클래스 개수)부분은 dataset에 맞게 바꿔주어야 합니다.cfg와 weights는 같이 쓰는 것이 아니라 weight가 없는 모델을 만들고 싶을 때는 cfg를, weight가 있는 모델을 만들고 싶을 때는 weights를 쓰면 된다고 합니다.

사실 같이써도 작동에 이상은 없지만, 굳이 그럴필요는 없어 보입니다.

3. --data

dataset config파일입니다.yaml확장자로 되어있습니다. dataset이 어떻게 구성되는지, labels(annotations)가 어떻게 구성되는 지 알려주는 지표라고 생각하시면 됩니다.내용은 아래와 같이 구성됩니다.

4. --epochs

총 epoch입니다.

5. --batch-size

모든 gpu에 대한 batch_size입니다.

6. --img

입력받는 이미지 사이즈입니다.
yolo의 경우 32의 배수를 입력받는 것이 좋다고 합니다. ex) 640
(원본 이미지의 사이즈를 작성하는 것이 아닙니다.)

7. --nosave

마지막 모델만 저장하겠다는 의미입니다.

8. --noval

마지막에만 validation을 적용하겠다는 의미입니다.

9. --cache

더 빠른 학습을 위해 data를 내부의 임시 저장 공간으로 가지고 옵니다.
(빠른 학습을 보장하지만, 그만큼 저장공간을 잡아먹습니다. 강의에서는 거의 안 쓰는 것이 좋다고 합니다.)

10. --image-weights

학습 시 이미지 sampling에 가중치를 적용합니다. ex) 불균형한 이미지 => 최대한 균일하게
(제가 더 못찾아본 것일수도 있지만, 자세한 내용은 없었습니다.)

11. --multi-scale

입력으로 다양한 이미지가 들어오도록 합니다.(+/- 50%)

12. --optimizer

SGD, Adam, AdamW중에 선택할 수 있습니다.

13. --project

모델 저장 경로중 root directory에 해당하는 경로입니다.모델을 학습시키면 weight를 저장합니다.
이때 저장하는 경로는 project/name이 됩니다.
default값은 runs/train입니다.

14. --name

모델 저장 경로 project/name에서 name에 해당하는 파일명입니다. default값은 exp입니다.

15. --exist-ok

모델을 저장할 때 기존에 존재하는 파일인 경우 덮어쓰겠다는 의미입니다. default값을 그대로 두면 계속해서 파일이 생겨납니다. ex) exp1, exp2, exp3...

16. --cos-lr

cosine learning rate scheduler를 적용할 지 여부입니다.조정하는 값에따라 다르겠지만, 기본적인 구조는 다음과 같습니다.

(그냥 오랜만에 복습할 겸 가져왔습니다.)

17. --patience

EarlyStopping patience입니다.
default값은 100으로 n을 입력했을 때 n만큼 epoch를 돌았는데 성능이 좋아지지 않으면 멈춥니다.
(아마 성능은 validation 값으로 측정하지 않을까 싶습니다.)

18. --freeze

모델을 fine tuning하고싶을 때 특정 layer를 freeze(학습이 안되게 막는)합니다.--freeze 0은 모든 layer가 학습되고, --freeze 1은 모델 전체를 고정, --freeze n과 같이 다른 숫자를 사용하면 첫 n개의 layer를 freeze하게 됩니다.

19. --save-period

특정 epoch마다(주기마다) 모델을 저장합니다.default값은 -1인데 1보다 작은 값이 입력될 경우, 적용되지 않습니다.n인 경우 n epoch마다 모델을 저장합니다.

20. --seed

training seed입니다.

아래는 train.py를 활용한 명령입니다.

!cd /content/yolov3; python train.py --img 640 --batch-size 16 --epochs 20 --data /content/ox_pet/ox_pet.yaml --weights yolov5l.pt --project=/mydrive/ultra_workdir \
                                     --name pet --exist-ok

✅ !python detect.py

학습한 모델을 가지고 추론하는 명령어입니다.
마찬가로 주요 인자에 대해 알아보겠습니다.
(Ultralytics yolov3에서 train.py와 비슷한 인자가 많으므로 간단하게 설명하겠습니다.)

1. --weights

pt확장자를 가진 파일 경로입니다.
인자로 주어진 weight.pt를 통해 추론을 진행할 모델이 만들어집니다.

2. --source

추론 할 data 경로입니다.
image path, directory path, video path, youtube url이 들어올 수 있습니다.
비디오의 경우 자동으로 프레임 단위로 예측해줍니다.

3. --img

image 사이즈입니다.(trian.py와 동일)

4. --conf-thres

confidence threshold값 입니다. 모델이 예측한 확률 값이 confidence threshold보다 높으면 결과를 반환합니다.
default값은 0.25입니다.

5. --iou-thres

IOU threshold입니다. 모델 내부에서 NMS 알고리즘을 진행할 때 사용합니다.
default값은 0.45입니다.

6. --max-det

하나의 이미지당 최대 예측 개수입니다.

7. --save-txt

결과 값을 txt형태로 저장합니다.

8. --save-conf

confidence 값을 save-text에 같이 저장합니다.

9. --nosave

이미지나 비디오를 저장하지 않습니다.

10. --augment

추론 시 이미지에 augmentation을 적용합니다.

11. --visualize

feature map을 시각화 합니다.

12. --project

결과를 저장하는 root directory입니다.
최종적으로 결과는 project/name 경로에 저장됩니다.

13. --name

결과를 저장하는 파일명입니다.

14. exist-ok

저장 경로가 이미 존재하면 파일을 더 만들지 않고 덮습니다.

15. line-thickness

bounding box의 thickness입니다. default값은 3입니다.

16. --hide-labels

label을 숨깁니다.

17. --hide-conf

confidence를 숨깁니다.

18. --dnn

ONNX를 활용하기 위해 OpenCV의 dnn을 활용합니다. ONNX라는 개념이 생소해서 찾아보니

"ONNX는 Open Neural Network Exchange의 줄인 말로서 이름과 같이 다른 DNN 프레임워크 환경(ex Tensorflow, PyTorch, etc..)에서 만들어진 모델들을 서로 호환되게 사용할 수 있도록 만들어진 공유 플랫폼이다." 라고 합니다.

19. --vid-stride

추론 시 비디오 프레임의 간격을 정합니다.
default값은 1이고, 1이상인 n인 경우 n만큼 프레임을 건너뛰면서 추론합니다. ex) 1, 3, 5, 7...

아래는 detect.py를 활용한 명령입니다.

!cd yolov3;python detect.py --source /content/data/images/pug_100.jpg --weights /mydrive/ultra_workdir/pet/weights/best.pt --conf 0.2 \
                            --project=/content/data/output --name=run_image --exist-ok --line-thickness 2

✅ !python val.py

학습한 모델을 테스트하는 명령입니다.
(원래는 test.py였는데 val.py로 바뀐 것 같습니다.)

인자는 다음과 같습니다.

1. --data
yaml 확장자 dataset파일 경로입니다.
인자로 파일 경로를 입력해주면 파일 내용중 test인자로 들어가있는 디렉토리에서 데이터를 가져옵니다.

2. --weights
pt확장자 모델 파일입니다.(설명에는 files도 된다고 합니다.)
앞에서 학습시킨 모델의 weights값이라고 생각하면 될 것 같습니다.

3. --batch-size
batch size입니다.

4. --img
이미지 크기입니다. default는 640입니다.

5. --conf-thres
confidence threshold입니다. default는 0.001입니다.

6. --iou-thres
NMS시 사용하는 IOU threhold입니다. default는 0.6입니다.

7. --max-det
하나의 이미지당 최대 예측 개수입니다. default는 300입니다.

8. --task
모델에 대해 어떤 작업을 수행할 지 알려줍니다. default값은 val입니다.
들어갈 수 있는 값은 train / val / test / speed / study입니다.

(저도 정확하지 않지만 어떤 인자값을 넣느냐에 따라 dataset.yaml에서 어떤 데이터를 읽어올 지 정하는 것 같습니다.
앞서 설명드릴 때 data인자에 들어간 yaml파일 경로에 들어가 그 안에서 어떤 값의 데이터를 읽어올 지 정하는 것 같습니다. ex) train => dataset.yaml => train : "path"를 선택. / val => dataset.yaml => val : "path"를 선택 ...)

9. --single-cls
단일 클래스를 다루는 경우에 사용합니다.

10. --augment
augmentation 적용 여부입니다.

11. --verbose
class에 대한 mAP를 보여줍니다.

12. --save-txt
예측 결과를 txt확장자로 저장합니다.

13. --save-hybrid
예측 결과와 gt를 모두 txt확장자로 저장합니다.
(그런데 실험을 해보니 --save-txt와 --save-hybrid 모두 같은 파일을 만들고 같은 값을 반환해서.. 정확한 차이는 모르겠습니다//)

14. --save-conf
confidence scores를 --save-txt에 저장합니다.

15. --save-json
예측 결과를 COCO JSON 형태로 저장합니다.

16. --project
예측 결과를 저장할 디렉토리입니다. default는 runs/val입니다.

17. --name
예측 결과를 저장할 파일 이름입니다. default는 exp입니다.project/name의 형태를 띄게 됩니다.

18. --exist-ok
저장 경로가 이미 존재하면 파일을 더 만들지 않고 덮습니다.

19. --dnn
ONNX를 활용하기 위해 OpenCV의 dnn을 활용합니다.

아래는 val.py를 활용한 명령입니다.

!cd yolov3; python val.py --img 640 --batch-size 16 --weights /content/yolov3/runs/train/exp/weights/best.pt --data coco128.yaml\
                          --task val --project /content/model/test --name result --exist-ok --save-txt --save-conf