# 참조 모델용 BEMA

이 기능은 DPO 학습 중에 참조 모델을 업데이트하기 위해 BEMA 알고리즘을 구현합니다.

## 사용

```python
from trl.experimental.bema_for_ref_model import BEMACallback, DPOTrainer
from datasets import load_dataset

dataset = load_dataset("trl-internal-testing/zen", "standard_preference", split="train")

bema_callback = BEMACallback(update_ref_model=True)

trainer = DPOTrainer(
    model="trl-internal-testing/tiny-Qwen2ForCausalLM-2.5",
    train_dataset=dataset,
    callbacks=[bema_callback],
)
trainer.train()
```

## DPOTrainer[[trl.DPOTrainer]]

#### trl.DPOTrainer[[trl.DPOTrainer]]

```python
trl.DPOTrainer(*args, **kwargs)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.0/trl/experimental/bema_for_ref_model/dpo_trainer.py#L19)

#### train[[trl.DPOTrainer.train]]

```python
train(resume_from_checkpoint: str | bool | None = None, trial: optuna.Trial | dict[str, Any] | None = None, ignore_keys_for_eval: list[str] | None = None)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L1450)

**매개변수:**

resume_from_checkpoint (`str` 또는 `bool`, *선택 사항*) : `str`인 경우, 이전 `Trainer` 인스턴스가 저장한 체크포인트의 로컬 경로입니다. `bool`이고 `True`와 같으면, 이전 `Trainer` 인스턴스가 저장한 *args.output_dir*의 마지막 체크포인트를 로드합니다. 이 값이 존재하면, 여기서 로드된 모델/옵티마이저/스케줄러 상태로부터 학습이 재개됩니다.

trial (`optuna.Trial` 또는 `dict[str, Any]`, *선택*) : 하이퍼파라미터 탐색을 위한 트라이얼 실행 또는 하이퍼파라미터 사전.

ignore_keys_for_eval (`list[str]`, *선택 사항*) : 모델의 출력(사전에 해당하는 경우)에서 학습 중 평가 시 예측을 수집할 때 무시해야 할 키의 목록입니다.

**반환값:** `~trainer_utils.TrainOutput`

전체 스텝 수, 학습 손실, 메트릭을 포함하는 객체.

주요 학습 진입점.

#### save_model[[trl.DPOTrainer.save_model]]

```python
save_model(output_dir: str | None = None, _internal_call: bool = False)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4077)

모델을 저장하므로 `from_pretrained()`를 사용하여 다시 로드할 수 있습니다.

main 프로세스에서만 저장합니다.

#### push_to_hub[[trl.DPOTrainer.push_to_hub]]

```python
push_to_hub(commit_message: str | None = 'End of training', blocking: bool = True, token: str | None = None, revision: str | None = None, private: bool | None = None, **kwargs)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4337)

**매개변수:**

commit_message (`str`, *선택 사항*, 기본값 `"End of training"`) : push할 때 커밋할 메시지.

blocking (`bool`, *선택 사항*, 기본값 `True`) : `git push`가 완료된 후에만 함수가 반환되어야 하는지 여부.

token (`str`, *선택 사항*, 기본값 `None`) : Trainer의 원래 args를 덮어쓸 수 있는 쓰기 권한이 있는 토큰입니다.

revision (`str`, *선택 사항*) : 커밋할 git 리비전입니다. 기본값은 "main" 브랜치의 head입니다.

private (`bool`, *선택 사항*) : 저장소가 생성될 때 비공개로 만들지 여부입니다. 기본값은 `args.hub_private_repo`입니다. 저장소가 이미 존재하는 경우 효과가 없습니다.

kwargs (`dict[str, Any]`, *선택*) : `~Trainer.create_model_card`에 함께 전달되는 추가 키워드 인자입니다.

**반환값:**

`blocking=False`인 경우 모델이 push된 저장소의 URL 또는 `blocking=True`인 경우 커밋 진행 상황을 추적하는 `Future` 객체를 반환합니다.

`self.args.hub_model_id` 저장소에 `self.model`과 `self.processing_class`를 🤗 모델 허브에 업로드합니다.

## BEMACallback[[trl.BEMACallback]]

#### trl.BEMACallback[[trl.BEMACallback]]

```python
trl.BEMACallback(update_freq: int = 400, ema_power: float = 0.5, bias_power: float = 0.2, lag: int = 10, update_after: int = 0, multiplier: float = 1.0, min_ema_multiplier: float = 0.0, device: str = 'cpu', update_ref_model: bool = False, ref_model_update_freq: int = 400, ref_model_update_after: int = 0)
```

