TRL documentation

DPO Trainer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

DPO Trainer

All_models-DPO-blue smol_course-Chapter_2-yellow

개요

TRL은 Rafael Rafailov, Archit Sharma, Eric Mitchell, Stefano Ermon, Christopher D. Manning, Chelsea Finn의 논문 Direct Preference Optimization: Your Language Model is Secretly a Reward Model에 설명된 언어 모델 학습을 위한 Direct Preference Optimization (DPO) Trainer를 지원합니다.

해당 논문의 초록은 다음과 같습니다:

대규모 비지도 언어 모델(LM)은 광범위한 세계 지식과 일부 추론 기술을 학습하지만, 학습이 완전히 비지도 방식이라는 특성 때문에 모델의 동작을 정밀하게 제어하는 것은 어렵습니다. 이러한 조향성(steerability)을 확보하기 위한 기존 방법들은 모델 생성 결과의 상대적 품질에 대한 인간 라벨을 수집하고, 이러한 선호도에 맞춰 비지도 LM을 미세 조정하며, 종종 인간 피드백 기반 강화 학습(RLHF)을 사용합니다. 그러나 RLHF는 복잡한 절차이며, 인간 선호도를 반영하는 보상 모델을 먼저 적합(fitting)한 다음, 원래 모델에서 크게 벗어나지 않으면서 이 추정 보상을 최대화하도록 대규모 비지도 LM을 강화 학습으로 미세 조정해야 하므로 불안정한 경우가 많습니다. 본 논문에서는 RLHF의 보상 모델에 대한 새로운 매개변수화를 소개하며, 이를 통해 해당 최적 정책을 폐쇄형(closed form)으로 추출할 수 있어 표준 RLHF 문제를 단순한 분류 손실만으로 해결할 수 있습니다. 이를 Direct Preference Optimization(DPO)라고 부르는 결과 알고리즘은 안정적이고 성능이 뛰어나며 계산량이 적어, 미세 조정 중에 LM에서 샘플링을 수행하거나 상당한 하이퍼파라미터 튜닝을 할 필요가 없습니다. 우리의 실험 결과, DPO는 기존 방법과 동등하거나 더 나은 수준으로 LM을 미세 조정하여 인간 선호도에 맞출 수 있음을 보여줍니다. 특히, DPO로 미세 조정하면 PPO 기반 RLHF보다 생성물의 감정을 제어하는 능력이 뛰어나며, 구현과 학습이 훨씬 간단함에도 불구하고 요약 및 단일 턴 대화에서 응답 품질을 동등하게 유지하거나 개선합니다.

이 포스트 트레이닝 방법은 Kashif Rasul이 기여했으며, 이후 Quentin Gallouédec에 의해 리팩토링되었습니다.

빠른 시작

이 예제는 TRL의 DPOTrainer를 사용하여 언어 모델을 학습하는 방법을 보여줍니다. UltraFeedback dataset에서 Qwen 3 0.6B 모델을 학습합니다.

from trl import DPOTrainer
from datasets import load_dataset

trainer = DPOTrainer(
    model="Qwen/Qwen3-0.6B",
    train_dataset=load_dataset("trl-lib/ultrafeedback_binarized", split="train"),
)
trainer.train()

기대되는 데이터셋 유형 및 형식

DPO에는 preference 데이터셋이 필요합니다. DPOTrainer는 standard 및 conversational 데이터셋 형식 모두와 호환됩니다. conversational 데이터셋을 제공하면 트레이너가 데이터셋에 chat 템플릿을 자동으로 적용합니다.

# Standard format
## Explicit prompt (recommended)
preference_example = {"prompt": "The sky is", "chosen": " blue.", "rejected": " green."}
# Implicit prompt
preference_example = {"chosen": "The sky is blue.", "rejected": "The sky is green."}

# Conversational format
## Explicit prompt (recommended)
preference_example = {"prompt": [{"role": "user", "content": "What color is the sky?"}],
                      "chosen": [{"role": "assistant", "content": "It is blue."}],
                      "rejected": [{"role": "assistant", "content": "It is green."}]}
## Implicit prompt
preference_example = {"chosen": [{"role": "user", "content": "What color is the sky?"},
                                 {"role": "assistant", "content": "It is blue."}],
                      "rejected": [{"role": "user", "content": "What color is the sky?"},
                                   {"role": "assistant", "content": "It is green."}]}

데이터셋이 이러한 형식 중 하나에 해당하지 않는 경우, 예상되는 형식으로 변환하기 위해 전처리할 수 있습니다. Vezora/Code-Preference-Pairs 데이터셋을 사용한 예시는 다음과 같습니다:

from datasets import load_dataset

dataset = load_dataset("Vezora/Code-Preference-Pairs")


def preprocess_function(example):
    return {
        "prompt": [{"role": "user", "content": example["input"]}],
        "chosen": [{"role": "assistant", "content": example["accepted"]}],
        "rejected": [{"role": "assistant", "content": example["rejected"]}],
    }


