일반적인 YOLO 문제 해결#

이 가이드에서는 Ultralytics YOLO26을 사용할 때 자주 발생하는 문제를 발생 위치에 따라 설치, 모델 학습, 예측, 배포로 나누어 다룹니다. 오류에 해당하는 카테고리로 이동하거나, 빠른 답변을 찾으려면 FAQ를 살펴보세요. 각 항목에는 문제와 바로 적용할 수 있는 구체적인 해결 방법이 제시되어 있습니다.

일반적인 문제#

설치 오류#

호환되지 않는 버전, 누락된 종속성, 잘못된 환경 설정 등 다양한 원인으로 설치 오류가 발생할 수 있습니다. 먼저 다음 사항을 확인하세요.

• 권장 사항에 따라 Python 3.8 이상을 사용하고 있습니다.
• 올바른 버전의 PyTorch(1.8 이상)가 설치되어 있는지 확인하세요.
• 충돌을 방지하려면 가상 환경을 사용하는 것이 좋습니다.
• 공식 설치 가이드의 단계를 순서대로 따르세요.

또한 일반적인 설치 문제를 해결하는 방법은 다음과 같습니다.

가져오기 오류 또는 종속성 문제#

YOLO26을 가져오는 중 오류가 발생하거나 종속성 충돌이 생기면 다음 단계를 시도하세요.

• 새로 설치: 새로 설치하면 예기치 않은 문제가 해결될 수 있습니다. 특히 패키지 구조나 기능을 변경하는 업데이트 후에 효과적입니다.
• 정기적으로 업데이트: 최신 버전의 라이브러리를 사용하세요. 이전 릴리스는 최근 업데이트와 호환되지 않을 수 있습니다.
• 종속성 확인: 필요한 종속성이 모두 올바르게 설치되어 있고 호환되는 버전인지 확인하세요.
• 변경 사항 검토: 이전 버전을 설치했다면 공식 문서나 변경 로그를 참조해 주요 구조 변경 사항을 확인하세요.

GPU에서 YOLO26 실행#

GPU에서 YOLO26을 실행하는 데 문제가 있다면 다음 문제 해결 단계를 고려하세요.

• CUDA 호환성 및 설치 확인: GPU가 CUDA와 호환되는지, CUDA가 올바르게 설치되었는지 확인하세요. nvidia-smi 명령을 사용해 NVIDIA GPU와 CUDA 버전 상태를 확인하세요.
• PyTorch와 CUDA 통합 확인: Python 터미널에서 import torch; print(torch.cuda.is_available())을 실행해 PyTorch가 CUDA를 사용할 수 있는지 확인하세요. 'True'가 반환되면 PyTorch가 CUDA를 사용하도록 설정된 것입니다.
• 환경 활성화: 필요한 패키지가 모두 설치된 올바른 환경을 사용하고 있는지 확인하세요.
• 패키지 업데이트: 오래된 패키지는 GPU와 호환되지 않을 수 있습니다. 패키지를 최신 상태로 유지하세요.
• 프로그램 설정: 코드에서 GPU 사용을 요청하는지 확인하세요. 학습이나 예측을 실행할 때 device 인수를 설정할 수 있습니다(예: device=0).

import torch

cap = torch.cuda.get_device_capability(0) if torch.cuda.is_available() else (0, 0)
cudnn = torch.backends.cudnn.version() or 0
ok = "not compatible" if cudnn >= 91100 and (cap[0] < 7 or (cap[0] == 7 and cap[1] < 5)) else "should be ok"
print(f"Compute capability: SM {cap[0]}.{cap[1]}, cuDNN: {cudnn} => {ok}")

모델 학습 문제#

일반적인 학습 문제와 해결 방법을 아래에서 다룹니다.

설정 확인#

문제: 모델 학습 중 .yaml 파일의 설정이 올바르게 적용되는지 확신할 수 없습니다.

해결 방법: 데이터셋 설정과 학습 설정은 서로 다른 .yaml 파일에 있으며, model.train()의 서로 다른 인수를 통해 전달됩니다. 설정이 올바르게 적용되도록 다음 단계를 따르세요.

• .yaml 파일의 경로가 올바른지 확인하세요.

• 데이터셋 .yaml(경로, 클래스 이름, 분할)을 data 인수로 전달하고, 사용자 지정 학습 설정 .yaml(예: epochs 또는 lr0)를 cfg 인수로 전달하세요. model.train()에 직접 전달한 인수는 두 설정 모두보다 우선합니다.

  model.train(data="/path/to/your/data.yaml", cfg="/path/to/your/cfg.yaml", batch=4)

여러 GPU로 학습 가속하기#

문제: 단일 GPU에서 학습 속도가 느려 여러 GPU를 사용해 프로세스를 가속하려고 합니다.

