> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hugging Face Transformers

> Transformers Trainer와 함께 Weights & Biases를 사용하여 실험 추적, 모델 체크포인트 저장, 데이터셋 버전 관리를 수행하세요.

export const ColabLink = ({url}) => <a href={url} target="_blank" rel="noopener noreferrer" className="colab-link">
    <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
      <path d="M14.25.18l.9.2.73.26.59.3.45.32.34.34.25.34.16.33.1.3.04.26.02.2-.01.13V8.5l-.05.63-.13.55-.21.46-.26.38-.3.31-.33.25-.35.19-.35.14-.33.1-.3.07-.26.04-.21.02H8.77l-.69.05-.59.14-.5.22-.41.27-.33.32-.27.35-.2.36-.15.37-.1.35-.07.32-.04.27-.02.21v3.06H3.17l-.21-.03-.28-.07-.32-.12-.35-.18-.36-.26-.36-.36-.35-.46-.32-.59-.28-.73-.21-.88-.14-1.05-.05-1.23.06-1.22.16-1.04.24-.87.32-.71.36-.57.4-.44.42-.33.42-.24.4-.16.36-.1.32-.05.24-.01h.16l.06.01h8.16v-.83H6.18l-.01-2.75-.02-.37.05-.34.11-.31.17-.28.25-.26.31-.23.38-.2.44-.18.51-.15.58-.12.64-.1.71-.06.77-.04.84-.02 1.27.05zm-6.3 1.98l-.23.33-.08.41.08.41.23.34.33.22.41.09.41-.09.33-.22.23-.34.08-.41-.08-.41-.23-.33-.33-.22-.41-.09-.41.09zm13.09 3.95l.28.06.32.12.35.18.36.27.36.35.35.47.32.59.28.73.21.88.14 1.04.05 1.23-.06 1.23-.16 1.04-.24.86-.32.71-.36.57-.4.45-.42.33-.42.24-.4.16-.36.09-.32.05-.24.02-.16-.01h-8.22v.82h5.84l.01 2.76.02.36-.05.34-.11.31-.17.29-.25.25-.31.24-.38.2-.44.17-.51.15-.58.13-.64.09-.71.07-.77.04-.84.01-1.27-.04-1.07-.14-.9-.2-.73-.25-.59-.3-.45-.33-.34-.34-.25-.34-.16-.33-.1-.3-.04-.25-.02-.2.01-.13v-5.34l.05-.64.13-.54.21-.46.26-.38.3-.32.33-.24.35-.2.35-.14.33-.1.3-.06.26-.04.21-.02.13-.01h5.84l.69-.05.59-.14.5-.21.41-.28.33-.32.27-.35.2-.36.15-.36.1-.35.07-.32.04-.28.02-.21V6.07h2.09l.14.01.21.03zm-6.47 14.25l-.23.33-.08.41.08.41.23.33.33.23.41.08.41-.08.33-.23.23-.33.08-.41-.08-.41-.23-.33-.33-.23-.41-.08-.41.08z" />
    </svg>
    Try in Colab
  </a>;

<ColabLink url="https://colab.research.google.com/github/wandb/examples/blob/master/colabs/huggingface/Optimize_Hugging_Face_models_with_Weights_&_Biases.ipynb" />

