SageMaker SDK v3로 모델 코드 바로 실행

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Amazon SageMaker Python SDK v3는 framework별 학습 클래스를 ModelTrainer로, 모델 배포 흐름을 ModelBuilder로 통합해 자체 알고리즘을 관리형 인프라에서 실행하는 절차를 단순화합니다. SourceCode가 로컬 학습·추론 코드를 작업 시작 시 컨테이너에 주입하므로 코드 수정마다 Docker 이미지를 다시 만들 필요가 없고, ModelBuilder는 S3 모델 아티팩트와 추론 핸들러를 DJL Serving 규약에 맞춰 패키징합니다. 글은 ml.m5.2xlarge에서 Random Forest를 학습하고 실시간 엔드포인트에 배포하는 흐름과, ml.g5.12xlarge의 4개 A10G GPU에서 Stable Diffusion 3.5를 LoRA와 Accelerate로 Fine-tuning하는 흐름을 같은 API로 구현합니다. S3 입력 채널, YAML 레시피, SageMaker warm pools, AWS Secrets Manager를 조합하면 데이터 배치와 반복 학습, 비밀값 관리까지 동일한 구성 체계 안에서 처리할 수 있습니다.

섹션별 상세

Amazon SageMaker Python SDK v3는 framework별 Estimator 클래스를 ModelTrainer 하나로 통합하고, 배포는 ModelBuilder가 맡도록 API 구조를 바꿨습니다. 사용자는 Amazon ECR의 자체 이미지, AWS Deep Learning Container 또는 서드파티 이미지를 선택한 뒤 SourceCode에 로컬 디렉터리와 실행 명령을 지정하면 됩니다. 학습 코드와 컨테이너 이미지를 분리하므로 Python 스크립트나 Bash 런처를 수정할 때마다 이미지를 다시 빌드하지 않아도 된다는 점이 핵심 변화입니다.

scikit-learn Random Forest 예제에서는 런타임과 프레임워크 라이브러리만 담은 Python 3.13 기반 컨테이너에 random_forest.py를 실행 시점에 주입합니다. ModelTrainer는 ml.m5.2xlarge 한 대와 30GB 볼륨을 사용하고, n_jobs 4, max_depth 10, n_estimators 120 인자를 전달하며, keep_alive_period_in_seconds를 3,600초로 설정해 warm pool을 유지합니다. 학습 스크립트가 SM_MODEL_DIR에 저장한 결과는 model.tar.gz로 S3에 올라가고, 이후 ModelBuilder가 이 아티팩트와 inference.py를 DJL Serving용 모델로 묶습니다.

python

source_code = SourceCode(
source_dir="./train/random_forest",
command=(
"python random_forest.py"
" --n_jobs 4 --max_depth 10 --n_estimators 120"
f" --mlflow_arn {MLFLOW_ARN}"
f" --mlflow_experiment_name {MLFLOW_EXPERIMENT_NAME}"
),
)
compute = Compute(
instance_type="ml.m5.2xlarge",
instance_count=1,
volume_size_in_gb=30,
keep_alive_period_in_seconds=3600, # Warm pool for faster re-runs
)
stopping_condition = StoppingCondition(max_runtime_in_seconds=3600)
output_config = OutputDataConfig(s3_output_path=MODEL_OUTPUT_S3_PATH)
model_trainer = ModelTrainer(
training_image=TRAINING_IMAGE_URI,
source_code=source_code,
compute=compute,
output_data_config=output_config,
stopping_condition=stopping_condition,
role=SAGEMAKER_EXECUTION_ROLE,
base_job_name="random-forest-training",
sagemaker_session=Session(),
)
model_trainer.train(wait=True)

로컬 Random Forest 학습 코드를 컨테이너 실행 시 주입하고, CPU 인스턴스에서 SageMaker 학습 작업을 시작합니다.

ModelBuilder는 모델 아티팩트와 로컬 추론 코드를 재패키징한 뒤 build()로 SageMaker 모델을 구성하고 deploy()로 실시간 엔드포인트를 생성합니다. DJL Python mode의 handle(inputs)는 초기 요청에서 모델을 한 번 로드하고, 이후 요청마다 Content-Type을 확인해 입력을 역직렬화한 뒤 JSON 예측 결과를 반환합니다. 같은 ModelBuilder 흐름은 SageMaker 관리형 엔드포인트뿐 아니라 LOCAL_CONTAINER와 IN_PROCESS 모드도 지원하므로, 실제 인프라를 만들기 전 로컬 핸들러 테스트가 가능합니다.

