Bring your own model with Amazon SageMaker AI: Script mode in SDK v3

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon SageMaker AI의 SDK v3는 ModelTrainer·ModelBuilder와 SourceCode로 학습·배포 인터페이스를 통합하고, 컨테이너 재빌드 없이 코드 변경을 반영하는 스크립트 모드를 제공한다.

📌 핵심 요약

• SDK v3는 프레임워크별 학습 클래스를 ModelTrainer로 통합하고, ModelBuilder로 모델을 구성·배포하며 예측은 invoke()로 처리한다.
• SourceCode는 로컬 코드 디렉터리와 학습용 command 또는 추론용 entry_script를 지정하며, 직접 만든 이미지·AWS Deep Learning Container·타사 이미지를 사용할 수 있다.
• 실행에는 SageMaker AI 접근 권한, SageMaker AI와 Amazon S3 권한을 갖춘 IAM 실행 역할, SDK v3, Amazon ECR의 학습 이미지, Amazon S3 버킷이 필요하며 MLflow 실험 추적은 선택 사항이다.
• scikit-learn 사례는 당뇨병 데이터셋으로 Random Forest 분류기를 학습하며, ml.m5.2xlarge 인스턴스 1대와 30GB 볼륨, 1시간 웜 풀 및 최대 학습 시간 설정을 사용한다.
• 학습 결과는 model.tar.gz로 Amazon S3에 저장되고, ModelBuilder는 추론 코드와 모델을 묶어 build()로 등록한 뒤 deploy()로 DJL Serving 기반 실시간 엔드포인트를 생성한다. Stable Diffusion 3.5의 LoRA 미세 조정은 개요에 소개되지만 제공된 본문에는 구현 과정이 없다.

🧩 주요 포인트

1. 런타임 이미지와 SourceCode의 분리 → 라이브러리 환경을 재사용하면서 학습 코드 수정에 따른 컨테이너 재빌드를 생략할 수 있다.
2. ModelTrainer·ModelBuilder로 인터페이스 통합 → 프레임워크별 클래스 대신 공통된 방식으로 학습 작업과 배포를 구성한다.
3. build()와 deploy()의 단계 분리 → 모델 패키징·등록과 실제 엔드포인트 인프라 생성을 구분하며, 학습 이미지와 추론 이미지도 별도로 선택할 수 있다.

🧠 상세 정리

1. 기존 스크립트 모드와 SDK v3의 변화

원문은 2021년에 소개한 SageMaker 스크립트 모드를 출발점으로 삼으며, 당시에는 AWS가 관리하는 프레임워크 컨테이너에서 사용자 정의 학습·추론 코드를 실행하는 방법을 설명했다고 회고한다. 이 방식은 사용자가 자신의 알고리즘을 실행하기 위해 Docker 이미지를 직접 만들고 유지할 필요를 줄였다는 점에서 의미가 있었다. SDK v3는 이를 바탕으로 설계를 새롭게 구성하면서 SKLearn, PyTorch, XGBoost처럼 프레임워크마다 달랐던 학습 클래스를 단일 ModelTrainer로 대체한다. 배포 역시 기존 Model과 Predictor 조합에서 ModelBuilder 중심으로 바뀌며, 비교표는 예측 처리를 invoke()의 역할로 설명한다.

2. SourceCode를 통한 코드와 실행 환경의 분리

SDK v3의 핵심 설정 객체인 SourceCode는 로컬 코드 디렉터리인 source_dir와 학습용 command 또는 추론용 entry_script를 받는다. 학습 작업을 시작하면 SDK가 디렉터리를 컨테이너 안으로 동기화하므로, 알고리즘 코드를 이미지에 미리 포함하지 않아도 실행할 수 있다. 이미지는 Amazon ECR에 있는 사용자 제작 이미지, AWS Deep Learning Container 또는 타사 이미지에서 선택할 수 있으며, 사용자는 시스템 패키지와 CUDA 라이브러리 등 내부 환경을 제어한다. 이 구조에서는 학습 스크립트를 바꾼 뒤 컨테이너를 재빌드하지 않고 다시 실행할 수 있고, 프레임워크가 달라져도 공통 인터페이스를 사용한다. 의존성을 source_dir의 requirements.txt에 두는 방식은 v2와 v3 비교에서 동일하게 제시된다.

