Train

`core.Trainer`

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

Usage

demo/train.py 참고

`build(config, data)` `classmethod`

Trainer class의 instance를 생성합니다.

Parameters:

Name Type Description Default

config

dict

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

{
    "network_type": str,                             # "v2a_fast" / "v2a_standard" / "v2a_accurate" 중 하나를 지원합니다.
    "total_iterations": int,                         # 총 학습 step 수 (default 10000)
    "image_resize_wh": list[int] | tuple[int, int],  # training image resize scale (default [512, 512])
    "roi": dict | None,                              # roi 세팅. ROIHandlerAPI의 build config와 동일합니다.
                                                     # Trainer build시 설정한 ROI를 Validation, Inference시에도 적용됩니다.
                                                     # None이면 ROI를 적용하지 않습니다. (default None)
    "augmentation": list[dict] | None,               # 학습에 사용할 augmentation config들을 모은 list 입니다. (default None)
    "num_workers": int,                              # number of train data worker processes (default 8)
    "batch_size": int,                               # train batch size (default 16)
}

required

data

dict

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

{
    "train_images": {
        "{image_id}": {
            "path": str,  # image path
            "labels": {
                "is_ng": bool,  # ng or not
            },
        },
        ...,  # times number of images
    },
    "validation_images": {...},  # optional
}

required

Returns:

Name	Type	Description
`Trainer`	`Trainer`	build가 완료된 core.Trainer class의 instance를 반환합니다.

`to_device(device)`

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

Parameters:

Name	Type	Description	Default
`device`	`device \| str \| int`	변경하고자 하는 device 입니다. int의 경우 해당 번호의 GPU, "cpu"(str)은 cpu를 사용합니다.	required

