YOLO 설치와 실행
YOLO를 사용하는 가장 빠른 방법은 Ultralytics 라이브러리를 설치하는 것입니다. 단 한 줄의 명령으로 설치가 완료되며, 사전학습된 모델을 즉시 사용할 수 있습니다. 이 문서에서는 설치부터 추론 실행, 결과 저장까지 전 과정을 안내합니다.
| 항목 | 내용 |
|---|---|
| 설치 명령 | pip install ultralytics 한 줄로 완료 |
| 지원 태스크 | Detection, Segmentation, Classification, Pose, OBB |
| 지원 소스 | 이미지, 폴더, 비디오, 웹캠, URL, 스트림 |
| 결과 접근 | results[0].boxes.xyxy, .conf, .cls |
| CLI 사용 | yolo detect predict source=... model=... |
문서 탐색
설치
ultralytics 하나만 설치하면 YOLO 관련 모든 기능을 사용할 수 있습니다. NumPy, OpenCV, PyYAML 등 필요한 의존성이 자동으로 함께 설치됩니다.
pip install ultralytics설치 확인:
import ultralytics
ultralytics.checks()
# Ultralytics 버전, Python 버전, PyTorch 버전, CUDA 상태를 한 번에 출력모델 로드
두 가지 방식으로 모델을 불러올 수 있습니다.
from ultralytics import YOLO
# 방법 1: 사전학습된 가중치 로드 (COCO 80 클래스로 학습된 상태)
# 파일이 없으면 자동으로 다운로드됩니다
model = YOLO("yolo11n.pt") # nano - 가장 빠름, 가장 작음
model = YOLO("yolo11s.pt") # small
model = YOLO("yolo11m.pt") # medium
model = YOLO("yolo11l.pt") # large
model = YOLO("yolo11x.pt") # extra-large - 가장 정확함
# 방법 2: 아키텍처 yaml 파일로 로드 (처음부터 학습 시작)
model = YOLO("yolo11n.yaml") # 가중치 없음, 학습 전 초기화 상태
# 방법 3: 직접 학습한 가중치 로드
model = YOLO("runs/detect/train/weights/best.pt")추론 (Predict)
기본 추론
from ultralytics import YOLO
model = YOLO("yolo11n.pt")
# 단일 이미지
results = model("drone_railway.jpg")
# 여러 이미지 (리스트 전달)
results = model(["image1.jpg", "image2.jpg", "image3.jpg"])
# 폴더 전체
results = model("images/")
# 비디오 파일
results = model("railway_inspection.mp4")
# 웹캠 (실시간)
results = model(0) # 0은 기본 웹캠
# 인터넷 URL
results = model("https://example.com/railway.jpg")
# RTSP 스트림 (드론 실시간 영상 수신)
results = model("rtsp://192.168.1.100:8554/stream")추론 옵션 지정
results = model.predict(
source="drone_images/",
conf=0.25, # 최소 신뢰도 임계값 (0~1)
iou=0.45, # NMS IoU 임계값
imgsz=640, # 입력 이미지 크기 (픽셀)
device="cuda:0", # GPU 지정 ("cpu", "cuda:0", "mps")
half=True, # FP16 추론으로 속도 향상 (GPU 필요)
classes=[0, 2], # 특정 클래스만 탐지 (클래스 ID 리스트)
max_det=100, # 이미지당 최대 탐지 개수
verbose=False, # 콘솔 출력 비활성화
)결과 데이터 접근
results = model("drone_railway.jpg")
result = results[0] # 첫 번째 이미지 결과
# 바운딩 박스
boxes = result.boxes
print(boxes.xyxy) # 절대 좌표: [[x1, y1, x2, y2], ...] - Tensor
print(boxes.xywh) # 중심점+크기: [[cx, cy, w, h], ...] - Tensor
print(boxes.xyxyn) # 정규화 좌표 (0~1 범위) xyxy
print(boxes.xywhn) # 정규화 좌표 (0~1 범위) xywh
# 신뢰도 점수
print(boxes.conf) # [0.89, 0.75, 0.62, ...] - Tensor
# 클래스 ID
print(boxes.cls) # [0., 2., 0., ...] - Tensor (정수형)
# 클래스 이름 (COCO 기준)
names = result.names # {0: 'person', 1: 'bicycle', ...}
cls_ids = boxes.cls.int().tolist()
cls_names = [names[i] for i in cls_ids]
# NumPy 배열로 변환
boxes_np = boxes.xyxy.cpu().numpy()
conf_np = boxes.conf.cpu().numpy()
cls_np = boxes.cls.cpu().numpy()
# 탐지된 개수
print(f"탐지된 객체 수: {len(boxes)}")결과 시각화
result = results[0]
# 화면에 표시 (주피터 노트북에서는 이미지가 인라인으로 표시됨)
result.show()
# 파일로 저장 (기본 경로: runs/detect/predict/)
result.save(filename="output.jpg")
# 저장 경로 지정
result.save(filename="results/railway_result.jpg")
# 어노테이션된 이미지를 NumPy 배열로 가져오기 (OpenCV로 추가 처리 시 유용)
import cv2
annotated_frame = result.plot() # BGR NumPy 배열 반환
cv2.imwrite("annotated.jpg", annotated_frame)
# 전체 결과 일괄 저장
results = model("images/", save=True, project="my_results", name="run1")
# → my_results/run1/ 폴더에 모든 결과 저장다양한 소스 지원
| 소스 유형 | 예시 값 | 설명 |
|---|---|---|
| 이미지 파일 | "photo.jpg", "photo.png" | 단일 이미지 파일 |
| 이미지 폴더 | "images/" | 폴더 내 모든 이미지 일괄 처리 |
| 이미지 리스트 | ["a.jpg", "b.jpg"] | 선택적 다중 이미지 |
| NumPy 배열 | np.zeros((640, 640, 3)) | OpenCV 프레임 직접 전달 |
| PIL 이미지 | Image.open("photo.jpg") | PIL/Pillow 이미지 객체 |
| 비디오 파일 | "video.mp4", "video.avi" | 전체 영상 프레임 처리 |
| 웹캠 | 0, 1, 2 | 로컬 카메라 (인덱스 번호) |
| HTTP URL | "https://example.com/img.jpg" | 인터넷 이미지 |
| RTSP 스트림 | "rtsp://ip:port/stream" | IP 카메라, 드론 영상 |
| YouTube URL | "https://youtu.be/..." | YouTube 영상 (yt-dlp 필요) |
CLI 사용법
Python 코드 없이 터미널에서 직접 YOLO를 실행할 수 있습니다. 빠른 테스트나 자동화 스크립트에 유용합니다.
# 기본 추론
yolo detect predict model=yolo11n.pt source=drone_railway.jpg
# 폴더 전체 추론
yolo detect predict model=yolo11n.pt source=images/
# 옵션 지정 (신뢰도, 이미지 크기, 저장 경로)
yolo detect predict model=yolo11n.pt source=images/ conf=0.3 imgsz=1280 project=results name=run1
# 비디오 추론 + 결과 저장
yolo detect predict model=yolo11n.pt source=railway.mp4 save=True
# 라벨 파일(.txt)도 함께 저장
yolo detect predict model=yolo11n.pt source=images/ save=True save_txt=True
# GPU 지정
yolo detect predict model=yolo11n.pt source=images/ device=0
# 특정 클래스만 탐지 (클래스 ID 지정)
yolo detect predict model=yolo11n.pt source=images/ classes=0,2
# 모델 정보 확인
yolo info model=yolo11n.pt
# 내보내기 (ONNX)
yolo export model=yolo11n.pt format=onnx
# 내보내기 (TensorRT - NVIDIA GPU 필요)
yolo export model=yolo11n.pt format=engine device=0