HF-TrainingArgument

TrainingArguments 는 Hugging Face Trainer의 실행 환경을 정의하는 선언적 설정 객체.

 

 

다음이 자동 구성됨:

• Optimizer 생성
• Scheduler 생성
• DataLoader 설정
• (Automatic) Mixed precision 설정
• 분산 학습 설정
• 평가/저장 정책
• 체크포인트 관리 전략

---

1. 기본 시그니처 구조

대표적인 주요 인자와 기본값은 다음과 같음.

TrainingArguments(
    # 체크포인트/로그 저장 경로. 
    # args 미지정 시 Trainer가 tmp_trainer를 사용 가능(Trainer 기본 동작). 
    output_dir: str | None = None,                 

	# v5.2 TrainingArguments 시그니처에 없음(제거).
    # overwrite_output_dir: bool = False,           

	# 학습 실행 플래그(스크립트/CLI용). Trainer 내부 로직 자체를 직접 바꾸는 핵심 스위치는 아님.
    do_train: bool = False,                        
    # eval_strategy != "no"이면 True로 세팅되는 성격(스크립트 편의).
    do_eval: bool = False,                         
    # predict 실행 플래그(스크립트/CLI용).
    do_predict: bool = False,                      

    # 디바이스(GPU/CPU) 1개당 train 배치 크기.                                        
    per_device_train_batch_size: int = 8,    
    # 디바이스 1개당 eval 배치 크기.
    per_device_eval_batch_size: int = 8,            

    # gradient 누적 step 수(실질적 global batch에 영향). 
    gradient_accumulation_steps: int = 1,          
    # 평가 시 예측/로스 텐서 누적을 몇 step마다 CPU로 넘길지(메모리 완화). 
    eval_accumulation_steps: int | None = None,    

    # 기본 optimizer에 전달되는 LR. 
    learning_rate: float = 5e-5,                   
    # weight decay(AdamW 계열에서 decoupled decay). 
    weight_decay: float = 0.0,                     
    # Adam/AdamW beta1.
    adam_beta1: float = 0.9,                       
    # Adam/AdamW beta2.
    adam_beta2: float = 0.999,                     
    # Adam/AdamW eps.  
    adam_epsilon: float = 1e-8,                    
    # gradient clipping의 norm 한계값. 
    max_grad_norm: float = 1.0,                    

    # epoch 기반 학습 횟수.  
    num_train_epochs: float = 3.0,                 
    # 총 update step 강제(-1이면 epoch로 결정).
    max_steps: int = -1,                           

    # 스케줄러 타입(기본 linear).
    lr_scheduler_type: str = "linear",             

    # v5에서 deprecated. 
    # warmup_ratio: float = 0.0,  # 제거 예정.                 
                                                   
    # warmup step 수. 
    # v5에서는 0~1 미만 float이면 "전체 step 대비 비율"로 해석 가능
    # (=구 warmup_ratio 역할).
    warmup_steps: float = 0,                       

    # evaluation_strategy는 이전 이름.
    eval_strategy: str = "no",         # "no"|"steps"|"epoch". 
    # (참고) eval_strategy="steps"일 때 평가 주기. 
    # eval_steps: float | None = None, # 0~1 미만 float이면 ratio 해석.
                                                   

    # 로깅 주기 단위("steps"|"epoch").
    logging_strategy: str = "steps",
    # 로깅 간격(step).
    logging_steps: float = 500,  # (v5.2 시그니처에서는 float로 표기).

    # 저장 주기 단위("steps"|"epoch").
    save_strategy: str = "steps",  
    # 저장 간격(step). (v5.2 시그니처에서는 float로 표기).
    save_steps: float = 500,                       
    # 남겨둘 체크포인트 개수 제한(None이면 제한 없음).
    save_total_limit: int | None = None,           

    # 학습 종료 시 best checkpoint 로드. 
    # (eval_strategy 설정 필요 + save/eval 정합성 제약 존재).
    load_best_model_at_end: bool = False,          
                                                   
    # best 판정 기준 metric (기본은 "loss")
    metric_for_best_model: str | None = None,                                                         
    # best metric의 방향(True면 클수록 좋음).
    greater_is_better: bool | None = None,         

    fp16: bool = False,    # AMP(fp16) 사용 여부.
    bf16: bool = False,    # AMP(bf16) 사용 여부.

    # DataLoader worker 수. 
    dataloader_num_workers: int = 0,       
    # pin_memory 사용 여부(GPU 전송 최적화).
    dataloader_pin_memory: bool = True,            
    seed: int = 42,  # 난수 시드.                              

    # 외부 로깅 연동 비활성화("none"). tensorboard/wandb 등 쓰려면 명시.
    report_to: None | str | list[str] = "none",    
    # 체크포인트 경로를 주면 그 지점에서 재개.
    resume_from_checkpoint: str | None = None,     
)

 

