전용 엔드포인트#

Ultralytics Platform을 사용하면 전 세계 42개 리전의 전용 엔드포인트에 YOLO 모델을 배포할 수 있습니다. 각 엔드포인트는 고유한 엔드포인트 URL과 독립적인 모니터링 기능을 갖춘 단일 테넌트 서비스입니다. 기본 리소스 크기는 유휴 상태일 때 0으로 축소되며, 사용자 지정 크기는 인스턴스를 항상 준비 상태로 유지하고 가동 시간에 따라 요금이 부과됩니다.

엔드포인트 만들기#

배포 탭에서#

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

1. 모델로 이동합니다
2. Deploy 탭을 클릭합니다.
3. 세계 지도와 리전 표를 확인합니다. 표는 현재 위치에서 측정한 지연 시간 순으로 정렬되어 있습니다.
4. 사용할 리전의 행에서 Deploy를 클릭합니다.
5. 대화상자에서 CPU, 메모리, 가격 및 배포 이름을 확인한 다음 Create Deployment를 클릭합니다.

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

배포 탭에서#

프로필의 Deployments 탭이나 사이드바에서 배포를 만듭니다:

1. Deployments 탭에서 New Deployment를 클릭하거나, 사이드바의 Deployments 옆에 있는 +을 클릭합니다.
2. 완료된 모델이 표시되는 모델 선택기에서 모델을 선택합니다.
3. 미니 지도 또는 지연 시간 표에서 리전을 선택합니다.
4. CPU와 메모리를 선택하고 가격을 확인한 다음, 필요한 경우 제안된 배포 이름을 수정합니다.
5. Create Deployment를 클릭합니다.

배포 수명 주기#

배포가 준비되거나 시작에 실패했을 때 메시지를 받으려면 Slack 알림을 연결하세요.

리전 선택#

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

• 리전 핀: 지연 시간에 따라 녹색에서 빨간색으로 색상이 표시됩니다(빠른 리전은 녹색에 가깝고, 느린 리전은 빨간색에 가깝습니다).
• 배포된 리전: 표에서 "Deployed" 배지로 강조 표시됩니다.
• 배포 중인 리전: 핀과 표 행에 애니메이션 펄스 표시기가 나타납니다.
• 양방향 강조 표시: 지도에 마우스를 올리면 표 행이 강조 표시되고, 표 행에 마우스를 올리면 지도에서 해당 리전이 강조 표시됩니다.

모델 Deploy 탭의 리전 표에는 다음 항목이 포함됩니다:

표는 도시, 국가 및 영역으로 검색할 수 있으며, 기본적으로 지연 시간순으로 정렬됩니다.

사용 가능한 리전#

엔드포인트 구성#

새 배포 대화상자#

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

리소스 설정에서 CPU와 메모리 크기를 선택하고 배포를 생성하기 전에 표시된 가격을 확인합니다. CPU 옵션은 1, 2, 4, 6 또는 8 vCPU이고, 메모리 옵션은 2~32 GiB입니다. 메모리 크기가 클수록 더 많은 vCPU가 필요합니다(예: 16 GiB에는 최소 4 vCPU 필요). 대화상자에는 유효하지 않은 조합에 대한 설명이 표시됩니다. 기본 크기(1 vCPU, 2 GiB)는 무료이며 유휴 상태일 때 0개로 축소됩니다. 사용자 지정 크기는 인스턴스 하나를 상시 대기 상태로 유지하며, 준비 완료 시점부터 엔드포인트를 중지할 때까지 유휴 시간을 포함해 표시된 리전별 시간당 요금이 부과됩니다. 사용자 지정 크기를 생성, 시작 또는 조정하려면 사용 가능한 크레딧이 필요하며, 워크스페이스의 크레딧이 소진되면 사용자 지정 크기 엔드포인트가 자동으로 중지됩니다. 새 배포…를 선택하면 에이전트에서도 이 대화상자를 사용합니다.

배포 탭(빠른 배포)#

