How-to guides

• 1: Job Failover 사용하기
• 2: Concurrent Checkpointing

1 - Job Failover 사용하기

Job Failover는 On-Demand Training으로 학습을 진행하는 도중 GPU 등 하드웨어 장애가 발생하더라도 학습이 중단되지 않도록 정상 자원으로 자동 재배치하여 학습을 이어가는 기능입니다. Job Failover 기능을 사용하면 시스템 오류 및 하드웨어 장애 감지 시 사용자가 직접 장애를 확인하고 Job을 다시 생성할 필요 없이 학습의 연속성을 확보할 수 있습니다.

Job Failover 개요

Training Job 실행 중에는 학습이 배치된 노드에서 GPU 오류, 노드 장애 등 다양한 하드웨어 이상이 발생할 수 있습니다.
Job Failover 기능을 사용하면 이러한 하드웨어 장애가 감지되었을 때 시스템이 장애 노드를 회피하여 정상 자원으로 Training Job을 자동 재배치하고 학습을 재개합니다.
Job Failover의 주요 동작은 다음과 같습니다.

• 장애 감지: 학습이 실행 중인 노드의 GPU 및 하드웨어 상태를 지속적으로 점검하여 이상을 감지합니다.
• 자동 재배치: 하드웨어 장애로 판단되면 장애 노드를 제외하고 정상 노드로 Training Job을 재배치하여 학습을 다시 시작합니다.
• 불필요한 재배치 방지: 하드웨어 장애가 아닌 사용자 코드 오류, 설정 오류 등은 Failover 대상에서 제외됩니다.
• 재시도 횟수 제한: Failover는 정해진 최대 횟수(3회) 내에서만 수행되며, 이를 초과하면 학습이 실패로 종료됩니다.

오류 원인 점검

시스템은 학습 중단이 발생하면 노드의 GPU 및 하드웨어 상태를 점검하여, 그 원인이 하드웨어 장애인지 아니면 사용자 애플리케이션, 설정과 같은 하드웨어 이외의 문제인지 판단합니다.
Failover 수행 여부는 이 판단 결과에 따라 결정됩니다.

하드웨어 장애로 판단되는 경우

GPU를 정상적으로 사용할 수 없는 물리적, 하드웨어 수준의 오류가 감지되면 하드웨어 장애로 판단하여 Failover를 수행합니다.
이러한 오류는 해당 노드에서 학습을 계속할 수 없으므로 장애 노드를 제외하고 정상 자원으로 재배치하여 학습을 재개합니다. 하드웨어 장애로 판단되는 오류 예시는 다음과 같습니다.

내부 오류로 판단되는 경우

학습 중단의 원인이 하드웨어 장애가 아니라 사용자 애플리케이션 코드나 설정 문제로 판단되면, 재배치를 하더라도 동일한 문제가 반복될 가능성이 높으므로 Failover를 거부하고 internalerror 상태로 종료합니다. 내부 오류로 판단되는 오류 예시는 다음과 같습니다.

Job Failover 상태 확인하기

1. 모든 서비스 > AI/ML > Simple AI Training 메뉴를 클릭하세요. Simple AI Training의 Service Home 페이지로 이동합니다.
2. Service Home 페이지에서 Training Job 메뉴를 클릭하세요. Training Job 목록 페이지로 이동합니다.
3. Training Job 목록 페이지에서 Job의 상태를 확인하세요.
   • Failover 사용 여부와 하드웨어 장애 판단 결과에 따른 상태 흐름은 다음과 같습니다.

     구분	상세 설명
     Failover 성공	하드웨어 장애가 감지되어 정상 자원으로 재배치가 완료된 상태 Running → Pending - failoverinprogress → Running 순서로 상태가 변경되면 Failover가 정상적으로 수행되어 학습 재개 완료
     Failover 거부	학습이 중단되었으나 하드웨어 장애 신호가 확인되지 않아 재배치 대상이 아니라고 판단된 상태 Running → Pending - failoverinprogress → Pending - internalerror 순서로 상태가 변경되면 Failover가 거부 사용자 코드 오류와 같이 하드웨어 이외의 원인일 수 있으므로 로그 확인 필요
     Failover 미설정	Job Failover를 사용하지 않도록 설정한 상태 학습 중단이 발생하면 재배치를 시도하지 않고 Running → Failed 순서로 학습을 종료

     표. Job Failover에 따른 상태 흐름
   • Failover 진행 중 표시되는 주요 상태값은 다음과 같습니다.

     상태	상세 설명
     Pending - failoverinprogress	하드웨어 장애를 감지하고 Failover 가능 여부를 판단하거나 정상 자원으로 재배치를 진행 중인 상태
     Pending - maxretriesexceeded	Failover 최대 시도 횟수를 초과하여 더 이상 재배치를 수행하지 않는 상태
     Pending - imagepullbackoff	컨테이너 이미지를 불러오지 못해 학습을 시작할 수 없는 상태(이미지 URL 및 인증 정보 확인 필요)
     Pending - internalerror	하드웨어 장애 신호가 확인되지 않는 등 Failover 대상이 아니라고 판단되어 재배치가 거부된 상태

     표. Job Failover 진행 중 주요 상태값

