학습 중 YOLO 모델의 성능을 어떻게 향상할 수 있나요?

배치 크기, 학습률, 모멘텀, 가중치 감쇠와 같은 하이퍼파라미터를 조정하여 성능을 향상하세요. 데이터 증강 설정을 조정하고 적절한 옵티마이저를 선택하며, 조기 종료 또는 혼합 정밀도와 같은 기법을 사용하세요. 자세한 내용은 학습 가이드를 참조하세요.

YOLO 모델 정확도에 중요한 하이퍼파라미터는 무엇인가요?

정확도에 영향을 미치는 주요 하이퍼파라미터는 다음과 같습니다: 배치 크기(batch): 배치 크기가 크면 학습이 안정화될 수 있지만 더 많은 메모리가 필요합니다. 학습률(lr0): 학습률이 낮으면 세밀하게 조정할 수 있지만 수렴 속도가 느려집니다. 모멘텀(momentum): 그래디언트 벡터를 가속하고 진동을 줄입니다. 이미지 크기(imgsz): 이미지 크기가 크면 정확도가 향상되지만 연산 부하가 증가합니다. 데이터 세트와 하드웨어에 따라 이 설정을 조정하세요. 자세한 내용은 학습 설정을 참조하세요.

YOLO 모델 학습을 위한 학습률은 어떻게 설정하나요?

학습률(lr0)은 매우 중요합니다. SGD에는 0.01, Adam 옵티마이저에는 0.001로 시작하고, 기본값인 auto는 lr0을 무시하므로 optimizer를 명시적으로 설정하세요. 지표를 모니터링하고 필요에 따라 조정하세요. 코사인 학습률 스케줄러(cos_lr) 또는 워밍업(warmup_epochs, warmup_momentum)을 사용하세요. 자세한 내용은 학습 가이드를 참조하세요.

YOLO 모델의 기본 추론 설정은 무엇인가요?

기본 설정은 다음과 같습니다: 신뢰도 임계값(conf=0.25): 감지 결과에 필요한 최소 신뢰도입니다. IoU 임계값(iou=0.7): 비최대 억제(NMS)에 사용됩니다. 이미지 크기(imgsz=640): 입력 이미지의 크기를 조정합니다. 장치(device=None): CPU, CUDA GPU, Apple MPS, Intel XPU(xpu) 또는 Huawei Ascend NPU(npu)를 선택합니다. 전체 개요는 예측 설정 및 예측 가이드를 참조하세요.

YOLO 모델 학습에 혼합 정밀도를 사용하는 이유는 무엇인가요?

혼합 정밀도 학습(amp=True)은 FP16과 FP32를 사용하여 메모리 사용량을 줄이고 학습 속도를 높입니다. 최신 GPU에 유용하며, 정확도를 크게 저하시키지 않으면서 더 큰 모델을 사용하고 계산을 더 빠르게 수행할 수 있습니다. 자세한 내용은 학습 가이드를 참조하세요.

구성#

YOLO 설정과 하이퍼파라미터는 모델의 성능, 속도, 정확도에 중요한 영향을 줍니다. 이러한 설정은 학습, 검증, 예측을 비롯한 여러 단계에서 모델의 동작에 영향을 미칠 수 있습니다.

시청: Ultralytics YOLO 마스터하기: 구성

Ultralytics 명령어는 다음 구문을 사용합니다.

예제

yolo TASK MODE ARGS

항목은 다음과 같습니다.

TASK(선택 사항)은 (탐지, 분할, 시맨틱, 깊이, 분류, 포즈, obb) 중 하나입니다.
MODE(필수)은 (학습, 검증, 예측, 내보내기, 추적, 벤치마크) 중 하나입니다.
ARGS(선택 사항)은 기본값을 재정의하는 imgsz=640와 같은 arg=value 쌍입니다.

기본 ARG 값은 이 페이지에 정의되어 있으며 cfg/default.yaml 파일에서 가져옵니다.

작업#

Ultralytics YOLO 모델은 다음을 포함한 다양한 컴퓨터 비전 작업을 수행할 수 있습니다.

탐지: 객체 탐지는 이미지나 동영상에서 객체를 식별하고 위치를 찾습니다.
분할: 인스턴스 분할은 이미지나 동영상을 서로 다른 객체 또는 클래스에 해당하는 영역으로 나눕니다.
시맨틱 분할(semantic): 시맨틱 분할은 장면을 세밀하게 이해할 수 있도록 이미지의 모든 픽셀에 클래스 레이블을 할당합니다.
깊이(depth): 단안 깊이 추정은 단일 RGB 이미지에서 픽셀별 깊이 맵을 미터 단위로 예측합니다.
분류: 이미지 분류는 입력 이미지의 클래스 레이블을 예측합니다.
포즈: 포즈 추정은 이미지나 동영상에서 객체를 식별하고 해당 객체의 키포인트를 추정합니다.
OBB: 방향성 경계 상자는 회전된 경계 상자를 사용하며, 위성 또는 의료 영상에 적합합니다.

인수	기본값	설명
`task`	`'detect'`	YOLO 작업을 지정합니다. `detect`은 객체 감지, `segment`는 인스턴스 분할, `semantic`은 의미론적 분할, `depth`는 단안 깊이 추정, `classify`는 분류, `pose`은 자세 추정, `obb`은 방향 경계 상자에 사용됩니다. 각 작업은 이미지 및 동영상 분석의 특정 출력과 문제에 맞게 설계되었습니다.

작업 가이드

모드#

Ultralytics YOLO 모델은 서로 다른 모드로 작동하며, 각 모드는 모델 수명 주기의 특정 단계에 맞게 설계되었습니다.

Train: 사용자 지정 데이터셋으로 YOLO 모델을 학습합니다.
Val: 학습된 YOLO 모델을 검증합니다.
Predict: 학습된 YOLO 모델을 사용하여 새 이미지 또는 동영상에 대한 예측을 수행합니다.
Export: 배포를 위해 YOLO 모델을 내보냅니다.
Track: YOLO 모델을 사용하여 실시간으로 객체를 추적합니다.
Benchmark: YOLO 내보내기 모델(ONNX, TensorRT 등)의 속도와 정확도를 벤치마크합니다.

인수	기본값	설명
`mode`	`'train'`	YOLO 모델의 작동 모드를 지정합니다. `train`은 모델 학습, `val`은 검증, `predict`는 추론, `export`은 배포 형식으로 변환, `track`는 객체 추적, `benchmark`는 성능 평가에 사용됩니다. 각 모드는 개발부터 배포까지 서로 다른 단계를 지원합니다.

모드 가이드

학습 설정#

YOLO 모델의 학습 설정에는 모델의 성능, 속도, 정확도에 영향을 미치는 하이퍼파라미터와 구성이 포함됩니다. 주요 설정에는 배치 크기, 학습률, 모멘텀, 가중치 감쇠가 있습니다. 옵티마이저, 손실 함수, 데이터셋 구성도 학습에 영향을 줍니다. 최적의 성능을 얻으려면 튜닝과 실험이 중요합니다. 자세한 내용은 Ultralytics 진입점 함수를 참조하세요.