dataset = dataset.map(preprocess_function, remove_columns=["instruction", "input", "accepted", "ID"])
print(next(iter(dataset["train"])))
{
    "prompt": [{"role": "user", "content": "Create a nested loop to print every combination of numbers [...]"}],
    "chosen": [{"role": "assistant", "content": "Here is an example of a nested loop in Python [...]"}],
    "rejected": [{"role": "assistant", "content": "Here is an example of a nested loop in Python [...]"}],
}

DPO 방법 자세히 살펴보기

Direct Preference Optimization(DPO)은 언어 모델을 선호 데이터와 정렬하기 위해 설계된 학습 방법입니다. 감독된 입력-출력 쌍 대신, 동일한 프롬프트에 대한 두 개의 완성 결과 쌍으로 모델을 학습하며, 이 중 하나의 완성이 다른 하나보다 선호됩니다. 목표는 명시적인 보상 모델 없이, 참조 모델에 대한 선호 및 비선호 완성 결과의 로그 가능도 간 마진을 넓히도록 모델을 직접 최적화하는 것입니다. 실제로 이는 선호 완성의 가능성을 높이는 것보다 비선호 완성의 가능성을 억제하는 방식으로 달성되는 경우가 많습니다.

이 섹션에서는 DPO가 실제로 어떻게 작동하는지, 주요 단계인 전처리와 손실 계산를 중심으로 설명합니다.

전처리 및 토큰화

학습 중 각 예시는 프롬프트와 함께 선호되는(chosen) 완료와 선호되지 않는(rejected) 완료를 포함해야 합니다. 예상되는 형식에 대한 자세한 내용은 Dataset formats를 참조하세요. DPOTrainer는 모델의 토크나이저를 사용하여 각 입력을 토큰화합니다.

손실 계산

dpo_figure

DPO에서 사용되는 손실은 다음과 같이 정의됩니다:LDPO(θ)=−E(x,y+,y−) ⁣[log⁡σ ⁣(β(log⁡πθ(y+ ⁣∣x)πref(y+ ⁣∣x)−log⁡πθ(y− ⁣∣x)πref(y− ⁣∣x)))] \mathcal{L}_{\mathrm{DPO}}(\theta) = -\mathbb{E}_{(x,y^{+},y^{-})}\!\left[\log \sigma\!\left(\beta\Big(\log\frac{\pi_{\theta}(y^{+}\!\mid x)}{\pi_{\mathrm{ref}}(y^{+}\!\mid x)}-\log \frac{\pi_{\theta}(y^{-}\!\mid x)}{\pi_{\mathrm{ref}}(y^{-}\!\mid x)}\Big)\right)\right]

여기서 x x 은 프롬프트이고, y+ y^+ 은 선호되는 완성 결과이며, y− y^- 은 선호되지 않는 완성 결과입니다. πθ \pi_{\theta} 은 학습 중인 정책 모델이고, πref \pi_{\mathrm{ref}} 은 참조 모델이며, σ \sigma 은 시그모이드 함수이고, β>0 \beta > 0 은 선호 신호의 강도를 제어하는 하이퍼파라미터입니다.

손실 유형

문헌에서는 목적 함수의 여러 수학적 표현이 제안되었습니다. 초기에는 DPO의 목적 함수가 위에서 제시된 바와 같이 정의되었습니다.