load_best_model_at_end=True 사용을 위해서:

• 가급적 save_strategy 와 eval_strategy 는 같아야 함.
• "steps" 일 때는 save_steps 가 eval_steps 의 정수배여야 함.

Trainer에서 train( resume_from_checkpoint=True) 는 가장 최근의 체크포인트를 찾음.

TrainingArguments에선 지정해줘야함.

---

2. 필수 인자

2.1 output_dir (필수)

• 체크포인트 저장 경로
• 반드시 지정해야 함: v5.x 기준으로 기본값이 "tmp_trainer"로 지정되긴 함.

Trainer는 여기에 다음의 파일들을 생성 및 저장함:

• pytorch_model.bin
• config.json
• trainer_state.json
• optimizer.pt
• scheduler.pt

---

3. 실행 플래그

인자	기본값	설명
overwrite_output_dir	False	기존 디렉토리 덮어쓰기 여부. v5.x에서 deprecated
do_train	False	학습 실행 여부
do_eval	False	평가 실행 여부
do_predict	False	추론 실행 여부

 

이들은 주로 Trainer.train() 호출에 의해 값이 읽어지거나 변경됨.

---

4. Epoch / Step 제어

인자	기본값	의미
num_train_epochs	3.0	epoch 수
max_steps	-1	전체 step 강제 지정

참고로

• max_steps > 0 이면 max_steps가 우선 반영됨.

---

5. 배치 관련

인자	기본값
per_device_train_batch_size	8
per_device_eval_batch_size	8
gradient_accumulation_steps	1

 

실제 optimizer가 한 번 업데이트할 때 사용된 전체 샘플 수인 global batch size 는 다음과 같음(optimizer.step()):

"global batch size" = per_device_train_batch_size × GPU 개수 × gradient_accumulation_steps

---

6. Optimizer 관련 - 기본값 포함

기본 optimizer는 AdamW.

• "adamw_torch_fused" 가 v5.2에서 기본값.

인자	기본값
learning_rate	5e-5
weight_decay	0.0
adam_beta1	0.9
adam_beta2	0.999
adam_epsilon	1e-8
max_grad_norm	1.0

 

내부적으로는 다음과 유사:

torch.optim.AdamW(
    model.parameters(),
    lr=5e-5,
    betas=(0.9, 0.999),
    eps=1e-8,
    weight_decay=0.0,
)

---

7. Scheduler 관련 - 기본값 명확히

7.1 lr_scheduler_type

기본값은 "linear" 임.

• 즉, linear decay가 기본 전략.

옵션:

• "linear" (기본)
• "cosine"
• "cosine_with_restarts"
• "polynomial"
• "constant"
• "constant_with_warmup"

---

7.2 warmup_steps

기본값은 0임.

• 즉, warmup 없음.
• v5.2에서 소수로 받을 경우, 기존의 warmup_ratio로 동작함.

---

7.3 warmup_ratio

기본값은 0.0임.

• 전체 step 대비 0%.
• v5.2에서 deprecated

