추론#

Ultralytics Platform은(는) 학습된 모델 테스트를 위한 브라우저 기반 추론 기능과 프로그래밍 방식 액세스를 위한 전용 엔드포인트를 제공합니다.

예측 탭#

모든 모델에는 브라우저 기반 추론을 위한 Predict 탭이 포함되어 있습니다:

1. 모델로 이동합니다
2. Predict 탭을 클릭합니다
3. 이미지를 업로드하거나, 예제를 사용하거나, 웹캠을 엽니다
4. 작업별 오버레이, 예측 요약, 타이밍 및 원시 응답을 검토합니다.

입력 방식#

Predict 패널은 여러 입력 방식을 지원합니다:

graph LR
    A[Upload Image]:::start --> D[Auto-Inference]:::proc
    B[Example Image]:::start --> D
    C[Webcam Capture]:::start --> D
    D --> E[Results + Overlays]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

이미지 업로드#

드래그 앤 드롭하거나 클릭하여 업로드하세요:

• 지원되는 형식: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP, DNG, MPO
• 최대 크기: 10MB
• 자동 추론: 업로드 후 결과가 자동으로 표시됩니다

예제 이미지#

Predict 패널은 모델에 연결된 데이터셋의 예제 이미지를 보여줍니다. 연결된 데이터셋이 없는 경우 기본 예제가 사용됩니다:

OBB 모델의 경우, 대신 보트와 공항의 항공 사진이 표시됩니다.

웹캠#

웹캠 카드를 클릭하여 실시간 카메라 피드를 시작합니다:

1. 메시지가 표시되면 카메라 권한을 허용합니다
2. 비디오 미리보기를 클릭하여 프레임을 캡처합니다
3. 캡처된 프레임에서 자동으로 추론이 실행됩니다
4. 다시 클릭하면 웹캠이 재시작됩니다

결과 확인#

추론 결과에는 모델 작업에 적절한 출력(박스, 마스크, 키포인트, 회전된 박스, 분류 점수, 시맨틱 커버리지 또는 깊이 맵)이 표시됩니다. 객체 결과는 가능한 경우 데이터셋 클래스 색상을 사용합니다. 또한 패널에는 전처리, 추론, 후처리 및 네트워크 타이밍이 표시됩니다.

결과 패널에 표시되는 항목:

추론 파라미터#

이미지 아래의 세 가지 슬라이더로 추론 동작을 조정합니다:

신뢰도 임계값#

신뢰도별로 예측 필터링:

• 높음 (0.5+): 더 적지만 확실한 예측
• 낮음 (0.1-0.25): 더 많은 예측, 일부 노이즈 포함
• 기본값 (0.25): 대부분의 사용 사례에 최적화된 균형

IoU 임계값#

NMS(비최대 억제) 제어:

• 높음 (0.7+): 겹치는 박스 허용
• 하한 (0.3-0.5): 겹치는 탐지를 더 적극적으로 억제합니다.
• 기본값 (0.7): 대부분의 사용 사례에 최적화된 균형 잡힌 NMS 동작

배포 모델 예측#

실행 중인 각 전용 엔드포인트에는 배포 카드에 직접 Predict 탭이 포함되어 있습니다. 이 탭은 공유 예측 서비스 대신 배포 자체의 추론 서비스를 사용하므로 브라우저에서 배포된 엔드포인트를 테스트할 수 있습니다.

전용 엔드포인트 API#

모델 Predict 탭의 API Docs 카드에는 Python, JavaScript 및 cURL 요청 예제가 포함되어 있습니다. 예제는 모델을 배포할 때까지 자리표시자를 사용합니다. 배포 후에는 배포 카드의 Code 탭에 엔드포인트 URL과 워크스페이스에서 사용할 수 있는 API 키가 입력됩니다.

인증#

요청에 API 키를 포함하세요:

Authorization: Bearer YOUR_API_KEY

엔드포인트#

POST https://YOUR_DEPLOYMENT_URL.run.app/predict

요청#

import requests

url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

with open("image.jpg", "rb") as image_file:
    response = requests.post(url, headers=headers, files={"file": image_file}, data=data)
print(response.json())

요청 파라미터#

응답#

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                },
                {
                    "class": 2,
                    "name": "car",
                    "confidence": 0.87,
                    "box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
                }
            ],
            "speed": {
                "preprocess": 1.2,
                "inference": 12.5,
                "postprocess": 2.3
            }
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

응답 필드#

작업별 응답#

응답 형식은 작업에 따라 다릅니다:

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}

속도 제한(Rate Limits)#

공유 모델 API는 각 API 키, 로그인한 호출자 또는 익명 IP당 분당 20회 요청으로 제한됩니다. 제한에 도달하면 API는 Retry-After 헤더와 함께 429을 반환합니다. 모든 엔드포인트 범주에 대해서는 전체 rate-limit reference를 참조하세요.

오류 처리#

일반적인 오류 응답:

FAQ#

비디오에서 추론을 실행할 수 있습니까?#

두 가지 추론 방법 모두 비디오 파일을 허용합니다:

• 전용 엔드포인트는 비디오 파일을 직접 허용합니다. 지원되는 형식 (최대 100 MB): ASF, AVI, GIF, M4V, MKV, MOV, MP4, MPEG, MPG, TS, WEBM, WMV. 각 프레임은 개별적으로 처리되며 결과는 프레임별로 반환됩니다. 자세한 내용은 전용 엔드포인트를 참조하세요.
• 공유 추론(/api/models/{id}/predict)은 동일한 예측 서비스를 사용하며 동일한 비디오 형식을 허용합니다. 브라우저 Predict 탭은 이미지만 선택하므로 비디오의 경우 API 또는 전용 엔드포인트를 사용하세요.

주석이 달린 이미지는 어떻게 얻습니까?#

API는 JSON 예측을 반환합니다. 시각화하려면:

1. 예측을 사용하여 로컬에서 박스 그리기
2. Ultralytics plot() 메서드를 사용하세요:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
results = model("image.jpg")
results[0].save("annotated.jpg")

전체 결과 API 및 시각화 옵션에 대해서는 Predict 모드 문서를 참조하세요.

최대 이미지 크기는 얼마입니까?#

• Predict 탭 제한: 10 MB
• 전용 엔드포인트 API 제한: 100 MB
• Predict 탭의 자동 크기 조절: 업로드하기 전에 이미지가 선택한 Image Size 크기로 조절됩니다.

큰 이미지는 종횡비를 유지하면서 자동으로 크기가 조정됩니다.

배치 추론을 실행할 수 있습니까?#

현재 API는 요청당 하나의 이미지를 처리합니다. 배치를 수행하려면:

1. 각 이미지마다 별도의 요청 전송
2. 적절한 경우 전용 엔드포인트 간에 요청 분산
3. 대규모 배치에는 로컬 추론 사용

import concurrent.futures

import requests

url = "https://predict-abc123.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
images = ["img1.jpg", "img2.jpg", "img3.jpg"]

def predict(image_path):
    with open(image_path, "rb") as f:
        return requests.post(url, headers=headers, files={"file": f}).json()

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(predict, images))