[Hugging Face Transformers](https://huggingface.co/docs/transformers/index) 라이브러리를 사용하면 BERT와 같은 NLP 모델과 혼합 정밀도 및 그라디언트 체크포인팅과 같은 트레이닝 기법을 쉽게 사용할 수 있습니다. [Weights & Biases 인테그레이션](https://huggingface.co/transformers/main_classes/callback.html#transformers.integrations.WandbCallback)은 중앙 집중식 대시보드에 실험 추적과 모델 버전 관리 기능을 추가합니다.

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

<h2 id="quick-start">
  빠른 시작
</h2>

```python theme={"system"}
os.environ["WANDB_PROJECT"] = "<my-project-name>"  # W&B 프로젝트 이름을 지정하세요
os.environ["WANDB_LOG_MODEL"] = "checkpoint"  # 모든 모델 checkpoint를 로깅하세요

from transformers import TrainingArguments, Trainer

args = TrainingArguments(..., report_to="wandb")  # W&B 로깅을 활성화하세요
trainer = Trainer(..., args=args)
```

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/huggingface_gif.gif?s=db5e1024dd0cbc0c1ea811c938358bd5" alt="Hugging Face 대시보드" width="600" height="320" data-path="products/wandb/_media/huggingface_gif.gif" />
</Frame>

<Note>
  바로 실행 가능한 코드부터 살펴보고 싶다면 이 [Google Colab](https://wandb.me/hf)을 확인하세요.
</Note>

<h2 id="get-started-track-experiments">
  시작하기: 실험 추적
</h2>

이 섹션에서는 첫 트레이닝 run이 W\&B 대시보드에 표시되도록 Weights & Biases 인증을 수행하고, 클라이언트 라이브러리를 설치하고, 프로젝트 이름을 지정하고, `Trainer`에서 로깅을 활성화하는 방법을 설명합니다.

<h3 id="sign-up-and-create-an-api-key">
  가입 및 API 키 생성
</h3>

API 키는 Weights & Biases에서 사용자의 컴퓨터를 인증하는 데 사용됩니다. API 키는 사용자 프로필에서 생성할 수 있습니다.

<Note>
  더 간단한 방법으로 [User Settings](https://forge.coreweave.com/settings)로 이동해 API 키를 생성하세요. API 키를 즉시 복사한 후 비밀번호 관리자와 같은 안전한 위치에 저장하세요.
</Note>

1. 오른쪽 상단의 사용자 프로필 아이콘을 클릭하세요.
2. **User Settings**를 선택한 다음 **API Keys** 섹션까지 스크롤하세요.

<h3 id="install-the-wandb-library-and-log-in">
  `wandb` 라이브러리 설치 및 로그인
</h3>

`wandb` 라이브러리를 로컬에 설치하고 로그인하려면:

<Tabs>
  <Tab title="Command Line">
    1. `WANDB_API_KEY` [환경 변수](/ko/products/wandb/track/environment-variables)를 API 키로 설정하세요. `<>`로 묶인 값을 본인의 값으로 교체하세요:

       ```bash theme={"system"}
       export WANDB_API_KEY=<your_api_key>
       ```

    2. `wandb` 라이브러리를 설치하고 로그인하세요.

       ```bash theme={"system"}
       pip install wandb

       wandb login
       ```
  </Tab>

  <Tab title="Python">
    ```bash theme={"system"}
    pip install wandb
    ```

    ```python theme={"system"}
    import wandb
    wandb.login()
    ```
  </Tab>

  <Tab title="Python notebook">
    ```notebook theme={"system"}
    !pip install wandb

    import wandb
    wandb.login()
    ```
  </Tab>
</Tabs>

Weights & Biases를 처음 사용하신다면 [퀵스타트](/ko/products/wandb/quickstart)를 확인하세요.

<h3 id="name-the-project">
  프로젝트 이름 지정
</h3>

Weights & Biases 프로젝트는 관련 run에서 로깅한 모든 차트, 데이터 및 모델을 저장합니다. 프로젝트 이름을 지정하면 작업을 정리하는 데 도움이 되며 단일 프로젝트에 대한 모든 정보를 한 곳에 보관할 수 있습니다.

프로젝트에 run을 추가하려면 `WANDB_PROJECT` 환경 변수를 프로젝트 이름으로 설정하세요. `WandbCallback`는 이 프로젝트 이름 환경 변수를 인식하여 run을 설정할 때 사용합니다.

<Tabs>
  <Tab title="Command Line">
    ```bash theme={"system"}
    WANDB_PROJECT=amazon_sentiment_analysis
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import os
    os.environ["WANDB_PROJECT"]="amazon_sentiment_analysis"
    ```
  </Tab>

  <Tab title="Python notebook">
    ```notebook theme={"system"}
    %env WANDB_PROJECT=amazon_sentiment_analysis
    ```
  </Tab>
</Tabs>

<Note>
  `Trainer`를 초기화하기 *전에* 프로젝트 이름을 설정해야 합니다.
</Note>

프로젝트 이름을 지정하지 않으면 프로젝트 이름은 기본적으로 `huggingface`로 설정됩니다.

<h3 id="log-your-training-runs-to-weights-biases">
  트레이닝 run을 Weights & Biases에 로깅하기
</h3>

코드 또는 명령줄에서 `Trainer` 트레이닝 인수를 정의할 때 `report_to`를 `"wandb"`로 설정하여 Weights & Biases 로깅을 활성화하세요. 이 설정이 없으면 `Trainer`는 Weights & Biases에 데이터를 보내지 않습니다.

`TrainingArguments`의 `logging_steps` 인수는 트레이닝 중 트레이닝 메트릭을 Weights & Biases에 전송하는 빈도를 제어합니다. `run_name` 인수를 사용하여 Weights & Biases의 트레이닝 run에 이름을 지정할 수도 있습니다.

이것으로 설정이 완료되었습니다. 이제 모델은 트레이닝 중에 손실, 평가 메트릭, 모델 토폴로지 및 그라디언트를 Weights & Biases에 로깅합니다.

<Tabs>
  <Tab title="Command Line">
    ```bash theme={"system"}
    python run_glue.py \     # Python 스크립트 실행
      --report_to wandb \    # W&B 로깅 활성화
      --run_name bert-base-high-lr \   # W&B run 이름(선택)
      # 여기에 기타 명령줄 인수 지정
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    from transformers import TrainingArguments, Trainer

    args = TrainingArguments(
        # 여기에 기타 args 및 kwargs 지정
        report_to="wandb",  # W&B 로깅 활성화
        run_name="bert-base-high-lr",  # W&B run 이름(선택)
        logging_steps=1,  # W&B 로깅 빈도
    )

    trainer = Trainer(
        # 여기에 기타 args 및 kwargs 지정
        args=args,  # 트레이닝 인수
    )

    trainer.train()  # 트레이닝 및 W&B 로깅 시작
    ```
  </Tab>
</Tabs>

<Note>
  TensorFlow를 사용하시나요? PyTorch `Trainer`를 TensorFlow `TFTrainer`로 교체하세요.
</Note>

<h3 id="turn-on-model-checkpointing">
  모델 체크포인트 저장 활성화
</h3>

메트릭 로깅 외에도 트레이닝된 모델 가중치 자체를 Weights & Biases에 저장하여 버전을 관리하고, 다운로드하고, 팀 내에서 공유할 수 있습니다.

[아티팩트](/ko/products/wandb/artifacts)를 사용하면 최대 100 GB의 모델과 데이터셋을 무료로 저장한 후 [레지스트리](/ko/products/registry)를 사용할 수 있습니다. 레지스트리에 모델을 등록하면 모델을 탐색하고 평가하며, 스테이징을 준비하거나 프로덕션 환경에 배포할 수 있습니다.

Hugging Face 모델 체크포인트를 아티팩트에 로깅하려면 `WANDB_LOG_MODEL` 환경 변수를 다음 중 \_하나\_로 설정하세요:

* **`checkpoint`**: [`TrainingArguments`](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments)의 `args.save_steps`마다 체크포인트를 업로드합니다.
* **`end`**: `load_best_model_at_end`도 설정되어 있으면 트레이닝이 끝날 때 모델을 업로드합니다.
* **`false`**: 모델을 업로드하지 않습니다.

<Tabs>
  <Tab title="Command Line">
    ```bash theme={"system"}
    WANDB_LOG_MODEL="checkpoint"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import os

    os.environ["WANDB_LOG_MODEL"] = "checkpoint"
    ```
  </Tab>

  <Tab title="Python notebook">
    ```notebook theme={"system"}
    %env WANDB_LOG_MODEL="checkpoint"
    ```
  </Tab>
</Tabs>

이제부터 초기화하는 모든 Transformers `Trainer`는 Weights & Biases 프로젝트에 모델을 업로드합니다. 로깅한 모델 체크포인트는 [아티팩트](/ko/products/wandb/artifacts) UI에서 확인할 수 있으며, 전체 모델 리니지를 포함합니다. [아티팩트 UI의 모델 체크포인트 예시](https://forge.coreweave.com/wandb/wandb/arttest/artifacts/model/iv3_trained/5334ab69740f9dda4fed/lineage?_gl=1*yyql5q*_ga*MTQxOTYyNzExOS4xNjg0NDYyNzk1*_ga_JH1SJHJQXJ*MTY5MjMwNzI2Mi4yNjkuMS4xNjkyMzA5NjM2LjM3LjAuMA..)를 확인하세요.

<Note>
  기본적으로 모델은 `WANDB_LOG_MODEL`이 `end`로 설정된 경우 `model-{run_id}`로, `WANDB_LOG_MODEL`이 `checkpoint`로 설정된 경우 `checkpoint-{run_id}`로 W\&B 아티팩트에 저장됩니다.
  하지만 `TrainingArguments`에 [`run_name`](https://huggingface.co/docs/transformers/main/en/main_classes/trainer#transformers.TrainingArguments.run_name)을 전달하면 모델은 `model-{run_name}` 또는 `checkpoint-{run_name}`으로 저장됩니다.
</Note>

<h4 id="registry">
  Registry
</h4>

체크포인트를 아티팩트에 로깅한 후, 최고 성능 모델 체크포인트를 등록하고 [레지스트리](/ko/products/registry)를 통해 팀 전체에서 중앙 관리할 수 있습니다. 레지스트리를 사용하면 최고 성능 모델을 작업별로 구성하고, 모델의 라이프사이클을 관리하고, 전체 ML 라이프사이클을 추적하고 감사하며, 후속 액션을 [자동화](/ko/products/wandb/automations)할 수 있습니다.

모델 아티팩트를 연결하려면 [레지스트리](/ko/products/registry)를 참고하세요.

<h3 id="visualize-evaluation-outputs-during-training">
  트레이닝 중 평가 출력 시각화
</h3>

트레이닝 또는 평가 중 모델 출력 시각화는 모델이 어떻게 트레이닝되는지 이해하는 데 종종 필수적입니다. 손실 곡선과 함께 구체적인 예측을 검사하면 집계된 메트릭이 숨길 수 있는 품질 문제를 발견하는 데 도움이 됩니다.

Transformers Trainer의 callback 시스템을 사용하면 W\&B Tables에 더 유용한 데이터를 로깅할 수 있습니다. 여기에는 모델의 텍스트 생성 출력 또는 기타 예측이 포함됩니다.

다음 예시와 같은 W\&B Table에 트레이닝 중 평가 출력을 로깅하는 방법에 대한 전체 가이드는 [트레이닝 중 평가 샘플 로깅 및 확인](#log-and-view-evaluation-samples-during-training)를 참조하세요.

<Frame>
  <img src="https://mintcdn.com/coreweave-dbfa0e8d/3Dv_sw2eg8feUJlx/products/wandb/_media/huggingface_eval_tables.png?fit=max&auto=format&n=3Dv_sw2eg8feUJlx&q=85&s=5d5fcf760a5b8770fe1253e3dcf0d80c" alt="평가 출력이 포함된 W&B Table 표시" width="2002" height="1214" data-path="products/wandb/_media/huggingface_eval_tables.png" />
</Frame>

<h3 id="finish-your-wb-run-notebook-only">
  W\&B run 종료하기 (노트북만 해당)
</h3>

트레이닝이 Python 스크립트 안에서 수행되는 경우, 스크립트가 완료되면 W\&B run이 종료됩니다.

Jupyter 또는 Google Colab 노트북을 사용하는 경우, `run.finish()`를 호출하여 트레이닝이 완료되었음을 알리세요.

```python theme={"system"}
run = wandb.init()
trainer.train()  # 트레이닝 및 W&B에 로깅 시작

# Post-training 분석, 테스트, 기타 로깅된 코드

run.finish()
```

<h3 id="visualize-your-results">
  결과 시각화하기
</h3>

트레이닝 결과를 로깅한 후에는 [W\&B 대시보드](/ko/products/wandb/track/workspaces)에서 결과를 살펴볼 수 있습니다. run을 비교하고, 발견 사항을 자세히 들여다보고, 대화형 시각화로 데이터를 탐색해 보세요.

이제 인테그레이션이 완성되었습니다. `Trainer`는 지정한 프로젝트에 메트릭을 로깅하고, 필요에 따라 체크포인트를 아티팩트에 저장하며, 평가 출력을 W\&B 대시보드에 표시합니다.

<h2 id="advanced-features-and-faqs">
  고급 기능 및 자주 묻는 질문
</h2>

다음 섹션에서는 최고 성능 모델 저장, 체크포인트에서 트레이닝 재개, 로깅 callback 맞춤 설정, 환경 변수를 통한 Weights & Biases 동작 설정 등 일반적인 후속 작업을 다룹니다.

<h3 id="save-the-best-model">
  최고 성능 모델 저장
</h3>

`TrainingArguments`에 `load_best_model_at_end=True`를 설정하여 `Trainer`에 전달하면, Weights & Biases는 최고 성능 모델 체크포인트를 아티팩트에 저장합니다.

모델 체크포인트를 아티팩트로 저장하면 [레지스트리](/ko/products/registry)로 승격할 수 있습니다. 레지스트리에서 다음을 수행할 수 있습니다:

* ML 작업별로 최고 성능 모델 버전을 정리합니다.
* 모델을 중앙 집중화하고 팀과 공유합니다.
* 프로덕션용으로 모델을 스테이징하거나 추가 평가를 위해 북마크합니다.
* 다운스트림 CI/CD 프로세스를 트리거합니다.

<h3 id="load-a-saved-model">
  저장된 모델 불러오기
</h3>

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

```python theme={"system"}
# 새 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
    )

    # 추가 트레이닝을 수행하거나 추론을 실행하세요
```

<h3 id="resume-training-from-a-checkpoint">
  체크포인트에서 트레이닝 재개
</h3>

`WANDB_LOG_MODEL='checkpoint'`를 설정하면 `TrainingArguments`의 `model_name_or_path` 인수로 `model_dir`을 사용하고 `Trainer`에 `resume_from_checkpoint=True`를 전달하여 트레이닝을 재개할 수 있습니다.

```python theme={"system"}
last_run_id = "xxxxxxxx"  # wandb 작업 공간에서 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_checkpoint_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)
```

<h3 id="log-and-view-evaluation-samples-during-training">
  트레이닝 중 평가 샘플 로깅 및 확인
</h3>

Transformers 라이브러리의 [`WandbCallback`](https://huggingface.co/transformers/main_classes/callback.html#transformers.integrations.WandbCallback)은 Transformers `Trainer`를 통해 Weights & Biases에 로깅하는 작업을 처리합니다. 이 callback을 사용자 지정하여 모델 예측, 혼동 행렬 또는 기타 맞춤형 데이터를 로깅할 수 있습니다. 이를 위해 `WandbCallback`을 상속하는 하위 클래스를 만들고 Trainer 클래스의 추가 방법을 사용하는 기능을 추가하세요.

다음은 이 새로운 callback을 Hugging Face Trainer에 추가하는 일반적인 패턴과, 평가 출력을 W\&B Table에 로깅하는 전체 코드 예시입니다.

```python theme={"system"}
# 평소처럼 Trainer 인스턴스를 생성하세요
trainer = Trainer()

# Trainer 객체를 전달하여 새 로깅 callback 인스턴스를 생성하세요
evals_callback = WandbEvalsCallback(trainer, tokenizer, ...)

# Trainer에 callback을 추가하세요
trainer.add_callback(evals_callback)

# 평소처럼 Trainer 트레이닝을 시작하세요
trainer.train()
```

<h4 id="view-evaluation-samples-during-training">
  트레이닝 중 평가 샘플 확인
</h4>

다음 섹션에서는 `WandbCallback`을 사용자 지정하여 트레이닝 중 모델 예측을 실행하고 평가 샘플을 W\&B Table에 로깅하는 방법을 설명합니다. 이 작업은 Trainer callback의 `on_evaluate` 방법을 사용하여 `eval_steps`마다 실행됩니다.

`decode_predictions` 함수는 토크나이저를 사용하여 모델 출력의 예측과 레이블을 디코딩합니다.

그런 다음 코드는 예측과 레이블로 pandas 데이터프레임을 만들고 데이터프레임에 `epoch` 열을 추가합니다.

마지막으로 코드는 데이터프레임으로 `wandb.Table`을 만들고 Weights & Biases에 로깅합니다. `freq` 에포크마다 예측을 로깅하여 로깅 빈도를 제어할 수 있습니다.

<Note>
  일반 `WandbCallback`과 달리 이 맞춤형 callback은 `Trainer` 초기화 중이 아니라 `Trainer`가 인스턴스화된 **후에** trainer에 추가해야 합니다. 초기화 중에 `Trainer` 인스턴스가 callback에 전달되기 때문입니다.
</Note>

```python theme={"system"}
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):
    """Custom WandbCallback to log model predictions during training.

    This callback logs model predictions and labels to a wandb.Table at each
    logging step during training. It allows to visualize the
    model predictions as the training progresses.

    Attributes:
        trainer (Trainer): The Hugging Face Trainer instance.
        tokenizer (AutoTokenizer): The tokenizer associated with the model.
        sample_dataset (Dataset): A subset of the validation dataset
          for generating predictions.
        num_samples (int, optional): Number of samples to select from
          the validation dataset for generating predictions. Defaults to 100.
        freq (int, optional): Frequency of logging. Defaults to 2.
    """

    def __init__(self, trainer, tokenizer, val_dataset, num_samples=100, freq=2):
        """Initializes the WandbPredictionProgressCallback instance.

        Args:
            trainer (Trainer): The Hugging Face Trainer instance.
            tokenizer (AutoTokenizer): The tokenizer associated
              with the model.
            val_dataset (Dataset): The validation dataset.
            num_samples (int, optional): Number of samples to select from
              the validation dataset for generating predictions.
              Defaults to 100.
            freq (int, optional): Frequency of logging. Defaults to 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에 table을 로깅합니다
            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에 callback을 추가합니다
trainer.add_callback(progress_callback)
```

더 자세한 예시는 이 [Colab](https://colab.research.google.com/github/wandb/examples/blob/master/colabs/huggingface/Custom_Progress_Callback.ipynb)을 참고하세요.

<h3 id="additional-weights-biases-settings">
  추가 Weights & Biases 설정
</h3>

`Trainer`로 로깅되는 내용을 환경 변수를 설정하여 추가로 구성할 수 있습니다. Weights & Biases 환경 변수의 전체 목록은 [환경 변수 레퍼런스](/ko/products/wandb/platform/hosting/env-vars)를 참조하세요.

| 환경 변수 | 사용 |
| - | - |
| `WANDB_PROJECT` | 프로젝트에 이름을 지정하세요 (`huggingface`가 기본값) |
| `WANDB_LOG_MODEL` | <p>모델 체크포인트를 W\&B 아티팩트로 로깅합니다 (`false`가 기본값) </p><ul><li><code>false</code> (기본값): 모델 체크포인트 저장 안 함 </li><li><code>checkpoint</code>: `args.save_steps`마다 체크포인트를 업로드합니다 (Trainer의 `TrainingArguments`에서 설정). </li><li><code>end</code>: 트레이닝 종료 시 최종 모델 체크포인트를 업로드합니다.</li></ul> |
| `WANDB_WATCH` | <p>모델의 그라디언트, 매개변수 또는 둘 다 로깅할지 설정합니다.</p><ul><li><code>false</code> (기본값): 그라디언트 또는 매개변수 로깅 안 함 </li><li><code>gradients</code>: 그라디언트의 히스토그램을 로깅합니다 </li><li><code>all</code>: 그라디언트와 매개변수의 히스토그램을 로깅합니다</li></ul> |
| `WANDB_DISABLED` | 로깅을 완전히 끄려면 `true`로 설정하세요 (`false`가 기본값) |
| `WANDB_QUIET` | 표준 출력으로 로깅되는 문장을 중요 문장만으로 제한하려면 `true`로 설정하세요 (`false`가 기본값) |
| `WANDB_SILENT` | `wandb`가 출력하는 내용을 음소거하려면 `true`로 설정하세요 (`false`가 기본값) |

<Tabs>
  <Tab title="Command Line">
    ```bash theme={"system"}
    WANDB_WATCH=all
    WANDB_SILENT=true
    ```
  </Tab>

  <Tab title="Notebook">
    ```notebook theme={"system"}
    %env WANDB_WATCH=all
    %env WANDB_SILENT=true
    ```
  </Tab>
</Tabs>

<h3 id="customize-wandbinit">
  `wandb.init()` 사용자 지정
</h3>

`Trainer`가 사용하는 `WandbCallback`은 `Trainer`가 초기화될 때 `wandb.init()`을 내부적으로 호출합니다. 또는 `Trainer`가 초기화되기 전에 `wandb.init()`을 호출하여 run을 수동으로 설정할 수 있습니다. 이를 통해 W\&B run 설정을 완전히 제어할 수 있습니다.

다음은 `init`에 전달할 수 있는 예시입니다. `wandb.init()`에 대한 자세한 내용은 [`wandb.init()` 레퍼런스](/ko/products/wandb/ref/python/functions/init)를 참조하세요.

```python theme={"system"}
wandb.init(
    project="amazon_sentiment_analysis",
    name="bert-base-high-lr",
    tags=["baseline", "high-lr"],
    group="bert",
)
```

<h2 id="additional-resources">
  추가 자료
</h2>

다음은 더 읽어볼 만한 Transformers 및 Weights & Biases 관련 아티클 여섯 편입니다.

<details>
  <summary>Hugging Face Transformers를 위한 하이퍼파라미터 최적화</summary>

  * Hugging Face Transformers의 하이퍼파라미터 최적화 전략 세 가지(그리드 검색, 베이지안 최적화, Population Based Training)를 비교합니다.
  * SuperGLUE 벤치마크의 RTE 데이터셋으로 파인튜닝한 Hugging Face transformers의 표준 uncased BERT 모델을 사용합니다.
  * 결과적으로 Hugging Face transformer 모델의 하이퍼파라미터 최적화에는 Population Based Training이 가장 효과적인 것으로 나타났습니다.

  [Hugging Face Transformers를 위한 하이퍼파라미터 최적화 리포트](https://forge.coreweave.com/wandb/amogkam/transformers/reports/Hyperparameter-Optimization-for-Hugging-Face-Transformers--VmlldzoyMTc2ODI)를 조회하세요.
</details>

<details>
  <summary>Hugging Tweets: 트윗을 생성하는 모델 트레이닝하기</summary>

  * 이 아티클에서는 사전 트레이닝된 GPT2 Hugging Face Transformer 모델을 특정 사용자의 트윗으로 5분 만에 파인튜닝하는 방법을 보여 줍니다.
  * 이 모델은 트윗 다운로드, 데이터셋 최적화, 초기 실험, 사용자 간 손실 비교, 모델 파인튜닝으로 이어지는 파이프라인을 사용합니다.

  [HuggingTweets 리포트](https://forge.coreweave.com/wandb/wandb/huggingtweets/reports/HuggingTweets-Train-a-Model-to-Generate-Tweets--VmlldzoxMTY5MjI)를 조회하세요.
</details>

<details>
  <summary>Hugging Face BERT와 WB를 사용한 문장 분류</summary>

  * 이 아티클에서는 최근 자연어 처리 분야의 혁신적인 성과를 활용하여 문장 분류기를 구축하며, 특히 NLP에 전이 학습을 적용하는 데 초점을 맞춥니다.
  * 단일 문장 분류에는 The Corpus of Linguistic Acceptability(CoLA) 데이터셋을 사용합니다. 2018년 5월에 처음 공개된 이 데이터셋은 문법적으로 올바른지 올바르지 않은지가 레이블로 지정된 문장 모음입니다.
  * Google의 BERT를 사용하여 다양한 NLP 작업에서 적은 노력으로 고성능 모델을 만듭니다.

  [Hugging Face BERT와 W\&B를 사용한 문장 분류 리포트](https://forge.coreweave.com/wandb/cayush/bert-finetuning/reports/Sentence-Classification-With-Huggingface-BERT-and-W-B--Vmlldzo4MDMwNA)를 조회하세요.
</details>

<details>
  <summary>Hugging Face 모델 성능 추적 단계별 가이드</summary>

  * Weights & Biases와 Hugging Face transformers를 사용하여 GLUE 벤치마크에서 DistilBERT를 트레이닝합니다. DistilBERT는 BERT보다 크기가 40% 작으면서도 BERT 정확도의 97%를 유지하는 Transformer입니다.
  * GLUE 벤치마크는 NLP 모델 트레이닝을 위한 9개의 데이터셋과 작업으로 구성된 컬렉션입니다.

  [Hugging Face 모델 성능 추적 리포트](https://forge.coreweave.com/wandb/jxmorris12/huggingface-demo/reports/A-Step-by-Step-Guide-to-Tracking-HuggingFace-Model-Performance--VmlldzoxMDE2MTU)를 조회하세요.
</details>

<details>
  <summary>HuggingFace의 조기 종료 예시</summary>

  * PyTorch나 TensorFlow의 기본 기능만으로 조기 종료(Early Stopping) 정규화를 적용하여 Hugging Face Transformer를 파인튜닝할 수 있습니다.
  * TensorFlow에서는 `tf.keras.callbacks.EarlyStopping` callback으로 EarlyStopping을 간단하게 사용할 수 있습니다.
  * PyTorch에는 바로 쓸 수 있는 조기 종료 방법이 없지만, GitHub Gist에서 제대로 동작하는 조기 종료 훅을 구할 수 있습니다.

  [Hugging Face의 조기 종료 리포트](https://forge.coreweave.com/wandb/ayush-thakur/huggingface/reports/Early-Stopping-in-HuggingFace-Examples--Vmlldzo0MzE2MTM)를 조회하세요.
</details>

<details>
  <summary>맞춤형 데이터셋으로 Hugging Face Transformers를 파인튜닝하는 방법</summary>

  맞춤형 IMDB 데이터셋으로 DistilBERT transformer를 파인튜닝하여 감성 분석(이진 분류)을 수행합니다.

  [맞춤형 데이터셋으로 Hugging Face Transformers 파인튜닝하기 리포트](https://forge.coreweave.com/wandb/ayush-thakur/huggingface/reports/How-to-Fine-Tune-HuggingFace-Transformers-on-a-Custom-Dataset--Vmlldzo0MzQ2MDc)를 조회하세요.
</details>

<h2 id="get-help-or-request-features">
  도움 받기 또는 기능 요청
</h2>

Hugging Face Weights & Biases 인테그레이션에 대한 문제, 질문 또는 기능 요청이 있으면 [Hugging Face 포럼의 이 스레드](https://discuss.huggingface.co/t/logging-experiment-tracking-with-w-b/498)에 게시하거나 Hugging Face [Transformers GitHub 저장소](https://github.com/huggingface/transformers)에 이슈를 여십시오.
