Skip to content

Train

detection.Trainer

Object Detection 모델을 학습시키기 위한 Trainer class 입니다.

Usage

demo/train.py 참고

Windows에서는 worker가 spawn으로 시작하므로 학습 진입점을 if __name__ == "__main__": 안에 둡니다. 실행 파일로 패키징한 제품은 같은 guard 안에서 multiprocessing.freeze_support()도 호출해야 합니다.

build(config, data) classmethod

Trainer class의 instance를 생성합니다.

Parameters:

Name Type Description Default
config Dict

Trainer를 build 하기 위한 config가 담겨 있는 dictionary 입니다. 

{
    "network_type": str,  # "v2_fast" / "v2_standard" / "v2_accurate" / "v2_extended" 중 하나를 지원합니다.
    "total_iterations": int,  # total training iterations
    "n_classes": int,  # number of data classes
    "image_resize_wh": Union[List[int], Tuple[int, int]],  # image resize width, height for training.
    "batch_size": int,  # number of train batch size (default 8)
    "roi": Optional[Dict],  # roi 세팅. ROIHandlerAPI의 build config와 동일합니다. None이면 ROI 적용 안함. (default None)
    "augmentation": Optional[List[Dict]],  # 학습에 사용할 augmentation config들을 모은 list 입니다. (default None)
    "num_workers": int,  # number of train data worker processes (default 8)
    "multipage": Optional[Dict],  # multipage 설정. None인 경우 multipage 사용 안 함. (default None)
        {
            "image_mode": List[str],  # multipage 이미지들의 모드 리스트. 리스트 길이 = 병합할 이미지 수.
                                      # 모드는 "RGB" 또는 "L" 사용 가능.
                                      # ex) ["RGB", "L", "RGB", ...] - 첫 번째 이미지는 color, 두 번째 이미지는 gray, ...
        },
    "crop_rows_and_columns": Optional[Tuple[int, int]],  # crop 학습 시 row, column 개수. (default None)
    "iou_threshold": float,  # Intersection Over Union의 임계치. Validation Metric 측정 시 실제 라벨과 추정 결과를 동일한 것으로 간주할 수 있는 두 박스이 겹치는 비율입니다. (default 0.5)
}

required
data Dict

Trainer가 사용 할 train/validation data가 담겨 있는 dictionary 입니다. 

{
    "train_images": {
        # 1: basic structure
        "{image_id}": {
            "path": Union[str, List[str]],  # 이미지 경로 (multipage인 경우 경로 리스트)
            "width": int,  # image width
            "height": int,  # image height
            "labels": [
                {
                    "class_index": int,  # class index
                    "bounding_box": List[int],  # [left, top, width, height]
                },
                ...,  # times number of labels in the image
            ],
        },
        ...,  # times number of images
    },
    "validation_images": {...},
}

required

Returns:

Name Type Description
Trainer Trainer

build가 완료된 detection.Trainer class의 instance를 반환합니다.

to_device(device)

Trainer의 device를 변경합니다. (cpu/gpu)

Parameters:

Name Type Description Default
device Union[device, str, int]

변경하고자 하는 device 입니다. int의 경우 해당 번호의 GPU를, "cpu" 문자열의 경우 cpu를 사용합니다.

 required

Returns:

Name Type Description
None None

None

train_one_step()

학습을 1스텝 수행하고, 결과를 반환합니다.

API 기본 설정은 별도 활성화 옵션 없이 pause()/resume()을 지원합니다. Pause 성공 후 또는 state 복원 도중 실패한 상태에서는 TrainingPausedError(-400324)를 반환합니다. Loss에서 NaN이 검출되면 error -413310을 반환합니다. Micro-batch 처리 중 실패하면 부분 누적 gradient를 비운 뒤 재시도할 수 있지만, 이미 소비한 batch/RNG나 변경된 weight를 되돌리지는 않습니다. 저장 시점부터 같은 학습을 재현하려면 resume()를 사용합니다. 데이터 fetch 오류는 해당 base batch를 건너뛴 뒤 원래 오류를 반환하며, 다음 호출에서 학습을 계속할 수 있습니다. Crop buffer에 이미 쌓인 patch는 유지합니다. Loader 복구 자체가 실패하면 -413338을 반환하고 학습을 차단합니다. Gradient clipping이나 optimizer/scaler/scheduler 처리 중 실패해도 학습을 차단합니다. 실패한 호출은 원래 오류를 반환하며, 이후 train_one_step()은 -400324를 반환합니다. 유효한 pause 파일이 있으면 resume()으로 복구하고, 없으면 새 Trainer를 build해야 합니다.

