Train

`classification.Trainer`

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

학습 일시정지·재개는 pause()와 resume()를 사용하며 SaigeToolkit 2.8.3 이상, 2.9.0 미만이 필요합니다. demo/train.py에서 학습 → pause → 새 Trainer에서 resume → 학습 → save_checkpoint 예시를 확인할 수 있습니다. Windows에서 worker를 사용하는 실행 코드는 if __name__ == "__main__": 안에서 시작합니다.

Usage

# Trainer 빌드
error, message, trainer = Trainer.build(CONFIG, DATA)
assert error >= 0, f"[CODE] ({error}) {message}"

# 0번 GPU로 이동
error, message, result = trainer.to_device(DEVICE)
assert error >= 0, f"[CODE] ({error}) {message}"

# validation 가능한지 확인
error, message, validation_enabled = trainer.validation_enabled()
assert error >= 0, f"[CODE] ({error}) {message}"

# 학습 루프
for step in range(CONFIG["total_iterations"]):
    error, message, result = trainer.train_one_step()
    assert error >= 0, f"[CODE] ({error}) {message}"

    if (step + 1) % PRINT_INTERVAL == 0:
        print(f"Train {step + 1}:", result)

    if validation_enabled and (step + 1) % VALIDATION_INTERVAL == 0:
        error, message, result = trainer.validate()
        assert error >= 0, f"[CODE] ({error}) {message}"
        print(f"Validation {step + 1}:", result)

# 학습 후처리 (default inference options)
error, message, post_train_process_result = trainer.post_train_process()
assert error >= 0, f"[CODE] ({error}) {message}"
print("post_train_process :", post_train_process_result)

# 체크포인트 저장
error, message, _ = trainer.save_checkpoint(
    checkpoint_path=CHECKPOINT_PATH,
    password=PASSWORD,
    metadata={"description": "demo"},
)

`build(config, data)` `classmethod`

Trainer class의 instance를 생성합니다.

Parameters:

Name Type Description Default

config

dict

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

{
    "network_type": str,  # "v1_shallow" / "v1_standard" / "v1_deep" / "v2_fast" / "v2_standard" / "v2_accurate" / "v2a_accurate" / "v2p_fast" / "v2p_standard" / "v2p_accurate" 중 하나를 지원합니다.
                         # v2p_*는 multipage image_mode ["RGB", "RGB"] 전용입니다. (multipage 문서 참고)
    "total_iterations": int,  # total training iterations
    "n_classes": int,  # number of data classes (including background class)
    "batch_size": int,  # number of train batch size (default 12)
    "roi": Optional[dict],  # roi 세팅. ROIHandlerAPI의 build config와 동일합니다. None이면 ROI 적용 안함. (default None)
    "image_resize_wh": Union[list[int], tuple[int, int]],  # training image resize (default (256, 256))
    "augmentation": Optional[list[dict]],  # 학습에 사용할 augmentation config들을 모은 list 입니다. (default None)
    "num_workers": int,  # number of train data worker processes (default 0)
    "multipage": Optional[dict],  # multipage 설정. None인 경우 multipage 사용 안 함. (default None)
        {
            "image_mode": Union[str, list[str]],  # multipage 이미지들의 모드 리스트. 리스트 길이 = 병합할 이미지 수.
                                      # 모드는 "RGB" 또는 "L" 사용 가능.
                                      # ex) ["RGB", "L", "RGB", ...] - 첫 번째 이미지는 color, 두 번째 이미지는 gray, ...
        }
}

required

data

dict

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

{
    "train_images": {
        "{image_id}": {
            "path": Union[str, list[str]],  # 이미지 경로 (multipage인 경우 경로 리스트)
            "width": int,  # image width
            "height": int,  # image height
            "class_index": int,  # label
        },
        ...,  # times number of images
    },
    "validation_images": Optional[dict[str, dict]], # validation data. train_images와 동일한 구조. (default None)
}

required

Returns:

Name	Type	Description
`Trainer`	`Trainer`	build가 완료된 classification.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: None: None

`get_class_label_counts()`

학습에 사용된 클래스별 라벨(이미지) 개수를 반환합니다.

Returns:

Type	Description
`list[int]`	list[int]: list index = class_index, 값 = 해당 class 로 학습에 사용된 라벨(이미지) 개수 입니다. `[120, 85, 200] # class 0: 120장, class 1: 85장, class 2: 200장`

`train_one_step()`

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