`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:

Type Description

dict[str, Any]

dict[str, Any]: 훈련 1 스텝 후 리턴하는 값입니다.

{
    "step": int,  # 현재까지 진행된 총 학습 step.
    "loss": float,  # 훈련 loss값.
    "step_time(sec)": float,  # 학습을 1 step 진행하는데 걸린 총 시간
    "data_time(sec)": float,  # 데이터를 로딩하는데 걸린 시간
    "model_time(sec)": float,  # 모델 학습에 걸린 시간
}

`post_train_process()`

train을 마무리하기 위한 작업을 합니다. 주로 threshold를 자동으로 계산해줍니다.

Returns:

Name Type Description

dict

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

{
    "params.object_score_threshold": float,     # default: 0.0
    "params.object_area_threshold": int,        # default: 0
    "params.batch_size": int,                   # default: 1

    # post_train_process를 호출해서 바뀌는 값은 아래 4가지 입니다.
    "params.anomaly_score_threshold": float,    # default: 0.0
    "params.object_boundary_threshold": float,  # default: 0.0
    "params.heatmap_color_range_max": float,    # default: 0.0
    "params.heatmap_color_range_min": float,    # default: 0.0
}

`validation_enabled()`

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

Returns:

Name	Type	Description
`bool`	`bool`	Trainer가 validation이 가능하면 True를, 불가능하다면 False를 반환합니다.

`get_validation_schedule(total_iterations, density_level)` `classmethod`

validation을 수행할 step을 반환합니다.

Parameters:

Name	Type	Description	Default
`total_iterations`	`int`	총 학습 스텝입니다.	required
`density_level`	`int`	validation을 수행할 step의 밀도입니다. [0, 1, 2] 중 1가지이며 작을수록 validation을 더 자주 수행합니다. 기본값은 1입니다.	required

Returns:

Type	Description
`list[int]`	list[int]: validation을 수행할 step이 담긴 list를 반환합니다.

`validate()`

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

Returns:

Name	Type	Description
`dict`	`dict`	validation 결과가 들어있는 dictionary를 반환합니다. OK와 NG와 OK이미지가 모두 적어도 1개 이상 있을때 출력합니다. 아니면 validate을 할 수 없습니다. `{ "AUROC": float, # Area under ROC "AUPR": float, # Area under PR curve "Best threshold": float, # Best threshold "Best F1-Score": float, # F1 score with labels }`

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

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

SaigeToolkit 2.8.3 이상, 2.9.0 미만과 기본 InfiniteRandomSampler 학습 경로를 지원합니다. 학습 시작 전이나 micro-batch 누적까지 끝난 optimizer step에서 저장할 수 있으며, 학습 도중 요청하면 해당 step이 끝날 때까지 기다립니다. 실패한 step 뒤에는 다음 step이 성공하거나 resume()하기 전까지 TrainingPauseBoundaryError에 해당하는 오류를 반환합니다. Custom finite loader는 학습할 수 있지만 pause() 요청에는 TrainerResumeSamplerError에 해당하는 오류 코드 -414204를 반환합니다.

post_train_process() 없이 저장할 수 있습니다. Model, optimizer, AMP scaler, loss state, 학습 step, threshold/calibration 상태, 소비한 dataloader 위치, validation iterator 생성 여부와 RNG를 metadata와 별도로 저장합니다. 성공 후 학습을 계속하려면 resume()을 호출해야 합니다. Pause 자체는 프로세스를 종료하지 않으며, 저장 성공 후 제품에서 종료할 수 있습니다.

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

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	학습 재개용 checkpoint를 저장할 path입니다.	required
`metadata`	`dict[str, Any] \| None`	호출자가 정의하는 추가 정보입니다. 고정 또는 필수 키는 없으며, step도 자동으로 추가하지 않습니다. 예를 들어 demo/train.py는 train_one_step() 결과의 step을 {"step": result["step"]}으로 전달하여 완료한 학습 step을 기록합니다. 생략하거나 None이면 빈 dictionary를 저장합니다. Defaults to None.	`None`
`password`	`str \| None`	checkpoint 암호화에 사용할 password입니다. None이면 암호화하지 않습니다. Defaults to None.	`None`

Returns:

Name	Type	Description
`None`	`None`	성공 시 public API는 (0, "Success", None)을 반환합니다. 실패 시에는 (음수 error_code, error_message, None)을 반환합니다.

`resume(checkpoint_path, password=None)`

pause()로 저장한 학습 상태를 복원하고, 함께 저장한 metadata를 반환합니다.

Module major/minor와 지원하는 training state format_version이 같아야 하며, patch 버전 차이는 양방향으로 허용합니다. 재개용 학습 state가 있는지 확인한 뒤, module version을 상세 state 형식보다 먼저 검사합니다. Module major/minor 불일치는 -400329, 지원하지 않는 training state 형식은 -400321로 반환합니다. 같은 config와 데이터 순서, module major/minor version으로 Trainer를 build하고, to_device()로 같은 device type과 AMP 설정을 준비한 뒤 호출합니다. Config의 dictionary 필드 순서도 유지해야 하며, 데이터 파일 내용과 library 환경도 같아야 합니다. 파일 내용의 hash는 검사하지 않습니다. 실제 학습 step은 metadata의 step 값과 별도로 복원됩니다. 같은 Trainer나 새 프로세스의 Trainer 모두 사용할 수 있으며, 일반 save_checkpoint() 파일은 resume()의 입력으로 사용할 수 없습니다.

Global Python/NumPy/Torch CPU RNG를 사용하는 training augmentation과 corruption을 지원합니다. Transform 내부 private generator나 자체 가변 상태, 임의의 stochastic validation transform의 worker RNG는 별도 관리가 필요합니다. Validation iterator 생성 정보가 없는 이전 pause 파일도 읽을 수 있지만, 대상 iterator의 기존 상태를 유지하므로 validation 이후의 정확한 RNG 연속성은 보장하지 않습니다.

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

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	pause()로 저장한 학습 재개용 checkpoint의 path입니다.	required
`password`	`str \| None`	저장할 때 사용한 password입니다. Defaults to None.	`None`

Returns:

Type Description

dict[str, Any]

dict[str, Any]: pause()에 전달했던 metadata의 키와 값을 반환합니다. 고정 또는 필수 키는 없으며, metadata를 생략했거나 None으로 저장했다면 {}입니다. 아래 키는 호출자가 직접 저장할 수 있는 예시이며, 자동으로 추가되지 않습니다.

{
    "step": int,  # 선택: 호출자가 기록한 완료 step (demo/train.py에서 사용)
    "description": str,  # 선택: 호출자가 기록한 설명
}

public API의 실제 반환값은 (0, "Success", metadata)입니다. 실패 시에는 (음수 error_code, error_message, None)을 반환합니다.

Examples:

같은 설정으로 build하고 to_device()를 호출한 Trainer에서 재개합니다. 아래 step 접근은 pause(metadata={"step": step})으로 저장한 경우의 예시입니다.

error, message, metadata = trainer.resume("pause.pt")
assert error == 0, message
start_step = metadata["step"]

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

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

학습 후에는 post_train_process()로 threshold를 갱신한 뒤 저장합니다. 이 checkpoint는 model과 step을 저장하며, optimizer와 RNG 등을 포함한 학습 재개용 checkpoint는 pause()로 저장해야 합니다.

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	checkpoint를 저장할 path 입니다.	required
`metadata`	`dict \| None`	호출자가 정의하는 추가 정보입니다. 고정 또는 필수 키는 없습니다. 예를 들어 {"description": "demo"}를 저장하면 load_checkpoint()가 그대로 반환합니다. 생략하거나 None이면 빈 dictionary를 저장합니다. Defaults to None.	`None`
`password`	`str \| None`	checkpoint 파일에서 중요한 정보를 암호화 하는데 사용되는 password 입니다. None이면 암호화하지 않습니다. Defaults to None.	`None`

Returns:

Name	Type	Description
`None`	`None`	성공 시 public API는 (0, "Success", None)을 반환합니다. 실패 시에는 (음수 error_code, error_message, None)을 반환합니다.

`load_checkpoint(checkpoint_path, password=None)`

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

Parameters:

Name	Type	Description	Default
`checkpoint_path`	`str`	load할 checkpoint가 저장 되어 있는 path 입니다.	required
`password`	`str \| None`	checkpoint 파일에서 중요한 정보를 복호화 하는데 사용되는 password 입니다. None이면 복호화하지 않습니다. Defaults to None.	`None`

Returns:

Name	Type	Description
`dict`	`dict`	save_checkpoint()에 전달했던 metadata의 키와 값을 반환합니다. 고정 또는 필수 키는 없으며, metadata를 생략했거나 None으로 저장했다면 {}입니다. 예를 들어 {"description": "demo"}로 저장한 경우 description (str) 키를 반환합니다. step 등 저장하지 않은 키는 자동으로 추가하지 않습니다. public API의 실제 반환값은 (0, "Success", metadata)입니다. 실패 시에는 (음수 error_code, error_message, None)을 반환합니다.

Train

core.Trainer

build(config, data) classmethod

to_device(device)

train_one_step()

post_train_process()

validation_enabled()

get_validation_schedule(total_iterations, density_level) classmethod

validate()

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

resume(checkpoint_path, password=None)

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

load_checkpoint(checkpoint_path, password=None)

`core.Trainer`

`build(config, data)` `classmethod`

`to_device(device)`

`train_one_step()`

`post_train_process()`

`validation_enabled()`

`get_validation_schedule(total_iterations, density_level)` `classmethod`

`validate()`

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

`resume(checkpoint_path, password=None)`

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

`load_checkpoint(checkpoint_path, password=None)`