2.3.3 YOLO 예제

YOLO 예제

이 문서는 YOLO를 처음 접하는 분들을 위한 실행 가능한 예제 모음입니다. 예제 1부터 순서대로 따라하면 5분 안에 첫 번째 객체 탐지 결과를 확인할 수 있습니다. 모든 예제는 Google Colab 또는 로컬 Python 환경에서 그대로 실행할 수 있습니다.

항목	내용
사전 조건	pip install ultralytics 설치 완료
예제 수	5개 (추론 → 배치 → 임계값 → 클래스 필터 → 저장)
권장 시작 모델	yolo11n.pt (가장 빠르고 가벼움)
테스트 데이터	Ultralytics 제공 샘플 이미지 (자동 다운로드)
예상 소요 시간	전체 약 20분 (예제 1만: 5분)

---

문서 탐색

이전	다음
2.3.2 YOLO 설정	2.4.1 SAM이란?

---

예제 1: 첫 번째 추론 (5분 코스)

가장 간단한 형태의 YOLO 추론입니다. 설치 후 바로 실행해 볼 수 있습니다.

# 1단계: 라이브러리 임포트
from ultralytics import YOLO
 
# 2단계: 모델 로드
# yolo11n.pt 파일이 없으면 자동으로 인터넷에서 다운로드됩니다 (~6MB)
model = YOLO("yolo11n.pt")
 
# 3단계: 추론 실행
# Ultralytics에서 제공하는 샘플 이미지 사용 (자동 다운로드)
results = model("https://ultralytics.com/images/bus.jpg")
 
# 4단계: 결과 확인
result = results[0]
print(f"탐지된 객체 수: {len(result.boxes)}")
 
# 각 탐지 결과 출력
for box in result.boxes:
    cls_id = int(box.cls.item())
    cls_name = result.names[cls_id]
    confidence = box.conf.item()
    x1, y1, x2, y2 = box.xyxy[0].tolist()
    print(f"  클래스: {cls_name}, 신뢰도: {confidence:.2f}, 위치: ({x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f})")
 
# 5단계: 결과 이미지 저장
result.save(filename="my_first_result.jpg")
print("결과 저장 완료: my_first_result.jpg")

예상 출력:

탐지된 객체 수: 5
  클래스: person, 신뢰도: 0.89, 위치: (16, 198, 193, 732)
  클래스: person, 신뢰도: 0.84, 위치: (671, 160, 810, 716)
  클래스: bus, 신뢰도: 0.98, 위치: (22, 82, 789, 732)
  클래스: person, 신뢰도: 0.67, 위치: (214, 208, 285, 498)
  클래스: person, 신뢰도: 0.54, 위치: (786, 218, 861, 440)
결과 저장 완료: my_first_result.jpg

Colab에서 결과를 바로 보려면 result.show() 대신 다음 코드를 사용합니다.

from PIL import Image
Image.open("my_first_result.jpg")

---

예제 2: 여러 이미지 배치 추론 (폴더 단위)

드론으로 촬영한 수백 장의 이미지를 한 번에 처리할 때 사용합니다.

from ultralytics import YOLO
import os
 
model = YOLO("yolo11n.pt")
 
# 폴더 내 모든 이미지를 한 번에 처리
# 지원 형식: jpg, jpeg, png, bmp, tiff, webp
results = model("drone_images/", stream=True)  # stream=True: 메모리 절약 (대용량 폴더 권장)
 
# 결과 순회
total_detections = 0
for i, result in enumerate(results):
    n = len(result.boxes)
    total_detections += n
    print(f"[{i+1}] {os.path.basename(result.path)}: {n}개 탐지")
 
print(f"\n전체 탐지 수: {total_detections}")
 
# 결과 일괄 저장 (각 이미지에 바운딩 박스가 그려진 상태로 저장)
results = model(
    "drone_images/",
    save=True,           # 이미지 저장
    project="runs",      # 저장 상위 폴더
    name="batch_run",    # 저장 하위 폴더
)
# 결과: runs/batch_run/ 폴더에 저장됨

stream=True는 이미지를 하나씩 불러와 처리하므로, 수천 장 이상의 폴더를 처리할 때 메모리 부족을 방지합니다.

---

예제 3: Confidence Threshold 조정

conf 파라미터는 탐지 결과의 최소 신뢰도를 설정합니다. 값이 낮을수록 더 많은 객체가 탐지되지만 오탐(False Positive)이 늘어납니다.

from ultralytics import YOLO
 
model = YOLO("yolo11n.pt")
image = "drone_railway.jpg"
 
# 낮은 임계값: 모든 후보 포함 (오탐 多, 놓침 少)
results_low = model(image, conf=0.25)
print(f"conf=0.25: {len(results_low[0].boxes)}개 탐지")
 
# 중간 임계값: 일반적인 기본값
results_mid = model(image, conf=0.50)
print(f"conf=0.50: {len(results_mid[0].boxes)}개 탐지")
 
# 높은 임계값: 확실한 것만 포함 (오탐 少, 놓침 多)
results_high = model(image, conf=0.70)
print(f"conf=0.70: {len(results_high[0].boxes)}개 탐지")

conf 값	탐지 수	특징	적합한 상황
0.10~0.25	많음	작은 결함도 놓치지 않음 (오탐 증가)	안전 점검 초기 스캔
0.40~0.50	보통	속도와 정확도 균형 (기본 권장)	일반 점검 업무
0.60~0.80	적음	확실한 결함만 출력 (놓침 증가)	자동 경고 시스템

