Release notes

`2.5.0`

2026/10/27
SaigeToolkit 요구 버전: >=2.8.3,<2.9.0
[기능 추가]
- Continuous Training: public Trainer의 pause(path, metadata=None, password=None) / resume(path, password=None) 추가.
- 같은 config/data/device 종류로 새 프로세스에서 완료된 step 다음부터 학습을 이어갈 수 있습니다.
- Generator/discriminator, 모든 optimizer/scheduler, defect/mask mode, network의 train/eval 상태, crop buffer, sampler 소비 위치, RNG와 완료된 auto-mode region 설정을 저장·복원합니다.
- Generator와 모든 discriminator update가 완료된 경계에서 pause하고 저장 성공 후 training worker를 종료합니다.
[Bug fix]
- Auto-mode fitting이 validity checker config를 소모하지 않도록 보호하여 이전 checkpoint 복원 후 다시 fitting할 수 있습니다.
- checkpoint의 epoch_step 저장값과 resume 직후 network의 train/eval 상태 복원 수정.
- Auto-mode fitting 전 checkpoint로 되돌릴 때 이후에 생긴 region 설정 제거.
- 실패한 step의 gradient 정리 및 optimizer 갱신 이후 실패한 경우 resume 전까지 학습 차단.
- Auto-mode fitting 중 실패하면 같은 Trainer에서 재시도할 수 있습니다. 영구 region 설정을 갱신한 뒤 실패한 경우에는 resume 전까지 학습을 차단합니다.
[호환성 및 지원 범위]
- Resume checkpoint는 module major/minor가 같아야 하며 patch 차이는 양방향으로 허용합니다. 호환되지 않는 version은 state schema보다 먼저 검사합니다.
- 일반 save_checkpoint() 형식은 유지합니다. 데이터 내용·순서, config/transform, library version과 device 종류가 같아야 합니다.
- 단일 training device를 지원합니다. Auto-mode fitting 내부의 부분 재개, multi-GPU와 custom style augmentor는 지원하지 않습니다.
- 미지원 device/loader/style augmentor와 잘못된 저장 mode는 모듈 전용 오류로 알립니다.
[CI/CD]
- GitHub 전용 credential helper로 private dependency를 설치하고 Git/pip URL에서 PAT를 제거합니다.
- 같은 PR의 이전 CI 실행을 취소하고 Linux/Windows에 source/native resume 검사를 연결합니다.
- Windows GPU lock의 run·attempt·job 소유권을 확인하여 해제합니다. 소유 정보를 기록한 뒤 lock을 공개하고, 종료된 workflow attempt의 남은 lock은 자동 회수합니다. 조회 실패나 소유 정보 누락 시 lock을 유지합니다. CPU resume 검사와 Cython build는 lock을 획득하기 전에 수행합니다.
- Python 변경이 없는 commit, 공백이 포함된 경로와 Python 파일 삭제도 Style check에서 처리합니다.
- Python 3.11.9를 설치하는 hosted Style job을 Ubuntu 24.04로 고정합니다.
Train API 사용법

`2.4.0`

2025/09/16
SaigeToolkit 버전 업데이트: 2.7.1

`2.3.1`

2025/06/17
[Bug fix]
- checkpoint의 config.data.validation이 NO_VALIDATION일 때 InferenceDataloader 빌드에 실패하는 오류 수정

`2.3.0`

2025/06/11
SaigeToolkit 버전 업데이트: 2.6.7
[기능 변경]
- 라이브러리 버전 업데이트
  - pytorch==2.7.0+cu128

`2.2.2`

2025/03/07
SaigeToolkit 버전 업데이트: 2.4.2
[버그 수정]
- train/validation image가 비어있는 경우, train/validation 이 정상작동 하지 않는 위험 방지

`2.2.1`

2025/01/22
[Bug fix]
- Offline 환경에서 학습 불가능한 버그 대응 [VISIONPRD-1882] GEN 학습 시 연결 거부 에러 (-760999)

`2.2.0`

2025/01/17
SaigeToolkit 버전 업데이트: 2.3.1
[버전 업데이트]
- SaigeToolkit 버전 업데이트.

`2.1.2`

2024/11/07
- docstring 일부 잘못 표기된 부분 수정
  - device 세팅에서 torch.device 타입이 누락된 부분 수정

`2.1.1`

2024/10/10
SaigeToolkit 버전 업데이트: 2.2.5
[버전 업데이트]
- SaigeToolkit 버전 업데이트.

`2.1.0`

2024/09/10
SaigeToolkit 버전 업데이트: 2.2.3
[버전 업데이트]
- SaigeToolkit 버전 업데이트에 따라 python 3.11 과 torch 2.3으로 업데이트 되었습니다.

