엔드포인트 배포 및 호출

공유 추론 또는 전용 엔드포인트#

모든 모델은 이미 Platform의 공유 추론 API를 통해 호출할 수 있어 테스트에 적합합니다. 프로덕션 트래픽에는 전용 엔드포인트를 사용하세요:

엔드포인트 생성 및 크기 설정#

모델의 Deploy 탭을 엽니다. 브라우저에서 42개 지역(미주 14개, 유럽 13개, 아시아 태평양 12개, 중동 및 아프리카 3개)까지의 지연 시간을 측정하고, 측정된 지연 시간을 기준으로 표를 정렬합니다:

호출자와 가장 가까운 행에서 Deploy를 클릭하고 CPU, 메모리, 가격, 생성된 이름(예: yolo26n-iowa)을 확인한 다음 Create Deployment를 클릭합니다. 프로필의 Deployments 탭에서 New Deployment를 선택해 시작할 수도 있습니다:

트래픽 패턴에 따라 크기를 설정합니다:

요금제별 배포 수는 Free 3개, Pro 10개, Enterprise 무제한이며, 중지된 엔드포인트도 개수에 포함됩니다. 배지가 Ready로 표시되면 엔드포인트가 트래픽을 수신합니다:

실전 예제: 프로덕션에서도 안정적으로 작동하는 클라이언트#

각 엔드포인트에는 https://predict-<id>-<hash>-<region>.a.run.app과 같은 URL이 있으며, /predict(POST), /health, 대화형 /docs 페이지를 제공합니다. 생성 시 연결된 API 키만 허용됩니다. 워크스페이스 소유자는 배포의 Predict 탭에 있는 Docs에서 해당 키가 미리 입력된 상태로 표시되는 것을 확인할 수 있으며, Python, JavaScript, cURL 코드 조각도 함께 제공됩니다. 코드 조각은 요청을 한 번 보내는 예제입니다. 프로덕션 코드는 콜드 스타트와 인스턴스 과부하에도 안정적으로 대응해야 합니다:

import os
import time
from collections import Counter

import httpx

URL = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
HEADERS = {"Authorization": f"Bearer {os.environ['ULTRALYTICS_API_KEY']}"}  # the deployment's bound key, server-side only

def predict(client, path, conf=0.25, attempts=4):
    """POST one image; retry timeouts, 429, and 5xx with backoff; fail fast on other errors."""
    for attempt in range(attempts):
        try:
            with open(path, "rb") as f:
                r = client.post(URL, headers=HEADERS, data={"conf": conf}, files={"file": f}, timeout=90)
            if r.status_code < 400:
                return r.json()
            if r.status_code != 429 and r.status_code < 500:
                r.raise_for_status()  # 401 wrong key, 413 too large: retrying won't help
            wait, reason = float(r.headers.get("Retry-After", 2**attempt)), r.status_code
        except httpx.TimeoutException:  # a scaled-to-zero endpoint can take up to a minute to wake
            wait, reason = 2**attempt, "timeout"
        print(f"attempt {attempt + 1}: {reason}, retrying in {wait:.0f} s")
        time.sleep(wait)
    raise RuntimeError(f"endpoint still unavailable after {attempts} attempts")

with httpx.Client() as client:
    response = predict(client, "bus.jpg")
for image in response["images"]:
    counts = Counter(d["name"] for d in image["results"])
    print(f"{sum(counts.values())} objects {dict(counts)} in {image['speed']['inference']:.1f} ms")

429에 한 번 응답한 뒤 엔드포인트 응답 형식에 따라 bus.jpg에 대한 실제 YOLO26n 결과를 반환하는 로컬 스텁을 사용해 테스트했습니다:

attempt 1: 429, retrying in 2 s
5 objects {'bus': 1, 'person': 4} in 34.9 ms

중요한 결정 사항을 한 줄씩 살펴보겠습니다:

• timeout=90은 최대 약 1분까지 걸릴 수 있는 콜드 스타트에 대비합니다. 대부분의 HTTP 클라이언트의 기본 시간 제한은 이보다 훨씬 짧습니다.
• 429 및 5xx 오류는 재시도하며, 엔드포인트가 Retry-After을 전송하면 이를 준수합니다. 각 엔드포인트는 단일 인스턴스에서 요청을 처리하며, 과부하 시 429을 사용해 부하를 줄입니다.
• 그 외 4xx 오류는 즉시 실패 처리합니다: 401은 잘못된 키를 의미하고 413은 32 MB를 초과하는 본문을 의미합니다. 어느 쪽도 저절로 해결되지 않습니다.
• 응답에는 images에 이미지(또는 비디오 프레임)당 항목 하나가 포함되며, 각 항목에는 results(class, name, confidence, box 및 x1, y1, x2, y2)과 밀리초 단위의 speed이 포함됩니다.

선택적 폼 필드는 conf(기본값 0.25), iou(0.7), imgsz(모델의 학습 크기), 비디오용 vid_stride, 0–1 좌표용 normalize=true입니다. 이에 해당하는 cURL 명령은 필드마다 한 줄씩 작성합니다:

curl -X POST "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer $ULTRALYTICS_API_KEY" \
  -F "file=@bus.jpg" -F "conf=0.25" -F "iou=0.7" -F "imgsz=640"

URL을 변경하지 않고 새 버전 배포하기#

배포 페이지의 Replace model을 사용하면 같은 워크스페이스에 있는 다른 완료된 모델로 교체할 수 있습니다. 새 모델이 준비될 때까지 기존 모델이 계속 요청을 처리하며, URL, 지역, 키는 그대로 유지됩니다. 롤아웃에 실패하면 이전 모델이 계속 서비스됩니다. 롤백은 이전 모델을 대상으로 같은 작업을 수행하면 되므로 해당 모델을 프로젝트에 보관하세요. Update configuration은 현재 위치에서 크기를 조정하며, Stop은 과금을 일시 중지하고 URL을 유지합니다.

일부 변경에는 새 엔드포인트가 필요합니다. 지역은 고정되어 있으므로 지역을 변경하려면 엔드포인트를 삭제하고 다시 만들어야 하며, 새 URL이 발급됩니다. 사용자 지정 도메인은 지원되지 않으므로 호출자에게 안정적인 브랜드 호스트 이름이 필요하면 자체 게이트웨이를 앞에 두세요. Platform 외부에서 실행하려면 모델을 내보내거나(배포용 내보내기) Triton Inference Server 뒤에서 직접 호스팅하세요.

주의할 점#