beautifulsoups.dev
Published on

SageMaker 엔드포인트 5xx·타임아웃 원인 9가지

Authors
Binance registration banner

SageMaker 실시간 엔드포인트는 InvokeEndpoint 호출이 성공하더라도 내부적으로는 컨테이너, 모델 로딩, 오토스케일링, 네트워크, 그리고 애플리케이션 코드까지 여러 계층을 통과합니다. 그래서 5xx 와 타임아웃은 “한 가지 원인”이 아니라, 요청 경로 어디에서 병목이나 실패가 발생했는지를 좁혀가는 방식으로 접근해야 합니다.

이 글에서는 운영에서 자주 마주치는 SageMaker 엔드포인트 5xx·타임아웃 원인 9가지를 증상, 확인 지표, 해결책 중심으로 정리합니다.

참고로 타임아웃 이슈는 로드밸런서나 게이트웨이의 유휴 타임아웃과도 결합됩니다. EKS 환경에서 504 가 60초로 끊기는 패턴은 이 글도 함께 보면 좋습니다: EKS ALB Ingress 504(60초) idle_timeout 해결

먼저: 5xx·타임아웃을 어디서 확인하나

진단은 “요청이 어디서 실패했는지”를 분리하는 것부터 시작합니다.

  • CloudWatch 지표(엔드포인트)
    • Invocations, Invocation4XXErrors, Invocation5XXErrors
    • ModelLatency, OverheadLatency
    • CPUUtilization, MemoryUtilization, GPUUtilization(GPU 인스턴스)
  • CloudWatch Logs
    • /aws/sagemaker/Endpoints/엔드포인트명
    • 컨테이너 stdout, stderr, 프레임워크별 서버 로그(TorchServe, MMS, custom gunicorn 등)
  • SageMaker DescribeEndpoint / DescribeEndpointConfig
    • 인스턴스 타입, 초기 인스턴스 수, 모델 아티팩트, ContainerStartupHealthCheckTimeoutInSeconds 등

아래 코드는 엔드포인트 지표를 빠르게 조회하는 예시입니다.

import boto3
from datetime import datetime, timedelta, timezone

cw = boto3.client("cloudwatch")
endpoint = "my-endpoint"

end = datetime.now(timezone.utc)
start = end - timedelta(hours=1)

def metric(name, stat="Sum", period=60):
    return cw.get_metric_statistics(
        Namespace="AWS/SageMaker",
        MetricName=name,
        Dimensions=[{"Name": "EndpointName", "Value": endpoint}],
        StartTime=start,
        EndTime=end,
        Period=period,
        Statistics=[stat],
    )["Datapoints"]

print("5XX:", metric("Invocation5XXErrors"))
print("Latency:", metric("ModelLatency", stat="Average"))
print("Overhead:", metric("OverheadLatency", stat="Average"))
  • ModelLatency 가 높으면 “모델 추론 자체”가 느린 경우가 많습니다.
  • OverheadLatency 가 높으면 “컨테이너 바깥 오버헤드” (직렬화, 라우팅, 큐잉, 네트워크, 런타임 준비 등) 가능성이 큽니다.

원인 1) 콜드 스타트: 모델 다운로드·로딩이 느림

대표 증상

  • 배포 직후 또는 오토스케일로 새 인스턴스가 붙은 직후 5xx 또는 타임아웃
  • 특정 시간대(트래픽 스파이크 직후)에만 오류가 집중

확인 방법

  • 엔드포인트 로그에서 모델 로딩 메시지가 오래 지속
  • ModelLatency 보다 OverheadLatency 가 비정상적으로 치솟기도 함

해결책

  • 모델 아티팩트 크기 축소(불필요 파일 제거, 압축 최적화)
  • 컨테이너 시작 시 가중치 로딩을 지연시키지 말고, readiness 이전에 끝내기
  • ContainerStartupHealthCheckTimeoutInSeconds 를 늘려 “헬스체크 실패로 교체 반복”을 막기
import boto3
sm = boto3.client("sagemaker")

# 엔드포인트 설정에서 startup health check timeout을 늘리는 예시
# 실제로는 EndpointConfig를 새로 만들고 UpdateEndpoint 해야 합니다.

print(sm.describe_endpoint_config(EndpointConfigName="my-endpoint-config"))

원인 2) 오토스케일링 지연: 트래픽 급증에 비해 스케일이 늦음

대표 증상

  • 평소엔 정상인데 피크에 Invocation5XXErrors 증가
  • InvocationsPerInstance 가 급격히 상승
  • ModelLatency 가 계단식으로 증가한 뒤 실패

확인 방법

  • Application Auto Scaling 이벤트, CloudWatch 알람 히스토리
  • 스케일 아웃이 발생했는데 실제 인스턴스 준비까지 시간이 오래 걸림