`2.1.0-rc1`

2024/08/16
SaigeToolkit 버전 업데이트: 2.1.0
[기능 변경]
- error message를 api output에서 직접 출력하도록 수정했습니다.
  - error_code, error_message, result = api()
- VISIONPRD-1029 이슈 및 Development guide 문서의 SaigeError 정의 섹션을 참고해 주세요.
[기능 개선]
- error message에 추가적인 message 를 argument 로 입력할수 있도록 개선했습니다.
- image_load 시 발생하는 에러에 대한 messaging을 개선했습니다.

`2.1.0-rc0`

2024/07/31
SaigeToolkit 버전 업데이트: 2.0.1
[기능 개선]
- lazy import 도입
  - 실제 모듈들이 사용되기 전까지 세부 파일들을 import 하지 않음.

`2.0.30`

2024/07/18
[Bug fix]
- Template이 너무 큰 경우 TemplateMatchRegionProposer에서 topk 수행 중 count가 candidate 수를 넘어 발생하는 에러 대응.

`2.0.29`

2024/07/15
[Bug fix]
- Image Truncated Error 대응 [VISIONPRD-796][DET] truncated image 처리

`2.0.28`

2024/07/04
[기능 변경]
- Auto generation 시 Object data type에 대해서 Shape pool option을 사용 가능하도록 변경.
[Bug Fix]
- Auto generation 시 Object data type에 대해서 Shape pool 모드의 결함이 일부 생성되던 문제 해결.

`2.0.27`

2024/06/11
[Bug Fix]
- Auto mode 학습 중, 데이터셋에 유난히 작은 이미지가 섞여 있는 경우 발생 가능한 ValueError를 예외처리.

`2.0.26`

2024/05/28
SaigeToolkit 버전 업데이트: 09cefc
[기능 추가]
- 학습 중 loss 값이 NaN인 경우 NanLossError 레이즈

`2.0.25`

2024/05/20
SaigeToolkit 버전 업데이트: 1b9ae2
[기능 개선]
- trainer 학습 시, 불필요한 train 모드 전환 연산 제거

`2.0.24`

2024/04/24
[Bug Fix]
- 일부 온라인 다운로드가 필요한 모델 웨이트를 cythonize setup 시 함께 다운로드 하도록 수정.

`2.0.23`

2024/03/19
[기능 개선]
- GPU 메모리 절감을 위해 기본 API batch size를 6 -> 4로 변경.
[Bug Fix]
- Docs 경로를 기존 research/defect_generation 에서 research/generation 으로 변경.

`2.0.22`

2024/01/26
SaigeToolkit 버전 업데이트
[기능 추가]
- setup 시 without-pretrained-model 기능 추가
  - setup.py, setup/all.py 파일에 해당 기능 추가
  - resource 를 다운로드 하지 않고, build 폴더로 저장하지 않음.
- ROI 설정시 큰 이미지에서 processing 시간이 과도하게 걸리는 문제 일부 해결

`2.0.21`

2024/01/09
SaigeToolkit 버전 업데이트: 7026244
[기능 개선]
- metadata 크기 1MB -> 12MB 변경

`2.0.20`

2024/01/04
[Bug Fix]
- Cythonize build 시 웨이트를 잘못된 경로에 다운로드 받고 있었던 문제 해결.

`2.0.19`

2023/12/26
[기능 개선]
- 학습 스테이지 중간에 불필요한 GPU 메모리 cache를 제거하는 코드 추가.
- SaigeToolkit 서브모듈 업데이트

`2.0.18`

2023/12/12
[Bug Fix]
- Docs 에 default batch_size, num_workers 가 오기입된 부분 수정.

`2.0.17`

2023/11/27
[기능 개선]
- update 이외의 api에 대해서도 label_id 키를 제공받을 수 있도록 수정. 단, label_id의 value가 전부 None이 아닐 시 종전과 같이 InferenceLabelIdNotRequiredError 에러를 raise 함.

`2.0.16`

2023/11/22
[기능 개선]
- intermediate 결과가 존재할 때, 특정 라벨만을 재 인퍼런스 할 수 있는 update_label_and_generate API 추가.
- 입력 포맷은 generate와 똑같지만 입력되는 image_info의 labels 딕셔너리에 업데이트 대상을 특정하기 위한 label_id 키가 무조건 제공되어야 함.
- DataLoader 속도 향상을 위한 옵션 수정
  - num_worker default 0 -> 4
  - pin_memory 추가

`2.0.15`

2023/11/16
[Bug Fix]
- 근접한 candidate label 사이에 박스 형태의 간섭이 생기는 현상 해결

