전용 엔드포인트#

Ultralytics Platform은 42개 글로벌 지역의 전용 엔드포인트에 YOLO 모델을 배포할 수 있도록 지원합니다. 각 엔드포인트는 고유한 엔드포인트 URL과 독립적인 모니터링을 갖춘 단일 테넌트 서비스입니다. 기본 리소스 크기는 유휴 상태일 때 0으로 확장 축소되며, 사용자 정의 크기는 웜 인스턴스를 유지하고 가동 시간에 따라 요금이 청구됩니다.

엔드포인트 생성#

Deploy 탭에서#

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

1. 모델로 이동합니다
2. Deploy 탭을 클릭합니다
3. 세계 지도와 리전 테이블을 검토합니다. 리전 테이블은 현재 위치에서 측정된 지연 시간순으로 정렬됩니다
4. 사용할 리전의 행에서 Deploy를 클릭합니다
5. 대화 상자에서 CPU, 메모리, 가격, 배포 이름을 검토한 다음 Create Deployment를 클릭하십시오.

제안된 이름은 모델 이름과 지역 도시를 결합한 것(예: yolo26n-iowa)이며 배포 전에 편집할 수 있습니다. 모델에 가중치가 있어야 하며, 그렇지 않으면 탭에 지역 표 대신 빈 상태가 표시됩니다.

Deployments 페이지에서#

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

1. New Deployment를 클릭합니다
2. 완료된 모델이 표시되는 모델 선택기에서 모델을 선택합니다
3. 미니 맵 또는 지연 시간 테이블에서 리전을 선택합니다
4. CPU와 메모리를 선택하고, 가격을 검토한 후, 필요한 경우 제안된 배포 이름을 수정하십시오.
5. Create Deployment를 클릭하십시오.

배포 수명 주기#

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 알림을 연결합니다.

리전 선택#

전 세계 42개 리전 중에서 선택할 수 있습니다. 대화형 리전 지도와 테이블에는 다음 정보가 표시됩니다:

• 리전 핀: 녹색에서 빨간색으로 이어지는 그라데이션으로 지연 시간에 따라 색상이 지정됩니다(빠른 리전일수록 녹색에 가깝고, 느린 리전일수록 빨간색에 가깝습니다)
• 배포된 리전: 테이블에서 "Deployed" 배지로 강조 표시됩니다
• 배포 중인 리전: 핀과 테이블 행에 애니메이션 펄스 표시기가 나타납니다
• 양방향 강조 표시: 지도 위에 마우스를 올리면 테이블 행이 강조 표시되고, 그 반대도 동일합니다

모델 Deploy 탭의 리전 테이블에는 다음 항목이 포함됩니다.

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

사용 가능한 리전#

Endpoint 구성#

새 배포 대화 상자#

New Deployment 대화 상자에서 모델, 지역, 리소스, 배포 이름을 선택할 수 있습니다:

리소스 제어에서 CPU 및 메모리 크기를 선택하고 배포를 생성하기 전에 표시된 가격을 검토하십시오. 기본 크기는 사용 가능한 무료 배포 허용량을 사용할 수 있으며, 사용자 정의 크기는 종량제 요금을 사용합니다. 기본 크기는 유휴 상태일 때 0으로 확장 축소됩니다. 사용자 정의 크기는 하나의 웜 인스턴스를 유지하며 유휴 시간을 포함하여 엔드포인트를 중지할 때까지 준비 상태부터 요금이 청구됩니다. Agents는 **New deployment…**를 선택할 때 이 대화 상자를 재사용합니다.

배포 탭(빠른 배포)#

모델의 Deploy 탭에서 배포하면 모델과 지역이 미리 선택된 동일한 대화 상자가 열립니다. 엔드포인트를 생성하기 전에 리소스 크기, 가격, 자동 생성된 이름을 검토하십시오. 생성되는 동안 배포는 Active Deployments 목록에 표시됩니다.

Endpoint 관리#

보기 모드#

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

배포 카드(카드 보기)#

카드 보기의 각 배포 카드에는 다음이 표시됩니다:

• 헤더: 이름, 지역 국기, 상태 배지, 그리고 현재 상태에서 사용할 수 있는 작업 버튼(준비 완료(Ready) 상태일 때 구성 업데이트, 교체 및 중지, 중지됨(Stopped) 상태일 때 시작, 언제든지 삭제)
• Endpoint URL: Endpoint 자체의 API 레퍼런스 링크가 포함된 복사 가능한 URL
• 지표: 요청 수(24시간), P95 지연 시간, 오류율 또는 "아직 트래픽 없음"
• 상태 확인: 지연 시간과 수동 새로 고침 기능이 포함된 실시간 상태 표시기
• 탭: Logs, Code, Predict; 유료 엔드포인트에는 Monitoring도 표시됩니다.
• 바닥글: 배포에 연결된 API 키 접두사와 준비 상태가 된 날짜
• 상태 메시지: 배포에 실패한 경우 실패 원인

