SFT Trainer

SFT Trainer (지도 파인튜닝)

모델을 특정 데이터로 "제대로 대답하도록" 길들이는 가장 기초적이면서도 널리 쓰이는 방법이 바로 지도 파인튜닝(SFT, Supervised Fine-Tuning)이에요. TRL의 SFTTrainer는 이 SFT 훈련을 편리하게 해주는 트레이너입니다. 이 가이드에서는 SFT가 실제로 어떻게 동작하는지, 그리고 SFTTrainer로 어떤 것들을 설정할 수 있는지 정리해요.

출처: SFT Trainer - Hugging Face TRL 공식문서

개요

TRL은 언어 모델 훈련을 위한 SFT(Supervised Fine-Tuning) 트레이너를 제공합니다. SFTTrainer는 diffusion 모델(DiffusionGemma)을 기본적으로 지원하지는 않지만, block-diffusion SFT 예시처럼 쉽게 확장해서 쓸 수 있어요.

SFT 방법 자세히 보기

지도 파인튜닝(SFT)은 언어 모델을 타깃 데이터셋에 적응시키는 가장 단순하면서도 흔한 방법입니다. 모델은 입력·출력 시퀀스 쌍을 이용해 완전 지도 방식(fully supervised)으로 훈련돼요.

SFT가 실제로 어떻게 동작하는지 핵심 단계인 전처리, 토큰화, 손실 계산으로 나눠 봅시다.

전처리와 토큰화

훈련 중 각 예시는 데이터셋 형식에 따라 text 필드 또는 (prompt, completion) 쌍을 담고 있어야 합니다. 기대되는 형식에 대한 자세한 내용은 Dataset formats를 참고하세요. SFTTrainer는 각 입력을 모델의 토크나이저로 토큰화하고, prompt와 completion이 따로 제공되면 토큰화 전에 이어붙입니다(concatenate).

손실 계산

sft_figure

SFT에 쓰이는 손실은 **토큰 레벨 크로스 엔트로피 손실(token-level cross-entropy loss)**로, 다음과 같이 정의됩니다.

$$ \mathcal{L}{\text{SFT}}(\theta) = - \sum{t=1}^{T} \log p_\theta(y_t \mid y_{<t}), $$

여기서 ( y_t ) 는 시간 단계 ( t ) 에서의 타깃 토큰이고, 모델은 이전 토큰들이 주어졌을 때 다음 토큰을 예측하도록 훈련돼요. 실제로는 손실 계산 시 padding 토큰은 마스킹됩니다.

이 방식은 SFTConfig에서 loss_type="dft"로 설정해서 켤 수 있어요. 자세한 내용은 Paper Index - Dynamic Fine-Tuning을 참고하세요.

라벨 시프트와 마스킹

훈련 중 손실은 한 토큰 시프트(one-token shift) 방식으로 계산됩니다. 즉, 모델은 시퀀스의 각 토큰을 이전 토큰들에 기반해 예측하도록 훈련되며, 구체적으로 입력 시퀀스가 오른쪽으로 한 칸 시프트되어 타깃 라벨이 됩니다.

커스터마이징

Packing

SFTTrainer는 여러 예시를 같은 입력 시퀀스에 채워 넣는 example packing 을 지원해서 훈련 효율을 높입니다. SFTConfig 생성자에 packing=True만 넘기면 켜집니다.

어시스턴트 메시지만 훈련하기

어시스턴트 메시지만 훈련하려면 conversational 데이터셋을 쓰고 SFTConfig에서 assistant_only_loss=True로 설정하세요.

training_args = SFTConfig(assistant_only_loss=True)

train_on_assistant

[!WARNING] 이 기능은 chat template에 {% generation %} 와 {% endgeneration %} 키워드가 포함돼 있어야 합니다. (예: Qwen3 같은) 알려진 모델 계열에서는 assistant_only_loss=True일 때 TRL이 템플릿을 자동으로 패치합니다.

completion만 훈련하기

train_on_completion

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 인자 없이 트레이너에 바로 넘기면 됩니다.

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()