인수	유형	기본값	설명
`model`	`str`	`None`	학습에 사용할 모델 파일을 지정합니다. `.pt` 사전 학습 모델 또는 `.yaml` 구성 파일의 경로를 지정할 수 있습니다. 모델 구조를 정의하거나 가중치를 초기화하는 데 필요합니다.
`data`	`str`	`None`	데이터셋 YAML의 경로입니다(예: `coco8.yaml`). 이 파일에는 학습 및 검증 데이터의 경로, 클래스 이름, 클래스 수가 포함됩니다. 분류 작업에서는 데이터셋 디렉터리 또는 기본 제공 데이터셋 이름(예: `imagenet10`)을 사용합니다.
`epochs`	`int`	`100`	총 학습 에포크 수입니다. 각 에포크는 전체 데이터셋을 한 번 순회하는 것을 의미합니다. 이 값을 조정하면 학습 시간과 모델 성능에 영향을 줄 수 있습니다.
`time`	`float`	`None`	최대 학습 시간(시간 단위)입니다. 이 값을 설정하면 `epochs` 인수를 덮어쓰고 지정된 시간이 지난 후 학습을 자동으로 중지합니다. 시간 제약이 있는 학습 시나리오에 유용합니다.
`patience`	`int`	`100`	검증 지표가 개선되지 않아도 조기 종료 전에 학습을 계속할 에포크 수입니다. 성능이 정체되었을 때 학습을 중단하여 과적합을 방지하는 데 도움이 됩니다.
`batch`	`int` 또는 `float`	`16`	배치 크기이며, 세 가지 모드로 설정할 수 있습니다. 정수로 지정(예: `batch=16`), GPU 메모리의 60%를 사용하는 자동 모드(`batch=-1`), 지정한 사용률에 맞추는 자동 모드(`batch=0.70`)입니다.
`imgsz`	`int`	`640`	학습에 사용할 목표 이미지 크기입니다. 이미지는 지정된 값과 같은 길이의 변을 가진 정사각형으로 크기가 조정됩니다(`rect=False`인 경우). YOLO 모델은 종횡비를 유지하지만 RT-DETR은 유지하지 않습니다. 모델 정확도와 계산 복잡도에 영향을 줍니다.
`save`	`bool`	`True`	학습 체크포인트와 최종 모델 가중치의 저장을 활성화합니다. 학습 재개 또는 모델 배포에 유용합니다.
`save_period`	`int`	`-1`	에포크 단위로 지정하는 모델 체크포인트 저장 주기입니다. -1로 설정하면 이 기능이 비활성화됩니다. 장시간 학습 중간에 모델을 저장할 때 유용합니다.
`cache`	`bool` 또는 `str`	`False`	데이터셋 이미지를 메모리(`True`/`ram`) 또는 디스크(`disk`)에 캐싱하거나 캐싱을 비활성화합니다(`False`). 메모리 사용량이 늘어나는 대신 디스크 I/O를 줄여 학습 속도를 높입니다.
`device`	`int` 또는 `str` 또는 `list`	`None`	학습에 사용할 계산 장치를 지정합니다. 단일 GPU(`device=0`), 여러 GPU(`device=[0,1]`), CPU(`device=cpu`), Apple 실리콘용 MPS(`device=mps`), Huawei Ascend NPU(`device=npu:0` 또는 `device=npu:0,1`), Intel XPU(`device=xpu:0`), 유휴 GPU 자동 선택(`device=-1`) 또는 여러 유휴 GPU 자동 선택(`device=[-1,-1]`)을 지정할 수 있습니다.
`workers`	`int`	`8`	데이터 로딩에 사용할 워커 스레드 수입니다(Multi-GPU 학습에서는 `RANK`당). 데이터 전처리와 모델 입력 속도에 영향을 미치며, 특히 Multi-GPU 구성에서 유용합니다.
`project`	`str`	`None`	학습 결과를 저장할 프로젝트 디렉터리의 이름입니다. 여러 실험 결과를 체계적으로 저장할 수 있습니다.
`name`	`str`	`None`	학습 실행의 이름입니다. 프로젝트 폴더 안에 하위 디렉터리를 생성하는 데 사용되며, 이 디렉터리에 학습 로그와 결과가 저장됩니다.
`exist_ok`	`bool`	`False`	True로 설정하면 기존 프로젝트/이름 디렉터리를 덮어쓸 수 있습니다. 이전 결과를 수동으로 삭제하지 않고 반복 실험을 수행할 때 유용합니다.
`save_dir`	`str`	`None`	`project`/`name` 조합을 덮어쓰고 실행 결과를 저장할 정확한 디렉터리를 지정합니다. 경로를 자동으로 증가시키지 않고 그대로 사용하므로, 연속 실행 시 같은 디렉터리를 재사용합니다.
`pretrained`	`bool` 또는 `str`	`True`	사전 학습 가중치로 학습을 시작할지 결정합니다. 불리언 값이나 로드할 가중치의 문자열 경로를 지정할 수 있습니다. `pretrained=False`은 모델 아키텍처를 유지하면서 무작위로 초기화된 가중치로 학습합니다.
`cls_remap`	`bool`	`True`	데이터셋 간에 파인튜닝할 때 클래스 이름이 일치하는 경우 사전 학습된 분류 헤드의 행을 새 모델로 복사합니다. 따라서 클래스가 겹치면 학습된 바이어스를 유지하며, 헤드 너비가 같을 경우 가중치도 유지합니다. 클래스 수가 다르거나 클래스 수는 같지만 순서가 달라도 적용됩니다.
`optimizer`	`str`	`'auto'`	학습에 사용할 옵티마이저입니다. `SGD`, `MuSGD`, `Adam`, `Adamax`, `AdamW`, `NAdam`, `RAdam`, `RMSProp` 또는 `auto`을 지정하면 학습 반복 횟수에 따라 `AdamW` 또는 `MuSGD`을 선택합니다. 수렴 속도와 안정성에 영향을 줍니다.
`seed`	`int`	`0`	학습의 무작위 시드를 설정하여 같은 구성으로 실행할 때 결과를 재현할 수 있도록 합니다.
`deterministic`	`bool`	`True`	결정론적 알고리즘을 강제하여 결과를 재현할 수 있도록 합니다. 비결정론적 알고리즘을 제한하므로 성능과 속도에 영향을 줄 수 있습니다.
`verbose`	`bool`	`True`	학습 중 상세 출력을 활성화하여 콘솔에 진행률 표시줄, 에포크별 지표, 추가 학습 정보를 표시합니다.
`single_cls`	`bool`	`False`	다중 클래스 데이터셋의 모든 클래스를 학습 중 단일 클래스로 취급합니다. 이진 분류 작업이나 분류보다 객체 존재 여부에 집중할 때 유용합니다.
`classes`	`list[int]`	`None`	학습에 사용할 클래스 ID 목록을 지정합니다. 학습 중 특정 클래스만 필터링하여 집중할 때 유용합니다.
`rect`	`bool`	`False`	최소 패딩 전략을 활성화합니다. 배치 내 이미지에 공통 크기를 적용하는 데 필요한 최소한의 패딩만 추가하며, 가장 긴 변은 `imgsz`과 같아집니다. 효율성과 속도를 높일 수 있지만 모델 정확도에 영향을 줄 수 있습니다.
`multi_scale`	`float`	`0.0`	각 배치에서 `imgsz`을 +/- `multi_scale`만큼 무작위로 변경합니다(예: `0.25` -> `0.75x`에서 `1.25x`까지). 값을 모델 스트라이드의 배수로 반올림하며, `0.0`는 멀티스케일 학습을 비활성화합니다.
`cos_lr`	`bool`	`False`	코사인 학습률 스케줄러를 사용하여 에포크에 따라 코사인 곡선 형태로 학습률을 조정합니다. 더 나은 수렴을 위해 학습률을 관리하는 데 도움이 됩니다.
`close_mosaic`	`int`	`10`	완료 전 학습을 안정화하기 위해 마지막 N개 에포크에서 모자이크 데이터 증강을 비활성화합니다. 0으로 설정하면 이 기능이 비활성화됩니다.
`resume`	`bool`	`False`	마지막으로 저장된 체크포인트부터 학습을 재개합니다. 모델 가중치, 옵티마이저 상태, 에포크 수를 자동으로 로드하여 학습을 원활하게 이어갑니다.
`amp`	`bool` 또는 `str`	`True`	학습 정밀도를 설정합니다. `True` 또는 `"fp16"`은 FP16을 사용하고, `"bf16"`는 지원되는 CUDA 장치에서 BF16을 사용하며, `False` 또는 `"fp32"`는 FP32를 사용합니다.
`quantize`	`int` 또는 `str`	`None`	INT8 양자화 인식 학습(QAT)을 활성화하려면 `8`(또는 `"int8"`)로 설정합니다. 가짜 양자화를 학습 루프에 적용해 파인튜닝함으로써 가중치가 INT8 내보내기를 지원하도록 합니다. 양자화 인식 학습을 참조하세요.
`fraction`	`float`, `int` 또는 `list`	`1.0`	데이터셋 하위 집합을 비율/개수 또는 `[train, val, test]` 목록으로 지정합니다. `1`은 전체 분할을 의미하고, `1`보다 큰 정수는 이미지 개수입니다. 선택적 테스트 항목에만 `0`/`0.0`를 지정하여 테스트 데이터가 없음을 나타낼 수 있습니다. 두 항목으로 된 목록은 테스트 데이터를 전체로 유지합니다.
`profile`	`bool`	`False`	학습 중 ONNX 및 TensorRT 속도 프로파일링을 활성화합니다. 모델 배포 최적화에 유용합니다.
`freeze`	`int` 또는 `list`	`None`	모델의 처음 N개 레이어 또는 인덱스나 모듈 이름으로 지정한 특정 레이어(`23.cv2`, 앞의 `model.` 제외)를 고정하여 학습 가능한 파라미터 수를 줄입니다. 파인튜닝 또는 전이 학습에 유용합니다.
`lr0`	`float`	`0.01`	초기 학습률(즉, `SGD=1E-2`, `Adam=1E-3`)입니다. 기본값인 `optimizer='auto'`에서는 무시되며, 사용하려면 옵티마이저를 명시적으로 지정해야 합니다.
`lrf`	`float`	`0.01`	초기 학습률 대비 최종 학습률의 비율 = (`lr0 * lrf`)입니다. 스케줄러와 함께 사용하여 시간에 따라 학습률을 조정합니다.
`momentum`	`float`	`0.937`	SGD의 모멘텀 계수 또는 Adam 옵티마이저의 beta1입니다. 현재 업데이트에 이전 그래디언트를 반영하는 정도를 결정합니다.
`weight_decay`	`float`	`0.0005`	과적합을 방지하기 위해 큰 가중치에 페널티를 부여하는 L2 정규화 항입니다.
`warmup_epochs`	`float`	`3.0`	학습률 워밍업에 사용할 에포크 수입니다. 초기에 학습을 안정화하기 위해 학습률을 낮은 값에서 초기 학습률까지 점진적으로 높입니다.
`warmup_momentum`	`float`	`0.8`	워밍업 단계의 초기 모멘텀입니다. 워밍업 기간 동안 설정된 모멘텀으로 점진적으로 조정됩니다.
`warmup_bias_lr`	`float`	`0.1`	워밍업 단계에서 바이어스 파라미터에 적용되는 학습률로, 초기 에포크의 모델 학습을 안정화하는 데 도움이 됩니다. 기본 `optimizer='auto'`에서는 `0.0`으로 자동 설정되므로, 사용하려면 옵티마이저를 명시적으로 지정해야 합니다.
`distill_model`	`str`	`None`	지식 증류에 사용할 교사 모델 체크포인트의 경로입니다(예: `yolo26x.pt`). 이 값을 설정하면 고정된 교사의 지도를 받는 추가 증류 손실을 사용하여 학생 모델을 학습합니다.
`dis`	`float`	`6.0`	표준 감지 손실에 더해지는 증류 손실의 가중치입니다. 값이 클수록 교사의 특징 지도 영향이 커집니다.
`box`	`float`	`7.5`	손실 함수의 박스 손실 구성요소 가중치로, 경계 상자 좌표를 정확하게 예측하는 데 부여되는 비중을 결정합니다.
`cls`	`float`	`0.5`	전체 손실 함수에서 분류 손실의 가중치로, 다른 구성요소에 비해 올바른 클래스를 예측하는 것의 중요도에 영향을 줍니다.
`cls_pw`	`float`	`0.0`	역 클래스 빈도를 사용하여 클래스 불균형을 처리하는 클래스 가중치의 지수입니다. `0.0`은 클래스 가중치를 비활성화하고, `1.0`은 역 빈도 가중치를 전부 적용합니다. 0과 1 사이의 값은 부분 가중치를 적용합니다.
`dfl`	`float`	`1.5`	박스 거리 회귀 항의 가중치입니다. 감지 헤드가 `reg_max > 1`을 사용하는 경우 분포 초점 손실(DFL)을 사용하고, DFL이 없는 YOLO26에서는 정규화된 박스 거리에 L1 손실을 적용합니다(`reg_max: 1`).
`pose`	`float`	`12.0`	자세 추정으로 학습된 모델의 자세 손실 가중치로, 자세 키포인트를 정확하게 예측하는 데 부여되는 비중을 결정합니다.
`kobj`	`float`	`1.0`	자세 추정 모델에서 키포인트 객체성 손실의 가중치로, 감지 신뢰도와 자세 정확도의 균형을 조정합니다.
`rle`	`float`	`1.0`	자세 추정 모델의 잔차 로그 우도 추정 손실 가중치로, 키포인트 위치 지정의 정밀도에 영향을 줍니다.
`angle`	`float`	`1.0`	OBB 모델의 각도 손실 가중치로, 방향 경계 상자 각도 예측의 정밀도에 영향을 줍니다.
`dlog`	`float`	`1.0`	깊이 추정 모델에서 척도 불변 로그(SILog) 손실의 가중치로, 깊이 정확도를 좌우하는 주요 항입니다.
`dgrad`	`float`	`0.5`	깊이 추정 모델의 그래디언트 손실 가중치입니다. 깊이 경계의 오류에 페널티를 부여하고 더 선명한 표면 경계를 유도합니다.
`dlam`	`float`	`1.0`	깊이 추정 모델에서 SILog 손실의 분산 집중 계수입니다. `1.0`은 손실을 완전히 척도 불변으로 만들고, `0.0`은 일반 로그-RMSE로 줄입니다.
`nbs`	`int`	`64`	손실 정규화에 사용할 기준 배치 크기입니다.
`overlap_mask`	`bool`	`True`	학습을 위해 객체 마스크를 단일 마스크로 병합할지, 객체별로 분리하여 유지할지 결정합니다. 병합 중 겹치는 영역이 있으면 작은 마스크가 큰 마스크 위에 배치됩니다.
`mask_ratio`	`int`	`4`	분할 마스크의 다운샘플링 비율로, 학습 중 사용되는 마스크의 해상도에 영향을 줍니다. 예측된 마스크의 해상도는 변경하지 않습니다.
`dropout`	`float`	`0.0`	분류 작업의 정규화에 사용할 드롭아웃 비율입니다. 학습 중 유닛을 무작위로 제외하여 과적합을 방지합니다.
`val`	`bool`	`True`	학습 중 검증을 활성화하여 별도의 데이터셋에서 모델 성능을 주기적으로 평가할 수 있습니다.
`nms`	`bool`, 선택 사항	`None`	에포크 검증, 체크포인트 선택, 조기 종료에 사용할 추론 헤드를 선택합니다. `None` 또는 `True`은 NMS를 사용하는 일대다 헤드를 사용하고, `False`는 사용 가능한 경우 NMS가 필요 없는 헤드를 사용합니다. 두 헤드 모두 학습 손실을 유지합니다.
`plots`	`bool`	`True`	학습 및 검증 지표와 예측 예시의 플롯을 생성하고 저장하여 모델 성능과 학습 진행 상황을 시각적으로 확인할 수 있습니다.
`compile`	`bool` 또는 `str`	`False`	`backend='inductor'`을 사용하여 PyTorch 2.x `torch.compile` 그래프 컴파일을 활성화합니다. `True` → `"default"`, `False` → 비활성화, 또는 `"default"`, `"reduce-overhead"`, `"max-autotune-no-cudagraphs"`과 같은 문자열 모드를 지정할 수 있습니다. 지원되지 않으면 경고를 표시하고 eager 모드로 대체합니다.
`channels_last`	`bool`	`None`	학습 중 컨볼루션에 channels_last(NHWC) 메모리 형식을 사용합니다. `None`은 Windows를 제외하고 CUDA에서 PyTorch 1.11 이상을 사용할 때 자동으로 활성화합니다. Windows에서는 성능이 더 느린 것으로 측정되었습니다. `False`은 비활성화하고 `True`는 명시적으로 활성화합니다. CPU 또는 MPS에서 학습할 때는 항상 NCHW를 사용합니다(`True`은 경고와 함께 무시됩니다).
`max_det`	`int`	`300`	학습 검증 중 이미지당 최대 감지 수입니다. detect, segment, pose, OBB 작업에서는 학습/검증 라벨 객체 수가 300을 초과하는 경우에만 기본값 300이 가장 큰 객체 수까지 증가합니다. 그 외 값은 고정됩니다. 한도를 초과하면 경고가 표시됩니다.