3. 두 가지 예제의 범위와 실행 전제

원문은 당뇨병 데이터셋을 이용한 scikit-learn Random Forest 학습·실시간 배포와 Stable Diffusion 3.5의 LoRA 미세 조정이라는 두 가지 예제를 소개한다. 두 번째 예제는 Hugging Face Accelerate를 활용한 다중 GPU 분산 학습으로 설명되지만, 제공된 본문은 첫 번째 예제의 배포 설명 도중 끝나므로 실제 구현을 확인할 수 있는 범위는 제한된다. 실행 전제는 SageMaker AI에 접근할 수 있는 계정, SageMaker AI와 Amazon S3 권한을 가진 IAM 실행 역할, SageMaker Python SDK 3.0 이상, Amazon ECR의 학습 이미지 및 Amazon S3 버킷이다. MLflow 앱이나 추적 서버는 선택 사항이며, 로컬 환경 대신 SageMaker Studio의 JupyterLab 공간에서 예제 컨테이너를 빌드하고 실행하려면 도메인 수준에서 Docker 접근을 활성화해야 한다.

4. 재사용 가능한 scikit-learn 학습 컨테이너

첫 번째 예제는 학습 코드를 제외하고 런타임과 프레임워크 라이브러리만 담는 최소한의 Docker 컨테이너를 구성한다. Dockerfile은 python:3.13-slim을 기반으로 build-essential, jq, git을 설치하고, requirements.txt를 복사한 뒤 해당 파일의 파이썬 의존성을 설치한다. 알고리즘별 코드는 source_dir에 따로 두고 SDK가 실행 시 주입하므로, 동일한 실행 환경을 다른 scikit-learn 모델에도 재사용할 수 있다. 예제 노트북은 build.sh와 push.sh에 .env.docker.sklearn 설정을 전달해 이미지를 빌드하고 Amazon ECR에 올리는 방식을 제시한다. 이처럼 이미지를 한 번 준비한 뒤 학습 코드만 바꾸는 흐름을 통해, 런타임 구성이 유지되는 동안 반복 실험마다 Docker 이미지를 다시 만들 필요를 없앤다.

5. 계정 설정과 선택적 MLflow 추적

설정 단계에서는 boto3와 SageMaker 세션을 사용해 리전, 계정 ID, 실행 주체의 ARN 및 기본 Amazon S3 버킷을 구한다. TRAINING_IMAGE_URI는 앞서 직접 빌드해 Amazon ECR에 올린 sklearn 이미지를 가리키며, MODEL_OUTPUT_S3_PATH는 Random Forest 학습 결과를 저장할 버킷 내 경로를 지정한다. 학습에는 패키지와 런타임 버전을 직접 제어하는 이미지를 사용하지만, 배포에는 사전 구축된 DJL 컨테이너도 사용할 수 있다고 설명한다. 예제 학습 스크립트에는 SageMaker AI의 완전관리형 MLflow 연동이 준비되어 있어 MLFLOW_ARN과 MLFLOW_EXPERIMENT_NAME을 설정하면 하이퍼파라미터, 지표, 모델 산출물 기록을 활성화할 수 있다. 실험 추적을 사용하지 않는 경우에는 두 값을 None으로 설정하도록 안내한다.

6. ModelTrainer로 학습 명령과 자원 구성

학습용 SourceCode는 ./train/random_forest 디렉터리를 지정하고, random_forest.py를 실행하면서 n_jobs 4, max_depth 10, n_estimators 120과 MLflow 관련 인수를 전달한다. Compute 설정은 ml.m5.2xlarge 인스턴스 1대, 30GB 볼륨, 3,600초의 웜 풀 유지 시간을 사용하며, StoppingCondition은 최대 실행 시간을 3,600초로 제한한다. 원문은 웜 풀이 인스턴스를 1시간 동안 유지해 반복 실행의 시작 시간을 분 단위에서 초 단위로 줄이는 데 쓰인다고 설명한다. ModelTrainer에는 학습 이미지, 소스 코드, 컴퓨팅 자원, 출력 위치, 종료 조건 및 실행 역할을 전달하고 train(wait=True)로 작업을 실행한다. source_dir에는 보조 모듈·설정 파일·셸 스크립트도 포함할 수 있으며, command는 파이썬에 한정되지 않고 컨테이너가 지원하는 명령을 실행한다.

