Hugging Face Transformers 라이브러리를 사용하면 BERT와 같은 최첨단 NLP 모델은 물론, 혼합 정밀도와 그라디언트 checkpointing 같은 트레이닝 기법도 쉽게 활용할 수 있습니다. W&B 인테그레이션은 이러한 사용 편의성을 유지하면서, 대화형 중앙 집중식 대시보드에 풍부하고 유연한 실험 추적과 모델 버전 관리 기능을 추가합니다.
os.environ["WANDB_PROJECT"] = "<my-amazing-project>" # W&B 프로젝트 이름 지정
os.environ["WANDB_LOG_MODEL"] = "checkpoint" # 모든 모델 체크포인트 로그
from transformers import TrainingArguments, Trainer
args = TrainingArguments(..., report_to="wandb") # W&B 로깅 활성화
trainer = Trainer(..., args=args)
API 키를 사용하면 머신을 W&B에 인증할 수 있습니다. 사용자 프로필에서 API 키를 생성할 수 있습니다.
더 간편하게 하려면 User Settings로 바로 이동해 API 키를 생성하세요. 새로 생성한 API 키는 즉시 복사해 비밀번호 관리자와 같은 안전한 위치에 저장하세요.
- 오른쪽 상단의 사용자 프로필 아이콘을 클릭합니다.
- User Settings를 선택한 다음 API Keys 섹션이 나올 때까지 아래로 스크롤합니다.
로컬에 wandb 라이브러리를 설치하고 로그인하려면 다음 단계를 따르세요.
명령줄
Python
Python notebook
-
WANDB_API_KEY 환경 변수를 API 키로 설정합니다.
export WANDB_API_KEY=<your_api_key>
-
wandb 라이브러리를 설치하고 로그인합니다.
pip install wandb
wandb login
import wandb
wandb.login()
!pip install wandb
import wandb
wandb.login()
W&B를 처음 사용하는 경우 퀵스타트를 확인해 보세요.
W&B 프로젝트는 관련 run에서 로깅된 모든 차트, 데이터, 모델이 저장되는 곳입니다. 프로젝트에 이름을 지정하면 작업을 더 체계적으로 정리하고, 하나의 프로젝트에 관한 모든 정보를 한곳에서 관리할 수 있습니다.
프로젝트에 run을 추가하려면 WANDB_PROJECT 환경 변수를 프로젝트 이름으로 설정하면 됩니다. WandbCallback은 이 프로젝트 이름 환경 변수를 읽어 run을 설정할 때 사용합니다.
명령줄
Python
Python notebook
WANDB_PROJECT=amazon_sentiment_analysis
import os
os.environ["WANDB_PROJECT"]="amazon_sentiment_analysis"
%env WANDB_PROJECT=amazon_sentiment_analysis
Trainer를 초기화하기 전에 프로젝트 이름을 설정해야 합니다.
프로젝트 이름을 지정하지 않으면 기본값은 huggingface입니다.
코드에서든 명령줄에서든 Trainer의 트레이닝 인수를 정의할 때 가장 중요한 단계는 W&B 로깅을 활성화할 수 있도록 report_to를 "wandb"로 설정하는 것입니다.
TrainingArguments의 logging_steps 인수는 트레이닝 중 트레이닝 메트릭이 W&B에 얼마나 자주 전송되는지를 제어합니다. run_name 인수를 사용해 W&B에서 트레이닝 run의 이름을 지정할 수도 있습니다.
이제 끝입니다. 이제 모델이 트레이닝되는 동안 loss, 평가 메트릭, 모델 토폴로지, 그라디언트를 W&B에 로깅합니다.
python run_glue.py \ # Python 스크립트 실행
--report_to wandb \ # W&B 로깅 활성화
--run_name bert-base-high-lr \ # W&B run 이름(선택)
# 여기에 다른 명령줄 인수
from transformers import TrainingArguments, Trainer
args = TrainingArguments( # 여기에 다른 인수와 kwargs
report_to="wandb", # W&B 로깅 활성화
run_name="bert-base-high-lr", # W&B run 이름(선택)
logging_steps=1, # W&B에 얼마나 자주 로깅할지
)
trainer = Trainer( # 여기에 다른 인수와 kwargs
args=args, # 트레이닝 인수
)
trainer.train() # 트레이닝과 W&B 로깅 시작
TensorFlow를 사용하시나요? PyTorch Trainer를 TensorFlow TFTrainer로 바꾸기만 하면 됩니다.
Artifacts를 사용하면 모델과 데이터셋을 최대 100GB까지 무료로 저장한 다음 W&B 레지스트리를 사용할 수 있습니다. 레지스트리를 사용하면 모델을 등록해 탐색하고 평가할 수 있으며, 스테이징을 준비하거나 프로덕션 환경에 배포할 수도 있습니다.
Hugging Face 모델 체크포인트를 Artifacts에 로그하려면 WANDB_LOG_MODEL 환경 변수를 다음 값 중 하나 로 설정하세요.
checkpoint: TrainingArguments의 args.save_steps마다 체크포인트를 업로드합니다.
end: load_best_model_at_end도 설정된 경우 트레이닝이 끝날 때 모델을 업로드합니다.
false: 모델을 업로드하지 않습니다.
WANDB_LOG_MODEL="checkpoint"
import os
os.environ["WANDB_LOG_MODEL"] = "checkpoint"
%env WANDB_LOG_MODEL="checkpoint"
이제부터 초기화하는 모든 Transformers Trainer는 모델을 W&B 프로젝트에 업로드합니다. 로그한 모델 체크포인트는 Artifacts UI에서 확인할 수 있으며, 전체 모델 리니지도 포함됩니다(UI에서 모델 체크포인트 예시는 여기에서 확인할 수 있습니다).
기본적으로 WANDB_LOG_MODEL이 end로 설정되면 모델은 W&B Artifacts에 model-{run_id}로 저장되고, WANDB_LOG_MODEL이 checkpoint로 설정되면 checkpoint-{run_id}로 저장됩니다.
하지만 TrainingArguments에 run_name을 전달하면 모델은 model-{run_name} 또는 checkpoint-{run_name}로 저장됩니다.
체크포인트를 Artifacts에 로깅한 후에는 레지스트리를 사용해 최고 성능의 모델 체크포인트를 등록하고 팀 전체에서 중앙 관리할 수 있습니다. 레지스트리를 사용하면 작업별로 최고 성능의 모델을 구성하고, 모델 수명 주기를 관리하며, 전체 ML 수명 주기를 추적하고 감사하고, 후속 작업을 자동화할 수 있습니다.
모델 Artifact를 연결하려면 레지스트리를 참고하세요.
트레이닝이나 평가 중에 모델 출력을 시각화하면 모델이 어떻게 트레이닝되고 있는지 제대로 이해하는 데 큰 도움이 되는 경우가 많습니다.
Transformers Trainer의 콜백 시스템을 사용하면 모델의 텍스트 생성 출력이나 기타 예측 같은 유용한 추가 데이터를 W&B Tables에 로깅할 수 있습니다.
트레이닝 중 평가 출력을 로깅해 아래와 같은 W&B Table에 기록하는 방법에 대한 전체 가이드는 아래의 맞춤형 로깅 섹션을 참조하세요:
트레이닝이 Python 스크립트 안에서 실행된다면, 스크립트가 끝날 때 W&B run도 함께 종료됩니다.
Jupyter 또는 Google Colab 노트북을 사용하는 경우에는 run.finish()를 호출해 트레이닝이 끝났음을 알려야 합니다.
run = wandb.init()
trainer.train() # W&B에 트레이닝 및 로깅 시작
# 사후학습(Post-training) 분석, 테스트, 기타 로깅 코드
run.finish()
트레이닝 결과를 로깅한 후에는 W&B 대시보드에서 결과를 동적으로 탐색할 수 있습니다. 수십 개의 run을 한 번에 쉽게 비교하고, 흥미로운 결과를 확대해 자세히 살펴보며, 유연한 대화형 시각화를 통해 복잡한 데이터에서 인사이트를 끌어낼 수 있습니다.
Trainer에 load_best_model_at_end=True가 포함된 TrainingArguments를 전달하면, W&B가 성능이 가장 좋은 모델 checkpoint를 Artifacts에 저장합니다.
모델 checkpoint를 Artifacts로 저장하면 레지스트리로 승격할 수 있습니다. 레지스트리에서는 다음과 같은 작업을 할 수 있습니다:
- ML 작업별로 가장 성능이 좋은 모델 버전을 구성합니다.
- 모델을 중앙에서 관리하고 팀과 공유합니다.
- 모델을 프로덕션에 맞게 스테이징하거나 추가 평가을 위해 북마크합니다.
- 다운스트림 CI/CD 프로세스를 트리거합니다.
WANDB_LOG_MODEL을 사용해 모델을 W&B Artifacts에 저장했다면, 추가 트레이닝을 하거나 Inference를 실행하기 위해 모델 가중치를 다운로드할 수 있습니다. 그런 다음 이전에 사용한 것과 동일한 Hugging Face 아키텍처에 다시 로드하면 됩니다.
# 새 run 생성
with wandb.init(project="amazon_sentiment_analysis") as run:
# 아티팩트의 이름과 버전 전달
my_model_name = "model-bert-base-high-lr:latest"
my_model_artifact = run.use_artifact(my_model_name)
# 모델 가중치를 폴더에 다운로드하고 경로 반환
model_dir = my_model_artifact.download()
# 동일한 모델 클래스를 사용하여
# 해당 폴더에서 Hugging Face 모델 로드
model = AutoModelForSequenceClassification.from_pretrained(
model_dir, num_labels=num_labels
)
# 추가 트레이닝 수행 또는 Inference 실행
체크포인트에서 트레이닝을 재개하려면 어떻게 하나요?
WANDB_LOG_MODEL='checkpoint'를 설정한 경우, TrainingArguments에서 model_dir를 model_name_or_path 인수로 사용하고 Trainer에 resume_from_checkpoint=True를 전달해 트레이닝을 재개할 수도 있습니다.
last_run_id = "xxxxxxxx" # wandb workspace에서 run_id를 가져옵니다
# run_id로 wandb run을 재개합니다
with wandb.init(
project=os.environ["WANDB_PROJECT"],
id=last_run_id,
resume="must",
) as run:
# run에 아티팩트를 연결합니다
my_checkpoint_name = f"checkpoint-{last_run_id}:latest"
my_checkpoint_artifact = run.use_artifact(my_model_name)
# 체크포인트를 폴더에 다운로드하고 경로를 반환합니다
checkpoint_dir = my_checkpoint_artifact.download()
# 모델과 trainer를 다시 초기화합니다
model = AutoModelForSequenceClassification.from_pretrained(
"<model_name>", num_labels=num_labels
)
# 트레이닝 인수를 여기에 입력하세요.
training_args = TrainingArguments()
trainer = Trainer(model=model, args=training_args)
# 체크포인트에서 트레이닝을 재개하려면 반드시 체크포인트 디렉토리를 사용하세요
trainer.train(resume_from_checkpoint=checkpoint_dir)
트레이닝 중 평가 샘플을 로깅하고 확인하려면 어떻게 해야 하나요
Transformers Trainer를 통해 W&B에 로깅하는 작업은 Transformers 라이브러리의 WandbCallback에서 처리합니다. Hugging Face 로깅을 사용자 지정해야 하는 경우, WandbCallback을 서브클래싱하고 Trainer 클래스의 추가 기능을 활용하는 기능을 덧붙여 이 콜백을 수정할 수 있습니다.
아래에는 이 새 콜백을 HF Trainer에 추가하는 일반적인 패턴이 나와 있으며, 더 아래에는 평가 출력을 W&B Table에 로깅하는 전체 코드 예제가 나와 있습니다:
# 평소와 같이 Trainer를 인스턴스화합니다
trainer = Trainer()
# 새 로깅 콜백을 인스턴스화하고 Trainer 객체를 전달합니다
evals_callback = WandbEvalsCallback(trainer, tokenizer, ...)
# Trainer에 콜백을 추가합니다
trainer.add_callback(evals_callback)
# 평소와 같이 Trainer 트레이닝을 시작합니다
trainer.train()
다음 섹션에서는 트레이닝 중에 모델 예측을 실행하고 평가 샘플을 W&B Table에 로깅하도록 WandbCallback을 사용자 지정하는 방법을 보여줍니다. eval_steps마다 Trainer 콜백의 on_evaluate 방법을 사용합니다.
여기서는 tokenizer를 사용해 모델 출력의 예측과 레이블을 디코딩하는 decode_predictions 함수를 작성합니다.
그런 다음 예측과 레이블로 pandas 데이터프레임을 만들고, 데이터프레임에 epoch column을 추가합니다.
마지막으로 데이터프레임으로 wandb.Table을 생성하고 이를 wandb에 로깅합니다.
또한 freq 에포크마다 예측을 로깅하여 로깅 빈도를 제어할 수 있습니다.
참고: 일반 WandbCallback과 달리, 이 맞춤형 콜백은 Trainer 초기화 중이 아니라 Trainer가 인스턴스화된 후에 trainer에 추가해야 합니다.
이는 초기화 시 Trainer 인스턴스가 콜백에 전달되기 때문입니다.
from transformers.integrations import WandbCallback
import pandas as pd
def decode_predictions(tokenizer, predictions):
labels = tokenizer.batch_decode(predictions.label_ids)
logits = predictions.predictions.argmax(axis=-1)
prediction_text = tokenizer.batch_decode(logits)
return {"labels": labels, "predictions": prediction_text}
class WandbPredictionProgressCallback(WandbCallback):
"""트레이닝 중 모델 예측을 로깅하는 맞춤형 WandbCallback.
이 콜백은 트레이닝 중 각 로깅 단계에서 모델 예측과 레이블을 wandb.Table에 로깅합니다.
트레이닝이 진행됨에 따라 모델 예측을 시각화할 수 있습니다.
Attributes:
trainer (Trainer): Hugging Face Trainer 인스턴스.
tokenizer (AutoTokenizer): 모델과 연결된 tokenizer.
sample_dataset (Dataset): 예측 생성을 위한 검증 데이터셋의 서브셋.
num_samples (int, optional): 예측 생성을 위해 검증 데이터셋에서 선택할 샘플 수. 기본값은 100.
freq (int, optional): 로깅 빈도. 기본값은 2.
"""
def __init__(self, trainer, tokenizer, val_dataset, num_samples=100, freq=2):
"""WandbPredictionProgressCallback 인스턴스를 초기화합니다.
Args:
trainer (Trainer): Hugging Face Trainer 인스턴스.
tokenizer (AutoTokenizer): 모델과 연결된 tokenizer.
val_dataset (Dataset): 검증 데이터셋.
num_samples (int, optional): 예측 생성을 위해 검증 데이터셋에서 선택할 샘플 수.
기본값은 100.
freq (int, optional): 로깅 빈도. 기본값은 2.
"""
super().__init__()
self.trainer = trainer
self.tokenizer = tokenizer
self.sample_dataset = val_dataset.select(range(num_samples))
self.freq = freq
def on_evaluate(self, args, state, control, **kwargs):
super().on_evaluate(args, state, control, **kwargs)
# `freq` 에포크마다 예측을 로깅하여 로깅 빈도를 제어합니다
if state.epoch % self.freq == 0:
# 예측 생성
predictions = self.trainer.predict(self.sample_dataset)
# 예측과 레이블 디코딩
predictions = decode_predictions(self.tokenizer, predictions)
# wandb.Table에 예측 추가
predictions_df = pd.DataFrame(predictions)
predictions_df["epoch"] = state.epoch
records_table = self._wandb.Table(dataframe=predictions_df)
# wandb에 테이블 로깅
self._wandb.log({"sample_predictions": records_table})
# 먼저 Trainer를 인스턴스화합니다
trainer = Trainer(
model=model,
args=training_args,
train_dataset=lm_datasets["train"],
eval_dataset=lm_datasets["validation"],
)
# WandbPredictionProgressCallback을 인스턴스화합니다
progress_callback = WandbPredictionProgressCallback(
trainer=trainer,
tokenizer=tokenizer,
val_dataset=lm_dataset["validation"],
num_samples=10,
freq=2,
)
# trainer에 콜백을 추가합니다
trainer.add_callback(progress_callback)
더 자세한 예시는 이 colab을 참고하세요.
추가로 사용할 수 있는 W&B 설정은 무엇인가요?
환경 변수를 설정하면 Trainer에서 무엇을 로깅할지 더 세부적으로 설정할 수 있습니다. W&B 환경 변수의 전체 목록은 여기에서 확인할 수 있습니다.
| 환경 변수 | 사용 |
|---|
WANDB_PROJECT | 프로젝트 이름을 지정합니다(기본값: huggingface) |
WANDB_LOG_MODEL | 모델 체크포인트를 W&B Artifact로 로깅합니다(기본값: false) false (기본값): 모델 체크포인트를 저장하지 않음checkpoint: 체크포인트를 args.save_steps마다 업로드합니다(Trainer의 TrainingArguments에서 설정).end: 트레이닝이 끝날 때 최종 모델 체크포인트를 업로드합니다.
|
WANDB_WATCH | 모델의 그라디언트, 파라미터를 로깅할지, 또는 둘 다 로깅하지 않을지 설정합니다 false (기본값): 그라디언트 또는 파라미터를 로깅하지 않음gradients: 그라디언트의 히스토그램을 로깅합니다all: 그라디언트와 파라미터의 히스토그램을 로깅합니다
|
WANDB_DISABLED | 로깅을 완전히 끄려면 true로 설정합니다(기본값: false) |
WANDB_QUIET. | 표준 출력에 로깅되는 메시지를 중요 메시지만 남기려면 true로 설정합니다(기본값: false) |
WANDB_SILENT | wandb가 출력하는 내용을 숨기려면 true로 설정합니다(기본값: false) |
WANDB_WATCH=all
WANDB_SILENT=true
%env WANDB_WATCH=all
%env WANDB_SILENT=true
wandb.init()를 어떻게 사용자 지정하나요?
Trainer가 사용하는 WandbCallback은 Trainer가 초기화되면 내부적으로 wandb.init()를 호출합니다. 또는 Trainer를 초기화하기 전에 wandb.init()를 호출해 run을 수동으로 설정할 수도 있습니다. 이렇게 하면 W&B run 설정을 완전히 제어할 수 있습니다.
init에 전달할 수 있는 항목의 예시는 아래와 같습니다. wandb.init()의 자세한 내용은 wandb.init() 레퍼런스를 참조하세요.
wandb.init(
project="amazon_sentiment_analysis",
name="bert-base-high-lr",
tags=["baseline", "high-lr"],
group="bert",
)
아래는 흥미롭게 읽어볼 만한 Transformers 및 W&B 관련 글 6편입니다
Hugging Face W&B 인테그레이션과 관련해 문제나 질문이 있거나 기능을 요청하려면 Hugging Face 포럼의 이 스레드에 글을 올리거나 Hugging Face Transformers GitHub repo에서 이슈를 열어 주세요.