loss_type=설명
"sigmoid" (기본값)선호 데이터가 주어지면 Bradley-Terry 모델에 따라 이진 분류기를 적합할 수 있으며, 실제로 DPO 저자들은 정규화된 가능도를 logsigmoid를 통해 시그모이드 손실로 사용하여 로지스틱 회귀를 적합하도록 제안합니다.
"hinge"RSO의 저자들은 SLiC 논문에서 제시한 정규화 가능도(normalized likelihood)에 대해 hinge loss를 사용하는 것을 제안합니다. 이 경우 beta는 마진(margin)의 역수입니다.
"ipo"IPO의 저자들은 logit 변환이 과적합될 수 있다고 주장하며, 선호를 직접 최적화하기 위해 identity 변환을 제안합니다. TRL은 이를 loss_type="ipo"로 제공합니다.
"exo_pair"EXO 저자들은 reverse-KL preference optimization을 제안합니다. label_smoothing은 0.0보다 엄격히 커야 하며, 권장 값은 1e-3입니다(단순화된 pairwise 변형에 대해서는 Eq. 16을 참조하세요). 전체 방법은 K>2개의 SFT completions를 사용하며, K가 커질수록 PPO에 근접합니다.
"nca_pair"NCA의 저자들은 NCA가 상대적 확률(relative likelihood)이 아니라 각 응답에 대한 절대적 확률(absolute likelihood)을 최적화한다고 보여줍니다.
"robust"Robust DPO의 저자들은 노이즈가 있는 선호 데이터에서 편향 없는 DPO 손실을 제안합니다. DPOConfig에서 label_smoothing을 사용하여 레이블 플립 확률을 모델링할 수 있으며, 유효한 값은 [0.0, 0.5) 범위입니다.
"bco_pair"BCO의 저자들은 이진 분류기를 학습하며, 이 분류기의 logit을 보상(reward)으로 사용하여 {prompt, chosen completion} 쌍을 1로, {prompt, rejected completion} 쌍을 0으로 매핑하도록 합니다.
"sppo_hard"SPPO의 저자들은 SPPO가 선택된 보상을 1/2에 가깝게, 거부된 보상을 -1/2에 가깝게 조정하여 나시 균형을 반복적으로 해결할 수 있으며 데이터 희소성 문제를 완화할 수 있다고 주장합니다. 구현에서는 이 알고리즘을 근사하기 위해 하드 라벨 확률을 사용하여 승자에게 1, 패자에게 0을 할당합니다.
"aot" 또는 loss_type="aot_unpaired"AOT 저자들은 Optimal Transport를 통한 Distributional Preference Alignment를 제안합니다. loss_type="aot"는 페어링된 데이터에, loss_type="aot_unpaired"는 페어링되지 않은 데이터에 사용됩니다. 두 방식 모두 정렬된 quantile을 통해 stochastic dominance를 강제하며, GPU당 더 큰 배치 크기가 도움이 됩니다.
"apo_zero" 또는 loss_type="apo_down"APO 방법은 앵커링된 목적 함수를 도입합니다. apo_zero는 승자의 가중치를 높이고 패자의 가중치를 낮춥니다(모델이 승자보다 성능이 낮을 때 유용합니다). apo_down는 둘 다의 가중치를 낮추되 패자에게 더 강한 압력을 가합니다(모델이 이미 승자보다 성능이 좋을 때 유용합니다).
"discopop"DiscoPOP 논문은 LLM을 사용하여 더 효율적인 오프라인 선호도 최적화 손실을 발견합니다. 해당 논문에서 제안된 DiscoPOP 손실(로그 비율 변조 손실)은 IMDb 긍정 텍스트 생성, Reddit TLDR 요약, Alpaca Eval 2.0 등 다양한 작업에서 다른 최적화 손실보다 우수한 성능을 보였습니다.
"sft"SFT(Supervised Fine-Tuning) 손실은 선호하는 응답을 생성하도록 모델을 학습시키기 위해 사용되는 음의 로그 우도(negative log likelihood) 손실입니다.
"sigmoid_norm"SimPO의 저자들은 원래의 sigmoid loss에 존재하는 길이 편향을 비마스크 토큰 수로 정규화하여 해결하며, TRL에서는 이를 loss_type="sigmoid_norm"으로 제공합니다.
"udpo"UDPO의 저자들은 노이즈가 있는 선호 조건에서 편향 없는 DPO 손실을 제안합니다. 이 손실은 "robust"와 달리 플립 확률이 과대 추정되어도 편향이 유지되지 않습니다. DPOConfig의 label_smoothing를 사용하여 플립 확률 ε을 설정합니다. 유효한 값의 범위는 [0.0, 0.5)입니다.

기록된 지표

학습 및 평가 중에 다음 메트릭을 기록합니다:

  • global_step: 지금까지 수행된 옵티마이저 스텝의 총 개수.
  • epoch: 데이터셋 반복에 기반한 현재 epoch 번호
  • num_tokens: 지금까지 처리된 토큰의 총 개수.
  • loss: 현재 로깅 구간의 평균 DPO 손실.
  • entropy: 모델이 예측한 토큰 분포의 평균 엔트로피(마스크되지 않은 토큰 기준).
  • aux_loss: Mixture-of-Experts 모델의 로드 밸런싱 보조 손실입니다. router_aux_loss_coef로 스케일링되어 손실에 추가되기 전의 값입니다. 모델이 MoE 모델이고 router_aux_loss_coef가 0이 아닌 경우에만 기록됩니다.
  • mean_token_accuracy: 선택된 completion의 토큰과 모델의 top-1 예측이 일치하는 비마스크 토큰의 비율.
  • learning_rate: 현재 학습률입니다. 스케줄러를 사용하는 경우 동적으로 변경될 수 있습니다.
  • grad_norm: 그라디언트 클리핑 전에 계산된 그라디언트의 L2 노름.
  • logits/chosen: 모델이 선택된 완료의 토큰에 할당하는 평균 logit 값.
  • logits/rejected: 거부된 completion에 포함된 토큰에 모델이 할당하는 평균 logit 값.
  • logps/chosen: 모델이 선택된 완료의 토큰에 할당하는 평균 로그 확률입니다.
  • logps/rejected: 모델이 거부된 completion의 토큰에 할당하는 평균 log-probability입니다.
  • rewards/chosen: 선택된 completion에 대해 계산된 평균 implicit reward로, 다음과 같이 계산됩니다. βlog⁡πθ(y+ ⁣∣x)πref(y+ ⁣∣x) \beta \log \frac{\pi_{\theta}(y^{+}\!\mid x)}{\pi_{\mathrm{ref}}(y^{+}\!\mid x)} .
  • rewards/rejected: 거절된 completion에 대해 계산된 평균 implicit reward로, 다음과 같이 계산됩니다. βlog⁡πθ(y− ⁣∣x)πref(y− ⁣∣x) \beta \log \frac{\pi_{\theta}(y^{-}\!\mid x)}{\pi_{\mathrm{ref}}(y^{-}\!\mid x)} .
  • rewards/margins: 선택된 완료와 거부된 완료 사이의 평균 암시적 보상 마진입니다.
  • rewards/accuracies: 선택된 completion의 implicit reward가 거부된 completion의 implicit reward보다 높은 예시의 비율.