7. 학습 산출물 저장과 추론 코드 패키징

OutputDataConfig는 학습 작업이 끝난 뒤 결과를 업로드할 Amazon S3 위치를 지정하며, 학습 스크립트는 배포할 파일을 /opt/ml/model에 저장한다. 이 디렉터리는 SM_MODEL_DIR 환경 변수로도 접근할 수 있고, 저장된 내용은 model.tar.gz로 패키징되어 지정된 출력 경로에 올라간다. 배포 단계에서는 describe_training_job으로 학습 작업 메타데이터를 조회하고 ModelArtifacts의 S3ModelArtifacts 값에서 최종 모델 산출물 위치를 얻는다. 추론용 SourceCode는 ./deploy/random_forest 디렉터리와 inference.py 진입 스크립트를 지정하며, ModelBuilder는 이 핸들러를 모델 산출물과 함께 다시 패키징한다. 예제는 DJL Serving을 모델 서버로 선택하고 OPTION_ENTRYPOINT를 code/inference.py로 설정해 추론 코드의 위치를 지정한다.

8. 모델 구성과 실시간 엔드포인트 생성

ModelBuilder의 build()는 선택한 모델 서버의 규약에 맞춰 추론 핸들러와 모델 산출물을 묶고, 추론 이미지 및 Amazon S3의 재패키징된 산출물을 참조하는 SageMaker 모델을 등록한다. 이 단계 자체는 엔드포인트 인프라를 시작하지 않으며, 배포 가능한 모델을 구성하는 역할을 맡는다. 이어서 deploy()를 호출하면 초기 인스턴스 수 1로 random-forest-endpoint라는 실시간 엔드포인트를 생성하고 Endpoint 인터페이스를 반환한다. 원문은 ModelBuilder가 컨테이너 자동 선택, 의존성 자동 수집, 원시 프레임워크 모델에서의 직렬화 코드 생성도 지원한다고 덧붙이지만, 해당 기능의 구체적인 실행은 예제에서 보여주지 않는다. 제공된 본문에서 확인되는 배포 흐름은 추론 디렉터리와 진입 스크립트 지정, 모델 아카이브 재패키징, 모델 등록, 엔드포인트 생성까지다.

🧾 핵심 주장 / 시사점

• 컨테이너 재빌드 없이 반복할 수 있다는 이점은 런타임과 라이브러리를 이미지에 두고 알고리즘 코드를 SourceCode로 분리하는 구조에서 나온다.
• 학습과 추론은 공통된 코드 지정 방식을 사용하지만, 학습 코드는 실행 시 동기화되고 추론 핸들러는 모델 산출물과 재패키징되는 차이가 있다.
• Stable Diffusion 3.5의 다중 GPU 학습은 적용 범위를 보여주는 개요이며, 제공된 본문만으로 구체적인 설정이나 실행 결과까지 판단할 수는 없다.

✅ 액션 아이템

• 기존 프레임워크별 학습·배포 구성을 ModelTrainer·ModelBuilder의 공통 인터페이스와 비교 검토.
• 컨테이너 재빌드 없는 코드 반복 실행을 위해 런타임 이미지와 SourceCode의 분리 적용 검토.
• Random Forest 배포에 필요한 IAM 실행 역할·Amazon ECR·Amazon S3 준비 상태와 build()·deploy()의 단계 구분 확인.

❓ 열린 질문

• 현재 학습·배포 구성에서 ModelTrainer·ModelBuilder로 전환할 대상은 무엇인가?
• Random Forest 예제의 ml.m5.2xlarge 인스턴스 1대, 30GB 볼륨, 1시간 웜 풀 설정을 적용할 작업은 무엇인가?
• 제공된 본문에 구현 과정이 없는 Stable Diffusion 3.5의 LoRA 미세 조정은 어떤 추가 자료로 확인할 수 있는가?