Hugging Face Transformers

Colab에서 실행해 보기

Hugging Face Transformers 라이브러리는 BERT와 같은 최신 NLP 모델과 mixed precision, gradient 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)

바로 실행해볼 수 있는 코드부터 살펴보고 싶다면 이 Google Colab 노트북을 확인하세요.

​

시작하기: 실험 추적하기

​

회원 가입 및 API key 생성

API key는 사용 중인 머신을 W&B에 인증하는 데 사용됩니다. 사용자 프로필에서 API key를 생성할 수 있습니다.

보다 간편하게 설정하려면 User Settings로 바로 이동해 API key를 생성하세요. 새로 생성된 API key는 즉시 복사하여 비밀번호 관리자와 같은 안전한 위치에 저장하세요.

1. 오른쪽 상단에 있는 사용자 프로필 아이콘을 클릭합니다.
2. User Settings를 선택한 다음, 아래로 스크롤하여 API Keys 섹션을 찾습니다.

​

wandb 라이브러리를 설치하고 로그인하기

로컬에서 wandb 라이브러리를 설치하고 로그인하려면 다음 단계를 따르세요.

명령줄

1. WANDB_API_KEY 환경 변수에 본인의 API key를 설정합니다.

   export WANDB_API_KEY=<your_api_key>
   

2. wandb 라이브러리를 설치하고 로그인합니다.

   pip install wandb
   
   wandb login
   

Python

pip install wandb

import wandb
wandb.login()

Python 노트북

!pip install wandb

import wandb
wandb.login()

W&B를 처음 사용하는 경우 빠른 시작을 확인해 보세요.

​

프로젝트 이름 지정

W&B 프로젝트는 관련 실행에서 로깅된 모든 차트, 데이터, 모델이 저장되는 곳입니다. 프로젝트에 이름을 지정하면 작업을 체계적으로 정리하고, 단일 프로젝트에 대한 모든 정보를 한곳에 모을 수 있습니다.

실행을 특정 프로젝트에 추가하려면 WANDB_PROJECT 환경 변수를 프로젝트 이름으로 설정하면 됩니다. WandbCallback은 이 프로젝트 이름 환경 변수를 감지하고, 실행을 설정할 때 해당 이름을 사용합니다.

명령줄

WANDB_PROJECT=amazon_sentiment_analysis

Python

import os
os.environ["WANDB_PROJECT"]="amazon_sentiment_analysis"

Python 노트북

%env WANDB_PROJECT=amazon_sentiment_analysis

Trainer를 초기화하기 전에 반드시 프로젝트 이름을 설정해야 합니다.

프로젝트 이름을 지정하지 않으면 프로젝트 이름은 기본값으로 huggingface가 사용됩니다.

​

학습 실행을 W&B에 로깅하기

코드 내부에서든 커맨드 라인에서든 Trainer의 학습 인자를 정의할 때 가장 중요한 단계는 W&B로 로깅을 활성화하기 위해 report_to를 "wandb"로 설정하는 것입니다.

TrainingArguments의 logging_steps 인자는 학습 중에 학습 지표를 W&B로 얼마나 자주 전송할지 제어합니다. 또한 run_name 인자를 사용해 W&B에서 학습 실행에 이름을 지정할 수 있습니다.

이것으로 설정은 완료되었습니다. 이제 모델은 학습하는 동안 손실, 평가 지표, 모델 토폴로지, 그래디언트를 W&B에 로깅합니다.

명령줄

python run_glue.py \     # Python 스크립트를 실행합니다
  --report_to wandb \    # W&B로 로깅을 활성화합니다
  --run_name bert-base-high-lr \   # W&B 실행 이름 (선택 사항)
  # 여기에 다른 명령줄 인자를 추가합니다

Python

from transformers import TrainingArguments, Trainer

args = TrainingArguments(
    # 여기에 다른 args 및 kwargs를 추가합니다
    report_to="wandb",  # W&B로 로깅을 활성화합니다
    run_name="bert-base-high-lr",  # W&B 실행 이름 (선택 사항)
    logging_steps=1,  # W&B에 얼마나 자주 로깅할지 설정합니다
)

trainer = Trainer(
    # 여기에 다른 args 및 kwargs를 추가합니다
    args=args,  # 학습 인자
)

trainer.train()  # 학습을 시작하고 W&B에 로깅합니다

TensorFlow를 사용하나요? PyTorch Trainer를 TensorFlow TFTrainer로 바꾸기만 하면 됩니다.

​

모델 체크포인트 저장 활성화하기