커스터마이징

호환성 및 제약

현재 DPOTrainer 구현에서는 일부 인자 조합이 의도적으로 제한되어 있습니다:

  • use_weighting=True는 loss_type="aot" 또는 loss_type="aot_unpaired"와 함께 사용할 수 없습니다.
  • lm_head를 대상으로 하는 PEPT 어댑터는 지원되지 않습니다(대신 modules_to_save=["lm_head"]를 사용하세요).
  • sync_ref_model=True는 독립적인 ref_model을 유지하지 않는 PEFT 모델로 학습할 때 지원되지 않습니다.
  • sync_ref_model=True는 precompute_ref_log_probs=True와 함께 사용할 수 없습니다.
  • precompute_ref_log_probs=True는 IterableDataset(train 또는 eval)과 함께 사용할 수 없습니다.

멀티-로스 조합

DPO trainer는 서로 다른 가중치를 가진 여러 손실 함수를 결합하는 것을 지원하여 더 정교한 최적화 전략을 가능하게 합니다. 이는 MPO(Mixed Preference Optimization)와 같은 알고리즘을 구현하는 데 특히 유용합니다. MPO는 Enhancing the Reasoning Ability of Multimodal Large Language Models via Mixed Preference Optimization 논문에서 설명된 바와 같이, 여러 최적화 목표를 결합하는 학습 접근법입니다.

여러 손실을 결합하려면 손실 유형과 해당 가중치를 리스트로 지정하세요:

# MPO: Combines DPO (sigmoid) for preference and BCO (bco_pair) for quality
training_args = DPOConfig(
    loss_type=["sigmoid", "bco_pair", "sft"],  # loss types to combine
    loss_weights=[0.8, 0.2, 1.0]  # corresponding weights, as used in the MPO paper
)

모델 초기화

from_pretrained() 메서드의 kwargs를 DPOConfig에 직접 전달할 수 있습니다. 예를 들어, 다른 정밀도로 모델을 로드하려면

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", dtype=torch.bfloat16)

model_init_kwargs={"dtype": torch.bfloat16} 인수를 DPOConfig에 전달하여 이를 수행할 수 있습니다.

from trl import DPOConfig

training_args = DPOConfig(
    model_init_kwargs={"dtype": torch.bfloat16},
)

from_pretrained()의 모든 키워드 인자가 지원되는 점에 유의하세요.

PEFT로 어댑터 학습

🤗 PEFT 라이브러리와 긴밀한 통합을 지원하여, 사용자는 전체 모델을 학습하는 대신 어댑터를 편리하게 학습하고 Hub에 공유할 수 있습니다.

from datasets import load_dataset
from trl import DPOTrainer
from peft import LoraConfig

dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

trainer = DPOTrainer(
    "Qwen/Qwen3-0.6B",
    train_dataset=dataset,
    peft_config=LoraConfig(),
)

trainer.train()

PeftModel의 학습을 계속할 수도 있습니다. 이를 위해 먼저 DPOTrainer 외부에서 PeftModel을 로드한 후, peft_config 인자를 전달하지 않고 trainer에 직접 전달합니다.

from datasets import load_dataset
from trl import DPOTrainer
from peft import AutoPeftModelForCausalLM

model = AutoPeftModelForCausalLM.from_pretrained("trl-lib/Qwen3-4B-LoRA", is_trainable=True)
dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

trainer = DPOTrainer(
    model=model,
    train_dataset=dataset,
)

trainer.train()

어댑터를 학습할 때는 새로운 매개변수만 학습되므로 전체 미세 조정보다 일반적으로 더 높은 학습률(≈1e‑5)을 사용합니다.

DPOConfig(learning_rate=1e-5, ...)

DPO를 위한 빠른 실험

RapidFire AI는 TRL 위에 구축된 오픈소스 실험 엔진으로, 단일 GPU에서도 여러 DPO 구성을 동시에 실행할 수 있습니다. 구성을 순차적으로 시도하는 대신, RapidFire는 재시작 없이 모든 학습 곡선을 더 일찍 확인하고, 성능이 낮은 실행을 중단하며, 유망한 실행을 새로운 설정으로 비행 중 복제할 수 있습니다. 자세한 내용은 RapidFire AI Integration을 참조하세요.

Unsloth로 학습

Unsloth는 LLM(Llama, Mistral, Gemma, DeepSeek 등)을 최대 2배 빠르게 학습하고 VRAM 사용량을 최대 70%까지 줄여주는 오픈소스 파인튜닝 및 강화 학습 프레임워크입니다. 학습, 평가, 배포를 위한 Hugging Face 호환 워크플로우를 제공합니다. 자세한 내용은 Unsloth Integration을 참조하세요.

DPO를 활용한 Tool Calling