Job Failover 로그 확인하기

Failover가 발생한 경우, 장애로 중단된 이전 학습의 로그와 재배치 후에 재개된 학습의 로그를 하나의 로그 스트림에서 함께 확인할 수 있습니다.

1. 모든 서비스 > AI/ML > Simple AI Training 메뉴를 클릭하세요. Simple AI Training의 Service Home 페이지로 이동합니다.
2. Service Home 페이지에서 Training Job 메뉴를 클릭하세요. Training Job 목록 페이지로 이동합니다.
3. Training Job 목록 페이지에서 로그를 확인할 자원을 선택하세요. Training Job 상세 페이지로 이동합니다.
4. Training Job 상세 페이지에서 로그 탭을 클릭하세요. 해당 Job의 로그 정보가 표시됩니다.
5. 로그 정보의 Training Job명 하단의 이름을 클릭하세요. ServiceWatch의 로그 그룹 상세 페이지로 이동합니다.
6. 로그 그룹 상세 페이지에서 로그 스트림 탭을 클릭하세요. 로그 스트림 목록이 표시됩니다.
7. 확인할 로그 스트림 이름(예시: master)을 클릭하세요. 해당 스트림의 로그가 시간순으로 표시됩니다.
   • Failover가 발생한 경우, 장애로 중단되었던 학습의 로그와 재배치 후 다시 시작된 학습의 로그가 하나의 스트림에 함께 기록됩니다.
   • 학습 시작 시 출력되는 초기화 로그(예시: Starting dataset initialization)가 두 번 이상 표시되면, 학습이 재배치되어 다시 시작되었음을 확인할 수 있습니다.

2 - Concurrent Checkpointing

Concurrent Checkpointing은 기존 방식과 달리 Forward/Backward 연산 중에도 체크포인트를 비동기적으로 저장하는 기능입니다.
따라서 이 기능을 사용하여 체크포인트 저장으로 인한 오버헤드를 줄여 전체 학습 시간을 효율적으로 단축하고, 예측 불가능한 학습 중단 발생 시 유실될 수 있는 학습 진행 상태를 자동으로 저장할 수 있습니다.

Concurrent Checkpointing 개요

Simple AI Training에서 제공하는 Training Job은 On-Demand Training 타입과 Spot Training 타입이 있습니다.
Concurrent Checkpointing은 두 가지 타입에서 모두 사용할 수 있으나 타입별로 기능의 활용 범위가 다릅니다. 타입별 활용 범위는 다음과 같습니다.

Concurrent Checkpointing 사용하기

사전 준비하기: 스크립트 작성

사용자는 Trainer, Concurrent Checkpoint의 save method를 동시에 사용할 수 있습니다.

Spot Training 사용법

Spot Training 사용 시 스크립트 예시는 다음과 같습니다.

|language = python | title = Training Script Example | collapse = true

// transformers==5.10.2 기준으로 작성합니다.

import os
import torch
from transformers import (
    AutoTokenizer,
    AutoModelForCausalLM,
    Trainer,
    TrainingArguments,
    DataCollatorForLanguageModeling
)
from datasets import load_dataset
import json
from datastates.llm import DecoratedCheckpointing
import argparse
import logging
import time

def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--local_rank",
        type=int,
        default=-1,
        help="local rank passed from distributed launcher (Deepspeed, torchrun, etc.)"
    )
    return parser.parse_args()

