Ultralytics YOLO를 사용한 모델 예측#

소개#

머신러닝과 컴퓨터 비전 분야에서는 시각 데이터를 해석하는 과정을 흔히 추론 또는 예측이라고 합니다. Ultralytics YOLO26은 predict 모드라는 강력한 기능을 제공하며, 다양한 데이터 소스에서 고성능 실시간 추론을 수행하도록 설계되었습니다.

추론 예시 계획은 미출시 YOLO27 미리보기를 참조하세요.

실제 적용 사례#

추론에 Ultralytics YOLO를 사용하는 이유#

다양한 추론 요구 사항에 YOLO26의 predict 모드를 고려해야 하는 이유는 다음과 같습니다.

• 다재다능함: 이미지, 동영상, 실시간 스트림에서 추론을 실행할 수 있습니다.
• 성능: 정확도를 저하시키지 않으면서 실시간 고속 처리를 제공하도록 설계되었습니다.
• 간편한 사용: 신속한 배포와 테스트를 위한 직관적인 Python 및 CLI 인터페이스를 제공합니다.
• 높은 사용자 지정 가능성: 특정 요구 사항에 맞게 모델의 추론 동작을 조정할 수 있는 다양한 설정과 매개변수를 제공합니다.
• 프로덕션 배포 준비 완료: 자동 확장 및 모니터링 기능을 갖춘 Ultralytics Platform 추론 엔드포인트로 모델을 배포하거나 로컬에서 추론을 실행할 수 있습니다.

Predict 모드의 주요 기능#

YOLO26의 predict 모드는 견고하고 다재다능하도록 설계되었으며, 다음 기능을 제공합니다.

• 다양한 데이터 소스 호환성: 개별 이미지, 이미지 모음, 동영상 파일 또는 실시간 동영상 스트림 등 데이터 형식에 관계없이 predict 모드를 사용할 수 있습니다.
• 스트리밍 모드: 스트리밍 기능을 사용하면 메모리 효율적인 Results 객체 제너레이터를 생성할 수 있습니다. 예측기의 호출 메서드에서 stream=True을 설정하여 이 기능을 활성화합니다. 모든 결과가 포함된 목록을 반환하는 기본 동작(stream=False)과 달리, stream=True은 결과를 한 번에 하나씩 생성하므로 긴 동영상과 실시간 스트림에 특히 유용합니다.
• 배치 처리: 여러 이미지 또는 동영상 프레임을 단일 배치로 처리하여 전체 추론 시간을 더욱 줄입니다.
• 간편한 통합: 유연한 API 덕분에 기존 데이터 파이프라인 및 기타 소프트웨어 구성 요소와 쉽게 통합할 수 있습니다.

Ultralytics YOLO 모델은 추론 시 모델에 stream=True를 전달하면 Results 객체의 Python 목록 또는 메모리 효율적인 Results 객체 제너레이터를 반환합니다.

from ultralytics import YOLO

# 모델 로드
model = YOLO("yolo26n.pt")  # 사전 학습된 YOLO26n 모델

# 이미지 목록에 대해 배치 추론 실행
results = model(["image1.jpg", "image2.jpg"])  # Results 객체 목록 반환

# 결과 목록 처리
for result in results:
    boxes = result.boxes  # 바운딩 박스 출력을 위한 Boxes 객체
    masks = result.masks  # 세그멘테이션 마스크 출력을 위한 Masks 객체
    keypoints = result.keypoints  # 포즈 출력을 위한 Keypoints 객체
    probs = result.probs  # 분류 출력을 위한 Probs 객체
    obb = result.obb  # OBB 출력을 위한 방향 지정 박스 객체
    result.show()  # 화면에 표시
    result.save(filename="result.jpg")  # 디스크에 저장

추론 소스#

YOLO26은 아래 표와 같이 다양한 유형의 입력 소스를 추론에 사용할 수 있습니다. 소스에는 정적 이미지, 동영상 스트림 및 다양한 데이터 형식이 포함됩니다. 또한 각 소스를 stream=True ✅ 인수를 사용하는 스트리밍 모드에서 사용할 수 있는지도 표에 표시되어 있습니다. 스트리밍 모드는 모든 프레임을 메모리에 로드하는 대신 결과 제너레이터를 생성하므로 동영상이나 실시간 스트림 처리에 유용합니다.