해결 방법: 배치 크기를 늘리면 학습 속도를 높일 수 있지만, GPU 메모리 용량을 고려해야 합니다. 여러 GPU를 사용해 학습 속도를 높이려면 다음 단계를 따르세요.

• 사용 가능한 GPU가 여러 개인지 확인하세요.

• device 인수를 GPU 인덱스 목록으로 설정하세요(예: device=[0,1,2,3]).

• 메모리 한도를 초과하지 않으면서 여러 GPU를 최대한 활용하도록 배치 크기를 적절히 늘리세요.

• 여러 GPU를 사용하도록 학습 명령을 수정하세요.

  # 학습 속도를 최적화하는 데 필요한 만큼 배치 크기와 기타 설정을 조정하세요.
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

지속적으로 모니터링할 매개변수#

문제: 손실 외에 학습 중 지속적으로 모니터링해야 할 매개변수가 무엇인지 알고 싶습니다.

해결 방법: 손실은 모니터링해야 할 중요한 지표이지만, 모델 성능을 최적화하려면 다른 지표도 추적해야 합니다. 학습 중 모니터링할 주요 지표는 다음과 같습니다.

• 정밀도
• 재현율
• 평균 정밀도 (mAP)

학습 로그에서 이러한 지표를 확인하거나 TensorBoard 또는 Weights & Biases와 같은 도구를 사용해 시각화할 수 있습니다. 이러한 지표를 기준으로 조기 종료를 구현하면 더 나은 결과를 얻는 데 도움이 됩니다.

학습 진행 상황 추적 도구#

문제: 학습 진행 상황을 추적할 도구를 추천받고 싶습니다.

해결 방법: 학습 진행 상황을 추적하고 시각화하려면 다음 도구를 고려해 보세요.

• TensorBoard: TensorBoard는 손실, 정확도 등의 학습 지표를 시각화하는 데 널리 사용됩니다. YOLO26 학습 과정에 통합할 수 있습니다.
• Comet: Comet은 실험 추적 및 비교를 위한 폭넓은 도구 모음을 제공합니다. 지표, 하이퍼파라미터, 모델 가중치까지 추적할 수 있습니다. YOLO 모델과도 간편하게 통합할 수 있어 실험 주기 전체를 한눈에 파악할 수 있습니다.
• Ultralytics Platform: Ultralytics Platform은 YOLO 모델 추적을 위한 특화된 환경을 제공하며, 지표와 데이터셋을 관리하고 팀과 협업할 수 있는 통합 플랫폼입니다. YOLO에 특화되어 있어 더욱 맞춤화된 추적 옵션을 제공합니다.

GPU에서 학습이 진행 중인지 확인하는 방법#

문제: 학습 로그의 'device' 값이 'null'로 표시되어 GPU에서 학습이 진행 중인지 확실하지 않습니다.

해결 방법: 'device' 값이 'null'인 것은 일반적으로 학습 프로세스가 사용 가능한 GPU를 자동으로 선택하도록 설정되었음을 의미하며, 이는 기본 동작입니다. 특정 GPU에서 학습하려면 학습을 시작할 때 device 인수를 설정하세요. device은 학습 인수이므로 데이터셋 .yaml에서 설정해도 적용되지 않습니다.

from ultralytics import YOLO

# 모델 로드
model = YOLO("yolo26n.pt")

# GPU 0 사용; 여러 GPU에는 device=[0, 1], CPU에는 device="cpu" 사용
model.train(data="path/to/data.yaml", device=0)

학습 진행 상황을 효과적으로 모니터링하려면 'runs' 폴더의 로그와 지표를 확인하세요.

효과적인 모델 학습을 위한 주요 고려 사항#

모델 학습과 관련된 문제가 발생했다면 다음 사항을 염두에 두세요.

데이터셋 형식 및 레이블

• 중요성: 모든 머신러닝 모델의 기반은 학습에 사용하는 데이터의 품질과 형식입니다.
• 권장 사항: 사용자 지정 데이터셋과 관련 레이블이 예상 형식을 따르는지 확인하세요. 어노테이션의 정확도와 품질을 검증하는 것이 중요합니다. 부정확하거나 품질이 낮은 어노테이션은 모델의 학습을 방해해 예측할 수 없는 결과를 초래할 수 있습니다.

모델 수렴

• 중요성: 모델이 학습 데이터에서 충분히 학습했음을 보장하려면 모델 수렴이 필요합니다.
• 권장 사항: 모델을 '처음부터' 학습할 때는 모델이 만족스러운 수준으로 수렴하도록 하는 것이 중요합니다. 기존 모델을 미세 조정하는 경우보다 학습 시간을 늘리고 에포크 수를 더 많이 설정해야 할 수 있습니다.

학습률 및 배치 크기