if __name__ == "__main__":
    args = parse_args()

    model_path="/root/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B/snapshots/4e20de362430cd3b72f300e6b0f18e50e7166e08"

    # Load tokenizer and model
    tokenizer = AutoTokenizer.from_pretrained(model_path, local_files_only=True)

    # Set pad token to EOS if not already defined
    if tokenizer.pad_token is None:
        tokenizer.pad_token = tokenizer.eos_token

    # Load WikiText-2 dataset
    dataset = load_dataset("wikitext", "wikitext-2-raw-v1",cache_dir="/root/.cache/huggingface/datasets")

    # Tokenization function
    def tokenize_function(examples):
        return tokenizer(
            examples["text"],
            truncation=True,
            max_length=128,
            padding="max_length"
        )

    # Tokenize the dataset
    tokenized_dataset = dataset.map(
        tokenize_function,
        batched=True,
        remove_columns=["text"]
    )

    train_dataset = tokenized_dataset["train"]
    valid_dataset = tokenized_dataset["validation"]

    data_collator = DataCollatorForLanguageModeling(
        tokenizer=tokenizer,
        mlm=False  # Causal LM (not masked LM)
    )

    script_directory = os.path.dirname(os.path.abspath(__file__))
    ds_config_path = os.path.join(script_directory, "ds_config.json")

    training_args = TrainingArguments(
        output_dir="./results",
        num_train_epochs=3,
        per_device_train_batch_size=2,  # Adjust based on GPU memory
        gradient_accumulation_steps=4,  # Effective batch size = batch_size * gradient_accumulation_steps
        save_strategy="steps",
        save_steps=200,
        logging_steps=2,
        eval_strategy="steps",
        eval_steps=100,
        bf16=True,  # Enable BF16 mixed precision (use fp16 if unsupported)
        deepspeed=ds_config_path,  # Path to DeepSpeed config file
        report_to="none",
    )

    model = AutoModelForCausalLM.from_pretrained( model_path,  local_files_only=True, low_cpu_mem_usage=True, device_map=None)

    # Initialize Trainer
    trainer = Trainer(
        model=model,
        args=training_args,
        train_dataset=train_dataset,
        eval_dataset=valid_dataset,  # Optional: validation set for evaluation
        processing_class=tokenizer,
        data_collator=data_collator,
    )

       # ADD configuration for Concurrent CHECKPOINT ENGINE
    config = {
        "host_cache_size": 50,
        "parser_threads": 1,
        "pin_host_cache": True,
        "trainer": trainer,
    }

    ckpt_engine = DecoratedCheckpointing(runtime_config=config, rank=args.local_rank)

    resume_from_checkpoint=False

    if os.getenv("CKPT_LAST_STEP") != None :
        resume_from_checkpoint=True

    trainer.train(resume_from_checkpoint=resume_from_checkpoint)

// transformers==5.10.2 기준으로 작성합니다.

import os
import torch
from transformers import (
    AutoTokenizer,
    AutoModelForCausalLM,
    Trainer,
    TrainingArguments,
    DataCollatorForLanguageModeling
)
from datasets import load_dataset
import json
from datastates.llm import DecoratedCheckpointing
import argparse
import logging
import time

def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--local_rank",
        type=int,
        default=-1,
        help="local rank passed from distributed launcher (Deepspeed, torchrun, etc.)"
    )
    return parser.parse_args()

