SFT Trainer

개요

TRL은 언어 모델 학습을 위한 Supervised Fine-Tuning (SFT) Trainer를 지원합니다.

SFTTrainer는 DiffusionGemma와 같은 diffusion 모델을 기본적으로 지원하지 않지만, block-diffusion SFT 예제를 참고하여 쉽게 확장할 수 있습니다.

이 포스트 트레이닝 방법은 Younes Belkada가 기여했습니다.

빠른 시작

이 예제는 TRL의 SFTTrainer를 사용하여 언어 모델을 학습하는 방법을 보여줍니다. 추론 및 일반화 성능을 벤치마킹하기 위한 컴팩트하고 다양한 다중 턴 데이터셋인 Capybara dataset에서 Qwen 3 0.6B 모델을 학습합니다.

from trl import SFTTrainer
from datasets import load_dataset

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

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

SFT는 language modeling과 prompt-completion 데이터셋을 모두 지원합니다. SFTTrainer는 standard 및 conversational 데이터셋 형식과 모두 호환됩니다. conversational 데이터셋이 제공되면, trainer는 데이터셋에 chat template을 자동으로 적용합니다.

# Standard language modeling
{"text": "The sky is blue."}

# Conversational language modeling
{"messages": [{"role": "user", "content": "What color is the sky?"},
              {"role": "assistant", "content": "It is blue."}]}

# Standard prompt-completion
{"prompt": "The sky is",
 "completion": " blue."}

# Conversational prompt-completion
{"prompt": [{"role": "user", "content": "What color is the sky?"}],
 "completion": [{"role": "assistant", "content": "It is blue."}]}

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

from datasets import load_dataset

dataset = load_dataset("FreedomIntelligence/medical-o1-reasoning-SFT", "en")

def preprocess_function(example):
    return {
        "prompt": [{"role": "user", "content": example["Question"]}],
        "completion": [
            {"role": "assistant", "content": f"<think>{example['Complex_CoT']}</think>{example['Response']}"}
        ],
    }

dataset = dataset.map(preprocess_function, remove_columns=["Question", "Response", "Complex_CoT"])
print(next(iter(dataset["train"])))

{
    "prompt": [
        {
            "content": "Given the symptoms of sudden weakness in the left arm and leg, recent long-distance travel, and the presence of swollen and tender right lower leg, what specific cardiac abnormality is most likely to be found upon further evaluation that could explain these findings?",
            "role": "user",
        }
    ],
    "completion": [
        {
            "content": "<think>Okay, let's see what's going on here. We've got sudden weakness [...] clicks into place!</think>The specific cardiac abnormality most likely to be found in [...] the presence of a PFO facilitating a paradoxical embolism.",
            "role": "assistant",
        }
    ],
}

SFT 방법 자세히 살펴보기

Supervised Fine-Tuning (SFT)은 언어 모델을 대상 데이터셋에 맞게 조정하는 가장 단순하고 가장 일반적으로 사용되는 방법입니다. 모델은 입력 및 출력 시퀀스의 쌍을 사용하여 완전히 감독된 방식으로 학습됩니다. 목표는 입력을 조건으로 하여 대상 시퀀스의 negative log-likelihood(NLL)를 최소화하는 것입니다.

이 섹션에서는 전처리, 토큰화, 손실 계산라는 핵심 단계를 다루며 SFT가 실제로 어떻게 작동하는지 설명합니다.

전처리 및 토큰화

학습 중에는 데이터셋 형식에 따라 각 예시에 text 필드 또는 (prompt, completion) 쌍이 포함되도록 기대됩니다. 기대되는 형식에 대한 자세한 내용은 Dataset formats를 참조하세요. SFTTrainer는 모델의 tokenizer를 사용하여 각 입력을 토큰화합니다. prompt와 completion이 별도로 제공되는 경우, 토큰화 전에 이 둘이 연결됩니다.

손실 계산

sft_figure

SFT에서 사용되는 손실 함수는 토큰 수준의 교차 엔트로피 손실, 이며, 다음과 같이 정의됩니다: $\mathcal{L}_{\text{SFT}}(\theta) = - \sum_{t=1}^{T} \log p_\theta(y_t \mid y_{<t}),$