• 중요성: 이러한 하이퍼파라미터는 학습 중 모델의 가중치 업데이트 방식을 결정하는 데 중요한 역할을 합니다.
• 권장 사항: 선택한 학습률과 배치 크기가 특정 데이터셋에 적합한지 정기적으로 평가하세요. 데이터셋의 특성과 맞지 않는 매개변수는 모델 성능을 저해할 수 있습니다.

클래스 분포

• 중요성: 데이터셋의 클래스 분포는 모델의 예측 경향에 영향을 줄 수 있습니다.
• 권장 사항: 데이터셋의 클래스 분포를 정기적으로 평가하세요. 클래스 불균형이 있으면 모델이 더 많이 나타나는 클래스에 편향될 위험이 있습니다. 이 편향은 혼동 행렬에서 확인할 수 있으며, 모델이 주로 다수 클래스를 예측할 수 있습니다.

사전 학습된 가중치와 교차 확인

• 중요성: 사전 학습된 가중치를 활용하면 모델 학습을 위한 견고한 출발점을 마련할 수 있으며, 특히 데이터가 제한적인 경우 유용합니다.
• 권장 사항: 진단 단계에서 동일한 데이터를 사용하되 사전 학습된 가중치로 초기화하여 모델을 학습해 보세요. 이 접근 방식으로 제대로 구성된 혼동 행렬이 생성된다면, '처음부터 학습한' 모델에 추가 학습이나 조정이 필요할 수 있음을 시사합니다.

모델 예측 관련 문제#

모델 예측 중 흔히 발생하는 문제와 해결 방법은 아래와 같습니다.

YOLO26 사용자 지정 모델에서 바운딩 박스 예측 가져오기#

문제: 사용자 지정 YOLO26 모델로 예측을 실행할 때 바운딩 박스 좌표의 형식과 시각화에 문제가 발생합니다.

해결 방법:

• 좌표 형식: YOLO26은 바운딩 박스 좌표를 절대 픽셀 값으로 제공합니다. 이를 상대 좌표(0~1 범위)로 변환하려면 이미지 크기로 나누어야 합니다. 예를 들어 이미지 크기가 640x640이라면 다음과 같이 처리합니다.

  # 절대 좌표를 상대 좌표로 변환
  x1 = x1 / 640  # x 좌표를 이미지 너비로 나누기
  x2 = x2 / 640
  y1 = y1 / 640  # y 좌표를 이미지 높이로 나누기
  y2 = y2 / 640

• 파일 이름: 예측 대상 이미지의 파일 이름을 가져오려면 예측 루프 내 각 결과 객체의 path 속성에서 이미지 파일 경로를 읽습니다(예: result.path).

YOLO26 예측에서 객체 필터링#

문제: Ultralytics 라이브러리에서 YOLO26을 실행할 때 예측 결과 중 특정 객체만 필터링하고 표시하는 방법에 문제가 있습니다.

해결 방법: 특정 클래스를 감지하려면 classes 인수를 사용하여 출력에 포함할 클래스를 지정합니다. 예를 들어 자동차만 감지하려면('cars'의 클래스 인덱스가 2라고 가정) 다음과 같이 합니다.

yolo segment predict model=yolo26n-seg.pt source='path/to/car.mp4' show=True classes=2

YOLO26의 정밀도 지표 이해하기#

문제: YOLO26에서 박스 정밀도, 마스크 정밀도, 혼동 행렬 정밀도의 차이가 명확하지 않습니다.

해결 방법: 박스 정밀도는 IoU(교집합 대비 합집합)를 지표로 사용하여 예측 바운딩 박스와 실제 정답 박스의 정확도를 측정합니다. 마스크 정밀도는 픽셀 단위 객체 분류에서 예측 분할 마스크와 정답 마스크 간의 일치도를 평가합니다. 반면 혼동 행렬 정밀도는 모든 클래스에 걸친 전반적인 분류 정확도에 중점을 두며 예측의 기하학적 정확도는 고려하지 않습니다. 바운딩 박스는 클래스 예측이 틀려도 기하학적으로 정확할 수 있으며(참 양성), 이로 인해 박스 정밀도와 혼동 행렬 정밀도에 차이가 생길 수 있습니다. 이러한 지표는 모델 성능의 서로 다른 측면을 평가하므로 작업마다 다른 평가 지표가 필요합니다.

YOLO26에서 객체 크기 추출하기#

문제: YOLO26에서 감지된 객체의 길이와 높이를 가져오기가 어렵습니다. 특히 이미지에서 여러 객체가 감지되는 경우 더욱 그렇습니다.

해결 방법: 바운딩 박스 크기를 가져오려면 먼저 Ultralytics YOLO26 모델을 사용하여 이미지의 객체를 예측합니다. 그런 다음 예측 결과에서 바운딩 박스의 너비와 높이 정보를 추출합니다.