배치 크기 설정에 대한 참고 사항

batch 인수에는 다음 세 가지 구성 옵션이 있습니다.

고정 배치 크기: 정수로 배치당 이미지 수를 지정합니다(예: batch=16).
자동 모드(GPU 메모리 60%): batch=-1을 사용하면 CUDA 메모리 사용률이 약 60%가 되도록 자동으로 조정합니다.
사용률 비율 지정 자동 모드: 비율을 설정하여(예: batch=0.70) 지정한 GPU 메모리 사용량에 맞춰 조정합니다.
적합한 크기를 찾지 못한 경우: 사용 가능한 프로파일을 생성하는 후보 배치 크기가 없으면 AutoBatch는 관련 없는 기본값으로 조용히 대체하는 대신 명확한 RuntimeError을 발생시킵니다.

학습 가이드

예측 설정#

YOLO 모델의 예측 설정에는 추론 중 성능, 속도, 정확도에 영향을 미치는 하이퍼파라미터와 구성이 포함됩니다. 주요 설정에는 신뢰도 임계값, 비최대 억제(NMS) 임계값, 클래스 수가 있습니다. 입력 데이터의 크기와 형식, 마스크와 같은 추가 기능도 예측에 영향을 줍니다. 최적의 성능을 위해서는 이러한 설정을 튜닝해야 합니다.

추론 인수:

인수	유형	기본값	설명
`source`	`str` 또는 `int` 또는 `None`	`None`	추론할 데이터 소스를 지정합니다. 이미지 경로, 동영상 파일, 디렉터리, URL 또는 라이브 피드용 장치 ID를 지정할 수 있습니다. 생략하면 경고가 로그에 기록되고 모델은 기본 제공 데모 에셋(`ultralytics/assets` 또는 OBB용 데모 URL)을 사용합니다. 다양한 형식과 소스를 지원하여 다양한 유형의 입력에 유연하게 적용할 수 있습니다.
`conf`	`float`	`0.25`	감지의 최소 신뢰도 임계값을 설정합니다. 신뢰도가 이 임계값보다 낮은 객체는 무시됩니다. 이 값을 조정하면 오탐을 줄일 수 있습니다.
`iou`	`float`	`0.7`	비최대 억제(NMS)에 적용되는 교집합 대비 합집합(IoU) 임계값입니다. 값을 낮추면 겹치는 박스를 제거하여 감지 수가 줄어들므로 중복을 줄이는 데 유용합니다.
`imgsz`	`int` 또는 `tuple`	`640`	레터박스 목표 크기입니다. 정수는 정사각형 `N×N`을 지정하고, 튜플은 `(height, width)`을 지정합니다. `rect=True`를 사용하면 최소 직사각형 패딩으로 인해 실제 텐서가 목표 크기보다 작을 수 있습니다. 고정 크기를 사용하려면 `rect=False`을 지정하세요. 고정 형식과 최소 직사각형 비교를 참조하세요.
`rect`	`bool`	`True`	`True`인 경우 가능하면 최소 직사각형 패딩을 사용합니다(동일한 형태의 배치 및 지원되는 백엔드). `False`인 경우 항상 전체 `imgsz` 크기에 맞춰 패딩합니다. 고정 형식과 최소 직사각형 비교를 참조하세요.
`quantize`	`int` 또는 `str`	`None`	추론 정밀도입니다. `16`/`"fp16"` 및 `32`/`"fp32"`/미설정 값은 PyTorch 및 TorchScript 모델의 FP16 또는 FP32 계산을 선택합니다. 다른 형식은 아티팩트와 런타임이 선택한 정밀도로 계산합니다. `16`에서는 OpenVINO가 클라이언트에서 입력을 FP16으로 반올림한 다음 FP32로 확장하지만, 런타임이 실제 계산에 사용하는 정밀도는 변경하지 않습니다. INT8/PTQ 양자화는 내보내기 중 구성한 다음 내보낸 모델을 로드하여 사용합니다. 더 이상 사용되지 않는 `half` 플래그를 대체합니다.
`device`	`str`	`None`	추론에 사용할 장치를 지정합니다(예: `cpu`, `cuda:0`, `0`, `npu` 또는 `npu:0`). CPU, 특정 GPU, Huawei Ascend NPU 또는 기타 계산 장치 중에서 선택하여 모델을 실행할 수 있습니다.
`dnn`	`bool`	`False`	`True`이면 ONNX 모델 추론에 ONNX Runtime 대신 OpenCV DNN 모듈을 사용합니다.
`data`	`str`	`None`	데이터셋 YAML 경로(예: `coco8.yaml`)입니다. YAML은 `names`에 대해서만 읽으며, 로드된 모델에 자체 클래스 이름이 없는 경우에만 사용됩니다. 여기에 해당하는 모델은 타사에서 내보낸 모델이거나, 함께 제공되는 메타데이터와 분리된 Ultralytics 내보내기 모델입니다. 그렇지 않은 경우 이러한 모델은 `class0`, `class1` 등을 보고합니다.
`batch`	`int`	`1`	추론 배치 크기를 지정합니다(소스가 디렉터리, 비디오 파일 또는 `.txt` 파일인 경우에만 작동합니다). 배치 크기를 늘리면 처리량이 향상되어 추론에 필요한 전체 시간이 단축될 수 있습니다.
`max_det`	`int`	`300`	이미지당 허용되는 최대 감지 수입니다. 한 번의 추론에서 모델이 감지할 수 있는 객체의 총수를 제한하여 밀집된 장면에서 출력이 지나치게 많아지는 것을 방지합니다.
`vid_stride`	`int`	`1`	비디오 입력의 프레임 간격입니다. 시간 해상도를 낮추는 대신 비디오의 프레임을 건너뛰어 처리 속도를 높입니다. 값이 1이면 모든 프레임을 처리하고, 더 큰 값이면 프레임을 건너뜁니다.
`stream_buffer`	`bool`	`False`	비디오 스트림의 입력 프레임을 대기열에 넣을지 결정합니다. `False`이면 새 프레임을 수용하기 위해 오래된 프레임을 삭제합니다(실시간 애플리케이션에 최적화됨). `True`이면 새 프레임을 버퍼에 대기시켜 프레임을 건너뛰지 않지만, 추론 FPS가 스트림 FPS보다 낮으면 지연이 발생합니다.
`visualize`	`bool`	`False`	각 예측 결과 옆에 클래스 활성화 히트맵을 저장하여 예측 클래스 점수를 높인 픽셀을 표시합니다. `conf` 및 `classes`을 따르므로 `classes=[0]`는 해당 클래스만 매핑합니다. Ultralytics PyTorch 모델에서만 사용할 수 있습니다.
`augment`	`bool`	`False`	예측에 테스트 시점 증강(TTA)을 적용하여 추론 속도가 느려질 수 있는 대신 감지 견고성을 높입니다. Ultralytics PyTorch 모델에서만 사용할 수 있습니다.
`agnostic_nms`	`bool`	`False`	클래스 구분 없는 비최대 억제(NMS)를 활성화하여 같은 클래스 내에서만 억제하는 대신 서로 다른 클래스에 걸친 겹치는 상자 중 점수가 낮은 상자를 억제합니다. 클래스 간 중첩이 흔한 다중 클래스 감지 시나리오에 유용합니다. NMS가 없는 추론(YOLO26 또는 YOLOv10에서 `nms=False`)에서는 동일한 감지가 여러 클래스 레이블로 나타나는 것(IoU=1.0 중복)만 방지하며, 서로 다른 상자 간 IoU 임계값 기반 억제는 수행하지 않습니다.
`classes`	`list[int]`	`None`	예측 결과를 클래스 ID 집합으로 필터링합니다. 지정된 클래스에 속하는 감지만 반환합니다. 다중 클래스 감지 작업에서 관련 객체에 집중할 때 유용합니다.
`retina_masks`	`bool`	`False`	고해상도 분할 마스크를 반환합니다. 활성화하면 반환된 마스크(`masks.data`)가 원본 이미지 크기와 일치합니다. 비활성화하면 추론에 사용된 이미지 크기의 마스크를 반환합니다.
`embed`	`list[int]`	`None`	특징 벡터 또는 임베딩을 추출할 레이어를 지정합니다. `model.embed(source)`은 끝에서 두 번째 레이어의 임베딩을 사용하고, `model.predict(source, embed=[layer])`는 특정 레이어를 선택합니다. 클러스터링이나 유사도 검색과 같은 다운스트림 작업에 유용합니다. Ultralytics PyTorch 모델에서만 사용할 수 있습니다.
`project`	`str`	`None`	`save`이 활성화된 경우 예측 출력을 저장할 프로젝트 디렉터리의 이름입니다.
`name`	`str`	`None`	예측 실행의 이름입니다. `save`이 활성화된 경우 프로젝트 폴더 안에 하위 디렉터리를 만들어 예측 출력을 저장하는 데 사용됩니다.
`stream`	`bool`	`False`	모든 프레임을 한꺼번에 메모리에 로드하는 대신 Results 객체의 생성기를 반환하여 긴 비디오나 다수의 이미지를 메모리 효율적으로 처리합니다.
`verbose`	`bool`	`True`	터미널에 자세한 추론 로그를 표시할지 제어하여 예측 과정에 대한 실시간 피드백을 제공합니다.
`compile`	`bool` 또는 `str`	`False`	`backend='inductor'`을 사용하여 PyTorch 2.x `torch.compile` 그래프 컴파일을 활성화합니다. `True` → `"default"`, `False` → 비활성화, 또는 `"default"`, `"reduce-overhead"`, `"max-autotune-no-cudagraphs"`과 같은 문자열 모드를 지정할 수 있습니다. 지원되지 않으면 경고를 표시하고 eager 모드로 대체합니다.
`channels_last`	`bool`	`None`	네이티브 PyTorch 추론에 channels_last(NHWC) 메모리 형식을 사용합니다. `None`은 PyTorch 1.13 이상을 사용하는 oneDNN 지원 Linux 및 Windows x86 CPU에서 자동으로 활성화하고, `False`은 비활성화하며, `True`는 지원되는 x86 CPU 또는 CUDA 장치에서 사용하도록 요청합니다. ARM64, MPS, 이전 PyTorch 버전, oneDNN을 지원하지 않는 CPU, TensorRT 및 ONNX와 같은 내보내기 형식은 변경되지 않습니다.
`nms`	`bool`, 선택 사항	`None`	기본적으로 NMS를 적용하는 일대다 추론을 실행합니다(`None` 또는 `True`). 사용 가능한 경우 NMS가 없는 일대일 헤드를 사용하려면 `False`로 설정합니다. 자세한 내용은 엔드투엔드 감지 가이드를 참조하세요.

시각화 인수:

인수	유형	기본값	설명
`show`	`bool`	`False`	`True`이면 주석이 추가된 이미지나 비디오를 창에 표시합니다. 개발 또는 테스트 중 즉각적인 시각적 피드백을 얻는 데 유용합니다.
`save`	`bool`	`False or True`	주석이 추가된 이미지나 비디오를 파일로 저장합니다. 문서화, 추가 분석 또는 결과 공유에 유용합니다. CLI 사용 시 기본값은 True이고, Python에서 사용 시 기본값은 False입니다.
`save_frames`	`bool`	`False`	비디오를 처리할 때 개별 프레임을 이미지로 저장합니다. 특정 프레임 추출이나 프레임별 상세 분석에 유용합니다.
`save_txt`	`bool`	`False`	감지 결과를 `[class] [x_center] [y_center] [width] [height] [confidence]` 형식에 따라 텍스트 파일로 저장합니다. 다른 분석 도구와 통합할 때 유용합니다.
`save_conf`	`bool`	`False`	저장된 텍스트 파일에 신뢰도 점수를 포함합니다. 후처리 및 분석에 사용할 수 있는 세부 정보가 늘어납니다.
`save_crop`	`bool`	`False`	감지된 객체의 크롭 이미지를 저장합니다. 데이터셋 증강, 분석 또는 특정 객체에 집중한 데이터셋 생성에 유용합니다.
`show_labels`	`bool`	`True`	시각화 출력에 각 감지 결과의 레이블을 표시합니다. 감지된 객체를 즉시 파악할 수 있습니다.
`show_conf`	`bool`	`True`	각 감지 결과의 레이블 옆에 신뢰도 점수를 표시합니다. 각 감지 결과에 대한 모델의 확신도를 파악할 수 있습니다.
`show_boxes`	`bool`	`True`	감지된 객체 주위에 경계 상자를 그립니다. 이미지나 비디오 프레임에서 객체를 시각적으로 식별하고 위치를 파악하는 데 필수적입니다.
`line_width`	`int or None`	`None`	경계 상자의 선 너비를 지정합니다. `None`이면 이미지 크기에 따라 선 너비를 자동으로 조정합니다. 가독성을 높이기 위해 시각적 설정을 사용자 지정할 수 있습니다.