여기서 $y_t$ 은 시간 단계 $t$ , 에서의 대상 토큰이며, 모델은 이전 토큰을 조건으로 다음 토큰을 예측하도록 학습됩니다. 실제로 손실 계산 시 패딩 토큰은 마스킹됩니다.

On the Generalization of SFT: A Reinforcement Learning Perspective with Reward Rectification 논문은 보상 신호를 교정하여 일반화 성능을 향상시키는 것을 목표로 하는 대안 손실 함수인 Dynamic Fine-Tuning (DFT)을 제안합니다. 이 방법은 SFTConfig에서 loss_type="dft"를 설정하여 활성화할 수 있습니다. 자세한 내용은 Paper Index - Dynamic Fine-Tuning을 참고하세요.

레이블 시프트 및 마스킹

학습 중에 손실은 one-token shift를 사용하여 계산됩니다: 모델은 시퀀스에서 각 토큰을 모든 이전 토큰을 기반으로 예측하도록 학습됩니다. 구체적으로, 입력 시퀀스는 오른쪽으로 한 위치만큼 이동되어 대상 라벨을 형성합니다. 패딩 토큰(존재하는 경우)은 해당 위치에 무시 인덱스(기본값: -100)를 적용하여 손실 계산에서 무시됩니다. 이를 통해 손실이 의미 있는, 패딩이 아닌 토큰에만 초점을 맞추도록 보장됩니다.

기록된 지표

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

global_step: 지금까지 수행된 옵티마이저 스텝의 총 개수.
epoch: 데이터셋 반복에 기반한 현재 epoch 번호
num_tokens: 지금까지 처리된 토큰의 총 개수.
loss: 현재 로깅 구간의 마스킹되지 않은 토큰에 대해 계산된 평균 교차 엔트로피 손실.
entropy: 모델이 예측한 토큰 분포의 평균 엔트로피(마스크되지 않은 토큰 기준).
aux_loss: Mixture-of-Experts 모델의 로드 밸런싱 보조 손실입니다. router_aux_loss_coef로 스케일링되어 손실에 추가되기 전의 값입니다. 모델이 MoE 모델이고 router_aux_loss_coef가 0이 아닌 경우에만 기록됩니다.
mean_token_accuracy: 모델의 top-1 예측이 ground truth 토큰과 일치하는 non-masked 토큰의 비율.
learning_rate: 현재 학습률입니다. 스케줄러를 사용하는 경우 동적으로 변경될 수 있습니다.
grad_norm: 그라디언트 클리핑 전에 계산된 그라디언트의 L2 노름.

커스터마이징

모델 초기화

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

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

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

from trl import SFTConfig

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

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

패킹

SFTTrainer는 여러 예시를 동일한 입력 시퀀스에 패킹하여 학습 효율을 높이는 예시 패킹을 지원합니다. 패킹을 활성화하려면 SFTConfig 생성자에 packing=True를 전달하면 됩니다.

training_args = SFTConfig(packing=True)

패킹에 대한 자세한 내용은 Packing을 참조하세요.

assistant 메시지에서만 학습

assistant 메시지만으로 학습하려면 conversational 데이터셋을 사용하고 SFTConfig에서 assistant_only_loss=True를 설정하세요. 이 설정은 loss가 user 또는 system 메시지를 무시하고 assistant 응답에만 계산되도록 보장합니다.

training_args = SFTConfig(assistant_only_loss=True)

train_on_assistant

이 기능은 채팅 템플릿에 {% generation %} 및 {% endgeneration %} 키워드가 포함되어 있어야 합니다. 알려진 모델 계열(예: Qwen3)의 경우, assistant_only_loss=True일 때 TRL이 템플릿을 자동으로 패치합니다. 번들된 학습 템플릿의 전체 목록은 Chat Templates을 참조하세요. 기타 모델의 경우, 채팅 템플릿에 해당 키워드가 포함되어 있는지 확인하세요. 예시는 HuggingFaceTB/SmolLM3-3B를 참조하세요.

비전 데이터셋을 사용하는 경우, 어시스턴트 전용 손실은 transformers>=5.18.0과 대화형 언어 모델링 데이터셋이 필요합니다.

완료 시에만 학습

완료 부분만 학습하려면 prompt-completion 데이터셋을 사용하세요. 기본적으로 trainer는 프롬프트 토큰을 무시하고 완료 토큰에만 대해 손실을 계산합니다. 전체 시퀀스에 대해 학습하려면 SFTConfig에서 completion_only_loss=False를 설정하세요.