`2.0.14`

2023/11/15
[기능 개선]
- Intermediate 파일 용량 대폭 개선.
[Bug Fix]
- 결함의 bbox가 서로 겹치는 경우, 한 결함의 삭제가 다른 결함의 모습에 영향을 미치던 현상 해결.

`2.0.13`

2023/11/14
[기능 개선]
- Assist intensity시 입력 마스크의 1%와 1px 중 큰 값을 최소 크기로 설정 (패치가 사라지는 현상 대응).
[Bug Fix]
- Assist On일 시 항상 최대 세기로 assist 되던 현상 해결.

`2.0.12`

2023/11/09
[기능 개선]
- DataLoader 속도 향상을 위해 InfiniteSampler 반영
[Bug Fix]
- 학습 데이터 일부가 random하게 섞이지 않는 버그 수정
- default batch size 가 1로 지정되어 있는 문제 해결

`2.0.11`

2023/11/08
[Bug Fix]
- add_label_and_generate 호출 시 이전 생성 결과가 사라지는 현상 해결.
- auto mode train 및 auto generate 시 지정하지 않는 GPU 디바이스 (0번) 에서 소량의 메모리 소모하던 문제 해결.
- 에러 레이즈 시 출력되는 메시지 전반적으로 수정

`2.0.10`

2023/11/07
[Bug Fix]
- add_label_and_generate 호출 시 generation 결과가 검게 변하는 현상 해결.

`2.0.9`

2023/11/06
[Bug Fix]
- auto_generate 호출 시 생성 실패한 이미지에 대해서도 intermediate 파일이 생성되는 현상 수정.
- auto_generate를 box_expand_ratio > 1.0 옵션으로 호출 시 생성된 라벨끼리 겹칠 수 있던 문제 해결.

`2.0.8`

2023/11/06
[Bug Fix]
- Texture auto mode 사용 시 학습-테스트 이미지 사이즈가 다를 경우 발생하던 에러 해결.
- box expand ratio 사용 시 특정 상황에서 발생하던 런타임에러 수정.
- Object auto mode 사용 시 특정 상황에서 발생하던 런타임에러 수정.
- Auto mode 사용 시 Gaussian KDE 피팅 함수에서 발생하던 no solution 케이스 해결.

`2.0.7`

2023/10/30
[기능 추가]
- 공통
  - API의 images 인풋의 각 image_info에 save_dir과 함께 save_idx라는 파라미터를 받도록 기능 변경.
    - manual의 경우 save_dir/save_idx 경로에 intermediate 생성
    - auto의 경우 한 이미지 당 여러 결함 이미지가 만들어질 경우, save_idx를 주어진 값에서 1씩 올려가며 save_dir 하위에 이미지 수만큼 서브디렉토리 생성.
  - generated_labels의 개별 라벨 딕셔너리에 label_id 파라미터 추가.
- Inferencer API
  - Auto mode generation
    - auto generate 시 이미지 하나 당 몇 개까지 결함을 생성 가능한지 컨트롤하는 max_count_per_image 옵션 추가.
  - Manual mode generation
    - generate, ..._generate 생성 메서드에 save_intermediate_file 옵션을 추가.
    - False일 경우 생성 후 intermediate를 생성하거나 업데이트 하지 않음. 테스트 용도 옵션.
    - save_dir에 기존 생성 결과가 존재할 때 사용할 수 있는 add_label_and_generate, delete_label_and_generate 메서드 추가.
      - 드로잉 툴에서 라벨을 지웠다 추가했다 하는 상황을 위해 추가된 기능.
- Analyzer API
  - 기존 생성 결과에서 일부 라벨을 영구적으로 제거하기 위한 delete_label_and_generate 메서드 추가
  - 기존 생성 결과에서 일부 라벨을 일시적으로 비활성화하기 위한 disable_label_and_generate 메서드 추가
  - 기존 Analyzer의 update_generated_labels 메서드가 disable_label_and_generate로 변경됨.
    - 이제는 disable 하고 싶은 label id를 명시적으로 입력받아 결과 업데이트 및 intermediate 변경을 수행함.

`2.0.6`

2023/10/19
[기능 추가]
- generate 등 메서드의 generated_labels에 bitmap 이외에 contour 정보도 포함되도록 동작 및 테스트 추가.

`2.0.5`

2023/10/17
[Bug Fix]
- Inferencer api의 auto_generate 및 generate 메서드에서 contour 형태의 seg 라벨 인풋을 처리할 수 있도록 동작 및 테스트 추가.

`2.0.4`

