Link to this section추론#

Ultralytics Platform은 학습된 모델을 테스트하기 위한 추론 API를 제공합니다. 브라우저 기반의 Predict 탭을 사용하여 빠르게 검증하거나 REST API를 통해 프로그래밍 방식으로 접근할 수 있습니다.

Link to this section예측 탭#

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

1. 모델로 이동합니다
2. Predict 탭을 클릭합니다
3. 이미지를 업로드하거나, 예제를 사용하거나, 웹캠을 엽니다
4. 바운딩 박스 오버레이가 포함된 예측 결과를 즉시 확인합니다

Link to this section입력 방식#

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

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

    style D fill:#2196F3,color:#fff
    style E fill:#4CAF50,color:#fff

Link to this section이미지 업로드#

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

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

Link to this section예제 이미지#

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

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

Link to this section웹캠#

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

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

Link to this section결과 확인#

추론 결과 표시 항목:

• 바운딩 박스: 클래스 레이블이 포함된 SVG 오버레이
• 신뢰도 점수: 각 탐지 결과에 대한 수치
• 클래스 색상: 데이터셋의 색상 팔레트(또는 Ultralytics 기본 팔레트)에서 지정
• 속도 분석: 전처리, 추론, 후처리 및 네트워크 시간

결과 패널 표시 내용:

Link to this section추론 파라미터#

접기 가능한 파라미터 섹션에서 탐지 동작을 조정할 수 있습니다:

Link to this section신뢰도 임계값#

신뢰도별로 예측 필터링:

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

Link to this sectionIoU 임계값#

NMS(비최대 억제) 제어:

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

Link to this section배포 모델 예측#

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

Link to this sectionREST API#

프로그래밍 방식으로 추론에 접근:

Link to this section인증#

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

Authorization: Bearer YOUR_API_KEY

Link to this section엔드포인트#

POST https://platform.ultralytics.com/api/models/{modelId}/predict

Link to this section요청#

import requests

url = "https://platform.ultralytics.com/api/models/MODEL_ID/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Link to this section요청 파라미터#

Link to this section응답#

{
    "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,
        "model": "model.pt",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Link to this section응답 필드#

Link to this section작업별 응답#

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

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

Link to this section결제(Billing)#

공유 추론(Predict 탭 및 /api/models/{id}/predict 엔드포인트)은 모든 플랜에 추가 비용 없이 포함되어 있습니다. 공유 추론에 대한 요청당 비용은 없습니다.

더 높은 처리량이 필요한 프로덕션 워크로드의 경우, 전용 엔드포인트를 배포하십시오.

Link to this section속도 제한(Rate Limits)#

Shared inference is rate-limited to 20 requests/min per API key. When throttled, the API returns 429 with a Retry-After header. See the full rate limit reference for all endpoint categories.

Link to this section오류 처리#

일반적인 오류 응답:

Link to this sectionFAQ#

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

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

• 전용 엔드포인트는 비디오 파일을 직접 허용합니다. 지원되는 형식(최대 100MB): ASF, AVI, GIF, M4V, MKV, MOV, MP4, MPEG, MPG, TS, WEBM, WMV. 각 프레임이 개별적으로 처리되고 결과는 프레임별로 반환됩니다. 자세한 내용은 전용 엔드포인트를 참조하십시오.
• 공유 추론(/api/models/{id}/predict)은 동일한 Predict 서비스를 사용하며 동일한 비디오 형식을 허용합니다. 그러나 UI의 브라우저 Predict 탭은 이미지만 업로드하므로 비디오 워크로드에는 REST API를 직접 사용하거나 전용 엔드포인트를 사용하십시오. 공유 엔드포인트는 분당 20회 요청으로 속도 제한이 적용되므로, 대규모 비디오 워크로드에는 전용 엔드포인트가 더 나은 선택입니다.

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

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 모드 문서를 참조하십시오.

Link to this section최대 이미지 크기는 얼마입니까?#

• 업로드 제한: 10MB
• 권장: 빠른 추론을 위해 <5MB
• 자동 크기 조정: 이미지는 선택된 Image Size 매개변수로 크기가 조정됩니다

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

Link to this section배치 추론을 실행할 수 있습니까?#

현재 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))