추론#

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

예제 이미지#

예측 패널은 모델의 연결된 데이터셋에서 최대 두 장의 예시 이미지를 표시하며, val 분할, 그다음 test, 마지막으로 train 순으로 우선 적용합니다. 연결된 데이터셋이 없으면 기본 예시가 사용됩니다:

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

웹캠#

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

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

결과 확인#

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

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

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

추론 파라미터#

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

신뢰도 임계값#

신뢰도별로 예측 필터링:

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

IoU 임계값#

NMS(비최대 억제) 제어:

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

배포 모델 예측#

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

전용 엔드포인트 API#

모델 Predict 탭의 API Docs 카드에는 현재 슬라이더에 설정된 confidence, IoU, 이미지 크기로 미리 채워진 Python, JavaScript 및 cURL 요청 예시가 포함되어 있습니다. URL과 키는 모델을 배포할 때까지 자리표시자 상태로 유지됩니다. 코드 탭 옆의 Deploy 버튼을 누르면 모델의 Deploy 탭으로 이동합니다. 배포 후, 배포 카드의 Code 탭에는 해당 엔드포인트의 URL과(워크스페이스 소유자의 경우) 바인딩된 API 키가 채워져 복사하여 실행할 준비가 됩니다.

인증#

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

Authorization: Bearer YOUR_API_KEY

엔드포인트#

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

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

공유 추론은 모델의 전체 경로가 포함된 Platform API를 사용합니다:

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

둘 다 동일한 multipart/form-data 본문을 허용하며 동일한 응답 형태를 반환합니다. Python SDK를 사용하여 공유 추론에는 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}
}

속도 제한(Rate Limits)#

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

오류 처리#

일반적인 오류 응답:

FAQ#