from trl import SFTConfig, SFTTrainer
from datasets import load_dataset

# Load a prompt-completion dataset; loss is computed on the completion only by default
dataset = load_dataset("trl-lib/kto-mix-14k", split="train")

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    args=SFTConfig(completion_only_loss=True),  # True by default for prompt-completion datasets
    train_dataset=dataset,
)
trainer.train()

train_on_completion

completion만 대상으로 하는 학습은 assistant 메시지만 대상으로 하는 학습과 호환됩니다. 이 경우 conversational prompt-completion 데이터셋을 사용하고 SFTConfig에서 assistant_only_loss=True를 설정합니다.

PEFT로 어댑터 학습

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

from datasets import load_dataset
from trl import SFTTrainer
from peft import LoraConfig

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

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

trainer.train()

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

from datasets import load_dataset
from trl import SFTTrainer
from peft import AutoPeftModelForCausalLM

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

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

trainer.train()

어댑터를 학습할 때는 새로운 매개변수만 학습되므로 일반적으로 더 높은 학습률(≈1e‑4)을 사용합니다.
SFTConfig(learning_rate=1e-4, ...)

SFT를 위한 빠른 실험

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

Unsloth로 학습

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

지시 튜닝 예제

Instruction tuning은 기본 언어 모델이 사용자 지시를 따르고 대화에 참여하도록 학습시킵니다. 이를 위해 다음이 필요합니다:

채팅 템플릿: 역할 마커(user/assistant), 특수 토큰, 턴 경계 등을 포함하여 대화를 텍스트 시퀀스로 구조화하는 방식을 정의합니다. Chat templates에서 채팅 템플릿에 대해 자세히 알아보세요.
대화형 데이터셋: 지시-응답 쌍을 포함합니다

이 예제는 Capybara dataset과 HuggingFaceTB/SmolLM3-3B의 chat template를 사용하여 Qwen 3 0.6B Base 모델을 지시 따르기(instruction-following) 모델로 변환하는 방법을 보여줍니다. SFT Trainer는 토크나이저 업데이트와 특수 토큰 구성을 자동으로 처리합니다.

from trl import SFTConfig, SFTTrainer
from datasets import load_dataset

trainer = SFTTrainer(
    model="Qwen/Qwen3-0.6B-Base",
    args=SFTConfig(
        output_dir="Qwen3-0.6B-Instruct",
        chat_template_path="HuggingFaceTB/SmolLM3-3B",
    ),
    train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()

Qwen과 같은 일부 베이스 모델은 모델의 토크나이저에 미리 정의된 채팅 템플릿을 포함합니다. 이러한 경우 토크나이저가 이미 포맷팅을 처리하므로 clone_chat_template()을 적용할 필요가 없습니다. 그러나 모델의 응답이 올바르게 종료되도록 보장하려면 EOS 토큰을 채팅 템플릿과 일치시켜야 합니다. 이러한 경우 SFTConfig에서 eos_token을 지정해야 하며, 예를 들어 Qwen/Qwen2.5-1.5B의 경우 eos_token="<|im_end|>"로 설정해야 합니다.

학습이 완료되면, 모델은 이제 새로운 채팅 템플릿을 사용하여 지시를 따르고 대화에 참여할 수 있습니다.

>>> from transformers import pipeline
>>> pipe = pipeline("text-generation", model="Qwen3-0.6B-Instruct/checkpoint-5000")
>>> prompt = "<|im_start|>user\nWhat is the capital of France? Answer in one word.<|im_end|>\n<|im_start|>assistant\n"
>>> response = pipe(prompt)
>>> response[0]["generated_text"]
'<|im_start|>user\nWhat is the capital of France? Answer in one word.<|im_end|>\n<|im_start|>assistant\nThe capital of France is Paris.'

대신 구조화된 대화 형식(권장)을 사용하세요:

>>> prompt = [{"role": "user", "content": "What is the capital of France? Answer in one word."}]
>>> response = pipe(prompt)
>>> response[0]["generated_text"]
[{'role': 'user', 'content': 'What is the capital of France? Answer in one word.'}, {'role': 'assistant', 'content': 'The capital of France is Paris.'}]

SFT를 활용한 Tool Calling

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

도구 호출(tool_calls) 및 도구 응답(tool 역할 메시지)을 포함한 대화 메시지
tools 열에 있는 사용 가능한 도구 목록, 일반적으로 JSON 스키마로 제공됩니다

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

비전 언어 모델 학습

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

from trl import SFTConfig, SFTTrainer
from datasets import load_dataset

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    args=SFTConfig(max_length=None),
    train_dataset=load_dataset("trl-lib/llava-instruct-mix", split="train"),
)
trainer.train()

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