[소스](https://github.com/huggingface/trl/blob/v1.18.0/trl/experimental/bema_for_ref_model/callback.py#L59)

**매개변수:**

update_freq (`int`, *선택 사항*, 기본값 `400`) : X단계마다 BEMA 가중치를 업데이트합니다. 논문에서는 이를 \\( \phi \\)로 표기합니다.

ema_power (`float`, *선택 사항*, 기본값 `0.5`) : EMA 감쇠 인자의 거듭제곱입니다. 논문에서는 \\( \kappa \\)로 표기합니다. EMA를 비활성화하려면 이 값을 `0.0`으로 설정하세요.

bias_power (`float`, *선택 사항*, 기본값 `0.2`) : BEMA 스케일링 인자의 지수입니다. 논문에서는 \\( \eta \\)로 표기됩니다. 큰 값(예: `8.0`)은 \\( \alpha_t \\)이 `0`으로 감소하도록 하여 편향 보정 비활성화를 근사합니다. 반면 `0.0`은 모든 단계에서 \\( \alpha_t \\)을 `1`로 고정하여 최대(감쇠되지 않은) 보정을 적용합니다.

lag (`int`, *선택 사항*, 기본값 `10`) : 업데이트의 가상 시작 연령으로 작용하여 초기 단계의 매끄러움을 제어하는 weight decay 스케줄의 초기 오프셋입니다. 논문에서는 \\( \rho \\)로 표기됩니다.

update_after (`int`, *선택 사항*, 기본값 `0`) : BEMA 가중치 업데이트를 시작하기 전의 버닝인 시간. 논문에서는 \\( \tau \\)로 표기합니다.

multiplier (`float`, *선택 사항*, 기본값 `1.0`) : EMA 감쇠 계수의 초기 값입니다. 논문에서는 \\( \gamma \\)로 표기됩니다.

min_ema_multiplier (`float`, *선택 사항*, 기본값 `0.0`) : EMA 감쇠 계수의 최소값입니다.

device (`str`, *선택 사항*, 기본값 `"cpu"`) : BEMA 버퍼에 사용할 장치, 예: `"cpu"` 또는 `"cuda"`. 대부분의 경우 OOM을 피하기 위해 이 장치는 학습에 사용되는 장치와 다르게 설정해야 합니다.

update_ref_model (`bool`, *선택 사항*, 기본값 `False`) : BEMA 가중치로 참조 모델을 업데이트할지 여부입니다. 이를 통해 주 모델의 지연 및 평활화 버전을 참조 모델로 생성합니다.

ref_model_update_freq (`int`, *선택 사항*, 기본값 `400`) : 이 간격의 스텝마다 BEMA 가중치로 참조 모델을 업데이트합니다.

ref_model_update_after (`int`, *선택 사항*, 기본값 `0`) : 참조 모델 업데이트를 시작하기 전에 대기할 스텝 수.

[Adam Block](https://huggingface.co/abblock)와 [Cyril Zhang](https://huggingface.co/cyrilzhang)의 [BEMA](https://huggingface.co/papers/2508.00180)(Bias-Corrected Exponential Moving Average)를 구현한 [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback)입니다. 코드는 MIT 라이선스에 따라 https://github.com/abblock/bema에서 가져왔습니다.

BEMA는 다음과 같이 스케일링되는 모델 가중치를 계산합니다:

$$ \theta_t' = \alpha_t \cdot (\theta_t - \theta_0) + \text{EMA}_t $$

여기서 \\( \theta_t \\)는 현재 모델 가중치, \\( \theta_0 \\)는 첫 번째 `update_after` 단계에서의 모델 가중치 스냅샷, \\( \text{EMA}_t  \\)는 모델 가중치의 지수 이동 평균, \\( \alpha_t \\)는 단계 수 \\( t \\)에 따라 감소하는 스케일링 계수입니다.

$$ \alpha_t = (\rho + \gamma \cdot t)^{-\eta}. $$

EMA는 다음과 같이 계산됩니다:

$$ \text{EMA}_t = (1 - \beta_t) \cdot \text{EMA}_{t-1} + \beta_t \cdot \theta_t $$

여기서 \\( \beta_t \\)는 단계 수 \\( t \\)에 따라 감소하는 감쇠 계수입니다.

$$ \beta_t = (\rho + \gamma \cdot t)^{-\kappa}. $$

예:

```python
>>> from trl import BEMACallback

>>> trainer = Trainer(..., callbacks=[BEMACallback()])
```

