시작하기¶

설치, 로컬 검증, --dry-run, 실제 배포 순서로 진행합니다.

1. 설치¶

curl -LsSf https://astral.sh/uv/install.sh | sh    # uv 미설치 시
git clone https://github.com/daekeun-ml/encoder-serving-sagemaker.git
cd encoder-serving-sagemaker
uv sync --extra notebook

uv.lock이 package 버전을 고정합니다. SageMaker Python SDK v3를 사용하며, v2의 Estimator, HuggingFaceModel, sagemaker.image_uris는 사용할 수 없습니다.

export AWS_REGION=us-east-1
export SAGEMAKER_ROLE_ARN=arn:aws:iam::<ACCOUNT>:role/<Role>   # 비우면 IAM에서 자동 탐지

설정은 common/config.py 에 있으며 환경 변수로 override할 수 있습니다. secret은 파일에 저장하지 마세요.

2. 필요한 것¶

항목	설명
AWS 계정	SageMaker AI endpoint 생성 권한. 실제 endpoint 배포 시 비용 발생
IAM execution role	`AmazonSageMaker-ExecutionRole-*` 또는 동등한 권한
Service Quotas	`ml.g5.xlarge`, `ml.g6.12xlarge`. 신규 계정은 quota가 0일 수 있음
Region	기본값 `us-east-1`. GPU capacity는 Region과 시점에 따라 다름
Python	3.12 이상
Docker	로컬 검증용 (선택이지만 권장)
로컬 GPU	선택 사항. 있으면 배포 전에 추론까지 검증 가능
HF 토큰	불필요 (대상 모델 3종 전부 ungated)

쿼터를 먼저 확인하세요

quota가 있어도 Region의 capacity가 부족하면 배포가 실패할 수 있습니다. 이 실험에서는 ml.g5.12xlarge가 약 50분 뒤 Failed 상태가 되었고, ml.g6.12xlarge는 약 3분 만에 생성됐습니다. 사용할 Region에서 두 유형의 quota와 capacity를 확인하세요.

3. Endpoint 인스턴스 생성 전 확인¶

로컬에서 모델 로드와 추론 검증¶

uv run python -m common.local_test --all --bench

모델 3종을 로드해 NLI sample의 예측을 확인합니다. GPU가 있으면 benchmark도 실행합니다. 로컬 모델 로드나 추론이 실패하면 원인을 해결한 뒤 endpoint 배포를 진행하세요.

로컬 Docker로 실제 DLC 띄우기¶

실제 DLC를 실행해 SageMaker container contract(/ping, /invocations)와 payload 형식을 확인합니다. 클라우드 환경의 IAM, network, capacity 문제는 별도로 확인해야 합니다.

bash 01_single_endpoint/scripts/serve_local.sh          # HF DLC (GPU)
uv run python 01_single_endpoint/invoke.py --mode local
uv run python -m benchmark.run --mode local --pad-to-max --sweep-batch
bash 01_single_endpoint/scripts/cleanup_local.sh

`--dry-run`으로 API 요청 구성 확인¶

--dry-run은 endpoint 인스턴스를 생성하지 않고 create_model과 create_endpoint_config를 호출합니다. image URI, role, 인스턴스 유형 등 API 요청 구성을 확인할 수 있지만, 실제 container 기동, 모델 로드, capacity 확보 여부는 검증하지 않습니다.

uv run python 01_single_endpoint/deploy.py --dry-run

배포 제약 확인¶

# 멀티컨테이너 endpoint의 GPU 제한 확인
uv run python 02_cpu_cohost_multicontainer/deploy.py --prove-gpu-fails

# vLLM model registry에서 지원 여부 확인
uv run python 08_engine_comparison/check_vllm_support.py

4. 실제 배포¶

uv run python 01_single_endpoint/deploy.py --gpu --workers 4
uv run python 01_single_endpoint/invoke.py --mode cloud --endpoint <name>
uv run python -m benchmark.run --mode cloud --endpoint <name> --pad-to-max --sweep-batch

실습 후 리소스 정리

uv run python -m common.cleanup --list        # 남아 있는 리소스 확인
uv run python -m common.cleanup --delete-all  # 전부 삭제

Cleanup 명령은 RESOURCE_PREFIX(기본값 encoder-serving)로 시작하는 리소스만 대상으로 합니다.

5. 시나리오 선택¶

배포 방식 고르기에서 상황별 선택 기준을 설명합니다.

상황	시나리오
처음 시작	01 단일 endpoint
경량 모델 여러 개, 비용 우선	02 CPU co-host
GPU 필요, 모델별 독립 scaling	03 inference component
GPU 필요 + 비용 우선	04 LMI
유휴 시간이 많음 + GPU 필요	05 Scale to zero
트래픽이 산발적 + GPU 불필요	06 Serverless
모델 1개 + latency 최우선	07 Triton + TensorRT
vLLM 검토 중	인코더는 왜 다른가

비용 감각¶

인스턴스	용도	시간당 요금
ml.c6i.2xlarge	CPU + ONNX	$0.408
ml.g5.xlarge	GPU 단일 / LMI co-host	$1.408
ml.g6.12xlarge	inference component co-host	$5.752

us-east-1 on-demand hosting 요금이며 2026-08-07에 AWS Pricing API로 조회했습니다.

실측 환경에서는 시나리오 하나를 배포하고 정리하는 데 대체로 15~30분이 걸렸습니다. capacity 대기나 cold start가 길면 더 오래 걸릴 수 있습니다. GPU 인스턴스는 시간 단위로 비용이 발생하므로 로컬 검증과 --dry-run을 먼저 실행하세요.