추론#

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

Predict 탭#

가중치가 포함된 모든 모델에는 브라우저 기반 추론을 위한 Predict 탭이 있습니다.

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

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

입력 방법#

예측 패널은 여러 입력 방법을 지원합니다.

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. 실시간 피드로 돌아가려면 웹캠으로 돌아가기를 클릭하세요

자체 배포의 Predict 탭에서는 웹캠으로 연속 추론을 실행합니다. 실시간 카메라 추론을 참조하세요.

결과 보기#

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

결과 패널에는 다음 항목이 표시됩니다.

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

추론 매개변수#

이미지 아래의 슬라이더 3개를 사용해 추론 동작을 조정합니다(깊이 모델에는 Image Size만 표시됨).

신뢰도 임계값#

신뢰도를 기준으로 예측을 필터링합니다:

• 높음(0.5+): 예측 수는 적지만 신뢰도가 높습니다
• 낮음(0.1~0.25): 예측 수는 많지만 노이즈가 일부 포함됩니다
• 기본값(0.25): 대부분의 사용 사례에 적합한 균형값입니다

IoU 임계값#

비최대 억제(Non-Maximum Suppression)를 제어합니다:

• 높음(0.7+): 더 많은 겹치는 박스를 허용합니다
• 낮음(0.3~0.5): 겹치는 검출을 더 적극적으로 억제합니다
• 기본값(0.7): 대부분의 사용 사례에 적합한 균형 잡힌 NMS 동작입니다

배포 예측#

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

준비된 엔드포인트에서 처리된 이미지도 모니터링 탭에 반영됩니다. 예시와 집계 차트는 메모리에 보관되는 가볍고 임시적인 데이터이며, 서비스를 중지, 재시작, 재배포하거나 크기를 조정하거나 모델을 교체하면 삭제될 수 있습니다. 예시를 보존하려면 데이터셋에 저장하세요.

실시간 카메라 추론#

소유한 배포의 Predict 탭에서 웹캠 또는 IP 카메라를 선택하면 실시간 비디오에서 엔드포인트를 실행할 수 있습니다:

실시간 추론은 엔드포인트에 연결된 API 키를 사용하며, 이 키는 작업 공간 소유자만 불러올 수 있습니다. 다른 팀원은 웹캠으로 단일 프레임을 캡처하며, 모델의 Predict 탭과 마찬가지로 IP 카메라를 사용할 수 없습니다. IP 카메라는 인터넷에서 접근할 수 있어야 합니다. 엔드포인트는 192.168.x.x과 같은 로컬 네트워크 주소를 거부합니다. 각 결과는 최신 프레임을 대상으로 하므로 추론이 지연되면 프레임을 건너뜁니다. 슬라이더 변경은 다음 웹캠 프레임에 적용되며 IP 카메라 스트림을 다시 시작합니다. 브라우저 탭이 숨겨지면 실시간 추론이 일시 중지됩니다. 미리보기를 클릭해 프레임을 캡처하거나 연결 해제를 클릭해 IP 카메라 보기를 중지하세요.

백그라운드 카메라#

사용자 지정 CPU 및 메모리 크기를 사용하는 엔드포인트는 페이지 연결을 해제하거나 닫은 후에도 IP 카메라 하나를 계속 감시할 수 있습니다. 연결된 카메라에 결과가 표시되면 백그라운드에서 계속 실행을 켜세요. 배포 헤더에 카메라 켜짐이 표시되고, 결과는 임시 예제와 예측 통계로 모니터링 탭에 전송됩니다.