해결책

  • 최소 인스턴스 수를 1 이상으로 유지(항상 웜 상태)
  • 스케일 정책을 보수적으로(더 빨리) 조정
  • 트래픽 패턴이 예측 가능하면 스케줄 기반 스케일링 고려

원인 3) 인스턴스 리소스 부족: CPU·메모리·GPU OOM

대표 증상

  • 간헐적 500 또는 컨테이너 재시작
  • 특정 입력에서만 실패(큰 이미지, 긴 시퀀스 등)
  • 로그에 Killed, OOM, CUDA out of memory 류 메시지

확인 방법

  • CloudWatch MemoryUtilization 급등 후 오류
  • GPU 사용률과 GPU 메모리(프레임워크 로그 또는 커스텀 지표) 확인

해결책

  • 배치 크기 축소, 입력 크기 제한, 토큰 길이 제한
  • 모델 양자화, mixed precision
  • 더 큰 인스턴스 또는 GPU 인스턴스로 변경

이미지/생성 모델 계열은 VRAM 이슈가 특히 잦습니다. 유사한 최적화 아이디어는 이 글도 참고할 만합니다: Stable Diffusion VRAM OOM, xFormers·Tiled VAE로 해결

원인 4) 컨테이너 서버 설정 문제: 워커 수·타임아웃·큐잉

SageMaker는 컨테이너 내부에 웹 서버(예: gunicorn, uvicorn, TorchServe 등)가 떠서 요청을 처리합니다. 여기서 워커 수가 과하거나, 타임아웃이 너무 짧거나, 동시성 제어가 없으면 스레드/프로세스 경합으로 타임아웃이 터집니다.

대표 증상

  • ModelLatency 가 들쭉날쭉하고 tail latency가 큼
  • 동시 요청에서만 실패

확인 방법

  • 컨테이너 로그에서 request queueing, worker timeout, restart 흔적
  • CPU utilization 이 100% 근처에서 고정

해결책

  • 워커 수를 CPU 코어에 맞게 조정
  • 요청당 최대 처리 시간에 맞게 서버 타임아웃 조정
  • 동시 처리량을 제한하고(세마포어), 과부하 시 빠르게 429 로 실패시키는 전략도 고려
# 예: FastAPI에서 동시 처리 제한(간단한 세마포어)
import asyncio
from fastapi import FastAPI, HTTPException

app = FastAPI()
sem = asyncio.Semaphore(4)

@app.post("/invocations")
async def invocations(payload: dict):
    if sem.locked():
        raise HTTPException(status_code=429, detail="busy")
    async with sem:
        # heavy inference
        return {"ok": True}

과부하 제어(레이트리밋, 오토스케일링) 관점은 BentoML 사례지만 패턴은 동일합니다: BentoML 서빙 429 폭주 대응 - 오토스케일·레이트리밋

원인 5) 요청/응답 페이로드 문제: 크기 제한·직렬화 실패

대표 증상

  • 특정 요청만 5xx 또는 4xx 로 실패
  • base64 이미지나 대용량 JSON에서 오류 급증

확인 방법

  • 클라이언트에서 전송한 Content-Type, Content-Length 확인
  • 컨테이너 로그에 JSON decode error, payload too large 등

해결책

  • 입력을 S3에 두고 키만 전달하는 방식으로 변경
  • 압축, 바이너리 포맷(예: application/x-npy) 고려
  • 서버에서 입력 검증을 선제적으로 수행하고 명확히 4xx 로 반환

원인 6) 네트워크/VPC 설정: NAT, 보안그룹, 엔드포인트 접근

VPC에 붙인 엔드포인트가 외부 리소스(S3, ECR, 외부 API)를 호출할 때 NAT 게이트웨이, VPC 엔드포인트, 보안그룹이 꼬이면 “처음엔 되다가” 갑자기 타임아웃이 납니다.

대표 증상

  • 모델 다운로드(S3) 또는 이미지 pull(ECR) 단계에서 멈춤
  • 외부 API 호출이 있는 경우 특정 AZ에서만 타임아웃

확인 방법

  • VPC Flow Logs, NAT 게이트웨이 지표
  • 컨테이너 로그에서 DNS resolve failure, connect timeout

해결책

  • S3 Gateway Endpoint, ECR Interface Endpoint 구성
  • 보안그룹 egress, NACL 점검
  • 외부 호출이 꼭 필요하면 타임아웃/재시도/서킷브레이커 구현

원인 7) 멀티모델 또는 모델 캐시 문제: 디스크 공간·eviction

Multi-Model Endpoint 또는 모델을 동적으로 로딩하는 패턴은 인스턴스 로컬 디스크(EBS) 사용량과 eviction 정책에 영향을 크게 받습니다.

대표 증상

  • 시간이 지날수록 5xx 증가
  • 특정 모델만 유독 느리거나 실패
  • 디스크 부족으로 로딩 실패

확인 방법

  • 로그에서 “no space left on device” 류 메시지
  • 인스턴스 스토리지 사용량(커스텀 지표 필요)