API 기본 설정은 별도 활성화 옵션 없이 pause()/resume()을 지원합니다. Pause 성공 후 또는 state 복원 도중 실패한 상태에서는 TrainingPausedError(-400324)를 반환합니다. Optimizer/scaler 갱신 전 model 계산 중 실패하면 남은 gradient를 비운 뒤 재시도할 수 있습니다. 이미 소비한 batch와 RNG, 변경된 model 상태는 자동으로 되돌리지 않습니다. Optimizer/scaler 갱신이 시작된 뒤 실패하면 이후 호출은 TrainingPausedError(-400324)를 반환합니다. 유효한 pause 파일이 있으면 resume()으로 복구하고, 없으면 새 Trainer를 build해야 합니다.

Returns:

Name Type Description

dict

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

{
    "step": int,  # 현재까지 진행된 총 학습 step.
    "epoch": int,  # 현재까지 진행된 총 학습 epoch.
    "epoch_step": int,  # 현재 epoch에서 몇 번째 step인지를 나타냄.
    "loss/total": float,  # 학습에 사용되는 모든 loss를 모두 더한 값.
    "loss/cross_entropy": float,  # cross entropy 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

validation 결과가 들어있는 dictionary를 반환합니다. 아래 key 들을 반환합니다 (one-vs-rest ROC 곡선 raw data 포함).

{
    "mean_f1": float,            # mean f1 value.
    "class_{idx}_f1": float,     # 각 {idx} class 별 f1 value.
    "accuracy": float,           # accuracy
    "mean_auroc": float,             # 클래스 macro 평균 AUROC.
    "class_{idx}_auroc": float,      # 각 {idx} class 별 AUROC (one-vs-rest).
    "class_{idx}_roc": {             # 각 {idx} class 별 ROC 곡선 raw data.
        "fpr": list[float],          #   thresholds 와 같은 길이.
        "tpr": list[float],          #   thresholds 와 같은 길이.
        "thresholds": list[float],   #   고정 grid (모든 class 동일).
    },
}

`post_train_process()`

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

Returns:

Name	Type	Description
`dict`	`dict`	각 parameter에 대한 설명은 InferenceHandler.get_default_inference_option를 참고해주세요. `{ "params.additional_scores": list[float], "params.batch_size": int, }`

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

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

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	checkpoint를 저장할 path 입니다.	required
`metadata`	`Optional[dict]`	호출자가 정의하여 저장하는 추가 정보입니다. 고정 key나 자동으로 추가되는 key는 없으며, load_checkpoint()에서 반환합니다. 예: {"description": "demo"}에서 description (str)은 호출자가 정한 설명입니다. None이면 빈 dict를 저장합니다. Defaults to None.	`None`
`password`	`Optional[str]`	checkpoint 파일에서 중요한 정보를 암호화 하는데 사용되는 password 입니다. None이면 암호화하지 않습니다. Defaults to None.	`None`

Returns: None: None

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

완료된 step의 학습 상태를 저장하고 일시정지합니다.

Model, optimizer, scheduler, AMP scaler, RNG, train loader의 소비 위치와 step/epoch counter를 저장합니다. Epoch 중간에도 다음 batch부터 재개할 수 있습니다. 실패하거나 미완료된 step은 저장할 수 없습니다. Optimizer/scaler 갱신 전 실패하면 train_one_step()을 재시도할 수 있지만, 성공하거나 checkpoint를 resume하기 전까지 pause는 거부합니다. 재시도 자체가 이미 소비한 batch/RNG나 변경된 model 상태를 되돌리지는 않습니다.

성공 후에는 resume() 전까지 학습할 수 없습니다. pause()가 프로세스를 종료하거나 GPU를 반환하지는 않으므로, 필요하면 제품에서 저장 성공 후 프로세스를 종료합니다. 일반 save_checkpoint()에는 재개용 학습 상태를 추가하지 않으며, 재개용 파일은 일반 checkpoint와 별도 경로에 저장합니다. 지원하지 않는 sampler를 사용하면 API 오류 코드 -411336을 반환합니다.

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

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	재개용 checkpoint를 저장할 경로입니다.	required
`metadata`	`dict[str, Any] \| None`	호출자가 정의하여 저장하는 추가 정보입니다. 고정 key나 자동으로 추가되는 key는 없으며, resume()에서 반환합니다. demo/train.py는 아래 key를 직접 저장하여 외부 학습 loop의 시작 위치로 사용합니다. `{ "completed_steps": int, # 완료한 누적 train_one_step() 호출 수. 0부터 시작. }` completed_steps는 선택 사항이며, Trainer 내부의 step 복원에는 사용되지 않습니다. None이면 빈 dict를 저장합니다. Defaults to None.	`None`
`password`	`str \| None`	checkpoint 암호화에 사용할 password입니다. None이면 암호화하지 않습니다. Defaults to None.	`None`

Returns:

Name	Type	Description
`None`	`None`	API는 (error, message, None)을 반환합니다. error >= 0이면 저장이 완료되었으며, error < 0이면 저장에 실패한 것입니다.

Usage

# train_one_step()을 100번 완료한 뒤 호출합니다.
error, message, _ = trainer.pause(
    "./training.pause", metadata={"completed_steps": 100}
)
assert error >= 0, message

`resume(checkpoint_path, password=None)`

pause()로 저장한 학습 상태를 복원하고 다음 batch부터 재개합니다.

Module major/minor와 지원하는 training state format_version이 같아야 하며, patch 버전 차이는 양방향으로 허용합니다. 재개용 학습 state가 있는지 확인한 뒤, module version을 상세 state 형식보다 먼저 검사합니다. Module major/minor 불일치는 -400329, 지원하지 않는 training state 형식은 -400321로 반환합니다. 기존 Trainer 또는 동일한 원본 config(필드 순서 포함), data 순서, module major/minor version과 device/AMP 설정으로 build한 새 Trainer를 사용합니다. 이미지 내용의 hash는 검사하지 않습니다. pause() checkpoint만 허용하며, 일반 save_checkpoint() 파일로는 학습을 재개할 수 없습니다. 지원하지 않는 sampler를 사용하면 API 오류 코드 -411336을 반환합니다.

Sample별 Python/NumPy/Torch CPU 기본 RNG를 제어하여 학습 augmentation을 재현합니다. Custom transform의 자체 generator, CUDA augmentation 또는 다른 thread가 동시에 사용하는 global RNG는 별도 state 관리가 필요합니다. 복원한 step/epoch counter와 별개로, 호출자가 관리하는 외부 학습 loop의 시작 위치는 metadata 등을 사용하여 복원해야 합니다.

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

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	pause()로 저장한 재개용 checkpoint 경로입니다.	required
`password`	`str \| None`	pause()에서 사용한 password입니다. Defaults to None.	`None`

Returns:

Type Description

dict[str, Any]

dict[str, Any]: pause(metadata=...)에 전달한 호출자 정의 metadata입니다. metadata를 생략하거나 None으로 저장했다면 빈 dict를 반환합니다. 고정 key나 자동으로 추가되는 key는 없습니다. demo/train.py로 저장한 경우:

{
    "completed_steps": int,  # 완료한 누적 step 수. 외부 loop를 이 값부터 재개.
}

completed_steps는 pause() 시 직접 저장한 경우에만 존재합니다. Model, optimizer, scheduler, AMP scaler, RNG, loader 및 내부 step 상태는 Trainer에 복원되며, 반환 metadata에는 자동으로 포함되지 않습니다. API는 (error, message, metadata)를 반환합니다. error < 0이면 metadata는 None이므로, 성공 여부를 먼저 확인해야 합니다.

Usage

# 같은 config/data로 build하고 같은 device로 옮긴 Trainer를 사용합니다.
error, message, metadata = trainer.resume("./training.pause")
assert error >= 0, message
# pause() 예시처럼 completed_steps를 직접 저장한 경우에 사용합니다.
start_step = metadata["completed_steps"]
for step in range(start_step, CONFIG["total_iterations"]):
    error, message, result = trainer.train_one_step()
    assert error >= 0, message

`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`	save_checkpoint(metadata=...)에 전달한 호출자 정의 metadata입니다. metadata를 생략하거나 None으로 저장했다면 빈 dict를 반환합니다. 고정 key나 자동으로 추가되는 key는 없습니다. Trainer의 Usage 예시에서는: `{ "description": str, # 호출자가 직접 저장한 설명. 예: "demo". }` description은 save_checkpoint() 시 직접 저장한 경우에만 존재합니다. API는 (error, message, metadata)를 반환합니다. error < 0이면 metadata는 None이므로, 성공 여부를 먼저 확인해야 합니다.

Train

classification.Trainer

build(config, data) classmethod

to_device(device)

get_class_label_counts()

train_one_step()

validation_enabled()

validate()

post_train_process()

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

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

resume(checkpoint_path, password=None)

load_checkpoint(checkpoint_path, password=None)

`classification.Trainer`

`build(config, data)` `classmethod`

`to_device(device)`

`get_class_label_counts()`

`train_one_step()`

`validation_enabled()`

`validate()`

`post_train_process()`

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

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

`resume(checkpoint_path, password=None)`

`load_checkpoint(checkpoint_path, password=None)`