Ultralytics

Ultralytics

Ultralytics는 실시간 컴퓨터 비전 모델인 YOLO(You Only Look Once) 계열을 만드는 회사예요. 객체 탐지(object detection), 인스턴스 분할(instance segmentation), 의미론적 분할(semantic segmentation), 깊이 추정(depth estimation), 분류, 포즈 추정(pose estimation), 방향성 바운딩 박스(OBB), 추적(tracking)까지 하나의 Python 패키지와 CLI로 다룰 수 있게 해 줘요. YOLO26은 NMS 없는 엔드투엔드(end-to-end) 추론과 최적화된 엣지 배포를 선택적으로 지원하며, 엣지 디바이스부터 클라우드 API까지 다양한 하드웨어에서 쓰기 좋게 설계됐어요.

출처: 문서

본문

설치하기

pip으로 최신 안정 버전 ultralytics 패키지를 설치하거나, Ultralytics GitHub 저장소를 클론해서 최신 버전을 쓸 수 있어요.

# Install or upgrade the ultralytics package from PyPI
pip install -U ultralytics

디스플레이가 없는 서버 환경(클라우드 VM, Docker 컨테이너, CI/CD 파이프라인)에서는 ultralytics-opencv-headless 패키지를 쓰면 돼요. opencv-python 대신 opencv-python-headless에 의존해서 불필요한 GUI 의존성과 libGL 에러를 피할 수 있어요.

pip install ultralytics-opencv-headless

두 줄로 시작하기

패키지를 설치하고 사전 학습된 YOLO26 모델로 이미지에서 객체를 탐지하는 것까지 두 줄이면 돼요. 모델 가중치와 예시 이미지는 자동으로 다운로드되고, 결과는 runs/detect/predict 디렉터리에 저장돼요.

# Install the ultralytics package from PyPI
pip install ultralytics

# Detect objects in an image with a pretrained YOLO26 model
yolo predict model=yolo26n.pt source='https://github.com/ultralytics/assets/releases/download/v0.0.0/bus.jpg'

CLI로 사용하기

Ultralytics CLI는 Python 환경 없이 터미널에서 한 줄로 모든 작업을 실행하게 해 줘요. yolo 명령의 기본 문법은 다음과 같아요.

yolo TASK MODE ARGS
  • TASK(선택)는 detect, segment, semantic, classify, pose, obb 중 하나예요.
  • MODE(필수)는 train, val, predict, export, track, benchmark 중 하나예요.
  • ARGS(선택)는 imgsz=640 같은 arg=value 쌍으로 기본값을 덮어써요.

인자는 반드시 =로 구분된 arg=value 쌍으로, 공백으로 구분해서 넘겨야 해요. -- 접두사나 ,는 쓰면 안 돼요.

  • yolo predict model=yolo26n.pt imgsz=640 conf=0.25 ✅
  • yolo predict model yolo26n.pt imgsz 640 conf 0.25 ❌ (= 빠짐)
  • yolo predict --model yolo26n.pt --imgsz 640 --conf 0.25 ❌ (-- 사용)
  • yolo predict model=yolo26n.pt, imgsz=640, conf=0.25 ❌ (, 사용)

예를 들어 탐지 모델을 학습할 땐 이렇게 실행해요.

yolo train data=coco8.yaml model=yolo26n.pt epochs=10 lr0=0.01

Python으로 사용하기

Python 인터페이스는 몇 줄의 코드로 모델을 로드하고, 학습하고, 성능을 평가하고, ONNX 형식으로 내보낼 수 있게 해 줘요.

from ultralytics import YOLO

# Create a new YOLO model from scratch
model = YOLO("yolo26n.yaml")

# Load a pretrained YOLO model (recommended for training)
model = YOLO("yolo26n.pt")

# Train the model using the 'coco8.yaml' dataset for 3 epochs
results = model.train(data="coco8.yaml", epochs=3)

# Evaluate the model's performance on the validation set
results = model.val()

# Perform object detection on an image using the model
results = model("https://ultralytics.com/images/bus.jpg")

# Export the model to ONNX format

추론하기 (Predict mode)

predict 모드는 이미지, 비디오, 라이브 스트림 등 다양한 데이터 소스에서 고속 실시간 추론을 수행해요. 주요 특징으로는 스트리밍 모드, 배치 처리, 기존 파이프라인과의 손쉬운 통합이 있어요.

from ultralytics import YOLO

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

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")

추론 인자를 함께 지정할 수도 있어요. 예를 들어 결과 이미지를 저장하면서 입력 크기와 신뢰도 임계값을 조정하면 돼요.

from ultralytics import YOLO

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

# Run inference on 'bus.jpg' with arguments
model.predict("https://ultralytics.com/images/bus.jpg", save=True, imgsz=320, conf=0.25)

여러 이미지나 비디오 프레임을 배치로 처리하려면 리스트로 넘기면 돼요. 기본(stream=False)은 모든 결과를 담은 리스트를 반환하고, stream=True를 넘기면 메모리 효율적인 제너레이터로 결과를 하나씩 내보내요. 긴 비디오나 라이브 스트림에 특히 유용해요.

from ultralytics import YOLO

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

# Run batched inference on a list of images
results = model(["image1.jpg", "image2.jpg"])  # return a list of Results objects

# Process results list
for result in results:
    pass

객체 추적하기

비디오에서 객체를 추적할 때는 Python으로 YOLO("yolo26n.pt").track(source="path/to/video.mp4")를 호출하거나, CLI로 yolo track source=path/to/video.mp4를 실행하면 돼요. 둘 다 비디오 파일, 라이브 스트림, 웹캠 입력을 지원해요.

데이터 학습하기

커스텀 데이터로 모델을 학습하려면 다음 단계를 따라요.

  1. 주석이 달린 데이터셋을 준비하고 데이터셋 YAML 파일로 설명해요.
  2. 사전 학습된 모델을 로드해요. 예: Python에서 YOLO("yolo26n.pt").
  3. 학습을 시작해요. Python에선 model.train(data="path/to/dataset.yaml", epochs=100, imgsz=640), 명령줄에선 yolo detect train data=path/to/dataset.yaml epochs=100 imgsz=640.

기타 설치 방법

conda로 설치할 땐 이렇게 해요.

conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=12.1 ultralytics

Docker로 실행할 땐 Docker Hub에서 이미지를 받아 GPU 지원 컨테이너로 실행해요.

# Pull the latest ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --runtime=nvidia --gpus all ultralytics/ultralytics:latest

개발용으로 저장소를 클론해 editable 모드로 설치할 수도 있어요.

# Clone the ultralytics repository
git clone https://github.com/ultralytics/ultralytics

# Navigate to the cloned directory
cd ultralytics

# Install the package in editable mode for development
pip install -e .

Ultralytics는 데이터 어노테이션, 클라우드 학습, 배포를 더해 주는 Ultralytics Platform도 제공하며, 문서에서 다루는 구성의 핵심은 대부분 yolo [TASK] MODE ARGS 문법을 따르고 있어요. Task는 이미지에서 무엇을 얻을지(탐지, 분할, 분류, 포즈 등), Mode는 모델을 어떻게 쓸지(학습, 검증, 추론, 내보내기, 추적, 벤치마크), Args는 모델과 하이퍼파라미터를 설정해요.

더 알아보기 (Learn more)