if __name__ == "__main__":
    args = parse_args()

    model_path="/root/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B/snapshots/4e20de362430cd3b72f300e6b0f18e50e7166e08"

    # Load tokenizer and model
    tokenizer = AutoTokenizer.from_pretrained(model_path, local_files_only=True)

    # Set pad token to EOS if not already defined
    if tokenizer.pad_token is None:
        tokenizer.pad_token = tokenizer.eos_token

    # Load WikiText-2 dataset
    dataset = load_dataset("wikitext", "wikitext-2-raw-v1",cache_dir="/root/.cache/huggingface/datasets")

    # Tokenization function
    def tokenize_function(examples):
        return tokenizer(
            examples["text"],
            truncation=True,
            max_length=128,
            padding="max_length"
        )

    # Tokenize the dataset
    tokenized_dataset = dataset.map(
        tokenize_function,
        batched=True,
        remove_columns=["text"]
    )

    train_dataset = tokenized_dataset["train"]
    valid_dataset = tokenized_dataset["validation"]

    data_collator = DataCollatorForLanguageModeling(
        tokenizer=tokenizer,
        mlm=False  # Causal LM (not masked LM)
    )

    script_directory = os.path.dirname(os.path.abspath(__file__))
    ds_config_path = os.path.join(script_directory, "ds_config.json")

    training_args = TrainingArguments(
        output_dir="./results",
        num_train_epochs=3,
        per_device_train_batch_size=2,  # Adjust based on GPU memory
        gradient_accumulation_steps=4,  # Effective batch size = batch_size * gradient_accumulation_steps
        save_strategy="steps",
        save_steps=200,
        logging_steps=2,
        eval_strategy="steps",
        eval_steps=100,
        bf16=True,  # Enable BF16 mixed precision (use fp16 if unsupported)
        deepspeed=ds_config_path,  # Path to DeepSpeed config file
        report_to="none",
    )

    model = AutoModelForCausalLM.from_pretrained( model_path,  local_files_only=True, low_cpu_mem_usage=True, device_map=None)

    # Initialize Trainer
    trainer = Trainer(
        model=model,
        args=training_args,
        train_dataset=train_dataset,
        eval_dataset=valid_dataset,  # Optional: validation set for evaluation
        processing_class=tokenizer,
        data_collator=data_collator,
    )

       # ADD configuration for Concurrent CHECKPOINT ENGINE
    config = {
        "host_cache_size": 50,
        "parser_threads": 1,
        "pin_host_cache": True,
        "trainer": trainer,
    }

    ckpt_engine = DecoratedCheckpointing(runtime_config=config, rank=args.local_rank)

    resume_from_checkpoint=False

    if os.getenv("CKPT_LAST_STEP") != None :
        resume_from_checkpoint=True

    trainer.train(resume_from_checkpoint=resume_from_checkpoint)

다음 절차의 예시를 참고하여 스크립트를 작성하세요.

1. Import Concurrent CHECKPOINT

from datastates.llm import DecoratedCheckpointing
...

2. ADD configuration for Concurrent CHECKPOINT ENGINE

config = {
       "host_cache_size": 50,
       "parser_threads": 1,
       "pin_host_cache": True,
       "trainer": trainer,
}

3. Initialize Concurrent CHECKPOINT ENGINE

ckpt_engine = DecoratedCheckpointing(runtime_config=config, rank=args.local_rank)

4. Set Concurrent CHECKPOINT ENGINE parameter

resume_from_checkpoint=False

if os.getenv("CKPT_LAST_STEP") != None :
       resume_from_checkpoint=True

trainer.train(resume_from_checkpoint=resume_from_checkpoint)

Concurrent Checkpoint 저장 경로

저장 경로는 기본적으로 TrainingArgument의 output_dir을 기반으로 합니다.
해당 output_dir 하위 경로에 concurrent_checkpoint라는 디렉토리 하위에 저장됩니다.

On-Demand Training 사용하기

On-Demand Training 사용 방법 Spot Training 사용 방법과 유사합니다.

최초 학습

다음 절차의 예시를 참고하여 스크립트를 작성하세요.

1. Import Concurrent CHECKPOINT

from datastates.llm import DecoratedCheckpointing
...

2. ADD configuration for Concurrent CHECKPOINT ENGINE

config = {
       "host_cache_size": 50,
       "parser_threads": 1,
       "pin_host_cache": True,
       "trainer": trainer,
}

3. Initialize Concurrent CHECKPOINT ENGINE

ckpt_engine = DecoratedCheckpointing(runtime_config=config, rank=args.local_rank)

4. Set Concurrent CHECKPOINT ENGINE parameter

trainer.train(resume_from_checkpoint=False)

수동 활성화 시

최초 학습 시 지정한 output_dir 경로에 유효한 체크포인트가 확인될 경우, 학습 재실행 시 해당 체크포인트 경로를 직접 model initialize 시 지정하여 로드합니다. 또는 학습을 재실행할 때 기존 output_dir과 동일하게 지정하고 다음과 같이 설정하여 최신 체크포인트를 자동으로 로드할 수 있습니다.