URL, 지표, 상태 확인 및 탭은 배포가 준비 상태일 때만 표시됩니다. Logs 탭에는 심각도 필터링(All / Errors)이 적용된 최근 로그 항목이 표시됩니다. Code 탭에는 Endpoint URL이 포함된 Python, JavaScript, cURL용 즉시 사용 가능한 코드 예시와 워크스페이스 소유자에게 제공되는 연결된 API 키가 표시됩니다(모니터링 참조). Predict 탭에서는 배포에서 직접 테스트할 수 있는 인라인 예측 패널을 제공합니다.

CPU 및 메모리 업데이트#

1. 카드(Cards) 뷰에서 준비 완료(Ready) 엔드포인트를 엽니다.
2. **배포 구성 업데이트(Update deployment configuration)**를 클릭합니다.
3. CPU와 메모리를 선택하고 표시되는 시간당 비용을 검토합니다.
4. **구성 업데이트(Update Configuration)**를 클릭합니다. 새 구성이 준비될 때까지 기존 구성이 계속 서비스됩니다.

사용자 지정 리소스는 가동 시간 청구를 사용하며 인스턴스를 웜 상태로 유지합니다. 기본 리소스로 돌아가면 제로 스케일링(scale-to-zero) 동작이 복원되고 유료 모니터링 탭이 제거됩니다.

모델 교체#

URL을 변경하지 않고 준비된 Endpoint에서 사용되는 모델을 교체합니다:

1. 카드 보기에서 배포를 엽니다
2. 모델 교체를 클릭합니다
3. 동일한 워크스페이스에서 다른 완료된 모델을 선택합니다
4. 선택적으로 배포 이름을 편집합니다
5. 모델 교체를 클릭합니다

교체 모델이 시작되는 동안 현재 모델은 계속 서비스를 제공합니다. 교체 모델이 준비되면 트래픽이 새 모델로 이동합니다. 배포 ID, URL, 리전 및 API 키는 변경되지 않으며, 새 이름을 입력한 경우에만 표시 이름이 변경됩니다. 교체에 실패하면 이전 모델과 이름이 계속 활성 상태로 유지됩니다.

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

• 배포가 준비 상태이고 진행 중인 다른 수명 주기 작업이 없어야 합니다
• 교체 모델에 가중치가 있으며 배포와 동일한 워크스페이스에 속해야 합니다
• 교체 모델이 이미 배포된 모델과 달라야 합니다

배포 상태#

Endpoint URL#

각 Endpoint에는 고유한 URL이 있으며, 예를 들면 다음과 같습니다:

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

URL을 복사하려면 복사 버튼을 클릭하세요. 문서 아이콘을 클릭하여 엔드포인트 자체 API 참조를 엽니다. 엔드포인트는 다음 경로를 제공합니다.

수명 주기 관리#

Endpoint 상태를 제어합니다:

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. 엔드포인트 상태가 "Stopping"으로 변경된 후 "Stopped"로 변경됩니다

중지된 엔드포인트는 다음과 같습니다:

• 요청을 수락하지 않으며 라이브 지표나 상태를 보고하지 않습니다.
• 가동 시간 요금 청구 중단
• 서빙 인스턴스가 종료될 때 임시 모니터링 통계 및 예시 이미지 손실
• URL, 리전 및 연결된 API 키를 유지하며 언제든지 다시 시작할 수 있습니다
• 계획의 배포 할당량에 계속 포함됩니다. 슬롯을 확보하려면 엔드포인트를 삭제해야 합니다

엔드포인트 삭제#

엔드포인트를 영구적으로 삭제합니다:

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

모델 또는 프로젝트가 영구적으로 삭제되거나 휴지통에 있는 모델 또는 프로젝트의 보존 기간이 종료되면 배포도 삭제됩니다.

엔드포인트 사용#

인증#

각 배포는 모델을 소유한 workspace의 단일 API 키에 연결됩니다. 요청에 해당 키를 포함합니다:

Authorization: Bearer YOUR_API_KEY

엔드포인트는 생성 시 연결된 키만 수락하므로 다른 키로는 엔드포인트를 열 수 없습니다. 같은 workspace의 다른 활성 키도 사용할 수 없습니다. 연결할 키를 제어하려면 workspace 소유자의 키로 인증된 API를 통해 배포합니다. 해당 키가 정확히 연결되며 이미 키를 보유하고 있기 때문입니다. 다른 방식(Platform UI 또는 팀원으로 인증된 API 호출)으로 생성된 배포는 소유 workspace의 활성 키 중 하나에 자동으로 연결됩니다. 배포 카드 하단에 표시된 키 접두사를 통해 해당 키를 식별한 후 workspace 소유자에게 값을 요청해야 합니다. 키 값은 소유자만 확인할 수 있기 때문입니다(API 키 참조). 연결된 키가 없는 팀원도 브라우저에서 Platform predict 프록시를 통해 추론을 실행할 수 있습니다.

직접 엔드포인트 요청#

배포 카드에 표시된 URL로 프로덕션 요청을 직접 전송합니다. 이러한 요청은 Platform API 속도 제한기를 거치지 않으므로 분당 20회인 predict 제한이 적용되지 않습니다. 엔드포인트에는 자체 용량 제한이 있습니다:

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

요청 예시#

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 응답을 참조하세요.

응답 형식#

작업별 필드가 포함된 공유 추론과 동일합니다.

FAQ#