python

inference_source_code = SourceCode(
source_dir="./deploy/random_forest",
entry_script="inference.py",
)
# Build and deploy
model_builder = ModelBuilder(
image_uri=INFERENCE_IMAGE_URI,
model_server=ModelServer.DJL_SERVING,
source_code=inference_source_code,
s3_model_data_url=model_artifact_s3_uri,
env_vars={"OPTION_ENTRYPOINT": "code/inference.py"},
sagemaker_session=Session(),
role_arn=SAGEMAKER_EXECUTION_ROLE,
)
model_builder.build(model_name="random-forest-endpoint", mode=Mode.SAGEMAKER_ENDPOINT)

학습 결과가 저장된 S3 모델 아티팩트와 추론 핸들러를 ModelBuilder로 묶어 DJL Serving 기반 배포 모델을 구성합니다.

Stable Diffusion 3.5 Medium Fine-tuning 예제는 같은 API를 4개 A10G GPU를 사용하는 분산 학습으로 확장합니다. source_dir의 base.sh가 GPU 수를 감지하고 Accelerate를 실행하며, YAML 레시피에 모델 ID와 LoRA 설정을 두어 컨테이너 재빌드 없이 학습 구성을 바꿉니다. Hugging Face 데이터셋은 S3의 train 채널로 업로드되고 컨테이너의 /opt/ml/input/data/train에 배치되며, Hugging Face token은 AWS Secrets Manager의 ARN으로 전달해 노트북과 로그에 비밀값을 직접 노출하지 않습니다.

python

sd_source_code = SourceCode(
source_dir="./train/stable_diffusion",
command=(
"/bin/bash base.sh"
" --config recipes/default-medium-g5_12x.yaml"
" --training-script train_text_to_image_lora.py"
" --accelerate-config accelerate_configs/ddp.yaml"
f" --mlflow-arn {SD_MLFLOW_ARN}"
f" --mlflow-experiment-name {SD_MLFLOW_EXPERIMENT_NAME}"
),
)
sd_compute = Compute(
instance_type="ml.g5.12xlarge", # 4x A10G GPUs
instance_count=1,
volume_size_in_gb=30,
keep_alive_period_in_seconds=3600,
)

YAML 레시피와 Bash 런처를 소스 디렉터리에서 읽어 Hugging Face Accelerate 기반 4개 A10G GPU 분산 학습을 시작합니다.

용어 해설

Script mode: — 컨테이너 이미지에 학습·추론 코드를 포함하지 않고, 작업 실행 시 로컬 소스 디렉터리를 컨테이너 안으로 주입하는 SageMaker 실행 방식입니다. 이미지 재빌드 없이 알고리즘 코드를 반복 수정할 수 있습니다.
SourceCode 설정(SourceCode configuration): — 로컬 코드 디렉터리와 실행 명령 또는 추론 진입 스크립트를 묶는 SDK v3 구성 객체입니다. SageMaker가 작업 시작 시 파일을 컨테이너로 동기화해 코드와 실행 환경을 분리합니다.
모델 서버(Model server): — 모델을 로드하고 SageMaker가 요구하는 엔드포인트를 열며 요청을 추론 핸들러로 전달하는 실행 프로세스입니다. 이 글의 예제에서는 DJL Serving이 inference.py의 handle(inputs) 계약을 처리합니다.
LoRA: — 기존 모델의 전체 가중치를 업데이트하는 대신 저순위 적응 가중치를 학습하는 Fine-tuning 방식입니다. 글에서는 Stable Diffusion 3.5의 이미지·캡션 데이터 학습과 4개 A10G GPU 분산 학습에 사용됩니다.
SageMaker warm pools: — 이전 학습 작업의 인스턴스를 일정 시간 유지해 후속 작업이 초기 인스턴스 준비 시간을 다시 거치지 않도록 하는 기능입니다. 예제는 3,600초 유지 설정으로 반복 실행을 빠르게 만듭니다.