해결책

  • 모델 수를 줄이거나, 모델 크기 최적화
  • 캐시 디렉터리 정리, eviction 전략 설계
  • 엔드포인트를 모델별로 분리하는 것이 더 안정적인 경우도 많음

원인 8) 헬스체크/리드니스 미흡: 살아있지만 준비 안 됨

컨테이너가 프로세스는 떠 있지만 모델이 아직 로딩 중이거나, GPU 초기화가 끝나지 않았는데 트래픽이 들어오면 5xx 가 납니다. 특히 커스텀 컨테이너에서 /ping 과 /invocations 구현이 부실할 때 자주 발생합니다.

대표 증상

  • 배포 직후 5xx 후 안정화
  • 로그에 초기화 중 예외

확인 방법

  • /ping 응답이 너무 빨리 200 을 반환하는지 확인
  • readiness 조건(모델 로딩 완료 여부)을 로그로 남기기

해결책

  • /ping 에서 “모델 로딩 완료”를 확인한 뒤에만 200 반환
  • 초기화 실패 시 빠르게 프로세스를 종료하여 교체가 일어나게 하기
# 간단한 readiness 플래그 예시(Flask)
from flask import Flask, Response, request

app = Flask(__name__)
ready = False

@app.route("/ping", methods=["GET"])
def ping():
    return Response(status=200 if ready else 503)

@app.route("/invocations", methods=["POST"])
def invoke():
    if not ready:
        return Response("not ready", status=503)
    # inference...
    return {"ok": True}

def load_model():
    global ready
    # heavy init...
    ready = True

원인 9) 클라이언트 타임아웃·재시도 폭주: 실패를 증폭

서버가 느려지기 시작하면 클라이언트의 공격적인 재시도(특히 짧은 타임아웃)로 트래픽이 폭증하고, 결국 5xx 와 타임아웃이 “연쇄적으로” 증가합니다.

대표 증상

  • 트래픽이 실제 사용자 수보다 과도하게 튐
  • 서버가 회복 직전에 다시 과부하로 떨어짐

확인 방법

  • 클라이언트 로그에서 동일 요청의 반복
  • Invocations 대비 비즈니스 이벤트 수가 비정상

해결책

  • 클라이언트 타임아웃을 현실적으로 설정(모델 p95 기준)
  • 지수 백오프와 지터 적용
  • 멱등성 키를 도입하거나, 재시도 가능한 에러만 재시도
# boto3 호출에 타임아웃/재시도 정책을 명시하는 예시
import boto3
from botocore.config import Config

cfg = Config(
    read_timeout=70,
    connect_timeout=5,
    retries={"max_attempts": 3, "mode": "standard"},
)
rt = boto3.client("sagemaker-runtime", config=cfg)

resp = rt.invoke_endpoint(
    EndpointName="my-endpoint",
    ContentType="application/json",
    Body=b"{\"text\": \"hello\"}",
)
print(resp["Body"].read())

실전 체크리스트: 15분 안에 범위 좁히기

  1. Invocation5XXErrors 와 ModelLatency / OverheadLatency 를 같은 시간축으로 비교
  2. 오류가 배포/스케일 이벤트와 맞물리는지 확인(콜드 스타트 의심)
  3. CPU·메모리·GPU 지표가 상한에 붙는지 확인(OOM 또는 경합)
  4. 컨테이너 로그에서 OOM , worker timeout, decode error 같은 “명확한 문자열”을 찾기
  5. 입력 크기/형식이 특정 케이스에서만 커지는지 확인
  6. VPC 환경이면 S3/ECR 접근 경로(NAT, VPC 엔드포인트)부터 점검
  7. 클라이언트 재시도 정책이 장애를 증폭시키는지 확인

마무리: 5xx는 결과, 원인은 계층별로 다르다

SageMaker 엔드포인트의 5xx 와 타임아웃은 대개

  • 콜드 스타트와 스케일 지연,
  • 리소스 부족(OOM 포함),
  • 컨테이너 서버의 동시성/타임아웃 설정,
  • 네트워크 경로,
  • 클라이언트 재시도 정책 중 하나(또는 복합)로 수렴합니다.

가능하면 다음을 기본값으로 가져가면 장애 빈도가 크게 줄어듭니다.

  • 최소 인스턴스 1 유지로 콜드 스타트 제거
  • p95 기준으로 서버·클라이언트 타임아웃 정렬
  • 입력 크기 상한과 빠른 4xx 처리
  • 과부하 시 429 로 빠르게 실패시키는 전략과 오토스케일 튜닝

원하시면 사용 중인 스택(예: PyTorch + TorchServe, Hugging Face DLC, custom FastAPI)과 인스턴스 타입, 평균/최대 입력 크기, 현재 타임아웃 값을 알려주시면 9가지 중 어디를 먼저 파야 하는지 우선순위로 좁혀서 체크리스트를 더 구체화해 드릴게요.

Discuss on Twitter • View on GitHub