YOLO 하이퍼파라미터 조정하기 (yaml 파일)

좋아! 완전 처음부터 “하이퍼파라미터 YAML 파일로 YOLO-OBB 학습 설정” 하는 법을 단계별로 알려줄게.
(우리는 Ultralytics YOLO CLI를 쓸 거고, 한 번 만든 YAML로 계속 재사용/버전관리할 수 있어요.)

1) 하이퍼파라미터 YAML이 뭐야?

• YOLO는 보통 yolo TASK MODE ARGS 형태(예: yolo obb train imgsz=1280 ...)로 옵션을 넘기는데, 이 ARGS를 전부 YAML 파일로 적어두고 한 번에 불러오는 방법이 있어요.
• 즉, **학습에 쓰는 모든 설정(모델, 데이터 경로, epoch, 증강, 학습률 등)**을 한 YAML에 적어놓고 cfg=... 로 불러오면 됩니다. Ultralytics Docs

2) 기본 템플릿 만들기(권장)

터미널에서 아래를 실행:

 

pip install -U ultralytics opencv-python

# YOLO의 기본 설정 파일(defaults)을 복사해서 내 작업폴더로 가져오기
yolo copy-cfg

Ultralytics Docs

3) 내 프로젝트용 YAML 만들기

아래 예시는 당신의 프로젝트(OBB, 3클래스, 우리 전에 썼던 하이퍼들)를 한 파일로 정리한 거예요. 이름은 예를 들어 container_obb_train.yaml.

주의: 설치한 버전에 따라 가중치 파일명이 yolov8n-obb.pt 또는 yolo11n-obb.pt 일 수 있어요. OBB 모델은 -obb 접미사를 씁니다. Ultralytics Docs

# container_obb_train.yaml  ——  한 파일로 학습 설정을 모두 관리
# [작업/모드]
task: obb          # OBB(회전박스) 태스크
mode: train        # train / val / predict / export ...

# [모델/데이터]
model: yolov8n-obb.pt            # 또는 yolo11n-obb.pt (설치 버전에 맞게)
data: datasets/container-obb/data.yaml   # 당신의 데이터셋 YAML

# [학습 스케줄/리소스]
epochs: 200
batch: 16
imgsz: 1280
device: 0         # GPU index, 다중이면 [0,1] 가능
workers: 8
patience: 30      # 조기종료

# [옵티마이저/학습률]
optimizer: AdamW
lr0: 0.002        # 초기 학습률
lrf: 0.1          # 최종 학습률 비율
momentum: 0.9
weight_decay: 0.0005
warmup_epochs: 3

# [증강(기하/광학)]
degrees: 45.0
translate: 0.08
scale: 0.5
shear: 12.0
perspective: 0.0005
flipud: 0.0       # 컨테이너가 뒤집히진 않으므로 0 권장
fliplr: 0.5
mosaic: 1.0
mixup: 0.1
hsv_h: 0.015
hsv_s: 0.7
hsv_v: 0.5

# [손실 가중치]
box: 7.5
cls: 0.5
dfl: 1.5

증강/하이퍼 항목들의 의미는 Ultralytics 설정 문서와 증강 가이드를 보면 표로 자세히 나와 있어요(각도/이동/모자이크/HSV 등). Ultralytics Docs+1

4) 실행 방법(두 가지)

둘 중 편한 걸 쓰면 됩니다.

A. YAML만으로 실행(권장, 가장 깔끔)

yolo cfg=container_obb_train.yaml

YAML 안에 task: obb, mode: train을 이미 적어뒀기 때문에 이것만으로 학습이 시작됩니다. (cfg 파일로 기본설정을 통째로 교체하는 방식) Ultralytics Docs

B. 태스크/모드를 커맨드에서 명시

yolo obb train cfg=container_obb_train.yaml

같은 효과입니다. 커맨드에 task/mode를 적어도 되고, YAML에 적어도 됩니다. (둘 다 있으면 CLI 인자값이 우선 적용)

5) 데이터셋 YAML(참고)

이미 만들어 둔 datasets/container-obb/data.yaml 은 대략 이렇게 생겼어요:

path: datasets/container-obb
train: images/train
val: images/val
test: images/test
task: obb
names:
  0: BIC
  1: DOOR
  2: TYPESIZE

(데이터 YAML은 데이터 경로/클래스명을 정의하는 용도예요. 학습 하이퍼는 위의 container_obb_train.yaml에서 관리합니다.) Ultralytics Docs

6) 로그/결과는 어디에 생겨?

실행하면 runs/obb/train*/ 안에 학습 로그, 그래프, weights/best.pt 등이 저장돼요. (CLI/설정 사용법은 공식 문서에 표기) Ultralytics Docs

7) 자주 발생하는 이슈 체크

• 모델 파일명: 설치 버전에 맞는 …-obb.pt 사용(예: v8은 yolov8n-obb.pt, 최신은 yolo11n-obb.pt). Ultralytics Docs
• 키 오타: YAML 키 이름은 문서의 설정 키와 동일해야 합니다. (lr0, lrf, degrees 등) Ultralytics Docs
• 메모리 부족: imgsz↓(1024) 또는 batch↓.
• 작은 텍스트가 잘 안 잡힘: imgsz↑, mosaic 유지, 작은 BIC 사례를 학습셋에 더 추가.
• 윈도우 줄바꿈 이슈: 없습니다. YAML만 저장하면 되고, 실행은 한 줄 명령이면 끝.

원하면 지금 만든 container_obb_train.yaml을 바탕으로

• 폴더구조 샘플,
• 라벨(poly/rbox) 통일 변환 스크립트,
• 추론→BIC 투시보정→OCR→체크디지트 검증 파이프라인
  까지 바로 붙여 드릴게요.