DPOTrainer는 tool calling 기능이 있는 모델의 fine-tuning을 완전히 지원합니다. 이 경우, 각 데이터셋 예시에는 다음이 포함되어야 합니다:

  • 대화 메시지(프롬프트, 선택된 메시지, 거부된 메시지)에는 도구 호출(tool_calls) 및 도구 응답(tool 역할 메시지)이 포함됩니다.
  • tools 열에 있는 사용 가능한 도구 목록, 일반적으로 JSON 스키마로 제공됩니다

기대하는 데이터셋 구조에 대한 자세한 내용은 Dataset Format — Tool Calling 섹션을 참고하세요.

비전 언어 모델 학습

DPOTrainer은 Vision-Language Models(VLM) 학습을 완전히 지원합니다. VLM을 학습하려면 image 컬럼(샘플당 단일 이미지) 또는 images 컬럼(샘플당 이미지 목록)이 포함된 데이터셋을 제공해야 합니다. 예상되는 데이터셋 구조에 대한 자세한 내용은 Dataset Format — Vision Dataset 섹션을 참조하세요. 이러한 데이터셋의 예로는 RLAIF-V Dataset이 있습니다.

from trl import DPOConfig, DPOTrainer
from datasets import load_dataset

trainer = DPOTrainer(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    args=DPOConfig(max_length=None),
    train_dataset=load_dataset("HuggingFaceH4/rlaif-v_formatted", split="train"),
)
trainer.train()

VLM의 경우, 잘라내기(truncation)로 인해 이미지 토큰이 제거되어 학습 중 오류가 발생할 수 있습니다. 이를 방지하려면 DPOConfig에서 max_length=None을 설정하세요. 이렇게 하면 모델이 이미지 토큰을 잘라내지 않고 전체 시퀀스 길이를 처리할 수 있습니다.

DPOConfig(max_length=None, ...)

max_length은 데이터셋 전체에서 잘라내기(truncation)가 이미지 토큰을 제거하지 않는지 확인한 후에만 사용하세요.

DPOTrainer

클래스 trl.DPOTrainer

< >

( model: str | PreTrainedModel | PeftModelref_model: transformers.modeling_utils.PreTrainedModel | None = Noneargs: trl.trainer.dpo_config.DPOConfig | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = Nonecompute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)quantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = None )

매개변수

  • model (str 또는 PreTrainedModel 또는 PeftModel) — 학습할 모델. 다음 중 하나일 수 있습니다:
    • huggingface.co의 모델 저장소에 호스팅된 사전 학습 모델의 model id인 문자열, 또는 save_pretrained를 사용하여 모델 가중치를 저장한 디렉터리의 경로, 예: './my_model_directory/'입니다. 모델은 args.model_init_kwargs의 키워드 인수를 사용하여 <ModelArchitecture>.from_pretrained(여기서 <ModelArchitecture>는 모델 구성에서 파생됨)로 로드됩니다. args.model_init_kwargs에 dtype이 지정되지 않은 경우 기본값은 float32입니다. 이는 from_pretrained와 다르며, 후자의 경우(Transfomers v5부터) dtype은 모델 구성에서 추론됩니다.
    • PreTrainedModel 객체입니다. 인과적 언어 모델만 지원됩니다.
    • PeftModel 객체입니다. 인과 언어 모델만 지원됩니다.
  • ref_model (PreTrainedModel, 선택 사항) — 참조 로그 확률을 계산하는 데 사용되는 참조 모델입니다. 제공된 경우, 이 모델이 참조 정책으로 직접 사용됩니다. PeftModel일 수 없습니다. None인 경우, 트레이너는 DPO 학습이 시작되기 전의 모델 상태, 즉 model에 해당하는 초기 정책을 자동으로 사용합니다.
    • 제공된 경우, 이 모델은 참조 정책(reference policy)으로 직접 사용됩니다. PeftModel일 수 없습니다.
    • None인 경우, trainer는 DPO 학습이 시작되기 전의 모델 상태, 즉 model에 해당하는 초기 정책을 자동으로 사용합니다.
  • args (DPOConfig, 선택 사항) — 이 trainer의 설정입니다. None인 경우 기본 설정이 사용됩니다.
  • data_collator (DataCollator, 선택 사항) — 처리된 train_dataset 또는 eval_dataset 요소 목록에서 배치(batch)를 형성하는 데 사용할 함수입니다. 모델이 언어 모델인 경우 기본값은 DataCollatorForPreference이고, 비전-언어 모델인 경우 DataCollatorForVisionPreference입니다. 사용자 정의 collator는 패딩(padding) 전에 시퀀스를 잘라야 하며, trainer는 collation 후 truncation을 적용하지 않습니다.
  • train_dataset (Dataset 또는 IterableDataset) — 학습에 사용할 Dataset입니다. 이 trainer는 language modeling 형식과 prompt-completion 형식을 모두 지원합니다. 샘플의 형식은 다음과 같습니다:
    • Standard: 각 샘플에는 일반 텍스트가 포함됩니다.
    • 대화형: 각 샘플에는 구조화된 메시지(예: 역할 및 내용)가 포함됩니다.

    train_dataset이 IterableDataset(예: 스트리밍 데이터셋)인 경우, 그 길이를 추론할 수 없으므로 학습 루프를 제한하고 학습률 스케줄러를 구성하는 데 필요한 총 학습 단계 수를 지정하기 위해 학습 인자에 max_steps를 설정해야 합니다.

  • eval_dataset (Dataset, IterableDataset, DatasetDict, IterableDatasetDict 또는 dict[str, Dataset | IterableDataset]) — 평가에 사용할 Dataset입니다. train_dataset과 동일한 요구 사항을 충족해야 합니다.
  • processing_class (PreTrainedTokenizerBase 또는 ProcessorMixin, 선택 사항) — 데이터를 처리하는 데 사용되는 처리 클래스입니다. 패딩 쪽은 “left”로 설정해야 합니다. None인 경우, from_pretrained를 사용하여 모델 이름에서 처리 클래스를 로드합니다. 패딩 토큰인 tokenizer.pad_token이 설정되어 있어야 합니다. 처리 클래스에 패딩 토큰이 설정되지 않은 경우, tokenizer.eos_token이 기본값으로 사용됩니다.
  • compute_metrics (Callable[[EvalPrediction], dict], 선택 사항) — 평가 시 메트릭을 계산하는 데 사용되는 함수입니다. EvalPrediction를 인자로 받아 문자열에서 메트릭 값으로 매핑된 딕셔너리를 반환해야 합니다. SFTConfig에 batch_eval_metrics가 True로 설정된 경우, compute_metrics 함수는 불리언 compute_result 인자를 받아야 합니다. 이는 마지막 평가 배치 이후에 트리거되며, 함수가 배치 수준의 통계를 누적하는 대신 전역 요약 통계를 계산하고 반환해야 함을 나타냅니다. 이 함수가 받는 로짓은 추가적인 포워드 패스로 다시 계산됩니다. 이 기능은 비추천(deprecated) 상태이며 v2.0.0에서 제거될 예정입니다.
  • callbacks (의 목록 TrainerCallback, 선택 사항) — 학습 루프를 사용자 정의할 콜백 목록입니다. 여기.

    기본으로 사용되는 콜백 중 하나를 제거하려면 remove_callback 메서드를 사용하세요.

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], 선택 사항, 기본값 (None, None)) — 사용할 옵티마이저와 스케줄러를 포함하는 튜플입니다. 기본적으로 모델에 AdamW 인스턴스와 args에 의해 제어되는 get_linear_schedule_with_warmup로 생성된 스케줄러를 사용합니다.
  • quantization_config (BitsAndBytesConfig, 선택 사항) — 모델 식별자로부터 모델을 로드할 때 사용되는 양자화 구성입니다. QLoRA 학습을 위해 peft_config와 함께 사용하세요. 모델이 이미 인스턴스화되어 있으면 무시됩니다.
  • peft_config (PeftConfig, 선택 사항) — 모델을 래핑하는 데 사용되는 PEFT 구성입니다. None인 경우 모델은 래핑되지 않습니다.