우선순위:

• warmup_steps > 0 이면 warmup_ratio 무시

---

7.4 기본 상태 요약

아무 설정을 하지 않으면:

• AdamW optimizer
• linear decay
• warmup 없음

---

8. 평가 전략

인자	기본값
eval_strategy	"no"
load_best_model_at_end	False
metric_for_best_model	None
greater_is_better	None

• eval_strategy="no"가 기본이므로,
• evalutation을 자동으로 수행하지 않음.

eval_steps 도 warmup_steps와 마찬가지로 [0,1] 의 실수 표현 가능.

• 이 경우 전체 training step 대비 비율로 해석됨.

---

9. 저장 전략

인자	기본값
save_strategy	"steps"
save_steps	500
save_total_limit	None

즉, 기본 동작은 다음과 같음:

• 500 step마다 저장
• 저장 파일의 갯수 제한 없음

---

10. 로깅 전략

인자	기본값
logging_strategy	"steps"
logging_steps	500

즉, 500 step마다 로그 출력.

---

11. Automatic Mixed Precision (AMP)

Trainer와 TrainingArgument사용시 개발자가 직접 AMP 코드를 작성하지 않아도 됨.

인자	기본값
fp16	False
bf16	False

기본은 FP32 학습.

 

AMP 별 차이는 다음과 같음:

• FP32
  • 안정적
  • 느림
  • 메모리 많이 사용
• FP16
  • 빠름
  • 메모리 절약
  • underflow 위험 있음
• BF16
  • FP16보다 안정적
  • Ampere 이상 GPU에서 권장

---

12. DataLoader 관련

인자	기본값
dataloader_num_workers	0
dataloader_pin_memory	True

• 멀티 프로세스 로딩 안 함
• GPU 전송은 pin memory 사용

---

13. Seed

인자	기본값
seed	42

• 재현성 확보용.

---

14. 로거 (외부 logging backend)

인자	기본값
report_to	"none"

• 예전처럼 wandb/tensorboard 등이 “설치되어 있으면 자동 감지되어 붙는” 기본 동작이 아님.
• 기본이 "none" 임: 이 경우도 콘솔 출력은 정상 동작.
• 원하는 로거가 있으면 명시할 것.

Trainer는 내부적으로 여러 logging backend를 지원:

• "tensorboard"
• "wandb"
• "mlflow"
• "comet_ml"
• "azure_ml"
• "clearml"
• "neptune"

---

15. 재개

인자	기본값
resume_from_checkpoint	None

• None 인 경우가 기본값으로 새로 학습이 이루어짐.
• resume_from_checkpoint="path/to/checkpoint-xxxx" 이면 특정 checkpoint에서 학습이 이루어짐.

---

14. 구조적 이해

TrainingArguments는 단순한 옵션 묶음이 아님.

이 객체는 다음을 자동 수행함:

• optimizer 생성
• scheduler 생성
• AMP (Automatic Mixed Precision) 여부 결정 (float32가 일반적이나 fp16, bf16으로도 수행가능)
• gradient clipping 적용
• checkpoint 저장 전략 구성
• 분산 backend 설정

---

15. 실전에서 가장 많이 조정하는 항목

per_device_train_batch_size
gradient_accumulation_steps
learning_rate
weight_decay
num_train_epochs
lr_scheduler_type
warmup_ratio
evaluation_strategy
save_strategy
load_best_model_at_end
fp16 / bf16

---

참고

TrainingArgument의 기본값은 다음에 맞춰짐:

• BERT fine-tuning
• 작은 모델
• 안정적 데이터

대형 Vision Transformer, multi-stage fine-tuning 환경에서는
거의 반드시 재설정이 필요하다.

---

같이보면 좋은 자료들

https://huggingface.co/docs/transformers/v5.2.0/en/main_classes/trainer

Trainer

https://newreleases.io/project/github/huggingface/transformers/release/v5.0.0

huggingface/transformers v5.0.0 on GitHub