철도 점검처럼 놓침(미탐)이 위험한 상황에서는 conf를 낮게 설정하고 사람이 2차 검토하는 방식을 권장합니다.

---

예제 4: 특정 클래스만 탐지

철도 점검에서 균열과 볼트 누락만 탐지하고 싶을 때처럼, 특정 클래스만 필터링하는 방법입니다.

from ultralytics import YOLO
 
model = YOLO("yolo11n.pt")
 
# COCO 데이터셋에서 사람(0)과 자동차(2)만 탐지
results = model("drone_image.jpg", classes=[0, 2])
 
# 클래스 ID 확인 (COCO 80클래스 기준)
print(model.names)
# {0: 'person', 1: 'bicycle', 2: 'car', 3: 'motorcycle', ...}
 
# 커스텀 모델에서 균열(0)과 볼트누락(1)만 탐지
custom_model = YOLO("railway_detector.pt")
results = custom_model("drone_image.jpg", classes=[0, 1])
 
# 탐지 후 코드에서 필터링하는 방법 (추론은 모든 클래스로 수행)
results = model("drone_image.jpg")
result = results[0]
 
TARGET_CLASSES = [0, 2]  # 관심 클래스 ID
filtered_boxes = [
    box for box in result.boxes
    if int(box.cls.item()) in TARGET_CLASSES
]
print(f"필터링 후 탐지 수: {len(filtered_boxes)}")

classes= 파라미터로 필터링하는 것이 추론 후 필터링보다 빠릅니다. 하지만 커스텀 모델을 학습할 때는 처음부터 필요한 클래스만 포함한 데이터셋을 구성하는 것이 가장 효율적입니다.

---

예제 5: 결과 저장

탐지 결과를 이미지, 텍스트 라벨, JSON 등 다양한 형식으로 저장합니다.

from ultralytics import YOLO
 
model = YOLO("yolo11n.pt")
 
# 이미지 + 라벨 파일 모두 저장
results = model(
    source="drone_images/",
    save=True,           # 바운딩 박스가 그려진 이미지 저장
    save_txt=True,       # YOLO 형식 라벨 파일(.txt) 저장
    save_conf=True,      # 라벨 파일에 신뢰도 점수 포함
    save_crop=True,      # 탐지된 객체를 잘라서 별도 저장
    project="output",    # 저장 상위 디렉토리
    name="inspection",   # 저장 하위 디렉토리
)
 
# 저장 구조:
# output/inspection/
# ├── image1.jpg          (save=True: 바운딩 박스가 그려진 이미지)
# ├── image2.jpg
# ├── labels/
# │   ├── image1.txt      (save_txt=True: YOLO 형식 라벨)
# │   └── image2.txt
# └── crops/
#     ├── person/         (save_crop=True: 클래스별 잘라낸 이미지)
#     └── car/
 
# 라벨 파일 형식 확인 (save_txt=True 사용 시)
with open("output/inspection/labels/image1.txt") as f:
    print(f.read())
# 0 0.512 0.438 0.245 0.187 0.893
# 클래스ID cx cy w h confidence (정규화 좌표, save_conf=True일 때 confidence 포함)
 
# JSON 형식으로 결과 저장
import json
results = model("drone_images/")
all_results = []
for result in results:
    data = json.loads(result.tojson())
    all_results.extend(data)
 
with open("detections.json", "w", encoding="utf-8") as f:
    json.dump(all_results, f, ensure_ascii=False, indent=2)
 
print("JSON 저장 완료: detections.json")

---

초보자 팁

팁	이유
nano 모델(yolo11n.pt)부터 시작하세요	빠르고 가벼워서 파이프라인 테스트에 최적, 나중에 큰 모델로 교체 가능
COCO8 데이터셋으로 파이프라인 먼저 검증하세요	COCO 전체(~20GB)보다 8장짜리 COCO8로 학습-검증-추론 흐름을 빠르게 확인
imgsz=640을 기본으로 사용하세요	대부분의 모델이 640×640에 최적화됨, 소형 객체가 많으면 1280으로 올리세요
stream=True로 대용량 폴더 처리하세요	수백 장 이상 처리 시 메모리 부족 방지
Colab에서 런타임을 GPU로 설정하세요	CPU 대비 10~50배 빠름, 무료 T4 GPU 사용 가능
결과가 이상하면 conf 값을 낮춰보세요	기본 0.25보다 낮게 설정하면 더 많은 탐지 결과를 확인 가능

# COCO8 데이터셋으로 빠른 파이프라인 검증 예시
from ultralytics import YOLO
 
model = YOLO("yolo11n.pt")
 
# COCO8: COCO train/val 각 4장씩 8장으로 구성된 미니 데이터셋 (자동 다운로드)
metrics = model.val(data="coco8.yaml")
print(f"mAP@0.5: {metrics.box.map50:.3f}")
print(f"mAP@0.5:0.95: {metrics.box.map:.3f}")

---

문서 탐색

이전	다음
2.3.2 YOLO 설정	2.4.1 SAM이란?

---

참고 자료

• Ultralytics Predict 예제
• Ultralytics 빠른 시작 (Colab 노트북)
• COCO8 데이터셋 소개
• 결과 저장 옵션 전체 목록