SFTTrainer

클래스 trl.SFTTrainer

< source >

( model: str | PreTrainedModel | PeftModelargs: trl.trainer.sft_config.SFTConfig | transformers.training_args.TrainingArguments | 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_loss_func: collections.abc.Callable | 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)optimizer_cls_and_kwargs: tuple[type[torch.optim.Optimizer], dict[str, typing.Any]] | None = Nonepreprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = Nonequantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = Noneformatting_func: collections.abc.Callable[[dict], str] | 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 객체입니다. 인과 언어 모델만 지원됩니다.
args (SFTConfig, 선택 사항) — 이 trainer에 대한 설정입니다. None인 경우 기본 설정이 사용됩니다.
data_collator (DataCollator, 선택 사항) — 처리된 train_dataset 또는 eval_dataset 요소 목록에서 배치(batch)를 형성하는 데 사용할 함수입니다. 기본값은 DataCollatorForLanguageModeling이며, 데이터셋에 이미지가 포함된 경우 DataCollatorForVisionLanguageModeling이 됩니다.
train_dataset (Dataset 또는 IterableDataset) — 학습에 사용할 Dataset입니다. 이 trainer는 language modeling 형식과 prompt-completion 형식을 모두 지원합니다. 샘플의 형식은 다음과 같습니다:
- Standard: 각 샘플에는 일반 텍스트가 포함됩니다.
- 대화형: 각 샘플에는 구조화된 메시지(예: 역할 및 내용)가 포함됩니다.
Trainer는 필수 input_ids 컬럼으로 식별되는 사전 토큰화 데이터셋도 지원합니다. 선택적 labels 컬럼(-100은 손실 계산에서 제외된 토큰에 사용됨)이 존재하면 그대로 사용되고, 그렇지 않으면 선택적 assistant_masks / completion_mask 컬럼(이후 접합된 뒤 제거되며, completion_mask는 completion_only_loss=True인 경우에만)을 기반으로 labels가 생성되거나, 기본적으로 input_ids의 복사본으로 설정됩니다. 시퀀스는 준비 단계에서 max_length로 잘립니다. skip_prepare_dataset=True인 경우 준비 단계가 건너뛰어지고, collator가 데이터셋을 그대로 처리할 것으로 기대됩니다.