아티팩트를 사용하면 최대 100GB까지 모델과 데이터셋을 무료로 저장할 수 있고, 이어서 W&B Registry를 활용할 수 있습니다. Registry를 사용하면 모델을 등록해 탐색 및 평가하고, 스테이징 환경에 준비하거나 프로덕션 환경에 배포할 수 있습니다.

Hugging Face 모델 체크포인트를 아티팩트에 로깅하려면 WANDB_LOG_MODEL 환경 변수를 다음 값 중 하나로 설정합니다:

• checkpoint: TrainingArguments의 args.save_steps마다 체크포인트를 업로드합니다.
• end: load_best_model_at_end도 설정되어 있는 경우, 학습이 끝났을 때 모델을 업로드합니다.
• false: 모델을 업로드하지 않습니다.

Command Line

WANDB_LOG_MODEL="checkpoint"

Python

import os

os.environ["WANDB_LOG_MODEL"] = "checkpoint"

Python notebook

%env WANDB_LOG_MODEL="checkpoint"

지금부터 초기화하는 모든 Transformers Trainer는 모델을 해당 W&B 프로젝트에 업로드합니다. 로깅한 모델 체크포인트는 아티팩트 UI에서 확인할 수 있으며, 전체 모델 계보(lineage)를 포함합니다(UI에서 예시 모델 체크포인트를 보려면 여기를 참조하세요).

기본적으로, WANDB_LOG_MODEL이 end로 설정된 경우 모델은 model-{run_id}로, checkpoint로 설정된 경우 checkpoint-{run_id}로 W&B 아티팩트에 저장됩니다. 그러나 TrainingArguments에 run_name을 전달하면, 모델은 model-{run_name} 또는 checkpoint-{run_name}으로 저장됩니다.

​

W&B Registry

체크포인트를 아티팩트로 로깅한 후에는 Registry를 사용하여 최적의 모델 체크포인트를 등록하고 팀 전체가 중앙에서 관리할 수 있습니다. Registry를 사용하면 작업별로 최적의 모델을 구성하고, 모델 라이프사이클을 관리하며, 전체 ML 라이프사이클을 추적 및 감사하고, 다운스트림 작업을 자동화할 수 있습니다.

모델 아티팩트를 연결하려면 Registry를 참조하십시오.

​

학습 중 평가 결과 시각화하기

모델을 학습하거나 평가하는 동안 출력 결과를 시각화하는 것은 모델이 어떻게 학습되고 있는지 정확히 이해하는 데 필수적인 경우가 많습니다.

Transformers Trainer의 콜백 시스템을 사용하면, 모델의 텍스트 생성 결과나 기타 예측값 등과 같은 추가적인 유용한 데이터를 W&B Tables에 로깅할 수 있습니다.

아래의 Custom logging 섹션을 참고하여, 학습 중 평가 출력을 아래와 같은 W&B Table에 로깅하는 전체 과정을 확인하세요:

​

W&B 실행 종료하기 (노트북 전용)

학습이 하나의 Python 스크립트로 작성되어 있다면, 스크립트가 종료될 때 W&B 실행도 함께 종료됩니다.

Jupyter 또는 Google Colab 노트북을 사용하는 경우에는 run.finish()를 호출해서 학습이 끝났음을 W&B에 알려야 합니다.

run = wandb.init()
trainer.train()  # 학습 시작 및 W&B에 로깅

# 학습 후 분석, 테스트, 기타 로깅 코드

run.finish()

​

결과 시각화하기

학습 결과를 로그로 남겼다면 W&B Dashboard에서 결과를 동적으로 탐색할 수 있습니다. 수십 개의 실행을 한 번에 쉽게 비교하고, 흥미로운 결과를 확대해 살펴보며, 유연하고 대화형 시각화를 통해 복잡한 데이터에서 인사이트를 찾아낼 수 있습니다.

​

고급 기능 및 자주 묻는 질문

​

최고 성능의 모델을 저장하려면 어떻게 하나요?

Trainer에 load_best_model_at_end=True로 설정된 TrainingArguments를 전달하면, W&B에서 가장 성능이 좋은 모델 체크포인트를 아티팩트로 저장합니다.

모델 체크포인트를 아티팩트로 저장하면, 이를 Registry로 승격할 수 있습니다. Registry에서는 다음을 수행할 수 있습니다:

• ML 태스크별로 최고 성능의 모델 버전을 체계적으로 정리할 수 있습니다.
• 모델을 중앙에서 관리하고 팀과 공유할 수 있습니다.
• 모델을 프로덕션 배포용으로 스테이징하거나 추가 평가를 위해 북마크할 수 있습니다.
• 후속 CI/CD 프로세스를 트리거할 수 있습니다.

​