from ultralytics import YOLO

# Load a pretrained YOLO26 model
model = YOLO("yolo26n.pt")

# Specify the source image
source = "https://ultralytics.com/images/bus.jpg"

# Make predictions
results = model.predict(source, save=True, imgsz=320, conf=0.25)

# Extract bounding box dimensions
boxes = results[0].boxes.xywh.cpu()
for box in boxes:
    x, y, w, h = box
    print(f"Width of Box: {w}, Height of Box: {h}")

배포 관련 문제#

GPU 배포 문제#

문제: 멀티 GPU 환경에서 모델을 배포하면 예상치 못한 메모리 사용량이나 GPU 간 결과 불일치 등 예기치 않은 동작이 발생할 수 있습니다.

해결 방법: 기본 GPU 초기화 여부를 확인하세요. PyTorch와 같은 일부 프레임워크는 지정된 GPU로 전환하기 전에 기본 GPU에서 CUDA 작업을 초기화할 수 있습니다. 예기치 않은 기본 초기화를 방지하려면 배포 및 예측 시 GPU를 직접 지정하세요. 그런 다음 도구를 사용하여 GPU 사용률과 메모리 사용량을 모니터링하고 이상 징후를 실시간으로 파악하세요. 또한 프레임워크 또는 라이브러리의 최신 버전을 사용하고 있는지 확인하세요.

모델 변환/내보내기 문제#

문제: 머신러닝 모델을 다른 형식이나 플랫폼으로 변환하거나 내보내는 과정에서 오류나 예기치 않은 동작이 발생할 수 있습니다.

해결 방법: 내보내기 모드 문서에서 지원 형식과 형식별 옵션을 확인한 다음, 아래 항목을 점검하세요.

• 호환성 확인: 서로 호환되는 라이브러리 및 프레임워크 버전을 사용하고 있는지 확인하세요. 버전이 일치하지 않으면 변환 중 예기치 않은 오류가 발생할 수 있습니다.
• 환경 초기화: Jupyter 또는 Colab과 같은 대화형 환경을 사용하는 경우, 주요 변경이나 설치를 진행한 후 환경을 다시 시작해 보세요. 환경을 새로 시작하면 근본적인 문제가 해결될 수 있습니다.
• 공식 문서: 변환에 사용하는 도구나 라이브러리의 공식 문서를 항상 참고하세요. 모델 내보내기에 관한 구체적인 지침과 모범 사례가 포함되어 있는 경우가 많습니다.
• 커뮤니티 지원: 다른 사용자가 유사한 문제를 보고했는지 라이브러리 또는 프레임워크의 공식 저장소에서 확인하세요. 유지 관리자나 커뮤니티가 토론 스레드에 해결 방법이나 우회 방법을 제공했을 수 있습니다.
• 정기 업데이트: 도구 또는 라이브러리의 최신 버전을 사용하고 있는지 확인하세요. 개발자는 알려진 버그를 수정하거나 기능을 개선하는 업데이트를 자주 배포합니다.
• 단계별 테스트: 전체 변환을 수행하기 전에 더 작은 모델이나 데이터셋으로 프로세스를 테스트하여 잠재적인 문제를 조기에 파악하세요.

커뮤니티 및 지원#

다음 채널과 리소스를 통해 도움을 받고 해결 방법을 공유하세요.

도움을 받을 수 있는 포럼 및 채널#

GitHub 이슈: GitHub의 Ultralytics 저장소에는 질문을 하고, 버그를 보고하며, 새로운 기능을 제안할 수 있는 이슈 탭이 있습니다. 이곳에서는 커뮤니티 구성원과 유지 관리자가 활발히 활동하며, 구체적인 문제에 대한 도움을 받기에도 좋습니다.

Ultralytics Discord 서버: Ultralytics에는 다른 사용자 및 개발자와 소통할 수 있는 Discord 서버가 있습니다.

공식 문서 및 리소스#

Ultralytics YOLO26 문서: 공식 문서에서는 YOLO26의 전반적인 내용을 확인할 수 있으며, 설치, 사용 및 문제 해결에 관한 가이드도 제공합니다.

결론#

대부분의 YOLO26 문제는 몇 가지 원인으로 귀결됩니다. 버전 불일치, 데이터셋 형식, GPU 구성입니다. 여기에 설명되지 않은 오류가 발생하면 GitHub Issues 탭에서 검색하거나 Discord 서버에 문의해 보세요. 이미 해결된 문제일 가능성이 높습니다. 더 심층적인 학습 문제가 있다면 모델 학습 팁 가이드에서 컴퓨터 비전 프로젝트의 결과를 개선하는 실용적인 조언을 확인하세요.

자주 묻는 질문#