Returns:

Name Type Description
Dict Dict

학습 결과가 들어있는 dictionary를 반환합니다. 

{
    "step": int,  # 현재까지 진행된 총 학습 step.
    "epoch": int,  # 현재까지 진행된 총 학습 epoch.
    "epoch_step": int,  # 현재 epoch에서 몇 번째 step인지를 나타냄.
    "loss/total": float,  # 학습에 사용되는 모든 loss를 모두 더한 값.
    "loss/box": float,  # v2_fast / v2_extended 모델에서 사용하는 loss
    "loss/obj": float,  # v2_fast / v2_extended 모델에서 사용하는 loss
    "loss/cls": float,  # v2_fast / v2_extended 모델에서 사용하는 loss
    "loss/loss_classifier": float,  # v2_standard 모델에서 사용하는 loss
    "loss/loss_box_reg": float,  # v2_standard 모델에서 사용하는 loss
    "loss/loss_objectness": float,  # v2_standard 모델에서 사용하는 loss
    "loss/loss_rpn_box_reg": float,  # v2_standard 모델에서 사용하는 loss
    "loss/loss_bbox": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_0": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_1": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_2": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_3": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_4": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_dn": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_dn_0": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_dn_1": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_dn_2": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_dn_3": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_dn_4": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_bbox_interm": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_0": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_1": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_2": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_3": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_4": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_dn": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_dn_0": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_dn_1": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_dn_2": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_dn_3": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_dn_4": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_ce_interm": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_0": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_1": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_2": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_3": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_4": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_dn": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_dn_0": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_dn_1": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_dn_2": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_dn_3": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_dn_4": float, # v2_accurate 모델에서 사용하는 loss
    "loss/loss_giou_interm": float, # v2_accurate 모델에서 사용하는 loss
    "learning_rate/0": float,  # optimizer의 learning rate
    "step_time(sec)": float,  # 학습을 1 step 진행하는데 걸린 총 시간
    "data_time(sec)": float,  # 데이터를 로딩하는데 걸린 시간
    "model_time(sec)": float,  # 모델 학습에 걸린 시간
}

validation_enabled()

Trainer가 validation이 가능한지 bool로 반환합니다.

Returns:

Name Type Description
bool bool

Trainer가 validation이 가능하면 True를, 불가능하다면 False를 반환합니다.

validate()

Validation을 수행하고, 결과를 리턴합니다.

Returns:

Name Type Description
Dict Dict

validation 결과가 들어있는 dictionary를 반환합니다. 

{
    "object/mean_f1": float,  # mean f1 value.
    "object/class_{idx}_f1": float,  # 각 {idx} class 별 f1 value.
}

post_train_process()

train 후처리를 수행하고, 해당 모델의 default inference options을 리턴합니다.

Returns:

Name Type Description
Dict Dict

각 parameter에 대한 설명은 InferenceHandler.get_default_inference_option를 참고해주세요. 

{
    "params.object_score_threshold": List[int],
    "params.object_area_threshold": List[int],
    "params.max_num_of_detected_objects": List[int],
    "params.batch_size": int,
}

get_untrainable_images()

PatchCrop 학습 모드 사용 시, 학습에 사용되지 않은 이미지들을 리턴 합니다.

Returns:

Type Description
list[str]

list[str]: 학습에 사용되지 않은 이미지 path 가 담겨있는 list 입니다.

get_class_label_counts()

학습에 사용된 클래스별 라벨(어노테이션 인스턴스) 개수를 반환합니다.

Returns:

Type Description
list[int]

list[int]: list index = class_index, 값 = 해당 class 로 학습에 사용된 라벨(어노테이션) 개수 입니다. 

[12, 85, 200]  # class 0: 12개, class 1: 85개, class 2: 200개

save_checkpoint(checkpoint_path, metadata=None, password=None)

현재 Trainer의 상태를 암호화하여 저장합니다.

Parameters:

Name Type Description Default
checkpoint_path str

checkpoint를 저장할 path 입니다.

 required
metadata Optional[Dict]

