추론#

Ultralytics Platform은 학습된 모델을 테스트할 수 있는 브라우저 기반 inference와 프로그래밍 방식으로 액세스할 수 있는 전용 엔드포인트를 제공합니다.

Predict 탭#

가중치가 포함된 모든 모델에는 브라우저 기반 inference를 위한 Predict 탭이 표시됩니다:

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

가중치가 없는 모델에는 대신 빈 상태가 표시됩니다. 먼저 모델을 학습하거나 가중치를 업로드합니다.

입력 방법#

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
• 최대 크기: 10 MB
• 자동 inference: 업로드 후 결과가 자동으로 표시됩니다

예제 이미지#

Predict 패널은 모델에 연결된 데이터셋에서 최대 2개의 예제 이미지를 표시하며, 먼저 val split을 선택하고 그다음 test, train 순으로 선택합니다. 연결된 데이터셋이 없으면 기본 예제가 사용됩니다:

OBB 모델의 경우 보트와 공항의 항공 이미지가 대신 표시됩니다.

Webcam#

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

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

결과 보기#

Inference 결과에는 모델 작업에 적합한 출력이 표시됩니다. 여기에는 box, mask, keypoint, oriented box, classification score, semantic coverage 또는 depth map이 포함됩니다. 사용 가능한 경우 객체 결과에는 데이터셋 클래스 색상이 사용됩니다. 패널에는 preprocess, inference, postprocess 및 network 처리 시간도 표시됩니다.

결과 패널에 표시되는 내용은 다음과 같습니다:

결과가 표시되면 미리 보기 위에 두 가지 컨트롤이 나타납니다. 이미지를 클릭하면 오버레이를 유지한 채 확대할 수 있고, 다운로드 버튼을 사용하면 현재 결과에 주석이 표시된 JPEG를 저장할 수 있습니다.

Inference 파라미터#

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

Confidence 임계값#

confidence를 기준으로 prediction을 필터링합니다:

• 높음(0.5 이상): 더 적고 확실성이 높은 prediction
• 낮음(0.1~0.25): 더 많은 prediction과 일부 noise
• 기본값(0.25): 대부분의 사용 사례에 균형 잡힌 설정

IoU 임계값#

비최대 억제를 제어합니다:

• 높음(0.7 이상): 더 많이 겹치는 box 허용
• 낮음(0.3~0.5): 겹치는 감지를 더 적극적으로 억제
• 기본값(0.7): 대부분의 사용 사례에 균형 잡힌 NMS 동작

배포 Predict#

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

모니터링이 활성화된 유료 엔드포인트에서는 처리된 이미지도 Monitoring 탭에 기여합니다. 샘플링된 예시와 집계 차트는 메모리에 유지되는 경량의 임시 데이터이며, 모델을 중지, 재시작, 재배포, 크기 조정 또는 교체하면 삭제될 수 있습니다. 예시를 유지하려면 데이터셋에 저장하세요.

전용 엔드포인트 API#

모델의 Predict 탭에 있는 API Docs 카드에는 confidence, IoU 및 현재 슬라이더에서 설정된 이미지 크기가 미리 입력된 Python, JavaScript 및 cURL 요청 예제가 포함되어 있습니다. 배포하기 전까지 URL과 key는 자리 표시자로 유지되며, 코드 탭 옆의 Deploy 버튼을 클릭하면 모델의 Deploy 탭으로 이동합니다. 배포 후에는 배포 카드의 Code 탭에 해당 엔드포인트의 URL과 workspace 소유자의 경우 연결된 API key가 입력되므로 복사하여 바로 실행할 수 있습니다.

인증#

요청에 API key를 포함합니다:

Authorization: Bearer YOUR_API_KEY

엔드포인트#

전용 엔드포인트는 자체 URL로 요청을 받습니다:

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

공유 inference는 모델의 전체 경로와 함께 Platform API를 사용합니다:

POST https://platform.ultralytics.com/api/models/{owner}/{project}/{model}/predict

두 방식 모두 동일한 multipart/form-data body를 허용하고 동일한 response shape을 반환합니다. Python SDK를 사용하는 경우 공유 inference에는 client.models.predict(owner, project, model, body=...)를, 전용 배포에는 client.deployments.predict(owner, deployment, body=...)을 사용합니다:

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
with open("image.jpg", "rb") as f:
    results = client.models.predict("acme-vision", "inspection", "v3", body={"file": f, "conf": 0.25})

요청#

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,
        "functionTimeAlive": 1284.51,
        "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}
}

속도 제한#

공유 모델 API는 각 API 키, 로그인한 호출자 또는 익명 IP마다 분당 20개 요청으로 제한됩니다. 요청이 제한되면 API는 429과 Retry-After 헤더를 반환합니다. 모든 엔드포인트 범주에 대한 자세한 내용은 속도 제한 참조를 확인하십시오.

오류 처리#

일반적인 오류 응답:

FAQ#