• 설정: 백그라운드 카메라는 항상 기본 신뢰도(0.25), IoU(0.7), 모델의 학습 이미지 크기를 사용하며 슬라이더 설정은 적용되지 않습니다.
• 비용: 추가 요금 없이 엔드포인트의 가동 인스턴스에서 실행됩니다. 카메라를 켜거나 꺼도 시간당 가동 요금은 동일하게 적용됩니다.
• 변경: 카메라를 켜거나 끄거나 다른 카메라로 전환하면 엔드포인트 인스턴스가 다시 시작됩니다. 엔드포인트는 사용할 수 있는 상태로 유지되지만 임시 모니터링 데이터는 삭제됩니다.
• 중지: 스위치를 끄세요. 연결을 해제하거나 페이지를 닫아도 카메라는 중지되지 않습니다. 엔드포인트 크기를 기본값으로 조정하면 카메라가 제거됩니다. 카메라가 오프라인 상태가 되면 엔드포인트는 계속 재연결을 시도합니다.
• 엔드포인트 수명 주기: 엔드포인트를 중지하면 카메라와 요금 청구가 중지됩니다. 엔드포인트를 다시 시작하면 저장된 카메라가 재개됩니다.

기본 크기 엔드포인트는 백그라운드 옵션 없이 실시간 웹캠 및 IP 카메라 추론을 지원합니다. API에서 백그라운드 카메라를 저장하려면 배포 camera 작업을 사용하세요.

API에서 결과 스트리밍#

전용 엔드포인트 URL에 source로 RTSP 또는 RTSPS URL을 보내고 Accept: text/event-stream 헤더를 포함하면 서버 전송 이벤트로 결과를 받을 수 있습니다:

curl -N -X POST \
  "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -F "source=rtsp://user:password@camera.example.com:554/stream" \
  -F "conf=0.25"

각 프레임 이벤트에는 정규화된(0-1) 좌표가 포함된 images 응답 객체가 응답 형식으로 들어 있습니다. 또한 프레임의 preview JPEG 데이터 URL과 작업 및 클래스 이름이 포함된 metadata도 포함됩니다. conf, iou, imgsz만 적용되며, 엔드포인트의 백그라운드 카메라 URL을 스트리밍하면 기본 설정이 사용됩니다. status만 포함된 이벤트에는 프레임이 없습니다. error 메시지가 포함된 이벤트(카메라를 읽을 수 없거나 엔드포인트에서 모델을 실행할 수 없음)가 발생하면 스트림이 종료됩니다. 엔드포인트가 다시 시작되거나 요청이 시간 제한에 도달해도 스트림이 닫힙니다. 오류 없이 종료되면 지수 백오프를 적용해 다시 연결하세요. Platform API의 배포 예측 경로와 SDK는 스트리밍을 지원하지 않습니다. 카메라 요청은 연결된 API 키와 함께 엔드포인트 URL로 보내세요. 헤더 없이 카메라 source를 요청하면 400이 반환됩니다.

전용 엔드포인트 API#

모델의 Predict 탭에 있는 API Docs 카드에는 현재 슬라이더에 설정된 신뢰도, IoU, 이미지 크기가 미리 채워진 Python, JavaScript, cURL 요청 예시가 있습니다. 모델을 배포하기 전까지 URL과 키는 자리 표시자입니다. 코드 탭 옆의 Deploy 버튼을 누르면 모델의 Deploy 탭으로 이동합니다. 배포 후에는 배포 페이지의 Predict 탭에 있는 Docs 결과 탭에 해당 엔드포인트의 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=...)을 사용하세요. 두 SDK 메서드 모두 Platform API를 호출하므로 요청 제한과 요청 크기 제한이 적용됩니다. 이러한 제한을 피하려면 요청에 표시된 대로 전용 엔드포인트 URL에 직접 요청을 전송하세요. 공유 추론 예시:

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,
        "classNames": ["person", "bicycle", "car", "..."],
        "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회 요청으로 제한됩니다. Platform 배포 예측 경로(POST /api/deployments/{owner}/{deployment}/predict)에도 동일한 제한이 적용됩니다. 요청이 제한되면 API는 429을 Retry-After 헤더와 함께 반환합니다. 모든 엔드포인트 범주에 대한 자세한 내용은 요청 제한 참조 문서를 확인하세요.

오류 처리#

일반적인 오류 응답:

자주 묻는 질문#