checkpoint에 저장할 사용자 정의 dictionary. 고정된 key는 없으며 load_checkpoint()가 같은 내용을 반환합니다. 예: {"description": "demo"}. 생략하거나 None이면 {}로 저장합니다.

 None
password Optional[str]

checkpoint 파일에서 중요한 정보를 암호화 하는데 사용되는 password 입니다. None이면 암호화하지 않습니다. Defaults to None.

 None

Returns: None: None

load_checkpoint(checkpoint_path, password=None)

저장한 checkpoint로부터 Trainer의 상태를 불러오고, metadata를 반환합니다.

Parameters:

Name Type Description Default
checkpoint_path str

load할 checkpoint가 저장 되어 있는 path 입니다.

 required
password Optional[str]

checkpoint 파일에서 중요한 정보를 복호화 하는데 사용되는 password 입니다. None이면 복호화하지 않습니다. Defaults to None.

 None

Returns:

Name Type Description
Dict Dict

성공 시 반환 tuple (error, message, metadata)의 세 번째 값입니다. save_checkpoint()에 전달했던 사용자 정의 dictionary이며 고정된 key는 없습니다. metadata를 생략했거나 None으로 저장했다면 {}입니다. demo/train.py의 일반 checkpoint는 다음 metadata를 저장합니다. 

{
    "description": "demo",  # str: 호출자가 저장한 설명. 선택 key.
}
description은 API가 자동으로 추가하는 key가 아닙니다. 실패 시 error는 음수이며 세 번째 값은 None입니다.

pause(checkpoint_path, metadata=None, password=None)

현재 step까지의 학습 상태를 저장하고 Trainer를 일시정지합니다.

train_one_step() 호출 사이에 사용합니다. 성공한 뒤 제품에서 학습 프로세스를 종료할 수 있습니다. 이 함수는 프로세스를 종료하거나 GPU를 반환하지 않습니다. 저장 실패 시 기존 checkpoint와 학습 가능 상태를 유지합니다.

완료된 optimizer step 경계에서 저장합니다. 다른 thread에서 학습 중 요청하면 micro-batch accumulation을 포함한 현재 train_one_step()이 끝날 때까지 기다립니다. Step이 실패하면 다음 step이 성공하거나 정상 resume하기 전까지 pause할 수 없습니다.

Model, optimizer/scheduler/scaler, step/epoch/epoch_step, loader의 소비 위치와 main-process RNG를 저장합니다. Crop 학습에서는 미사용 patch buffer도 저장하므로 파일이 커질 수 있습니다. 일반 save_checkpoint()의 저장 형식은 유지합니다.

API 기본 InfiniteRandomSampler 경로와 crop 학습을 지원하며 SaigeToolkit 2.8.3 이상, 2.9.0 미만이 필요합니다. Optimizer는 Adam/AdamW, scheduler는 MultiStepLR만 지원합니다. 그 외 custom 설정의 일반 학습과 save_checkpoint()는 유지하지만 pause/resume은 지원하지 않습니다.

학습 실패 시 누적 gradient를 비웁니다. Optimizer/scaler 갱신 단계 이후 실패하면 이전 pause 파일을 resume()하거나 새 Trainer를 build해야 다시 학습할 수 있습니다. Pause 성공 후 training loader를 닫습니다.

Parameters:

Name Type Description Default
checkpoint_path str

재개용 checkpoint 경로. 기존 모델 파일과 별도로 지정합니다.

 required
metadata Optional[Dict[str, Any]]

checkpoint에 함께 저장할 사용자 정의 dictionary. resume()가 같은 내용을 반환하며, 생략하거나 None이면 {}로 저장합니다. 고정된 key는 없습니다. demo/train.py는 완료한 학습 횟수를 직접 저장합니다. 

{
    "completed_steps": result["step"],  # int: 성공한 train_one_step() 결과의 누적 step.
}
completed_steps는 demo에서 진행률을 확인하는 선택 key이며 API의 필수 key가 아닙니다.

 None
password Optional[str]

checkpoint 암호화 password. None이면 암호화하지 않습니다.

 None

Returns:

Name Type Description
None None

반환 tuple (error, message, result)의 세 번째 값입니다. error가 0 이상이면 저장에 성공했으며 result는 None입니다. 이미 pause 상태이거나 성공한 step 경계가 아니면 error는 -413322입니다. 지원하지 않는 optimizer는 -413339, scheduler는 -413340입니다.