train_dataset이 IterableDataset(예: 스트리밍 데이터셋)인 경우, 그 길이를 추론할 수 없으므로 학습 루프를 제한하고 학습률 스케줄러를 구성하는 데 필요한 총 학습 단계 수를 지정하기 위해 학습 인자에 max_steps를 설정해야 합니다.
eval_dataset (Dataset, IterableDataset, DatasetDict, IterableDatasetDict 또는 dict[str, Dataset | IterableDataset]) — 평가에 사용할 Dataset입니다. train_dataset과 동일한 요구 사항을 충족해야 합니다.
processing_class (PreTrainedTokenizerBase, ProcessorMixin, 선택 사항) — 데이터를 처리하는 데 사용되는 처리 클래스입니다. None인 경우, from_pretrained를 사용하여 모델 이름에서 처리 클래스를 로드합니다. 패딩 토큰인 tokenizer.pad_token이 설정되어 있어야 합니다. 처리 클래스에 패딩 토큰이 설정되지 않은 경우, tokenizer.eos_token이 기본값으로 사용됩니다.
compute_loss_func (Callable, 선택 사항) — 모델 출력, 라벨, 그리고 누적 배치 전체의 항목 수(batch_size * gradient_accumulation_steps)를 받아 손실을 반환하는 함수입니다. 이 항목은 비추천(deprecated)되며 v2.0.0에서 제거될 예정입니다: 대신 SFTTrainer를 서브클래스로 상속받아 compute_loss를 오버라이드하세요.
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로 생성된 스케줄러를 사용합니다.
optimizer_cls_and_kwargs (tuple[Type[torch.optim.Optimizer], Dict[str, Any]], 선택 사항) — 사용할 옵티마이저 클래스와 키워드 인수를 포함하는 튜플입니다. optim 과 optim_args 의 args. 을(를) 덮어씁니다. optimizers 인수와 호환되지 않습니다.
optimizers와 달리, 이 인수는 Trainer를 초기화하기 전에 모델 매개변수를 올바른 장치에 배치할 필요가 없도록 합니다.
preprocess_logits_for_metrics (Callable[[torch.Tensor, torch.Tensor], torch.Tensor], 선택 사항) — 평가 단계마다 logits를 캐시하기 직전에 전처리하는 함수입니다. logits와 labels라는 두 개의 텐서를 받아야 하며, 원하는 방식으로 처리된 logits를 반환해야 합니다. 이 함수가 수행한 수정 사항은 compute_metrics.
데이터셋에 라벨이 없는 경우 라벨(두 번째 매개변수)은 None이 됩니다.
quantization_config (BitsAndBytesConfig, 선택 사항) — 모델 식별자로부터 모델을 로드할 때 사용되는 양자화 구성입니다. QLoRA 학습을 위해 peft_config와 함께 사용하세요. 모델이 이미 인스턴스화되어 있으면 무시됩니다.
peft_config (PeftConfig, 선택 사항) — 모델을 래핑하는 데 사용되는 PEFT 구성입니다. None인 경우 모델은 래핑되지 않습니다.
formatting_func (Callable, 선택 사항) — 토큰화 전에 데이터셋에 적용되는 포맷팅 함수. 포맷팅 함수를 명시적으로 적용하면 데이터셋이 language modeling 유형으로 변환됩니다.

Supervised Fine-Tuning (SFT) 방법용 Trainer.

이 클래스는 Trainer 클래스를 래핑한 것으로, 해당 클래스의 모든 속성과 메서드를 상속합니다.

예:

>>> from trl import SFTTrainer
>>> from datasets import load_dataset

>>> dataset = load_dataset("roneneldan/TinyStories", split="train[:1%]")

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

train

< source >

매개변수

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

< source >

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

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

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

push_to_hub

< source >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | 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입니다.
kwargs (dict[str, Any], 선택) — ~Trainer.create_model_card에 함께 전달되는 추가 키워드 인자입니다.

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

SFTConfig

클래스 trl.SFTConfig

< source >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 2e-05lr_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 = 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 = Nonechat_template_path: str | None = Nonedataset_text_field: str = 'text'dataset_kwargs: dict[str, typing.Any] | str | None = Nonedataset_num_proc: int | None = Noneeos_token: str | None = Nonemax_length: int | None = 1024truncation_mode: str = 'keep_start'shuffle_dataset: bool = Falsepacking: bool = Falsepacking_strategy: str = 'bfd'padding_free: bool = Falsepad_to_multiple_of: int | str | None = 'auto'eval_packing: bool | None = Nonecompletion_only_loss: bool | None = Noneassistant_only_loss: bool = Falseloss_type: str = 'nll'activation_offloading: bool = Falsepad_token: str | None = None )

모델을 제어하는 매개변수

model_init_kwargs (dict[str, Any], 선택) — model 인수가 SFTTrainer에 문자열로 제공될 때 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가 아닌 모델과 함께 사용하면 실패합니다.
chat_template_path (str, 선택 사항) — 지정된 경우, 모델의 chat template을 설정합니다. 이는 토크나이저의 경로(로컬 디렉터리 또는 Hugging Face Hub 모델)이거나 Jinja template 파일의 직접 경로일 수 있습니다. Jinja 파일을 사용하는 경우, template에서 참조하는 특수 토큰이 토크나이저에 추가되었는지, 그리고 모델의 embedding layer가 이에 맞게 조정되었는지 확인해야 합니다.

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