2023/09/18
[기능 추가]
- inference_option
  - "mask.smooth_mask" (bool), "mask.assist_intensity" (int) 추가
  - 이에 따라 trainer.post_train_process() 기능 추가 및 출력 값으로 위 두개의 inference option 출력되도록 설정.
- Generation API 수정
  - Manual 및 Auto 모드 generation을 위한 메서드를 분리 (generate / auto_generate)
  - 각 메서드의 입력 형식 변경
    - Manual: assist, assist_intensity, smooth_mask가 라벨 정보로 추가됨.
    - Auto: images와 options를 받아 이미지 여러장을 한번에 생성. 자세한 정보는 docs 참고.
[기능 변경]
- 학습시 사용되는 crop 알고리즘 변경
  - 이미지 내부만을 자르도록 수정

`2.0.3`

2023/09/06
[기능 추가]
- auto mode 에서 (실제 데이터 라벨에 있는 mask / 랜덤 ellipse / 랜덤 box) 마스크 사용하는 기능 추가
[기능 개선]
- auto mode 학습에 사용되는 이미지 패치가 너무 작아, 이후의 이미지 패치 관련 통계 알고리즘에 문제를 일으키는 부분 수정
- XGB Classifier의 augmentation을 변경
- 베이스 네트워크 성능 향상
- init_weight 파일에 "defect_generator", "defect_discriminator" weight 외의 용량이 큰 optimizer 등 제거
  - 용량이 1/4 수준으로 압축
  - download 속도 향상
  - 기존 weight 삭제하고 재 다운로드 필요
[기능 변경]
- manual mode 가 대폭 수정되었습니다.
  - "pen"/"box" 를 없애고 "manual" 로 통일
  - mask 입력은 bitmap 을 활용한 형식으로 통일
  - assist boolean 옵션 추가
- Augmentation 지원 리스트 수정
  - Docs 에 random_rotate90, perspective_transform 가 잘못 기입되어 있는 부분 삭제
- allow_tf32 변경 기능 제거
  - torch default 값으로 고정되도록 allow_tf32 를 조작하는 기능을 제거
- box_to_seg_ratio_range (List[float], 0.0~1.0) 인퍼런스 옵션을 assist_intensity (int, 0~100) 옵션으로 변경.
[Bug Fix]
- auto mode 알고리즘 버그 수정
- postprocess의 일부 기능 버그 수정
- Windows에서 0번 이외의 GPU 사용 시 속도 저하 및 메모리 이슈 해결

`2.0.2`

2023/06/30
[기능 추가]
- Box proposer에서 박스 사이즈 확장이 가능하도록 기능 구현.
  - auto inference 시에만 조절 가능
- Box proposer에서 최소 박스 넓이를 설정할 수 있도록 기능 구현.
  - 넓이의 제곱근 임계값을 integer 타입으로 설정
[Bug Fix]
- Box mode 에서 bounding rot box 타입 핸들링 버그 수정
  - ((center_x, center_y), (width, height), angle)
- auto mode 학습시 데이터 타입에 따른 버그 수정
- mask generator loss 계산 시 알고리즘 오류로 NaN 이 발생하는 버그 수정

`2.0.1`

2023/05/15
[기능 추가]
- Analysis API: 모델 빌드 없이 analysis postprocess & generate 수행
[기능 변경]
- Inference.generate의 인풋 파라미터에서 use_saved_file 삭제: 해당 기능은 Anaylsis.generate로 분리됨.
- Inference에서 update_generated_labels api 삭제: 해당 기능은 Analysis.update_generated_labels로 분리됨.
[기능 개선]
- Trainer.to_device() 호출 시 CPU로 보내는 경우 torch.cuda.empty_cache() 호출해 GPU 메모리 일부 해제

`2.0.0`

2023/04/26
[기능 추가]
- 패치 object 단위로 출력하도록 변경
  - inferencer의 update_generated_labels 메소드 참고
- 테스트 파이프라인 수정
  - windows 에서 테스트 수행하도록 추가
  - inferencer 가 cpu 에 대해 테스트 수행하도록 추가
- Trainer 설명에 요구 데이터 수에 대한 정보가 추가되었습니다.
- Inferencer 에 warmup 기능이 추가되었습니다.
[기능 변경]
- 기존 inference option 제거 (timer 만 남아있음)
- resize factor 제거
- torch 2.0.0 적용
- Analysis API가 InferenceHandler.analyze() & InferenceHandler.summarize_analysis() 로 변경되었습니다.
- 기존 Analysis API들은 제거되었습니다.
- box mode 의 input 이 bounding_rot_box 타입으로 변경되었습니다.

`1.0.0`

2023/04/##
initial release