저장된 모델은 어떻게 불러오나요?

WANDB_LOG_MODEL을 사용해 모델을 W&B 아티팩트에 저장했다면, 추가 학습이나 추론 실행을 위해 모델 가중치를 다운로드할 수 있습니다. 이전에 사용했던 것과 동일한 Hugging Face 모델 아키텍처에 이 가중치를 다시 로드하면 됩니다.

# 새 실행 생성
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
    )

    # 추가 학습 수행 또는 추론 실행

​

체크포인트에서 학습을 다시 시작하려면 어떻게 하나요?

WANDB_LOG_MODEL='checkpoint'를 설정해 두었다면, TrainingArguments에서 model_name_or_path 인자로 model_dir를 사용하고, Trainer에 resume_from_checkpoint=True를 전달하여 학습을 재개할 수 있습니다.

last_run_id = "xxxxxxxx"  # wandb 워크스페이스에서 run_id를 가져옵니다

# run_id로 wandb 실행을 재개합니다
with wandb.init(
    project=os.environ["WANDB_PROJECT"],
    id=last_run_id,
    resume="must",
) as 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()

    # 모델과 트레이너를 다시 초기화합니다
    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을 상속(subclassing)하여 Trainer 클래스의 추가 메서드를 활용하는 기능을 더해 이 콜백을 수정할 수 있습니다.

아래는 이 새로운 콜백을 Hugging Face Trainer에 추가하는 일반적인 패턴이며, 그 아래에는 평가 결과를 W&B Table에 로깅하는 완전한 코드 예제가 있습니다.

# 평소와 같이 Trainer를 인스턴스화합니다
trainer = Trainer()

# 새 로깅 콜백을 인스턴스화하고 Trainer 객체를 전달합니다
evals_callback = WandbEvalsCallback(trainer, tokenizer, ...)

# Trainer에 콜백을 추가합니다
trainer.add_callback(evals_callback)

# 평소와 같이 Trainer 학습을 시작합니다
trainer.train()

​

학습 중 평가 샘플 보기

다음 섹션에서는 WandbCallback을 커스터마이즈하여 모델 예측을 수행하고, 학습 중에 평가 샘플을 W&B Table에 로깅하는 방법을 보여줍니다. Trainer 콜백의 on_evaluate 메서드를 사용해 매 eval_steps마다 이 작업을 수행합니다.

여기서는 토크나이저를 사용해 모델 출력으로부터 예측값과 레이블을 디코딩하는 decode_predictions 함수를 작성했습니다.

그다음 예측값과 레이블로부터 pandas DataFrame을 생성하고, DataFrame에 epoch 열을 추가합니다.

마지막으로 DataFrame으로부터 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): 모델과 연결된 토크나이저.
        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): 모델과 연결된 토크나이저.
            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 환경 변수 전체 목록은 여기에서 확인할 수 있습니다.

Environment Variable	Usage
WANDB_PROJECT	프로젝트 이름을 지정합니다(기본값: huggingface)
WANDB_LOG_MODEL	모델 체크포인트를 W&B 아티팩트로 로깅합니다(기본값: false) false (기본): 모델 체크포인트를 업로드하지 않음 checkpoint: Trainer의 TrainingArguments에서 설정한 args.save_steps마다 체크포인트를 업로드합니다. end: 학습 종료 시 최종 모델 체크포인트를 업로드합니다.
WANDB_WATCH	모델의 gradient, parameter를 로깅할지 여부를 설정합니다 false (기본): gradient와 parameter를 로깅하지 않음 gradients: gradient에 대한 히스토그램을 로깅 all: gradient와 parameter에 대한 히스토그램을 모두 로깅
WANDB_DISABLED	전체 로깅을 비활성화하려면 true로 설정합니다(기본값: false)
WANDB_QUIET	표준 출력에 기록되는 메시지를 중요 메시지만 출력하도록 제한하려면 true로 설정합니다(기본값: false)
WANDB_SILENT	wandb가 출력하는 메시지를 모두 숨기려면 true로 설정합니다(기본값: false)

Command Line

WANDB_WATCH=all
WANDB_SILENT=true

Notebook

%env WANDB_WATCH=all
%env WANDB_SILENT=true

​

wandb.init를 어떻게 사용자 지정하나요?

Trainer가 사용하는 WandbCallback은 Trainer가 초기화될 때 내부적으로 wandb.init을 호출합니다. 대신 Trainer가 초기화되기 전에 wandb.init을 호출해 실행을 직접 설정할 수도 있습니다. 이렇게 하면 W&B 실행 구성을 온전히 제어할 수 있습니다.

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 저장소에 이슈를 생성해 주세요.