[!TIP] 어댑터를 훈련할 때는 새 파라미터만 학습되므로 보통 더 높은 학습률(≈1e‑4)을 씁니다.
SFTConfig(learning_rate=1e-4, ...)

Liger Kernel로 훈련하기

Liger Kernel은 LLM 훈련용 Triton 커널 모음으로, 멀티 GPU 처리량을 20% 높이고 메모리 사용을 60% 줄여(최대 4× 더 긴 컨텍스트) FlashAttention, PyTorch FSDP, DeepSpeed 등과 매끄럽게 함께 동작합니다.

SFT 빠른 실험

RapidFire AI는 TRL 위에서 동작하는 오픈소스 실험 엔진으로, 단일 GPU에서도 여러 SFT 설정을 동시에 실행할 수 있게 해줍니다.

Unsloth로 훈련하기

Unsloth는 Llama·Mistral·Gemma·DeepSeek 같은 LLM을 최대 2× 빠르게, 최대 70% 적은 VRAM으로 훈련하는 오픈소스 파인튜닝·강화학습 프레임워크로, Hugging Face 호환 워크플로(훈련·평가·배포)를 제공합니다.

명령어 튜닝 예시

HuggingFaceTB/SmolLM3-3B 모델을 예시로 들 수 있어요. SFT Trainer가 토크나이저 업데이트와 특수 토큰 설정을 자동으로 처리합니다.

    train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()

Tool Calling과 함께 쓰는 SFT

SFTTrainer는 tool calling 능력을 가진 모델 파인튜닝을 완전히 지원합니다. 이 경우 각 데이터셋 예시에는 관련 필드가 담겨 있어야 합니다.

비전 언어 모델(VLM) 훈련

SFTTrainer는 비전 언어 모델(VLM) 훈련을 완전히 지원합니다. VLM을 훈련하려면 이미지 image 컬럼(샘플당 단일 이미지)이나 images 컬럼(샘플당 이미지 목록)이 있는 데이터셋을 제공하세요.

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()

[!TIP] VLM에서 절단(truncate)하면 이미지 토큰이 제거돼 훈련 오류가 날 수 있어요. 이를 피하려면 SFTConfig에서 max_length=None으로 설정하세요. 그러면 이미지 토큰을 절단하지 않고 전체 시퀀스 길이를 처리합니다.

핵심 API 요약

SFTTrainer

model (str 또는 PreTrainedModel 또는 PeftModel): 훈련할 모델. 사전학습 모델 id 문자열, 가중치가 저장된 디렉토리 경로, PreTrainedModel 객체(인과언어모델만 지원), PeftModel 객체 중 하나.
args (SFTConfig, optional): 이 트레이너용 설정. None이면 기본 설정 사용.
train_dataset (Dataset 또는 IterableDataset): 훈련에 쓸 데이터셋. IterableDataset(스트리밍 데이터셋)일 때는 길이를 추론할 수 없으므로 max_steps를 반드시 설정해야 해요.
processing_class (PreTrainedTokenizerBase 등, optional): 데이터 처리를 담당하는 클래스. None이면 모델 이름으로 로딩됩니다. tokenizer.pad_token이 반드시 설정돼 있어야 해요.
quantization_config (BitsAndBytesConfig, optional): 모델 id에서 모델을 로딩할 때 사용할 양자화 설정. peft_config와 조합하면 QLoRA 훈련이 됩니다.
peft_config (PeftConfig, optional): 모델을 감쌀 PEFT 설정. None이면 모델을 감싸지 않아요.

SFTConfig

SFT 훈련에 특화된 파라미터만 포함하며, 전체 훈련 인자 목록은 TrainingArguments 문서를 참고하세요.

기본값 중 TrainingArguments와 다른 것들은 다음과 같습니다: logging_steps는 500 대신 10이 기본, gradient_checkpointing은 False 대신 True가 기본, bf16은 기본이... (원문 문서에서 확인하세요)

더 알아보기 (Learn more)

SFT 데이터셋 형식: Dataset formats
GRPO 훈련: GRPO Trainer
선호도 정렬: DPO Trainer