각 소스 유형을 사용하는 코드 예시는 다음과 같습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n 모델 로드
model = YOLO("yolo26n.pt")

# 이미지 파일 경로 정의
source = "path/to/image.jpg"

# 소스에서 추론 실행
results = model(source)  # Results 객체 목록

추론 인수#

model.predict()은 추론 시 기본값을 재정의하기 위해 전달할 수 있는 여러 인수를 지원합니다:

고정 형태와 최소 사각형(rect)#

기본적으로 predict는 rect=True을 사용하며, 가능한 경우 최소 사각형 패딩을 적용합니다. 이미지는 imgsz 안에 맞도록 크기가 조정되고 가장 가까운 stride 배수까지만 패딩되므로 최종 텐서는 imgsz보다 작을 수 있습니다. 최소 사각형 패딩은 배치의 모든 이미지가 동일한 형태이고 백엔드가 이를 지원하는 경우에만 사용됩니다(PyTorch .pt 또는 동적 ONNX와 같은 동적 형태 내보내기). 그렇지 않으면 이미지에 전체 imgsz 대상 크기까지 패딩이 적용됩니다.

항상 전체 imgsz 대상 크기까지 패딩하려면 rect=False을 사용합니다. 내보낸 모델(ONNX, TensorRT 등)에 맞춰 고정 입력 크기가 필요한 경우 이 방법을 권장합니다.

정수와 튜플 imgsz

• 정수 imgsz=640은 stride 반올림 후 정사각형 대상 크기 (640, 640)이 됩니다.
• 튜플 imgsz=(384, 672)은 직사각형 대상 크기를 설정합니다. rect=True을 사용하면 실제 텐서가 이 대상 크기보다 작을 수 있습니다.

학습과 predict/export

학습에서는 단일 정수 imgsz만 지원합니다([h, w] 목록은 가장 큰 값으로 변환됩니다). Predict와 export에서는 정수 또는 (height, width) 튜플을 사용할 수 있습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n 모델 로드
model = YOLO("yolo26n.pt")

# 'bus.jpg'에서 인수를 사용해 추론 실행
model.predict("https://ultralytics.com/images/bus.jpg", save=True, imgsz=320, conf=0.25)

추론 인수:

시각화 인수:

이미지 및 동영상 형식#

YOLO26은 ultralytics/data/utils.py에 명시된 다양한 이미지 및 동영상 형식을 지원합니다. 유효한 접미사와 predict 명령 예시는 아래 표를 참조하세요.

이미지#

아래 표에는 유효한 Ultralytics 이미지 형식이 나와 있습니다.

동영상#

아래 표에는 유효한 Ultralytics 동영상 형식이 나와 있습니다.

Results 사용#

모든 Ultralytics predict() 호출은 Results 객체 목록을 반환합니다:

from ultralytics import YOLO

# 사전 학습된 YOLO26n 모델 로드
model = YOLO("yolo26n.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")
results = model(
    [
        "https://ultralytics.com/images/bus.jpg",
        "https://ultralytics.com/images/zidane.jpg",
    ]
)  # 배치 추론

Results 객체에는 다음 속성이 있습니다:

작업별 Results#

아래에서 어떤 필드가 채워지는지는 모델의 작업에 따라 달라집니다. 아직 작업을 선택하지 않았다면 탐지, 세그멘테이션, 시맨틱 세그멘테이션, 깊이 추정, 분류, 포즈, OBB 비교를 참조하세요. 각 예측은 이미지 또는 프레임마다 Results 객체 하나를 반환합니다. 위의 공통 필드는 항상 사용할 수 있으며, 작업별 예측 데이터는 아래 필드에 저장됩니다. YOLO 좌표 및 신뢰도 텐서는 torch.float32이고, 확률 텐서는 FP16 추론(quantize=16)을 사용하는 경우가 아니면 torch.float32입니다. FP16 추론을 사용하면 torch.float16가 됩니다. result.numpy() 이후 텐서는 해당 NumPy dtype을 유지하는 NumPy 배열이 됩니다. 인스턴스 마스크는 torch.uint8 이진 텐서이며, 시맨틱 마스크는 클래스 수에 따라 클래스 ID에 가장 적합한 최소 정수 dtype인 torch.uint8, torch.int16 또는 torch.int32을 사용합니다.

