Trainer를 W&B에 연결하는 방법을 설명합니다. 연결하면 트레이닝 run이 메트릭, 모델 체크포인트, 평가 출력을 중앙 집중식 대시보드에 자동으로 로깅합니다. 가이드를 마치면 run을 비교하고, W&B 아티팩트에 모델 체크포인트를 저장하고 다시 불러오며, 자신의 워크플로에 맞게 로깅을 사용자 지정할 수 있습니다. 이 가이드는 Hugging Face Transformers Trainer를 사용한 모델 트레이닝에 이미 익숙하다고 가정합니다.
빠른 시작

바로 실행 가능한 코드부터 살펴보고 싶다면 이 Google Colab을 확인하세요.
시작하기: 실험 추적
이 섹션에서는 첫 트레이닝 run이 W&B 대시보드에 표시되도록 W&B 인증을 수행하고, 클라이언트 라이브러리를 설치하고, 프로젝트 이름을 지정하고,Trainer에서 로깅을 활성화하는 방법을 설명합니다.
가입 및 API 키 생성
API 키는 W&B에서 사용자의 컴퓨터를 인증하는 데 사용됩니다. API 키는 사용자 프로필에서 생성할 수 있습니다.더 간단한 방법으로 User Settings로 이동해 API 키를 생성하세요. API 키를 즉시 복사한 후 비밀번호 관리자와 같은 안전한 위치에 저장하세요.
- 오른쪽 상단의 사용자 프로필 아이콘을 클릭하세요.
- User Settings를 선택한 다음 API Keys 섹션까지 스크롤하세요.
wandb 라이브러리 설치 및 로그인
wandb 라이브러리를 로컬에 설치하고 로그인하려면:
- Command Line
- Python
- Python notebook
-
WANDB_API_KEY환경 변수를 API 키로 설정하세요.<>로 묶인 값을 본인의 값으로 교체하세요: -
wandb라이브러리를 설치하고 로그인하세요.
프로젝트 이름 지정
W&B 프로젝트는 관련 run에서 로깅한 모든 차트, 데이터 및 모델을 저장합니다. 프로젝트 이름을 지정하면 작업을 정리하는 데 도움이 되며 단일 프로젝트에 대한 모든 정보를 한 곳에 보관할 수 있습니다. 프로젝트에 run을 추가하려면WANDB_PROJECT 환경 변수를 프로젝트 이름으로 설정하세요. WandbCallback는 이 프로젝트 이름 환경 변수를 인식하여 run을 설정할 때 사용합니다.
- Command Line
- Python
- Python notebook
Trainer를 초기화하기 전에 프로젝트 이름을 설정해야 합니다.huggingface로 설정됩니다.
트레이닝 run을 W&B에 로깅하기
코드 또는 명령줄에서Trainer 트레이닝 인수를 정의할 때 report_to를 "wandb"로 설정하여 W&B 로깅을 활성화하세요. 이 설정이 없으면 Trainer는 W&B에 데이터를 보내지 않습니다.
TrainingArguments의 logging_steps 인수는 트레이닝 중 트레이닝 메트릭을 W&B에 전송하는 빈도를 제어합니다. run_name 인수를 사용하여 W&B의 트레이닝 run에 이름을 지정할 수도 있습니다.
이것으로 설정이 완료되었습니다. 이제 모델은 트레이닝 중에 손실, 평가 메트릭, 모델 토폴로지 및 그라디언트를 W&B에 로깅합니다.
- 명령줄
- Python
TensorFlow를 사용하시나요? PyTorch
Trainer를 TensorFlow TFTrainer로 교체하세요.모델 체크포인트 저장 활성화
메트릭 로깅 외에도 트레이닝된 모델 가중치 자체를 W&B에 저장하여 버전을 관리하고, 다운로드하고, 팀 내에서 공유할 수 있습니다. 아티팩트를 사용하면 최대 100 GB의 모델과 데이터셋을 무료로 저장한 후 W&B 레지스트리를 사용할 수 있습니다. 레지스트리에 모델을 등록하면 모델을 탐색하고 평가하며, 스테이징을 준비하거나 프로덕션 환경에 배포할 수 있습니다. Hugging Face 모델 체크포인트를 아티팩트에 로깅하려면WANDB_LOG_MODEL 환경 변수를 다음 중 _하나_로 설정하세요:
checkpoint:TrainingArguments의args.save_steps마다 체크포인트를 업로드합니다.end:load_best_model_at_end도 설정되어 있으면 트레이닝이 끝날 때 모델을 업로드합니다.false: 모델을 업로드하지 않습니다.
- 명령줄
- Python
- Python 노트북
Trainer는 W&B 프로젝트에 모델을 업로드합니다. 로깅한 모델 체크포인트는 아티팩트 UI에서 확인할 수 있으며, 전체 모델 리니지를 포함합니다. 아티팩트 UI의 모델 체크포인트 예시를 확인하세요.
기본적으로 모델은
WANDB_LOG_MODEL이 end로 설정된 경우 model-{run_id}로, WANDB_LOG_MODEL이 checkpoint로 설정된 경우 checkpoint-{run_id}로 W&B 아티팩트에 저장됩니다.
하지만 TrainingArguments에 run_name을 전달하면 모델은 model-{run_name} 또는 checkpoint-{run_name}으로 저장됩니다.Registry
체크포인트를 아티팩트에 로깅한 후, 최고 성능 모델 체크포인트를 등록하고 레지스트리를 통해 팀 전체에서 중앙 관리할 수 있습니다. 레지스트리를 사용하면 최고 성능 모델을 작업별로 구성하고, 모델의 라이프사이클을 관리하고, 전체 ML 라이프사이클을 추적하고 감사하며, 후속 액션을 자동화할 수 있습니다. 모델 아티팩트를 연결하려면 레지스트리를 참고하세요.트레이닝 중 평가 출력 시각화
트레이닝 또는 평가 중 모델 출력 시각화는 모델이 어떻게 트레이닝되는지 이해하는 데 종종 필수적입니다. 손실 곡선과 함께 구체적인 예측을 검사하면 집계된 메트릭이 숨길 수 있는 품질 문제를 발견하는 데 도움이 됩니다. Transformers Trainer의 callback 시스템을 사용하면 W&B Tables에 더 유용한 데이터를 로깅할 수 있습니다. 여기에는 모델의 텍스트 생성 출력 또는 기타 예측이 포함됩니다. 다음 예시와 같은 W&B Table에 트레이닝 중 평가 출력을 로깅하는 방법에 대한 전체 가이드는 트레이닝 중 평가 샘플 로깅 및 확인를 참조하세요.
W&B run 종료하기 (노트북만 해당)
트레이닝이 Python 스크립트 안에서 수행되는 경우, 스크립트가 완료되면 W&B run이 종료됩니다. Jupyter 또는 Google Colab 노트북을 사용하는 경우,run.finish()를 호출하여 트레이닝이 완료되었음을 알리세요.
결과 시각화하기
트레이닝 결과를 로깅한 후에는 W&B 대시보드에서 결과를 살펴볼 수 있습니다. run을 비교하고, 발견 사항을 자세히 들여다보고, 대화형 시각화로 데이터를 탐색해 보세요. 이제 인테그레이션이 완성되었습니다.Trainer는 지정한 프로젝트에 메트릭을 로깅하고, 필요에 따라 체크포인트를 아티팩트에 저장하며, 평가 출력을 W&B 대시보드에 표시합니다.
고급 기능 및 자주 묻는 질문
다음 섹션에서는 최고 성능 모델 저장, 체크포인트에서 트레이닝 재개, 로깅 callback 맞춤 설정, 환경 변수를 통한 W&B 동작 설정 등 일반적인 후속 작업을 다룹니다.최고 성능 모델 저장
TrainingArguments에 load_best_model_at_end=True를 설정하여 Trainer에 전달하면, W&B는 최고 성능 모델 체크포인트를 아티팩트에 저장합니다.
모델 체크포인트를 아티팩트로 저장하면 레지스트리로 승격할 수 있습니다. 레지스트리에서 다음을 수행할 수 있습니다:
- ML 작업별로 최고 성능 모델 버전을 정리합니다.
- 모델을 중앙 집중화하고 팀과 공유합니다.
- 프로덕션용으로 모델을 스테이징하거나 추가 평가를 위해 북마크합니다.
- 다운스트림 CI/CD 프로세스를 트리거합니다.
저장된 모델 불러오기
WANDB_LOG_MODEL을 사용해 모델을 W&B 아티팩트에 저장했다면, 추가 트레이닝이나 추론 실행을 위해 모델 가중치를 다운로드할 수 있습니다. 이전에 사용한 것과 동일한 Hugging Face 아키텍처에 가중치를 다시 불러오세요.
체크포인트에서 트레이닝 재개
WANDB_LOG_MODEL='checkpoint'를 설정하면 TrainingArguments의 model_name_or_path 인수로 model_dir을 사용하고 Trainer에 resume_from_checkpoint=True를 전달하여 트레이닝을 재개할 수 있습니다.
트레이닝 중 평가 샘플 로깅 및 확인
Transformers 라이브러리의WandbCallback은 Transformers Trainer를 통해 W&B에 로깅하는 작업을 처리합니다. 이 callback을 사용자 지정하여 모델 예측, 혼동 행렬 또는 기타 맞춤형 데이터를 로깅할 수 있습니다. 이를 위해 WandbCallback을 상속하는 하위 클래스를 만들고 Trainer 클래스의 추가 방법을 사용하는 기능을 추가하세요.
다음은 이 새로운 callback을 Hugging Face Trainer에 추가하는 일반적인 패턴과, 평가 출력을 W&B Table에 로깅하는 전체 코드 예시입니다.
트레이닝 중 평가 샘플 확인
다음 섹션에서는WandbCallback을 사용자 지정하여 트레이닝 중 모델 예측을 실행하고 평가 샘플을 W&B Table에 로깅하는 방법을 설명합니다. 이 작업은 Trainer callback의 on_evaluate 방법을 사용하여 eval_steps마다 실행됩니다.
decode_predictions 함수는 토크나이저를 사용하여 모델 출력의 예측과 레이블을 디코딩합니다.
그런 다음 코드는 예측과 레이블로 pandas 데이터프레임을 만들고 데이터프레임에 epoch 열을 추가합니다.
마지막으로 코드는 데이터프레임으로 wandb.Table을 만들고 W&B에 로깅합니다. freq 에포크마다 예측을 로깅하여 로깅 빈도를 제어할 수 있습니다.
일반
WandbCallback과 달리 이 맞춤형 callback은 Trainer 초기화 중이 아니라 Trainer가 인스턴스화된 후에 trainer에 추가해야 합니다. 초기화 중에 Trainer 인스턴스가 callback에 전달되기 때문입니다.추가 W&B 설정
Trainer로 로깅되는 내용을 환경 변수를 설정하여 추가로 구성할 수 있습니다. W&B 환경 변수의 전체 목록은 환경 변수 레퍼런스를 참조하세요.
- Command Line
- Notebook
wandb.init() 사용자 지정
Trainer가 사용하는 WandbCallback은 Trainer가 초기화될 때 wandb.init()을 내부적으로 호출합니다. 또는 Trainer가 초기화되기 전에 wandb.init()을 호출하여 run을 수동으로 설정할 수 있습니다. 이를 통해 W&B run 설정을 완전히 제어할 수 있습니다.
다음은 init에 전달할 수 있는 예시입니다. wandb.init()에 대한 자세한 내용은 wandb.init() 레퍼런스를 참조하세요.