모델의 Deploy 탭에서 배포하면 모델과 리전이 미리 선택된 동일한 대화상자가 열립니다. 엔드포인트를 생성하기 전에 리소스 크기, 가격 및 자동 생성된 이름을 확인합니다. 배포가 생성되는 동안 해당 모델의 배포 목록에 리전 테이블 아래에 표시됩니다.

엔드포인트 관리#

뷰 모드#

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

배포 페이지#

각 배포에는 /{username}/deploy/{deployment}의 전용 페이지가 있으며, 다음 항목이 표시됩니다:

• 헤더: 리전 국기, 표시 이름(클릭하여 이름을 변경합니다. 페이지 URL과 API 경로는 새 이름의 슬러그로 변경되지만 엔드포인트 URL은 변경되지 않습니다), 상태 배지, 위치, CPU 및 메모리 크기
• 작업: 준비 완료 상태일 때 구성 업데이트, 모델 교체, 배포 중지; 중지됨 상태일 때 배포 시작; 그리고 정보, 새로고침, 배포 삭제가 포함된 추가 작업(…) 메뉴
• 지표: 스파크라인과 함께 표시되는 24시간 동안의 HTTP 요청, HTTP 오류율 및 HTTP P95 지연 시간, 그리고 배포된 모델로 연결되는 카드
• 탭: Overview, Monitoring, Predict 및 Logs
• 상태 메시지: 배포에 실패한 경우 실패 이유

Overview 탭에는 위치 지도, 복사할 수 있는 엔드포인트 URL이 표시된 엔드포인트 카드, API 문서 링크 및 상태 확인, 그리고 가격, 리전, CPU 및 메모리가 표시된 배포 정보 카드가 표시됩니다. Logs 탭에는 심각도 필터링(전체 / 오류)을 지원하는 최근 로그 항목이 표시됩니다. Predict 탭에는 배포에서 직접 테스트할 수 있는 인라인 예측 패널이 제공됩니다. 문서 결과 탭에는 엔드포인트 URL과 워크스페이스 소유자의 경우 연결된 API 키가 입력된 Python, JavaScript 및 cURL용 코드 예제가 제공됩니다(모니터링 참조). 정보 대화상자에는 배포 속성이 나열되며 사용자 지정 메타데이터를 수정할 수 있습니다.

CPU 및 메모리 업데이트#

1. 준비 완료 상태의 엔드포인트에서 배포 페이지를 엽니다.
2. 구성 업데이트를 클릭합니다.
3. CPU와 메모리를 선택하고 표시된 시간당 비용을 확인합니다.
4. 구성 업데이트를 클릭합니다. 새 구성이 준비될 때까지 현재 구성으로 계속 서비스를 제공합니다.

사용자 지정 리소스는 가동 시간 기준으로 요금이 부과되고 인스턴스를 가동 상태로 유지합니다. 따라서 추가 요금 없이 IP 카메라도 계속 실행할 수 있습니다(백그라운드 카메라 참조). 기본 리소스로 돌아가면 0으로 축소되는 동작이 복원되고 백그라운드 카메라는 제거됩니다.

모델 교체#

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

1. 배포 페이지를 엽니다
2. 모델 교체를 클릭합니다
3. 같은 워크스페이스에서 완료된 다른 모델을 선택합니다
4. 필요에 따라 배포 이름을 수정합니다
5. 모델 교체를 클릭합니다

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

교체에는 다음 조건이 모두 필요하며, 그렇지 않으면 요청이 거부됩니다:

• 배포가 Ready 상태이며 진행 중인 다른 수명 주기 작업이 없습니다.
• 대체 모델에 가중치가 있으며 배포와 동일한 워크스페이스에 속합니다.
• 대체 모델은 이미 배포된 모델이 아닙니다.

배포 상태#

Ready 상태의 배포에서는 엔드포인트가 최초 상태 확인에 응답할 때까지 페이지의 배지가 Starting으로 표시되고, 상태 확인에 실패하면 Not responding으로 표시됩니다.

