전용 엔드포인트#

Ultralytics Platform은(는) 42개의 전 세계 리전에 전용 엔드포인트로 YOLO 모델을 배포할 수 있도록 지원합니다. 각 엔드포인트는 스케일 투 제로(scale-to-zero) 동작, 고유한 엔드포인트 URL, 독립적인 모니터링을 갖춘 단일 테넌트 서비스입니다.

엔드포인트 생성#

배포(Deploy) 탭에서 생성#

Deploy 탭에서 모델을 배포합니다:

1. 모델로 이동합니다
2. Deploy 탭을 클릭합니다.
3. 사용자의 위치에서 측정한 지연 시간(latency)을 기준으로 정렬된 세계 지도와 리전(region) 테이블을 검토합니다.
4. 사용하고자 하는 리전 행에서 Deploy를 클릭합니다.

배포는 이름 지정 단계 없이 즉시 시작됩니다. 이름은 모델 이름과 지역 도시 이름(예: yolo26n-iowa)을 조합하여 생성됩니다. 모델에는 가중치가 포함되어 있어야 하며, 그렇지 않으면 탭에 지역 테이블 대신 빈 상태가 표시됩니다.

배포(Deployments) 페이지에서 생성#

사이드바의 전역 Deploy 페이지에서 배포를 생성합니다:

1. New Deployment를 클릭합니다.
2. 완료된 모델이 나열되는 모델 선택기에서 모델을 선택하세요.
3. 미니 맵 또는 지연 시간 테이블에서 지역을 선택하세요.
4. 여기서 편집할 수 있는 자동 생성된 배포 이름을 검토하세요.
5. Deploy Model을 클릭합니다.

배포 수명 주기#

stateDiagram-v2
    [*] --> Creating: Deploy
    Creating --> Deploying: Service starting
    Deploying --> Ready: Service URL published
    Ready --> Stopping: Stop
    Ready --> Deploying: Replace model
    Stopping --> Stopped: Stopped
    Stopped --> Deploying: Start
    Deploying --> Stopped: Start failed
    Ready --> [*]: Delete
    Stopped --> [*]: Delete
    Creating --> Failed: Error
    Deploying --> Failed: Error
    Failed --> [*]: Delete

    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff
    class Creating,Deploying,Stopping proc
    class Ready out
    class Failed error
    class Stopped extern

Slack alerts을(를) 연결하여 배포가 준비되었거나 시작에 실패했을 때 메시지를 받으세요.

리전 선택#

전 세계 42개 지역 중에서 선택하십시오. 대화형 지역 지도와 표는 다음 정보를 보여줍니다:

• 지역 핀(Region pins): 지연 시간에 따라 녹색에서 빨간색으로 그라데이션 색상이 지정됩니다(빠를수록 녹색, 느릴수록 빨간색).
• 배포된 지역: 테이블에서 "Deployed" 배지로 강조 표시됩니다.
• 배포 중인 지역: 핀과 테이블 행에 애니메이션 펄스 표시기가 나타납니다.
• 양방향 강조(Bidirectional highlighting): 지도에 마우스를 올리면 표의 행이 강조 표시되며, 그 반대의 경우도 동일합니다.

모델의 Deploy 탭에 있는 리전 테이블에는 다음 내용이 포함됩니다:

테이블은 도시, 국가, 영역별로 검색할 수 있으며 기본적으로 지연 시간 순으로 정렬됩니다.

사용 가능한 지역#

엔드포인트 구성#

새 배포 대화 상자#

New Deployment 대화상자는 다음 세 가지 입력을 수집합니다:

이름 아래에는 읽기 전용 Resources 패널과 Custom resources coming soon 배지가 표시됩니다. 현재 리소스를 구성할 수는 없습니다. 모든 엔드포인트는 유휴 상태일 때 0으로 축소(scale-to-zero)되는 단일 인스턴스로 실행됩니다.

배포 탭 (빠른 배포)#

모델의 Deploy 탭에서 배포를 진행하면 대화상자 단계 없이 동일한 고정 리소스와 자동 생성된 이름이 사용됩니다. 배포가 생성되는 동안 지역 테이블 아래의 Active Deployments 목록에 즉시 나타납니다.

엔드포인트 관리#

보기 모드#

배포 목록은 다음 세 가지 보기 모드를 지원합니다:

배포 카드 (카드 보기)#

카드 보기에 있는 각 배포 카드는 다음 정보를 표시합니다:

• 헤더: 이름, 지역 국기, 상태 배지, 그리고 현재 상태에서 사용할 수 있는 작업 버튼(준비 완료 상태일 때는 Ready, 중지 상태일 때는 Ready 상태에서 교체 및 중지, Stopped 상태일 때는 시작, 언제든지 삭제 가능)
• 엔드포인트 URL: 엔드포인트 고유의 API 참조 링크가 포함된 복사 가능한 URL
• 측정 항목: 요청 수(24시간), P95 지연 시간, 오류율 또는 "No traffic yet"
• 상태 점검: 지연 시간과 수동 새로 고침 기능을 갖춘 실시간 상태 표시기
• 탭: Logs, Code, Predict
• 푸터: 배포에 바인딩된 API 키 접두사와 준비 완료된 날짜
• 상태 메시지: 배포가 실패한 경우의 실패 원인

URL, 측정 항목, 상태 확인 및 탭은 배포가 Ready 상태인 동안에만 표시됩니다. Logs 탭에는 심각도 필터링(전체 / 오류)이 포함된 최근 로그 항목이 표시됩니다. Code 탭에는 엔드포인트 URL이 포함된 Python, JavaScript, cURL 형식의 즉시 사용 가능한 코드 예제와 워크스페이스 소유자를 위한 바인딩된 API 키가 표시됩니다(Monitoring 참조). Predict 탭은 배포에서 직접 테스트할 수 있는 인라인 예측 패널을 제공합니다.