Results 객체에는 다음 메서드가 있습니다.

자세한 내용은 Results 클래스 문서를 참조하세요.

박스#

Boxes 객체를 사용하여 바운딩 박스를 인덱싱하고 조작하거나 다른 형식으로 변환할 수 있습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n 모델 로드
model = YOLO("yolo26n.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")  # 결과 목록

# 결과 보기
for r in results:
    print(r.boxes)  # 탐지 바운딩 박스가 포함된 Boxes 객체를 print합니다

다음은 이름, 유형 및 설명을 포함한 Boxes 클래스 메서드와 속성의 표입니다.

자세한 내용은 Boxes 클래스 문서를 참조하세요.

마스크#

Masks 객체를 사용하여 마스크를 인덱싱하고 조작하거나 세그먼트로 변환할 수 있습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n-seg 세그먼트 모델 로드
model = YOLO("yolo26n-seg.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")  # 결과 목록

# 결과 보기
for r in results:
    print(r.masks)  # 탐지된 인스턴스 마스크가 포함된 Masks 객체를 print합니다

다음은 이름, 유형 및 설명을 포함한 Masks 클래스 메서드와 속성의 표입니다.

자세한 내용은 Masks 클래스 문서를 참조하세요.

SemanticMask#

SemanticMask은 시맨틱 세그멘테이션 결과를 위한 조밀한 클래스 맵 하나를 저장합니다. Masks과 달리 객체별 이진 마스크를 포함하지 않으며 폴리곤 헬퍼도 제공하지 않습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n-sem 시맨틱 모델 로드
model = YOLO("yolo26n-sem.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")  # 결과 목록

# 결과 보기
for r in results:
    print(r.semantic_mask.data)  # H x W 클래스 ID 맵을 print합니다

키포인트#

Keypoints 객체를 사용하여 좌표를 인덱싱하고 조작하거나 정규화할 수 있습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n-pose 포즈 모델 로드
model = YOLO("yolo26n-pose.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")  # 결과 목록

# 결과 보기
for r in results:
    print(r.keypoints)  # 탐지된 키포인트가 포함된 Keypoints 객체를 print합니다

다음은 이름, 유형 및 설명을 포함한 Keypoints 클래스 메서드와 속성의 표입니다.

자세한 내용은 Keypoints 클래스 문서를 참조하세요.

확률값#

Probs 객체를 사용하여 top1 분류 인덱스와 top5 점수를 가져올 수 있습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n-cls 분류 모델 로드
model = YOLO("yolo26n-cls.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/bus.jpg")  # 결과 목록

# 결과 보기
for r in results:
    print(r.probs)  # 탐지된 클래스 확률이 포함된 Probs 객체를 print합니다

다음은 Probs 클래스의 메서드와 속성을 요약한 표입니다.

자세한 내용은 Probs 클래스 문서를 참조하세요.

OBB#

OBB 객체를 사용하여 방향 경계 상자를 인덱싱하고 조작하며 다양한 형식으로 변환할 수 있습니다.

from ultralytics import YOLO

# 사전 학습된 YOLO26n 모델 로드
model = YOLO("yolo26n-obb.pt")

# 이미지에서 추론 실행
results = model("https://ultralytics.com/images/boats.jpg")  # 결과 목록

# 결과 보기
for r in results:
    print(r.obb)  # 방향 탐지 경계 상자를 포함하는 OBB 객체를 출력합니다

다음은 이름, 유형 및 설명을 포함한 OBB 클래스 메서드와 속성의 표입니다.

자세한 내용은 OBB 클래스 문서를 참조하세요.

결과 시각화#