예측 가이드

검증 설정#

YOLO 모델 검증 설정에는 검증 데이터셋에서 성능을 평가하기 위한 하이퍼파라미터와 구성이 포함됩니다. 이러한 설정은 성능, 속도 및 정확도에 영향을 미칩니다. 일반적인 설정에는 배치 크기, 검증 빈도 및 성능 지표가 포함됩니다. 검증 데이터셋의 크기와 구성, 그리고 구체적인 작업도 검증 과정에 영향을 미칩니다.

인수	유형	기본값	설명
`data`	`str`	`None`	데이터셋 YAML의 경로(예: `coco8.yaml`)를 지정하며, YAML에는 검증 데이터 경로가 포함되어야 합니다. 분류 작업에서는 데이터셋 디렉터리 또는 기본 제공 데이터셋 이름(예: `imagenet10`)을 사용합니다.
`imgsz`	`int`	`640`	입력 이미지 크기를 정의합니다. 처리 전에 모든 이미지의 크기를 이 크기로 조정합니다. 크기를 늘리면 작은 객체의 정확도가 향상될 수 있지만 계산 시간이 늘어납니다.
`batch`	`int`	`16`	배치당 이미지 수를 설정합니다. 값이 클수록 GPU 메모리를 효율적으로 사용하지만 더 많은 VRAM이 필요합니다. 사용 가능한 하드웨어 리소스에 맞게 조정하세요.
`save_json`	`bool`	`False`	`True`이면 추가 분석, 다른 도구와의 통합 또는 COCO와 같은 평가 서버 제출을 위해 결과를 JSON 파일로 저장합니다. 감지 데이터셋에서는 예측 결과를 `faster-coco-eval`로 평가하고, 학습 중 `results.csv`의 `metrics/mAP_small(B)`, `metrics/mAP_medium(B)`, `metrics/mAP_large(B)`로 기록되는 소형·중형·대형 객체 mAP도 보고합니다.
`conf`	`float`	`0.001`	감지 결과의 최소 신뢰도 임계값을 설정합니다. 값을 낮추면 재현율이 높아지지만 오탐이 늘어날 수 있습니다. 정밀도-재현율 곡선, mAP 및 감지 혼동 행렬은 모두 이 값을 사용합니다. `0.25`과 같은 더 높은 `conf`은 예측 출력과 더 가까운 혼동 행렬을 제공하지만 mAP를 낮출 수 있습니다. 요약 정밀도와 재현율은 최대 F1 신뢰도를 사용하므로 `confusion_matrix.png`에서 산출한 값과 다를 수 있습니다. 메모리 사용량을 줄이기 위해 OBB 검증의 기본값은 `0.01`입니다.
`iou`	`float`	`0.7`	비최대 억제를 위한 교집합 대비 합집합 임계값을 설정합니다. 중복 감지를 제거하는 기준을 제어합니다.
`max_det`	`int`	`300`	이미지당 최대 감지 수를 제한합니다. detect, segment, pose 및 OBB에서는 기본값 300으로 설정된 경우 이미지의 감지 수가 이를 초과하면 경고를 표시하고 검증 분할에서 레이블이 지정된 객체 수의 최댓값까지 한도를 늘립니다. 다른 값은 그대로 유지되며, 이미지의 감지 수가 이를 초과하면 재현율이 제한될 수 있다는 경고가 표시됩니다.
`quantize`	`int` 또는 `str`	`None`	검증 정밀도: `16`/`"fp16"` 및 `32`/`"fp32"`/미설정은 PyTorch 및 TorchScript 모델의 FP16 또는 FP32 연산을 선택합니다. 다른 형식은 아티팩트와 런타임이 선택한 정밀도로 연산합니다. `16`에서는 OpenVINO가 클라이언트에서 입력을 FP16으로 반올림한 뒤 FP32로 다시 확장하지만, 런타임의 연산 정밀도는 변경하지 않습니다. INT8/PTQ 양자화는 내보내기 중에 구성한 뒤 내보낸 모델을 검증할 때 사용합니다. 더 이상 사용되지 않는 `half` 플래그를 대체합니다.
`device`	`str`	`None`	검증에 사용할 장치(`cpu`, `cuda:0`, `npu`, `npu:0` 등)를 지정합니다. `None`이면 사용 가능한 장치 중 최적의 장치를 자동으로 선택합니다. 여러 CUDA 장치는 쉼표로 구분해 지정할 수 있습니다.
`dnn`	`bool`	`False`	`True`이면 ONNX 모델 추론에 OpenCV DNN 모듈을 사용하여 PyTorch 추론 방식의 대안을 제공합니다.
`plots`	`bool`	`True`	`True`으로 설정하면 모델 성능을 시각적으로 평가할 수 있도록 예측 결과와 정답 비교 그래프, 혼동 행렬, PR 곡선을 생성하고 저장합니다.
`classes`	`list[int]`	`None`	평가할 클래스 ID 목록을 지정합니다. 평가 중 특정 클래스만 포함하도록 필터링하고 집중할 때 유용합니다.
`rect`	`bool`	`True`	`True`이면 배치 처리에 직사각형 추론을 사용하여 패딩을 줄이고, 원본 종횡비로 이미지를 처리해 속도와 효율성을 높일 수 있습니다. 모든 이미지를 패딩하지 않고 고정된 `imgsz` 정사각형으로 늘리는 `depth` 검증에서는 무시됩니다.
`split`	`str`	`'val'`	검증에 사용할 데이터셋 분할(`val`, `test` 또는 `train`)을 결정합니다. 성능 평가에 사용할 데이터 부분을 유연하게 선택할 수 있습니다.
`fraction`	`float`, `int` 또는 `list`	`1.0`	검증 분할의 하위 집합입니다. `[train, val, test]` 목록을 사용하면 `split`에 해당하는 항목이 적용됩니다(`1` = 전체 분할, `1`보다 큰 정수 = 이미지 수, 생략된 항목 = 전체). 스칼라 값은 `split=train`에만 적용되며, 이 경우 `val` 및 `test`은 전체 분할을 사용합니다.
`project`	`str`	`None`	검증 출력을 저장할 프로젝트 디렉터리의 이름입니다. 여러 실험 또는 모델의 결과를 정리하는 데 도움이 됩니다.
`name`	`str`	`None`	검증 실행의 이름입니다. 프로젝트 폴더 안에 하위 디렉터리를 만들어 검증 로그와 출력을 저장하는 데 사용됩니다.
`verbose`	`bool`	`True`	`True`이면 클래스별 지표, 배치 진행 상황 및 추가 디버깅 정보를 포함해 검증 과정의 자세한 정보를 표시합니다.
`save_txt`	`bool`	`False`	`True`이면 이미지당 하나씩 텍스트 파일에 감지 결과를 저장합니다. 추가 분석, 사용자 지정 후처리 또는 다른 시스템과의 통합에 유용합니다.
`save_conf`	`bool`	`False`	`True`이면 `save_txt`이 활성화된 경우 저장된 텍스트 파일에 신뢰도 값을 포함하여 분석 및 필터링에 더 상세한 출력을 제공합니다.
`workers`	`int`	`8`	데이터 로딩에 사용할 작업자 스레드 수입니다. 값을 높이면 데이터 전처리 속도가 빨라질 수 있지만 CPU 사용량이 늘어날 수 있습니다. 0으로 설정하면 메인 스레드를 사용하며, 일부 환경에서 안정성이 향상될 수 있습니다.
`augment`	`bool`	`False`	검증 중 테스트 시점 증강(TTA)을 활성화합니다. 입력의 변환된 버전으로 추론을 수행하여 추론 속도가 느려질 수 있는 대신 감지 정확도를 높일 수 있습니다. Ultralytics PyTorch 모델에서만 사용할 수 있습니다.
`agnostic_nms`	`bool`	`False`	클래스 구분 없는 비최대 억제를 활성화하여 예측 클래스와 관계없이 겹치는 상자 중 점수가 낮은 상자를 억제합니다. 인스턴스 중심 애플리케이션에 유용합니다. NMS가 없는 추론(YOLO26 또는 YOLOv10에서 `nms=False`)에서는 동일한 감지가 여러 클래스 레이블로 나타나는 것(IoU=1.0 중복)만 방지하며, 서로 다른 상자 간 IoU 임계값 기반 억제는 수행하지 않습니다.
`single_cls`	`bool`	`False`	검증 중 모든 클래스를 단일 클래스로 취급합니다. 이진 감지 작업에서 모델 성능을 평가하거나 클래스 구분이 중요하지 않을 때 유용합니다.
`visualize`	`bool`	`False`	각 이미지의 정답, 참양성, 거짓양성 및 거짓음성을 시각화합니다. 디버깅과 모델 해석에 유용합니다.
`show_labels`	`bool`	`True`	`visualize=True`이면 검증 시각화에 클래스 레이블을 표시합니다. 대응 결과와 오류를 더 깔끔하게 보려면 `False`로 설정하세요.
`show_conf`	`bool`	`True`	`visualize=True`이면 검증 시각화에 신뢰도 점수를 표시합니다. 대응 결과와 오류를 더 깔끔하게 보려면 `False`로 설정하세요.
`compile`	`bool` 또는 `str`	`False`	`backend='inductor'`을 사용하여 PyTorch 2.x `torch.compile` 그래프 컴파일을 활성화합니다. `True` → `"default"`, `False` → 비활성화, 또는 `"default"`, `"reduce-overhead"`, `"max-autotune-no-cudagraphs"`과 같은 문자열 모드를 지정할 수 있습니다. 지원되지 않으면 경고를 표시하고 eager 모드로 대체합니다.
`channels_last`	`bool`	`None`	네이티브 PyTorch 검증에 channels_last(NHWC) 메모리 형식을 사용합니다. `None`은 PyTorch 1.13 이상을 사용하는 oneDNN 지원 Linux 및 Windows x86 CPU에서 자동으로 활성화하고, `False`은 비활성화하며, `True`는 지원되는 x86 CPU 또는 CUDA 장치에서 사용하도록 요청합니다. ARM64, MPS, 이전 PyTorch 버전, oneDNN을 지원하지 않는 CPU 및 내보낸 형식은 변경되지 않습니다. 학습 중 검증은 학습 모델의 레이아웃을 유지합니다.
`nms`	`bool`, 선택 사항	`None`	기본적으로 NMS를 적용하는 일대다 추론을 실행합니다(`None` 또는 `True`). 사용 가능한 경우 NMS가 없는 일대일 헤드를 사용하려면 `False`로 설정합니다. 자세한 내용은 엔드투엔드 감지 가이드를 참조하세요.