resume(checkpoint_path, password=None)

pause()로 저장한 checkpoint에서 다음 step부터 학습을 재개합니다.

일시정지한 Trainer에서 바로 호출할 수 있습니다. 새 Trainer에서 재개하려면 동일한 config와 data 순서로 build하고, to_device()로 기존과 동일한 CPU/CUDA 및 AMP 설정을 선택한 후 호출합니다. 일반 save_checkpoint() 파일은 resume에 사용할 수 없습니다. Optimizer는 Adam/AdamW, scheduler는 MultiStepLR만 지원합니다.

Module의 major/minor version과 각 state의 format_version은 같아야 합니다. Patch version 차이는 허용하며, 이미지 파일 내용, transform, library 환경은 같아야 합니다. 이미지 metadata와 annotation의 dictionary 필드 순서는 달라도 되지만, 이미지 ID dictionary와 list 순서는 유지해야 합니다. 파일 content hash는 검사하지 않습니다.

DataLoader의 sample 순서와 crop buffer를 복원합니다. Toolkit은 sample 추출 순번별로 Python/NumPy/Torch CPU 기본 RNG를 제어하여 worker augmentation을 재현합니다. Prefetch한 sample도 같은 순번으로 다시 계산하며, main-process의 patch 선택 RNG와 이미 생성한 patch buffer도 복원합니다. Custom transform의 별도 numpy.random.Generator/torch.Generator, OpenCV RNG, 외부 thread의 난수 사용, CUDA augmentation이나 시간·외부 상태 의존 transform은 이 보장에 포함하지 않습니다. GPU 연산의 nondeterminism까지 없애지는 않습니다.

Module의 major/minor version이 다른 pause 파일은 -413329로 거절합니다. 재개용 학습 state가 있는지 확인한 뒤, module version을 상세 state 형식보다 먼저 검사합니다. 지원하지 않는 state format_version은 patch version과 관계없이 -413321로 거절합니다. 초기 DET 전용 loader의 pause 파일은 지원하지 않으며, 이전 버전과 같은 seed로 새 학습을 시작했을 때의 shuffle/augmentation 순서는 보장하지 않습니다.

복원 전 검사에서 거절되면 Trainer의 기존 상태를 유지합니다. State 복원을 시작한 뒤 실패하면 추가 학습은 TrainingPausedError(-400324)로 차단합니다. 유효한 pause 파일로 resume()을 다시 시도하거나 새 Trainer를 build해야 합니다.

Parameters:

Name Type Description Default
checkpoint_path str

pause()로 저장한 checkpoint 경로.

 required
password Optional[str]

checkpoint 복호화 password.

 None

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: 성공 시 반환 tuple (error, message, metadata)의 세 번째 값입니다. pause()에 전달했던 사용자 정의 dictionary이며 고정된 key는 없습니다. metadata를 생략했거나 None으로 저장했다면 {}입니다. demo/train.py에서 100 step을 완료하고 pause한 경우의 반환 예시입니다. 

{
    "completed_steps": 100,  # int: 호출자가 저장한 누적 완료 step 수. 선택 key.
}
completed_steps는 API가 자동으로 추가하지 않습니다. demo처럼 이 key를 읽으려면 pause()의 metadata에 직접 저장해야 합니다. Trainer의 step/epoch/epoch_step, optimizer 등의 학습 상태는 내부에서 복원되며 반환 metadata에 자동으로 추가되지 않습니다. epoch/epoch_step은 저장된 step과 현재 epoch 길이를 기준으로 다시 계산합니다. 실패 시 error는 음수이며 metadata는 None입니다. 일반 모델 파일이나 잘못된 patch loader state는 -413321, module major/minor version 불일치는 -413329, config/data 순서 불일치는 -413330, device/AMP 불일치는 -413331입니다. 지원하지 않는 optimizer는 -413339, scheduler는 -413340입니다.

Examples:

# 동일한 config/data로 build하고 to_device()를 호출한 뒤 재개합니다.
error, message, metadata = trainer.resume(
    "./demo/demo_training.pause.pt", password="password"
)
assert error >= 0, message
# demo/train.py에서 completed_steps를 저장한 checkpoint에 해당합니다.
completed_steps = metadata["completed_steps"]