모델 교체하기#

URL을 변경하지 않고 준비된 엔드포인트 뒤의 모델을 교체합니다:

1. 배포를 Cards 뷰로 엽니다
2. Replace model을 클릭합니다
3. 동일한 워크스페이스에서 완료된 다른 모델을 선택합니다
4. 선택 사항으로 배포 이름을 수정합니다
5. Replace Model을 클릭합니다

교체 작업이 시작되는 동안 기존 모델은 계속 트래픽을 처리합니다. 교체가 완료되면 트래픽이 새 모델로 이동합니다. 배포 ID, URL, 지역, API 키는 유지되며, 표시 이름은 새 이름을 입력할 때만 변경됩니다. 교체가 실패하면 이전 모델과 이름이 그대로 활성 상태로 유지됩니다.

모델을 교체하려면 다음 조건을 모두 충족해야 하며, 그렇지 않으면 요청이 거부됩니다:

• 배포가 Ready 상태이며 진행 중인 다른 수명 주기 작업이 없음
• 교체할 모델에 가중치가 있고 배포와 동일한 워크스페이스에 속함
• 교체할 모델이 현재 이미 배포된 모델이 아님

배포 상태#

엔드포인트 URL#

각 엔드포인트는 다음과 같은 고유한 URL을 가집니다:

https://predict-<deployment-id>-<hash>-<region>.a.run.app

복사 버튼을 클릭하여 URL을 복사합니다. 문서 아이콘을 클릭하여 엔드포인트 고유의 API 참조를 엽니다. 엔드포인트는 다음 경로를 제공합니다:

수명 주기 관리#

엔드포인트 상태 제어:

graph LR
    R[Ready]:::out -->|Stop| S[Stopped]:::extern
    S -->|Start| R
    R -->|Delete| D[Deleted]:::error
    S -->|Delete| D

    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

엔드포인트 중지#

요청을 수락하지 않도록 하려면 엔드포인트를 중지합니다:

1. 배포 카드에서 일시 중지 아이콘을 클릭하십시오
2. 엔드포인트 상태가 "중지 중"에서 "중지됨"으로 변경됩니다

중지된 엔드포인트:

• 요청을 수락하지 않으며, 측정 항목이나 상태 정보를 보고하지 않습니다.
• URL, 지역, 바인딩된 API 키가 유지되며 언제든지 다시 시작할 수 있습니다.
• 플랜의 배포 할당량에 계속산되므로 슬롯을 확보하려면 엔드포인트를 삭제하세요.

엔드포인트 삭제#

엔드포인트를 영구적으로 제거하려면:

1. 배포 카드에서 삭제(휴지통) 아이콘을 클릭하십시오
2. 대화 상자에서 삭제를 확인하십시오

모델이나 프로젝트가 영구적으로 삭제되거나, 휴지통에 버려진 모델 또는 프로젝트가 보관 기간 만료에 도달했을 때도 배포가 제거됩니다.

엔드포인트 사용#

인증#

각 배포는 모델을 소유한 워크스페이스의 단일 API 키에 바인딩됩니다. 요청에 해당 키를 포함하세요:

Authorization: Bearer YOUR_API_KEY

엔드포인트는 생성 시 바인딩된 키만 수락하므로 다른 어떤 키도 이를 열 수 없습니다. 동일한 워크스페이스 내의 다른 활성 키조차도 불가능합니다. 바인딩될 키를 제어하려면 워크스페이스 소유자의 키로 인증된 API를 통해 배포하세요. 해당 정확한 키가 바인딩되며 이미 보유하고 있는 키입니다. 그 외의 방법(플랫폼 UI 또는 팀원의 권한으로 인증된 API 호출)으로 생성된 배포는 소유 워크스페이스의 활성 키 중 하나를 자동으로 바인딩합니다. 배포 카드 푸터에 표시되는 키 접두사로 이를 식별하고, 소유자만 키 값을 볼 수 있으므로 워크스페이스 소유자에게 값을 문의하세요(API Keys 참조). 바인딩된 키가 없는 팀원도 브라우저의 플랫폼 예측 프록시를 통해 추론을 실행할 수 있습니다.

직접 엔드포인트 요청#

프로덕션 요청을 배포 카드에 표시된 URL로 직접 전송하세요. 이 요청은 플랫폼 API 속도 제한기를 거치지 않으므로 분당 20회의 예측 제한이 적용되지 않습니다. 단, 엔드포인트 자체의 용량 한계는 여전히 존재합니다:

• 각 엔드포인트는 단일 인스턴스로 서빙되며 한 번에 제한된 수의 요청을 처리합니다.
• 즉시 처리할 수 없는 요청은 429 헤더와 함께 Retry-After을 반환합니다.
• 단일 요청은 최대 1시간 동안 실행될 수 있으므로 비디오 추론이 완료될 수 있습니다.
• 1 KB보다 큰 응답은 gzip으로 압축되며, 교차 출처(CORS) 브라우저 요청이 허용됩니다.

요청 예시#

import requests

# Deployment endpoint
url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"

# Headers with your deployment API key
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Inference parameters
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

# Send image for inference
with open("image.jpg", "rb") as f:
    response = requests.post(url, headers=headers, data=data, files={"file": f})

print(response.json())

요청 파라미터#

bits이 반환된 깊이 맵(depth map)을 변경하는 방식과 이를 디코딩하는 방법에 대해서는 Depth responses를 참조하세요.

응답 형식#

태스크별 필드가 포함된 shared inference와 동일합니다.

FAQ#