Direct Preference Optimization (DPO) 방법용 Trainer입니다. 이 알고리즘은 Direct Preference Optimization: Your Language Model is Secretly a Reward Model 논문에서 처음 제안되었습니다. 이 클래스는 Trainer 클래스를 래핑하며, 해당 클래스의 모든 속성과 메서드를 상속합니다.

예:

>>> from trl import DPOTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

>>> trainer = DPOTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     train_dataset=dataset,
... )
>>> trainer.train()

train

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

매개변수

  • 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

< >

( output_dir: str | None = None_internal_call: bool = False )

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

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

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

매개변수

  • commit_message (str, 선택 사항, 기본값 "End of training") — 푸시할 때 커밋할 메시지입니다.
  • blocking (bool, 선택 사항, 기본값 True) — git push가 완료된 후에만 함수가 반환되어야 하는지 여부.
  • token (str, 선택 사항, 기본값 None) — Trainer의 원래 args를 덮어쓸 수 있는 쓰기 권한이 있는 토큰.
  • revision (str, 선택 사항) — 커밋할 git revision입니다. 기본값은 “main” 브랜치의 head입니다.
  • private (bool, 선택 사항) — 리포지토리가 생성될 때 비공개로 만들지 여부입니다. 기본값은 args.hub_private_repo입니다. 리포지토리가 이미 존재하는 경우 효과가 없습니다.
  • kwargs (dict[str, Any], 선택) — ~Trainer.create_model_card에 함께 전달되는 추가 키워드 인자입니다.

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

DPOConfig

클래스 trl.DPOConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool = Truegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 10logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Falserestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Truelabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonetrust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonedisable_dropout: bool = Truedataset_num_proc: int | None = Nonemax_length: int | None = 1024truncation_mode: str = 'keep_start'padding_free: bool = Falsepad_to_multiple_of: int | str | None = 'auto'precompute_ref_log_probs: bool = Falseprecompute_ref_batch_size: int | None = Noneloss_type: list[str] = <factory>loss_weights: list[float] | None = Noneld_alpha: float | None = Nonef_divergence_type: str = 'reverse_kl'f_alpha_divergence_coef: float = 0.5label_smoothing: float = 0.0beta: float = 0.1use_weighting: bool = Falsediscopop_tau: float = 0.05activation_offloading: bool = Falsesync_ref_model: bool = Falseref_model_mixup_alpha: float = 0.6ref_model_sync_steps: int = 512pad_token: str | None = None )