엔드포인트 URL#

각 엔드포인트에는 고유한 URL이 있습니다. 예:

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

복사 버튼을 클릭하여 URL을 복사하세요. API documentation을 클릭하면 해당 엔드포인트 전용 API 참조 문서가 열립니다. 엔드포인트는 다음 경로를 제공합니다:

수명 주기 관리#

엔드포인트 상태를 제어합니다:

엔드포인트 중지#

요청을 받지 않도록 하려면 엔드포인트를 중지하세요:

1. 배포 페이지에서 Stop deployment를 클릭합니다.
2. 엔드포인트 상태가 "Stopping"으로 바뀐 다음 "Stopped"로 바뀝니다.

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

• 요청을 받지 않으며 실시간 메트릭이나 상태 정보를 보고하지 않습니다.
• 가동 시간 요금이 더 이상 발생하지 않습니다.
• 서빙 인스턴스가 종료되면 임시 모니터링 통계와 예시 이미지가 사라집니다.
• URL, 리전 및 연결된 API 키는 유지되며 언제든지 다시 시작할 수 있습니다.
• 계획의 배포 할당량에는 계속 포함됩니다. 슬롯을 비우려면 엔드포인트를 삭제하세요.

엔드포인트 삭제#

엔드포인트를 영구적으로 제거하려면 다음을 수행하세요:

1. 배포 페이지에서 More actions (…)을 열고 Delete Deployment를 클릭하거나, 사이드바에서 배포 옆의 휴지통 아이콘을 클릭합니다.
2. Delete를 클릭하여 확인합니다.

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

엔드포인트 사용#

인증#

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

Authorization: Bearer YOUR_API_KEY

엔드포인트는 생성 시 연결된 키만 허용하므로, 같은 워크스페이스의 다른 활성 키를 포함해 다른 키로는 엔드포인트를 열 수 없습니다. 연결할 키를 제어하려면 워크스페이스 소유자의 키로 인증된 API를 통해 배포하세요. 바로 그 키가 연결되므로 이미 해당 키를 보유하고 있습니다. 다른 방법(Platform UI 또는 팀원 계정으로 인증된 API 호출)으로 생성된 배포에는 소유 워크스페이스의 활성 키 중 하나가 자동으로 연결됩니다. 키 값은 소유자만 확인할 수 있으므로 워크스페이스 소유자에게 키 값을 요청하세요(API 키 참조). 연결된 키가 없는 팀원도 브라우저의 Platform 예측 프록시를 통해 추론을 실행할 수 있습니다.

엔드포인트에 직접 요청 보내기#

프로덕션 요청은 배포 페이지에 표시된 URL로 직접 보내세요. 이 요청은 Platform API 속도 제한기를 거치지 않으므로 분당 20회인 예측 제한이 적용되지 않습니다. 단, 엔드포인트 자체 용량 한도는 적용됩니다:

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

요청 예시#

import requests

# 배포 엔드포인트
url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"

# 배포 API 키가 포함된 헤더
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# 추론 매개변수
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

# 추론을 위한 이미지 전송
with open("image.jpg", "rb") as f:
    response = requests.post(url, headers=headers, data=data, files={"file": f})

print(response.json())

요청 매개변수#

엔드포인트는 마지막 롤아웃의 추론 런타임을 유지하므로, 학습 크기 imgsz 기본값이나 위의 vid_stride과 같은 새로운 동작은 새 리비전이 롤아웃될 때 적용됩니다. 예를 들어 모델을 교체하거나 CPU 또는 메모리를 변경한 후 적용됩니다. 고정 입력 크기를 사용하려면 imgsz를 명시적으로 전달하세요.

bits이 반환된 깊이 맵을 어떻게 변경하는지와 디코딩 방법은 깊이 응답을 참조하세요.

응답 형식#

작업별 필드를 포함하며 공유 추론과 동일합니다.

자주 묻는 질문#