다음 절차의 예시를 참고하여 스크립트를 작성하세요.

1. Import Concurrent CHECKPOINT

from datastates.llm import DecoratedCheckpointing
...

2. ADD configuration for Concurrent CHECKPOINT ENGINE

config = {
       "host_cache_size": 50,
       "parser_threads": 1,
       "pin_host_cache": True,
       "trainer": trainer,
}

3. Initialize Concurrent CHECKPOINT ENGINE

ckpt_engine = DecoratedCheckpointing(runtime_config=config, rank=args.local_rank)

4. Set Concurrent CHECKPOINT ENGINE parameter

trainer.train(resume_from_checkpoint=True)

Job 실행하기

Training Job 생성 화면의 Command 필드에 사용하고자 하는 명령어와 함께 기능 관련 환경 변수를 추가하여 실행합니다.

| language = go

PYTHONPATH=$CHECKPOINT_VENDOR HF_DATASETS_OFFLINE="1" ${USER_SCRIPT}

• PYTHONPATH=$CHECKPOINT_VENDOR: 기능 활성화를 위한 라이브러리 경로를 로드하도록 설정합니다.
• HF_DATASETS_OFFLINE=“1”: Samsung Cloud Platform 망은 huggingface 로그인 및 모델/데이터셋 다운로드를 지원하지 않습니다. 따라서 사용자 스크립트에서 huggingface 네트워크 호출을 방지하는 용도로 설정합니다.

예시

기본 코드

| language = actionscript

• python 파일

python /mnt/experiment/training/compatiblitiy-test/version_check.py

• deepspeed

deepspeed --num_gpus=2 /mnt/experiment/training/compatiblitiy-test/train_llama_8b-demo.py

• accelerate

accelerate launch --config_file /mnt/experiment/training/compatiblitiy-test/sat-test/fsdp_config.yaml --num_processes 4 /mnt/experiment/training/compatiblitiy-test/sat-test/train_llama_1b-demo.py

기능 사용 시

| language = actionscript

• python 파일

PYTHONPATH=$CHECKPOINT_VENDOR python /mnt/experiment/training/compatiblitiy-test/version_check.py

• deepspeed

PYTHONPATH=$CHECKPOINT_VENDOR deepspeed --num_gpus=4 /mnt/experiment/training/compatiblitiy-test/train_llama_8b-demo.py

• accelerate

PYTHONPATH=$CHECKPOINT_VENDOR accelerate launch --config_file /mnt/experiment/training/compatiblitiy-test/sat-test/fsdp_config.yaml --num_processes 4 /mnt/experiment/training/compatiblitiy-test/sat-test/train_llama_1b-demo.py

transformers==5.10.2
numpy==2.4.6
pybind11==3.0.4
safetensors==0.8.0
torch==2.12.1
torchvision==0.27.1
datasets==4.8.4
pytest
cuda-bindings~=13.2.0
packaging<=26.0

#--- test deepspeed version library
deepspeed==0.18.9
accelerate==1.13.0

진행 상황 확인

진행 상황은 Training Job 상세 페이지의 로그 탭에서 확인할 수 있습니다.
진행 상황을 확인하려면 다음 절차를 따르세요.

1. 모든 서비스 > AI/ML > Simple AI Training 메뉴를 클릭하세요. Simple AI Training의 Service Home 페이지로 이동합니다.
2. Service Home 페이지에서 Training Job 메뉴를 클릭하세요. Training Job 목록 페이지로 이동합니다.
3. Training Job 목록 페이지에서 상세 정보를 확인할 자원을 클릭하세요. Training Job 상세 페이지로 이동합니다.
4. 로그 탭을 클릭한 후, 로그를 확인하세요. 환경 준비 상태로 로그를 확인할 수 있습니다.

| language = actionscript | title = 

[INFO] Concurrent Checkpoint library is installed
waiting for validator through /channel/stage.socket...
validator is running....
sidecar container is running and ready for training process to run!

| language = actionscript | title = 

[2026-07-10 01:50:09,939] [ERROR] [decorator.py:442:get_last_checkpoint_preprocess] [Concurrent Checkpoint] No Checkpoint found with step: -1
ERROR:datastates.llm.decorator:[Concurrent Checkpoint] No Checkpoint found with step: -1