모델을 제어하는 매개변수

  • model_init_kwargs (dict[str, Any], 선택) — model 인수가 DPOTrainer에 문자열로 제공될 때 from_pretrained에 사용되는 키워드 인수입니다. revision 값은 처리 클래스를 로드할 때에도 사용됩니다.
  • trust_remote_code (bool, optional, defaults to False) — Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to from_pretrained and from_pretrained.
  • router_aux_loss_coef (float, 선택 사항) — Mixture-of-Experts(MoE) 모델의 로드 밸런싱 보조 손실 계수로, 이 가중치로 학습 손실에 추가됩니다. 설정되지 않으면 모델 구성에서 선언된 값이 사용됩니다. 비활성화하려면 0.0으로 설정하세요. MoE가 아닌 모델과 함께 사용하면 실패합니다.
  • disable_dropout (bool, 선택 사항, 기본값 True) — 모델과 참조 모델에서 dropout을 비활성화할지 여부입니다.

데이터 전처리를 제어하는 매개변수

  • dataset_num_proc (int, 선택 사항) — 데이터셋 처리에 사용할 프로세스 수.
  • max_length (int 또는 None, 선택 사항, 기본값 1024) — 토큰화 시퀀스의 최대 길이입니다. max_length보다 긴 시퀀스는 truncation_mode에 따라 왼쪽 또는 오른쪽에서 잘립니다. None인 경우 잘라내기가 적용되지 않습니다.
  • truncation_mode (str, 선택 사항, 기본값 "keep_start") — 시퀀스가 max_length를 초과할 때 사용할 절단 모드입니다. 지원되는 유일한 값은 "keep_start"입니다. "keep_end" 값은 비추천(deprecated) 상태이며 v2.0.0에서 제거될 예정입니다.
  • padding_free (bool, 선택 사항, 기본값 False) — 패딩 없이 모든 시퀀스를 단일 연속 시퀀스로 평탄화하여 포워드 패스를 수행할지 여부입니다. 이는 패딩 오버헤드를 제거하여 메모리 사용량을 줄입니다. 현재 이 기능은 평탄화된 배치 구조를 효율적으로 처리할 수 있는 FlashAttention 2 또는 3에서만 지원됩니다. 일시적으로 사용 불가: DPO 리팩토링 이후 True로 설정하면 경고가 표시되고 표준 패딩으로 폴백됩니다. 향후 업데이트에서 복원될 예정입니다.
  • pad_to_multiple_of (int 또는 str, 선택 사항, 기본값 "auto") — 설정된 경우, 시퀀스는 해당 값의 배수로 패딩됩니다. "auto"는 Neuron(AWS Trainium)에서 입력 형식별로 한 번씩 컴파일되므로 128의 배수로 패딩하며, 다른 환경에서는 패딩하지 않습니다.
  • precompute_ref_log_probs (bool, 선택 사항, 기본값 False) — 학습 전에 전체 학습 데이터셋에 대한 참조 모델의 로그 확률을 미리 계산할지 여부입니다. 참조 모델을 메모리에 유지할 필요가 없으므로 학습 중 메모리를 절약할 수 있습니다.
  • precompute_ref_batch_size (int, 선택 사항) — 참조 모델의 로그 확률을 사전 계산할 때 사용할 배치 크기입니다. 전처리 속도를 높이기 위해 학습 배치 크기보다 크게 설정할 수 있습니다. None인 경우, 학습에는 per_device_train_batch_size, 평가에는 per_device_eval_batch_size가 기본값으로 사용됩니다.