최적의 성능을 보장하고 과적합을 감지 및 방지하려면 신중한 튜닝과 실험이 중요합니다.

검증 가이드

내보내기 설정#

YOLO 모델 내보내기 설정에는 다양한 환경에서 모델을 사용할 수 있도록 모델을 저장하거나 내보내는 구성이 포함됩니다. 이러한 설정은 성능, 크기 및 호환성에 영향을 미칩니다. 주요 설정에는 내보낼 파일 형식(예: ONNX, TensorFlow SavedModel), 대상 장치(예: CPU, GPU), 마스크와 같은 기능이 포함됩니다. 모델의 작업과 대상 환경의 제약 조건도 내보내기 과정에 영향을 미칩니다.

인수	유형	기본값	설명
`format`	`str`	`'torchscript'`	내보낸 모델의 대상 형식입니다. `'onnx'`, `'torchscript'`, `'engine'`(TensorRT) 등이 있습니다. 형식마다 서로 다른 배포 환경과의 호환성을 제공합니다.
`name`	`str`	`None`	지원이 필요한 형식의 하드웨어 타깃 이름: Hailo 아키텍처(`'hailo8'`, `'hailo8l'`, `'hailo10h'`, `'hailo15h'`, `'hailo15l'`; 기본값은 `'hailo8l'`), Rockchip RKNN 칩(기본값은 `'rk3588'`), Huawei Ascend SoC(CANN `--soc_version`; 기본값은 `'Ascend310B4'`), Qualcomm QNN HTP 타깃(기본값은 `'73'`), 또는 AMD Xilinx Versal AI Edge Series Gen 2 디바이스(기본값은 `'ve2-xc2ve3858'`, VEK385 평가 키트)입니다. 다른 모드에서 사용하는 `project`/`name` 실행 이름 쌍과는 별개입니다.
`imgsz`	`int` 또는 `tuple`	`640`	모델 입력에 사용할 이미지 크기입니다. 정사각형 이미지의 경우 정수(예: 640×640을 나타내는 `640`)를 사용하거나, 특정 크기의 경우 튜플 `(height, width)`을 사용할 수 있습니다. 지정하지 않으면 내보내기에 로드된 체크포인트에 기록된 학습 크기를 재사용합니다. 공식 YOLO26 체크포인트는 depth의 경우 `768`, classify의 경우 `224`, OBB의 경우 `1024`, 그 외 작업의 경우 `640`를 기록하며, 파인튜닝된 모델은 학습에 사용한 `imgsz`을 기록합니다. YAML에서 생성한 모델에는 기록된 학습 크기가 없으므로 `640`을 사용합니다.
`optimize`	`bool`	`False`	DEEPX의 컴파일러 최적화 수준을 높여 컴파일 시간을 늘리는 대신 추론 지연 시간을 줄입니다.
`quantize`	`int` 또는 `str`	`None`	양자화 정밀도: `16` (FP16, 모델 크기를 줄이고 지원되는 하드웨어에서 추론 속도를 높일 수 있습니다) 또는 `8` (INT8/PTQ, 정확도 손실을 최소화하면서 모델을 추가로 압축하며, 주로 엣지 디바이스에 사용되고 캘리브레이션에는 `data`/`fraction` 옵션이 필요합니다); `32`/미설정은 FP32입니다. `quantize=8`로 학습된 체크포인트는 항상 INT8로 내보냅니다: `onnx` 및 `engine`는 캘리브레이션 없이 체크포인트가 보유한 범위를 사용해 내보내며, 다른 형식이나 정밀도는 거부됩니다. `'w8a8'` 및 `'w16a16'`은 `8` 및 `16`의 별칭이며, 혼합 정밀도인 `'w8a16'`(16비트 활성화를 사용하는 INT8 가중치: CoreML, LiteRT, QNN)와 `'w8a32'`(동적 INT8: LiteRT)는 해당 형식에서만 허용됩니다. 더 이상 권장되지 않는 `half`/`int8` 플래그를 대체합니다 (`half=True` → `16`, `int8=True` → `8`; 기존 플래그는 사용 중단 경고와 함께 계속 허용됩니다). 대상 형식에서 지원하는 정밀도만 허용됩니다(아래를 참조하시기 바랍니다).
`dynamic`	`bool`	`False`	TorchScript, ONNX, OpenVINO, TensorRT, CoreML 및 MNN 내보내기에서 동적 입력 크기를 허용하여 다양한 이미지 크기를 유연하게 처리할 수 있습니다.
`simplify`	`bool`	`True`	내보내기 형식을 참고하세요. ONNX 그래프를 생성하는 내보내기의 중간 ONNX 그래프를 `onnxslim`으로 단순화하여 추론 엔진의 성능과 호환성을 높일 수 있습니다.
`opset`	`int`	`None`	ONNX 그래프를 생성하는 내보내기의 ONNX opset 버전을 지정합니다(내보내기 형식 참조). 다양한 ONNX 파서 및 런타임과의 호환성을 위한 설정입니다. 지정하지 않으면 지원되는 최신 버전을 사용합니다.
`workspace`	`float` 또는 `None`	`None`	메모리 사용량과 성능의 균형을 맞추기 위해 TensorRT 최적화에 사용할 최대 워크스페이스 크기를 GiB 단위로 설정합니다. 장치의 최대값까지 TensorRT가 자동으로 할당하도록 하려면 `None`을 사용하세요.
`nms`	`bool`, 선택 사항	`None`	`None`은 외부 NMS를 위한 원시 일대다 예측을 내보내고, `True`은 지원되는 경우 NMS를 내장하며, `False`는 사용 가능한 경우 NMS가 없는 헤드를 선택합니다. CoreML 내장 NMS는 고정된 형태의 detect, segment 및 pose를 지원합니다. 자세한 내용은 엔드투엔드 감지 가이드를 참조하세요.
`conf`	`float`	`None`	내보내기 시 NMS를 생성하는 다음 항목에서 사용하는 신뢰도 임계값입니다. `nms=True` 내보내기, Hailo의 비엔드투엔드 detect 내보내기, 내부적으로 `nms=True`을 강제하는 IMX의 detect, pose 및 segment 내보내기입니다. 설정하지 않은 경우 기본값은 `0.25`입니다.
`iou`	`float`	`0.7`	내보내기 시 NMS를 생성하는 다음 항목에서 사용하는 IoU 임계값입니다. `nms=True` 내보내기, Hailo의 비엔드투엔드 detect 내보내기, 내부적으로 `nms=True`를 강제하는 IMX의 detect, pose 및 segment 내보내기입니다.
`max_det`	`int`	`300`	내보낸 모델 출력에서 유지할 최대 감지 수입니다. CoreML 감지의 기본 NMS 파이프라인에는 감지 수 제한이 없으므로 이를 제외한 모든 형식의 `nms=True` 내보내기에 적용됩니다. 또한 NMS가 없는 엔드투엔드 감지 내보내기(YOLO26, YOLOv10, 사용 가능한 앵커 수로 제한됨)와 IMX의 detect, pose 및 segment 내보내기에도 적용됩니다.
`agnostic_nms`	`bool`	`False`	표준 `nms=True` 파이프라인을 통해 내보내기 시 NMS를 생성하는 모든 경우에 클래스 구분 없는 NMS를 활성화합니다. 여기에는 CoreML 자체 NMS 단계도 포함되며, 같은 클래스 내에서만 억제하는 대신 서로 다른 클래스에 걸친 겹치는 상자 중 점수가 낮은 상자를 억제합니다. 자체 NMS 구성을 생성하는 Hailo 또는 IMX에는 적용되지 않습니다. 해당 구성에는 클래스 구분 옵션이 없으므로 이 플래그와 관계없이 클래스 구분을 유지합니다. NMS가 없는 엔드투엔드 내보내기(YOLO26, YOLOv10)에도 적용됩니다. 이 경우 IoU 임계값에 따른 서로 다른 상자 간 억제가 아니라 동일한 감지가 여러 클래스 레이블로 나타나는 것(IoU=1.0 중복)만 방지합니다.
`batch`	`int`	`1`	내보낸 모델의 배치 추론 크기 또는 `predict` 모드에서 내보낸 모델이 동시에 처리할 최대 이미지 수를 지정합니다. 내보내기 인수에 `batch`이 없는 형식(Edge TPU, IMX500, DEEPX, Hailo, AMD Xilinx)은 배치 크기 1로 내보내며 다른 값은 거부합니다.
`device`	`str`	`None`	내보내기에 사용할 장치를 지정합니다. GPU(`device=0`), CPU(`device=cpu`), Apple silicon용 MPS(`device=mps`), Huawei Ascend NPU(`device=npu` 또는 `device=npu:0`), NVIDIA Jetson용 DLA(`device=dla:0` 또는 `device=dla:1`) 중에서 선택합니다. TensorRT 내보내기는 GPU를 자동으로 사용하지만 TensorRT 11.0은 DLA를 지원하지 않습니다.
`verbose`	`bool`	`False`	`format='engine'` 내보내기 중 TensorRT 빌더 로그의 심각도 수준을 VERBOSE로 높입니다. 다른 내보내기 형식에서는 무시됩니다.
`data`	`str`	`None`	INT8 양자화 보정에 필요한 데이터셋 YAML 경로입니다. 분류 작업에서는 데이터셋 디렉터리 또는 기본 제공 데이터셋 이름을 사용합니다. INT8이 활성화된 상태에서 지정하지 않으면 Ultralytics는 필요한 경우 작업별 보정 데이터셋을 선택하고, 그렇지 않으면 해당 모델 작업의 기본 데이터셋을 사용합니다. `quantize=8`로 학습된 체크포인트에는 자체 INT8 범위가 포함되어 있으므로 보정 데이터가 필요하지 않습니다.
`split`	`str`	`'val'`	`data`에서 INT8 양자화 보정 데이터 로더를 생성할 때 사용할 데이터셋 분할(`'train'`, `'val'` 또는 `'test'`)입니다.
`fraction`	`float`, `int` 또는 `list`	`1.0`	INT8 보정에 사용할 데이터셋 하위 집합입니다. 비율, 이미지 수 또는 `[train, val, test]` 값을 지정할 수 있습니다. `1`은 전체 분할을 의미하고, `1`보다 큰 정수는 이미지 수를 의미합니다. 선택적 test 항목에서만 `0`/`0.0`를 지정해 없음을 나타낼 수 있습니다. 두 항목으로 이루어진 목록에서는 `test`가 전체로 유지됩니다.