Results 객체의 plot() 메서드는 감지된 객체(예: 경계 상자, 마스크, 키포인트, 확률)를 원본 이미지에 오버레이하여 예측 결과를 시각화합니다. 이 메서드는 주석이 추가된 이미지를 NumPy 배열로 반환하므로 쉽게 표시하거나 저장할 수 있습니다.

from PIL import Image

from ultralytics import YOLO

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

# Run inference on 'bus.jpg'
results = model(["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"])  # results list

# Visualize the results
for i, r in enumerate(results):
    # Plot results image
    im_bgr = r.plot()  # BGR-order numpy array
    im_rgb = Image.fromarray(im_bgr[..., ::-1])  # RGB-order PIL image

    # Show results to screen (in supported environments)
    r.show()

    # Save results to disk
    r.save(filename=f"results{i}.jpg")

plot() 메서드 매개변수#

plot() 메서드는 출력을 사용자 지정할 수 있는 다양한 인수를 지원합니다:

스레드 안전 추론#

여러 스레드에서 여러 YOLO 모델을 병렬로 실행할 때는 추론 중 스레드 안전성을 보장하는 것이 매우 중요합니다. 스레드 안전 추론은 각 스레드의 예측 결과가 서로 격리되어 간섭하지 않도록 하며, 경쟁 상태를 방지하고 일관되고 신뢰할 수 있는 출력을 보장합니다.

멀티스레드 애플리케이션에서 YOLO 모델을 사용할 때는 충돌을 방지하기 위해 각 스레드에 별도의 모델 객체를 인스턴스화하거나 스레드 로컬 저장소를 사용하는 것이 중요합니다:

from threading import Thread

from ultralytics import YOLO

def thread_safe_predict(model, image_path):
    """Performs thread-safe prediction on an image using a locally instantiated YOLO model."""
    model = YOLO(model)
    results = model.predict(image_path)
    # 결과를 처리합니다

# 각 스레드가 자체 모델 인스턴스를 갖도록 스레드를 시작합니다
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image1.jpg")).start()
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image2.jpg")).start()

YOLO 모델의 스레드 안전 추론에 대한 자세한 내용과 단계별 지침은 YOLO 스레드 안전 추론 가이드를 참조하세요. 이 가이드에서는 일반적인 문제를 방지하고 멀티스레드 추론이 원활하게 실행되도록 하는 데 필요한 모든 정보를 제공합니다.

스트리밍 소스 for 루프#

다음은 OpenCV(cv2)와 YOLO를 사용해 비디오 프레임에서 추론을 실행하는 Python 스크립트입니다. 이 스크립트는 필요한 패키지(opencv-python 및 ultralytics)를 이미 설치했다고 가정합니다.

import cv2

from ultralytics import YOLO

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

# 비디오 파일을 엽니다
video_path = "path/to/your/video/file.mp4"
cap = cv2.VideoCapture(video_path)

# 비디오 프레임을 순회합니다
while cap.isOpened():
    # 비디오에서 프레임을 읽습니다
    success, frame = cap.read()

    if success:
        # 프레임에서 YOLO 추론을 실행합니다
        results = model(frame)

        # 프레임에 결과를 시각화합니다
        annotated_frame = results[0].plot()

        # 주석이 추가된 프레임을 표시합니다
        cv2.imshow("YOLO Inference", annotated_frame)

        # 'q'를 누르면 루프를 종료합니다
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break
    else:
        # 비디오 끝에 도달하면 루프를 종료합니다
        break

# 비디오 캡처 객체를 해제하고 표시 창을 닫습니다
cap.release()
cv2.destroyAllWindows()

이 스크립트는 비디오의 각 프레임에서 예측을 실행하고, 결과를 시각화한 뒤 창에 표시합니다. 'q'를 눌러 루프를 종료할 수 있습니다.

다음 단계#

사전 학습 모델 사용을 넘어 다음 단계로 나아갈 준비가 되셨나요? 작업이 문제에 적합한지 확인하고, 데이터셋 가이드에 따라 데이터를 직접 준비한 다음 모델을 학습시키세요.

자주 묻는 질문#