학습을 제어하는 매개변수

  • loss_type (list[str], 선택 사항, 기본값 ["sigmoid"]) — 사용할 손실 함수의 유형입니다. 가능한 값은 다음과 같습니다: 'sigmoid', 'hinge', 'ipo', 'exo_pair', 'nca_pair', 'robust', 'bco_pair', 'sppo_hard', 'aot', 'aot_unpaired', 'apo_zero', 'apo_down', 'discopop', 'sft', 'sigmoid_norm', 'udpo'. 여러 손실 유형을 지정하면 loss_weights에 지정된 가중치를 사용하여 결합됩니다.
  • loss_weights (list[float], 선택 사항) — 멀티 로스 조합을 위한 로스 가중치 목록입니다. 여러 로스 유형을 조합할 때 사용됩니다. 예: MPO의 경우 [0.8, 0.2, 1.0]. 제공되지 않으면 모든 로스 유형에 대해 동일한 가중치(1.0)가 기본값으로 사용됩니다.
  • ld_alpha (float, 선택 사항) — LD-DPO 논문에서 α 파라미터로, 응답 내에서 상세한 토큰의 로그 확률(log-probabilities) 가중치를 제어합니다. None인 경우 상세한 부분에 가중치가 적용되지 않으며, 손실은 표준 DPO 손실과 동일해집니다. 값은 [0.0, 1.0] 범위여야 합니다: ld_alpha=1.0은 가중치를 적용하지 않으며, ld_alpha=0.0은 공유 길이 이후의 토큰을 마스킹합니다.
  • f_divergence_type (str, 선택 사항, 기본값 "reverse_kl") — 정책과 참조 모델 사이의 f-divergence 정규화 항(f-DPO 논문). 가능한 값은 다음과 같습니다: reverse_kl (기본값), forward_kl, js_divergence, alpha_divergence. 선택-거절 보상 차이에 기반한 손실 유형만 기본값이 아닌 값을 지원합니다: 'sigmoid', 'sigmoid_norm', 'hinge', 'ipo', 'exo_pair', 'robust', 'discopop', 'sft', 'udpo'. 다른 손실 유형에는 유효한 f-divergence 일반화가 없으므로 기본값이 아닌 값은 거부됩니다.
  • f_alpha_divergence_coef (float, 선택 사항, 기본값 0.5) — f_divergence_type='alpha_divergence'일 때만 사용되는 u^-α 정규화 항의 α 계수입니다.
  • label_smoothing (float, 선택 사항, 기본값 0.0) — Robust DPO, UDPO 및 EXO에서 사용되는 Label smoothing 매개변수입니다. Robust DPO와 UDPO에서는 선호도 레이블이 뒤집힐 확률 ε로 해석되며, 값은 [0.0, 0.5) 범위에 있어야 합니다. Robust DPO 논문에서 권장하는 일반적인 값은 0.1입니다. UDPO에서는 a = ε / (1 - ε)를 설정하는 데 사용되며, UDPO 논문에서는 a = 0.8, 즉 ε = 4/9를 권장합니다. EXO에서는 ε label smoothing 매개변수에 해당하며, 해당 논문에서는 일반적인 값으로 1e-3을 권장합니다.
  • beta (float, 선택 사항, 기본값 0.1) — 참조 모델과의 편차를 제어하는 매개변수입니다. β 값이 높을수록 참조 모델로부터의 편차가 작아집니다. IPO 손실(loss_type='ipo')의 경우, 이 값은 논문에서 τ로 표기된 정규화 매개변수입니다.
  • use_weighting (bool, 선택 사항, 기본값 False) — 정책의 길이 정규화 시퀀스 확률을 사용하여 선호 쌍에 WPO 스타일의 가중치를 적용할지 여부입니다.
  • discopop_tau (float, 선택 사항, 기본값 0.05) — DiscoPOP 논문에서 제시한 τ/temperature 파라미터로, loss_type='discopop'를 사용할 때 log-ratio modulated loss의 형태를 제어합니다. 해당 논문에서는 기본값 discopop_tau=0.05를 권장합니다.
  • activation_offloading (bool, 선택 사항, 기본값 False) — 활성화를 CPU로 오프로딩할지 여부입니다.
  • sync_ref_model (bool, 선택 사항, 기본값 False) — ref_model_sync_steps 스텝마다 ref_model_mixup_alpha 매개변수를 사용하여 참조 모델을 활성 모델과 동기화할지 여부입니다. 이 동기화 방식은 TR-DPO 논문에서 유래했습니다. sync_ref_model=True는 아직 PEFT 또는 precompute_ref_log_probs=True와 호환되지 않습니다.
  • ref_model_mixup_alpha (float, 선택 사항, 기본값 0.6) — TR-DPO 논문에서 가져온 α 파라미터로, 업데이트 과정에서 현재 정책과 이전 참조 정책 간의 혼합을 제어합니다. 참조 정책은 다음 방정식에 따라 업데이트됩니다: π_ref = α * π_θ + (1 - α) * π_ref_prev. 이 파라미터를 사용하려면 sync_ref_model=True를 설정해야 합니다.
  • ref_model_sync_steps (int, 선택 사항, 기본값 512) — TR-DPO 논문에서 제시한 τ 파라미터로, 현재 정책이 참조 정책과 얼마나 자주 동기화되는지를 결정합니다. 이 파라미터를 사용하려면 sync_ref_model=True를 설정해야 합니다.

비추천되는 매개변수

  • pad_token —

    pad_token 매개변수는 비추천(deprecated)되며 v2.0.0 버전에서 제거됩니다. 대신 tokenizer.pad_token을 직접 설정하고 trainer에 processing_class로 전달하세요.

DPOTrainer의 구성 클래스입니다.

이 클래스에는 DPO 학습에 특화된 매개변수만 포함되어 있습니다. 학습 인자의 전체 목록은 TrainingArguments 문서를 참고하세요. 이 클래스의 기본값은 TrainingArguments의 기본값과 다를 수 있습니다.

HfArgumentParser를 사용하면 이 클래스를 커맨드 라인에서 지정할 수 있는 argparse 인수로 변환할 수 있습니다.

이러한 파라미터는 TrainingArguments와 다른 기본값을 가집니다:

  • logging_steps: 기본값이 500 대신 10입니다.
  • gradient_checkpointing: 기본값이 False가 아닌 True입니다.
  • bf16: fp16가 설정되지 않은 경우 기본값이 False가 아닌 True입니다.
  • learning_rate: 기본값이 5e-5 대신 1e-6입니다.
Update on GitHub