적절한 구성을 통해 내보낸 모델이 사용 사례에 맞게 최적화되고 대상 환경에서 효과적으로 작동하도록 할 수 있습니다.

내보내기 가이드

Solutions 설정#

Ultralytics Solutions 구성 설정을 사용하면 객체 수 세기, 히트맵 생성, 운동 추적, 데이터 분석, 구역 추적, 대기열 관리 및 영역 기반 수 세기와 같은 작업에 맞춰 모델을 유연하게 사용자 지정할 수 있습니다. 이러한 옵션을 사용하면 특정 요구 사항에 맞는 정확하고 유용한 결과를 얻도록 쉽게 조정할 수 있습니다.

인수	유형	기본값	설명
`model`	`str`	`None`	Ultralytics YOLO 모델 파일의 경로입니다.
`region`	`list` 또는 `dict`	`None`	관심 영역을 정의하는 점입니다. `(x, y)` 튜플 목록 또는 여러 영역에 대해 영역 이름을 점 목록에 매핑하는 사전(`RegionCounter`만 해당)으로 지정할 수 있습니다. `None`이면 영역이 필요한 Solutions는 사전 정의된 기본값을 사용합니다.
`show_in`	`bool`	`True`	비디오 스트림에 진입 수를 표시할지 제어하는 플래그입니다.
`show_out`	`bool`	`True`	비디오 스트림에 이탈 수를 표시할지 제어하는 플래그입니다.
`analytics_type`	`str`	`'line'`	그래프 유형입니다. `line`, `bar`, `area` 또는 `pie`을 지정할 수 있습니다.
`colormap`	`int`	`cv2.COLORMAP_DEEPGREEN`	히트맵에 사용할 컬러맵입니다.
`line_width`	`int`	`2`	Solution에서 그리는 상자, 키포인트 및 개수 표시의 선 두께입니다.
`verbose`	`bool`	`True`	프레임별 입력 형태, 클래스 개수 및 처리 속도 로그를 활성화합니다. 추적 호출 자체는 항상 로그를 출력하지 않습니다.
`json_file`	`str`	`None`	모든 주차 좌표 데이터가 포함된 JSON 파일의 경로입니다.
`up_angle`	`float`	`145.0`	'위' 자세의 각도 임계값입니다.
`kpts`	`list[int]`	`[6, 8, 10]`	운동 모니터링에 사용할 키포인트 인덱스 3개의 목록입니다. 이 키포인트는 팔굽혀펴기, 턱걸이, 스쿼트 및 복근 운동과 같은 운동에 필요한 어깨, 팔꿈치, 손목 등의 신체 관절이나 부위에 해당합니다.
`down_angle`	`float`	`90.0`	'아래' 자세의 각도 임계값입니다.
`blur_ratio`	`float`	`0.5`	블러 강도의 비율을 조정하며, 값의 범위는 `0.1 - 1.0`입니다.
`crop_dir`	`str`	`'cropped-detections'`	잘라낸 감지 결과를 저장할 디렉터리 이름입니다.
`records`	`int`	`5`	보안 경보 시스템에서 이메일을 트리거하는 총 감지 횟수입니다.
`vision_point`	`tuple[int, int]`	`(20, 20)`	VisionEye 솔루션을 사용하여 객체를 추적하고 경로를 그릴 기준점입니다.
`source`	`str`	`None`	입력 소스(비디오, RTSP 등)의 경로입니다. Solutions 명령줄 인터페이스(CLI)에서만 사용할 수 있습니다.
`figsize`	`tuple[float, float]`	`(12.8, 7.2)`	`Analytics` 차트의 크기(인치)입니다. `(12.8, 7.2)`은 1280×720 프레임을 렌더링합니다.
`fps`	`float`	`30.0`	속도 계산에 사용하는 초당 프레임 수입니다.
`max_hist`	`int`	`5`	속도 및 방향 계산을 위해 객체별로 추적할 최대 과거 지점 수입니다.
`meter_per_pixel`	`float`	`0.05`	픽셀 거리를 실제 단위로 변환하는 데 사용하는 스케일링 계수입니다.
`max_speed`	`int`	`120`	최대 속도(km/h)입니다. 추정 속도가 이를 초과하면 이 값으로 제한됩니다.
`data`	`str`	`'images'`	유사도 검색에 사용하는 이미지 디렉터리 경로입니다.
`imgsz`	`int`	`640`	모델 추론에 사용할 입력 이미지 크기입니다.

솔루션 가이드

데이터 증강 설정#

데이터 증강 기법은 학습 데이터에 다양성을 도입하여 YOLO 모델의 견고성과 성능을 높이는 데 필수적이며, 모델이 이전에 보지 못한 데이터에도 더 잘 일반화하도록 돕습니다. 다음 표에서는 각 증강 인자의 목적과 효과를 설명합니다:

인수	유형	기본값	지원 작업	범위	설명
`hsv_h`	`float`	`0.015`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	색상환의 일부 비율만큼 이미지의 색조를 조정하여 색상 변화를 도입합니다. 다양한 조명 조건에 걸쳐 모델이 일반화하는 데 도움이 됩니다. `classify`의 경우 `auto_augment=None`일 때만 적용됩니다.
`hsv_s`	`float`	`0.7`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	이미지의 채도를 일정 비율만큼 변경하여 색상의 강도에 영향을 줍니다. 다양한 환경 조건을 시뮬레이션하는 데 유용합니다. `classify`의 경우 `auto_augment=None`일 때만 적용됩니다.
`hsv_v`	`float`	`0.4`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	이미지의 명도(밝기)를 일정 비율만큼 변경하여 다양한 조명 조건에서 모델이 원활하게 작동하도록 돕습니다. `classify`의 경우 `auto_augment=None`일 때만 적용됩니다.
`degrees`	`float`	`0`	`detect`, `segment`, `semantic`, `depth`, `pose`, `obb`	`0.0 - 180`	지정된 각도 범위 내에서 이미지를 무작위로 회전하여 다양한 방향의 객체를 인식하는 모델의 능력을 향상합니다.
`translate`	`float`	`0.1`	`detect`, `segment`, `semantic`, `depth`, `pose`, `obb`	`0.0 - 1.0`	이미지 크기의 일정 비율만큼 이미지를 가로 및 세로로 이동하여 일부만 보이는 객체를 감지하는 학습을 돕습니다.
`scale`	`float \| tuple`	`0.5`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0 - 1` 또는 명시적인 `(min, max)` 튜플입니다(`classify`에는 해당하지 않음).	배율 계수를 사용해 이미지 크기를 조정하여 카메라에서 서로 다른 거리에 있는 객체를 시뮬레이션합니다.
`shear`	`float`	`0`	`detect`, `segment`, `semantic`, `depth`, `pose`, `obb`	`-180 - +180`	지정된 각도만큼 이미지를 전단 변환하여 서로 다른 각도에서 객체를 바라보는 효과를 모방합니다.
`perspective`	`float`	`0`	`detect`, `segment`, `semantic`, `depth`, `pose`, `obb`	`0.0 - 0.001`	이미지에 무작위 원근 변환을 적용하여 3D 공간에서 객체를 이해하는 모델의 능력을 향상합니다.
`flipud`	`float`	`0`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	지정된 확률에 따라 이미지를 위아래로 뒤집어 객체의 특성에 영향을 주지 않고 데이터 다양성을 높입니다.
`fliplr`	`float`	`0.5`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	지정된 확률에 따라 이미지를 좌우로 뒤집습니다. 대칭 객체를 학습하고 데이터 세트의 다양성을 높이는 데 유용합니다.
`bgr`	`float`	`0`	`detect`, `segment`, `semantic`, `depth`, `pose`, `obb`	`0.0 - 1.0`	지정된 확률에 따라 이미지 채널을 RGB에서 BGR로 뒤집어 채널 순서가 잘못된 경우에도 견고성을 높입니다.
`mosaic`	`float`	`1`	`detect`, `segment`, `semantic`, `pose`, `obb`	`0.0 - 1.0`	학습 이미지 4개를 하나로 결합하여 다양한 장면 구성과 객체 간 상호작용을 시뮬레이션합니다. 복잡한 장면 이해에 매우 효과적입니다.
`mixup`	`float`	`0`	`detect`, `segment`, `semantic`, `pose`, `obb`	`0.0 - 1.0`	이미지 두 개와 해당 레이블을 혼합하여 합성 이미지를 만듭니다. 레이블 노이즈와 시각적 다양성을 도입하여 모델의 일반화 능력을 향상합니다.
`cutmix`	`float`	`0`	`detect`, `segment`, `semantic`, `pose`, `obb`	`0.0 - 1.0`	이미지 두 개의 일부를 결합하여 각 영역의 구분을 유지하면서 부분적으로 혼합합니다. 가림 상황을 만들어 모델의 견고성을 향상합니다.
`copy_paste`	`float`	`0`	`segment`, `semantic`, `obb`	`0.0 - 1.0`	붙여넣기 대상이 될 수 있는 객체 중 실제로 붙여넣는 비율입니다. `flip`은 이미지 내에서 객체를 복제하고, `mixup`은 이 값을 이미지 간 적용 확률로도 사용합니다.
`copy_paste_mode`	`str`	`flip`	`segment`, `semantic`, `obb`	-	사용할 `copy-paste` 전략을 지정합니다. `'flip'` 및 `'mixup'`를 선택할 수 있습니다.
`auto_augment`	`str`	`randaugment`	`classify`	-	미리 정의된 증강 정책(`'randaugment'`, `'autoaugment'` 또는 `'augmix'`)을 적용하여 시각적 다양성을 통해 모델 성능을 향상합니다.
`erasing`	`float`	`0.4`	`classify`	`0.0 - 1.0`	학습 중 이미지 영역을 무작위로 지워 모델이 덜 뚜렷한 특징에 집중하도록 유도합니다.
`augmentations`	`list`	`None`	`detect`, `segment`, `semantic`, `depth`, `pose`, `obb`	-	고급 데이터 증강을 위한 사용자 지정 Albumentations 변환입니다(Python API 전용). 특수한 증강 요구 사항에 맞춰 변환 객체 목록을 허용합니다.

데이터 세트와 작업 요구 사항에 맞게 이러한 설정을 조정하세요. 다양한 값을 시험하면 최상의 모델 성능을 위한 최적의 증강 전략을 찾는 데 도움이 됩니다.

증강 가이드

로깅, 체크포인트 및 플로팅 설정#

YOLO 모델을 학습할 때는 로깅, 체크포인트, 플로팅 및 파일 관리가 중요합니다:

로깅: TensorBoard와 같은 라이브러리를 사용하거나 파일에 기록하여 모델의 진행 상황을 추적하고 문제를 진단합니다.
체크포인트: 학습을 재개하거나 다양한 구성을 시험할 수 있도록 일정한 간격으로 모델을 저장합니다.
플로팅: Matplotlib 또는 TensorBoard와 같은 라이브러리를 사용하여 성능과 학습 진행 상황을 시각화합니다.
파일 관리: 체크포인트, 로그 파일, 플롯 등 학습 중 생성된 파일을 쉽게 액세스하고 분석할 수 있도록 정리합니다.

이러한 측면을 효과적으로 관리하면 진행 상황을 추적할 수 있으며 디버깅과 최적화도 쉬워집니다.

인수	기본값	설명
`project`	`None`	학습 실행을 저장할 루트 디렉터리를 지정합니다. 지정하지 않으면 실행 결과가 `runs/<task>`에 저장됩니다. 각 실행은 별도의 하위 디렉터리에 저장됩니다.
`name`	`None`	실험 이름을 정의합니다. 지정하지 않으면 YOLO는 모드 이름을 사용하고 실행할 때마다 이름에 번호를 추가합니다(예: `train`, `train-2`). 이렇게 하면 기존 파일을 덮어쓰지 않습니다.
`exist_ok`	`False`	기존 실험 디렉터리를 덮어쓸지 여부를 결정합니다. `True`은 덮어쓰기를 허용하고, `False`은 덮어쓰기를 방지합니다.
`plots`	`True`	학습 및 검증 플롯의 생성과 저장을 제어합니다. `True`으로 설정하면 손실 곡선, 정밀도-재현율 곡선, 샘플 예측 등의 플롯을 생성하여 성능을 시각적으로 추적할 수 있습니다.
`save`	`True`	학습 체크포인트와 최종 모델 가중치의 저장을 활성화합니다. `True`으로 설정하면 모델 상태를 주기적으로 저장하여 학습 재개 또는 모델 배포를 지원합니다.

사용자 지정 구성 파일#

저장된 YAML을 불러와 모든 인자를 명령줄에 일일이 전달하지 않고 재사용합니다. cfg 인자는 default.yaml의 값을 재정의하며, 함께 전달된 추가 인자는 계속 우선 적용됩니다.

인수	기본값	설명
`cfg`	`None`	값으로 `default.yaml` 항목을 대체할 YAML 파일의 경로입니다. CLI 사용 예제는 기본 구성 파일 재정의를 참조하세요.

자주 묻는 질문#

배치 크기, 학습률, 모멘텀, 가중치 감쇠와 같은 하이퍼파라미터를 조정하여 성능을 향상하세요. 데이터 증강 설정을 조정하고 적절한 옵티마이저를 선택하며, 조기 종료 또는 혼합 정밀도와 같은 기법을 사용하세요. 자세한 내용은 학습 가이드를 참조하세요.
정확도에 영향을 미치는 주요 하이퍼파라미터는 다음과 같습니다:
- 배치 크기(batch): 배치 크기가 크면 학습이 안정화될 수 있지만 더 많은 메모리가 필요합니다.
- 학습률(lr0): 학습률이 낮으면 세밀하게 조정할 수 있지만 수렴 속도가 느려집니다.
- 모멘텀(momentum): 그래디언트 벡터를 가속하고 진동을 줄입니다.
- 이미지 크기(imgsz): 이미지 크기가 크면 정확도가 향상되지만 연산 부하가 증가합니다.
데이터 세트와 하드웨어에 따라 이 설정을 조정하세요. 자세한 내용은 학습 설정을 참조하세요.
학습률(lr0)은 매우 중요합니다. SGD에는 0.01, Adam 옵티마이저에는 0.001로 시작하고, 기본값인 auto는 lr0을 무시하므로 optimizer를 명시적으로 설정하세요. 지표를 모니터링하고 필요에 따라 조정하세요. 코사인 학습률 스케줄러(cos_lr) 또는 워밍업(warmup_epochs, warmup_momentum)을 사용하세요. 자세한 내용은 학습 가이드를 참조하세요.
기본 설정은 다음과 같습니다:
- 신뢰도 임계값(conf=0.25): 감지 결과에 필요한 최소 신뢰도입니다.
- IoU 임계값(iou=0.7): 비최대 억제(NMS)에 사용됩니다.
- 이미지 크기(imgsz=640): 입력 이미지의 크기를 조정합니다.
- 장치(device=None): CPU, CUDA GPU, Apple MPS, Intel XPU(xpu) 또는 Huawei Ascend NPU(npu)를 선택합니다.
전체 개요는 예측 설정 및 예측 가이드를 참조하세요.
혼합 정밀도 학습(amp=True)은 FP16과 FP32를 사용하여 메모리 사용량을 줄이고 학습 속도를 높입니다. 최신 GPU에 유용하며, 정확도를 크게 저하시키지 않으면서 더 큰 모델을 사용하고 계산을 더 빠르게 수행할 수 있습니다. 자세한 내용은 학습 가이드를 참조하세요.

기여자

GLglenn-jocher³⁰ RIRizwanMunawar⁵ RAraimbekovm⁴ LALaughing-q³ MAMatthewNoyce³ AMambitious-octopus² FCfcakyon² JEJESUSROYETH¹ BOBovey0809¹ MImiles-deans-ultralytics¹ GIGiantAxeWhy¹ PDpderrenger¹ JKjk4e¹ PLplashchynski¹ BUBurhan-Q¹ AYAyushExel¹ TEtensorturtle¹

생성 날짜 2023년 11월 12일업데이트 날짜 지난주

Get Started

구성#

작업#

모드#