dataset_text_field (str, 선택 사항, 기본값 "text") — 데이터셋에서 텍스트 데이터를 포함하는 열의 이름.
dataset_kwargs (dict[str, Any], 선택) — 데이터셋 준비를 위한 선택적 키워드 인수의 사전입니다. 지원되는 유일한 키는 skip_prepare_dataset입니다. 데이터셋에 이미지가 포함된 경우, 전처리가 온더플라이로 수행되므로 skip_prepare_dataset는 제공된 값과 관계없이 자동으로 True로 처리됩니다.
dataset_num_proc (int, 선택 사항) — 데이터셋 처리에 사용할 프로세스 수.
eos_token (str, 선택 사항) — 턴 또는 시퀀스의 끝을 나타내는 데 사용되는 토큰입니다. None인 경우 기본값은 processing_class.eos_token입니다.
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에서 제거될 예정입니다.
shuffle_dataset (bool, 선택 사항, 기본값 False) — 데이터셋을 섞을지 여부.
packing (bool, 선택 사항, 기본값 False) — 계산 효율성을 높이고 패딩을 줄이기 위해 여러 시퀀스를 고정 길이 블록으로 묶을지 여부입니다. max_length를 사용하여 시퀀스 길이를 정의합니다.
packing_strategy (str, 선택 사항, 기본값 "bfd") — 시퀀스를 패킹하는 전략입니다. "bfd" (best-fit decreasing, 오버플로우를 잘라냄), "bfd_split" (best-fit decreasing, 오버플로우 시퀀스를 분할), 또는 "wrapped" (적극적, 시퀀스 중간에서 잘라냄) 중 하나를 사용할 수 있습니다.
padding_free (bool, 선택 사항, 기본값 False) — 패딩 없이 모든 시퀀스를 단일 연속 시퀀스로 평탄화하여 포워드 패스를 수행할지 여부입니다. 이는 패딩 오버헤드를 제거하여 메모리 사용량을 줄입니다. 현재 이 기능은 평탄화된 배치 구조를 효율적으로 처리할 수 있는 FlashAttention 2 또는 3에서만 지원됩니다. 전략 "bfd"로 패킹이 활성화되면 이 파라미터의 값과 관계없이 패딩-free가 활성화됩니다.
pad_to_multiple_of (int 또는 str, 선택 사항, 기본값 "auto") — 설정된 경우, 시퀀스는 해당 값의 배수로 패딩됩니다. "auto"는 Neuron(AWS Trainium)에서 입력 형식별로 한 번씩 컴파일되므로 128의 배수로 패딩하며, 다른 환경에서는 패딩하지 않습니다.
eval_packing (bool, 선택 사항) — 평가 데이터셋을 패킹할지 여부입니다. None인 경우 packing과 동일한 값을 사용합니다.

학습을 제어하는 매개변수

completion_only_loss (bool, 선택 사항) — 시퀀스의 completion 부분에서만 loss를 계산할지 여부입니다. True로 설정하면 prompt-completion 데이터셋에서만 지원되는 completion 부분에 대해서만 loss가 계산됩니다. False인 경우 전체 시퀀스에 대해 loss가 계산됩니다. None(기본값)인 경우 데이터셋에 따라 동작이 달라지며, prompt-completion 데이터셋에서는 completion에 대해, language modeling 데이터셋에서는 전체 시퀀스에 대해 loss가 계산됩니다.
assistant_only_loss (bool, 선택 사항, 기본값 False) — 시퀀스의 어시스턴트 부분에서만 손실을 계산할지 여부입니다. True로 설정하면 대화형 데이터셋에서만 지원되는 어시스턴트 응답에 대해서만 손실이 계산됩니다. False인 경우 전체 시퀀스에 대해 손실이 계산됩니다.
loss_type (str, 선택 사항, 기본값은 "nll") — 사용할 손실(loss)의 유형입니다. 가능한 값은 다음과 같습니다:
- "nll": 표준 음의 로그 우도.
- "dft": 이 논문에서 설명된 Dynamic Fine-Tuning.
- "chunked_nll": 동일한 방식으로 손실을 계산하는 "nll"의 비추천 별칭입니다. v2.0.0에서 제거됩니다.
activation_offloading (bool, 선택 사항, 기본값 False) — 활성화를 CPU로 오프로딩할지 여부입니다.

비추천되는 매개변수

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

SFTTrainer의 구성 클래스입니다.

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

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

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

logging_steps: 기본값이 500 대신 10입니다.

gradient_checkpointing: 기본값이 False가 아닌 True입니다.

bf16: fp16가 설정되지 않은 경우 기본값이 False가 아닌 True입니다.

learning_rate: 기본값이 5e-5 대신 2e-5입니다.

Update on GitHub