TRL documentation

일반 온라인 로짓 증류(GOLD) 트레이너

You are viewing v1.18.1 version. A newer version v1.18.2 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

일반 온라인 로짓 증류(GOLD) 트레이너

All_models-GOLD-blue

개요

General Online Logit Distillation(GOLD)은 서로 다른 토크나이저를 사용하는 학생/교사 쌍을 지원하는 Universal Logit Distillation(ULD)의 확장입니다. 두 토크나이저가 생성한 텍스트 스팬을 정렬하고 관련 로짓을 병합하여 완료 토큰이 누락되지 않도록 합니다. 이를 통해 LLaMA 학생 모델과 Qwen 교사 모델과 같은 혼합 모델 계열을 포함한 토크나이저 간 지식 증류가 가능합니다.

주요 기능:

  1. 토크나이저 간 정렬 – GOLD는 학생과 교사의 토큰을 점진적으로 디코딩하고, 동일한 가시 텍스트를 가진 패시지를 그룹화한 후 각 그룹 내에서 확률을 병합합니다. 이를 통해 토큰 경계가 달라지더라도 손실 항이 전체 완성 텍스트에 대해 계산되도록 보장합니다.
  2. 하이브리드 ULD 손실 – uld_use_hybrid_loss가 활성화되면 GOLD는 정확한 어휘 일치 항목을 직접 비교하고, 일치하지 않는 토큰에 대해서는 원래의 정렬된 확률 ULD 손실로 대체합니다. 이는 교사와 어휘가 부분적으로만 겹치는 학생 모델의 안정성을 향상시킵니다.
  3. GKD와의 원활한 통합 – GOLD는 experimental.gkd.GKDTrainer에서 on-policy와 off-policy 스케줄링을 상속하므로, 단일 학습 실행에서 시퀀스 수준 KD, 일반화된 JSD, 크로스 토크나이저 증류를 결합할 수 있습니다.

GOLD는 현재 trl.experimental 네임스페이스의 일부입니다. 해당 기능이 반복적으로 개선되는 동안 API가 사전 통보 없이 변경될 수 있습니다.

사용 팁

experimental.gold.GOLDTrainer는 SFTTrainer를 서브클래스로 상속하며, 다른 TRL 트레이너와 동일한 데이터셋(ChatML 스타일의 메시지 목록)을 받습니다. experimental.gold.GOLDConfig의 주요 구성 플래그에는 다음이 포함됩니다:

  • use_uld_loss – Universal Logit Distillation을 활성화합니다. 크로스 토크나이저 설정의 경우 이 값을 True로 설정하세요.
  • teacher_tokenizer_name_or_path – use_uld_loss=True인 경우 필수입니다. GOLD는 teacher tokenizer를 사용하여 토큰을 정렬합니다.
  • uld_use_hybrid_loss, uld_hybrid_matched_weight, uld_hybrid_unmatched_weight – 하이브리드 매칭/미매칭 손실을 활성화하고 가중치를 설정합니다.
  • beta, lmbda, seq_kd – experimental.gkd.GKDConfig에서 상속되며, 일반화된 JSD 보간 및 온-폴리시 샘플링 비율을 제어합니다.
  • use_privileged_context, teacher_prompt_template, privileged_context_column – student prompt은 변경되지 않은 채로 teacher가 예시별 추가 컨텍스트를 볼 수 있게 합니다. 현재 텍스트, off-policy, standard-JSD 학습으로만 제한됩니다.
  • num_generations, generation_batch_size – 그라디언트 축적 윈도우에 걸친 버퍼링된 롤아웃 생성을 제어합니다. generation_batch_size는 워커당 옵티마이저 스텝당 고유 프롬프트의 수입니다.

최소한의 끝에서 끝(end-to-end) 예시:

from datasets import load_dataset
from trl.experimental.gold import GOLDConfig, GOLDTrainer

train_dataset = load_dataset(
    "HuggingFaceTB/OpenR1-Math-220k-default-verified",
    "all",
    split="train[:1024]",
)

trainer = GOLDTrainer(
    model="meta-llama/Llama-3.2-1B-Instruct",
    teacher_model="Qwen/Qwen2.5-0.5B-Instruct",
    args=GOLDConfig(output_dir="gold-model", use_uld_loss=True, teacher_tokenizer_name_or_path="Qwen/Qwen2.5-0.5B-Instruct"),
    train_dataset=train_dataset,
)
trainer.train()

빠른 시작 워크플로에서는 위와 같이 문자열 식별자를 사용하면 됩니다. 트레이너가 모델과 토크나이저를 자동으로 로드합니다. AutoModelForCausalLM, AutoTokenizer를 명시적으로 인스턴스화하거나 GOLDConfig를 채우는 작업은 초기화에 대한 세밀한 제어가 필요한 고급 사용 사례에서만 권장됩니다.

모델 로딩, 토크나이저 설정, 학습 인자를 커스터마이즈해야 하는 경우 더 명시적인 설정은 다음과 같이 구성할 수 있습니다:

from datasets import load_dataset
from trl.experimental.gold import GOLDConfig, GOLDTrainer
from transformers import AutoModelForCausalLM, AutoTokenizer

student_name = "meta-llama/Llama-3.2-1B-Instruct"
teacher_name = "Qwen/Qwen2.5-0.5B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(student_name)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained(student_name)
teacher_model = AutoModelForCausalLM.from_pretrained(teacher_name)

train_dataset = load_dataset(
    "HuggingFaceTB/Countdown-Task-GOLD",
    "verified_Qwen2.5-0.5B-Instruct",
    split="train",
)

training_args = GOLDConfig(
    output_dir="gold-model",
    per_device_train_batch_size=1,
    teacher_model_name_or_path=teacher_name,
    teacher_tokenizer_name_or_path=teacher_name,
    use_uld_loss=True,
    uld_use_hybrid_loss=True,
)

trainer = GOLDTrainer(
    model=model,
    teacher_model=teacher_model,
    args=training_args,
    processing_class=tokenizer,
    train_dataset=train_dataset,
)
trainer.train()

GOLD는 하나의 전체 옵티마이저 윈도우 생성 배치(per_device_train_batch_size * gradient_accumulation_steps)를 버퍼링하고 이를 누적 단계에 걸쳐 재사용합니다. 마지막 배치의 크기가 부족하면 GOLD가 경고를 표시하고 해당 마지막 배치를 삭제합니다(Dropping last batch due to unexpected batch size). 이 경고를 피하려면 dataloader_drop_last=True를 설정하세요.

기대되는 데이터셋 유형

GOLD에는 대화형 언어 모델링 데이터셋이 필요합니다. 예:

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

GOLDTrainer는 원본 메시지를 유지하여 ChatML collator가 올바른 경계로 프롬프트와 completions을 구성할 수 있도록 합니다.

Privileged Context

Privileged-context distillation은 추론 시점에 학생 모델이 접근할 수 없는 추가 정보를 교사 모델에 제공합니다. 일반적인 프롬프트/완성 데이터셋에 컨텍스트 열을 추가한 후, 해당 기능을 명시적으로 활성화합니다:

from datasets import Dataset

dataset = Dataset.from_list(
    [
        {
            "prompt": [{"role": "user", "content": "What caused the outage?"}],
            "completion": [{"role": "assistant", "content": "A timeout change caused the outage."}],
            "privileged_context": "The deployment changed the timeout immediately before errors began.",
        }
    ]
)

args = GOLDConfig(
    output_dir="gold-model",
    lmbda=0.0,
    use_privileged_context=True,
)

Student은 원래의 prompt와 completion으로 학습됩니다. Teacher는 기본적으로 "{prompt}\n\n{privileged_context}"로 구성된 별도의 prompt를 수신한 후, 동일한 completion에 점수를 매깁니다. 대화형 데이터의 경우, GOLD는 chat template을 다시 적용하기 전에 마지막 user turn만 다시 작성하며, system, tool, assistant turn은 변경되지 않습니다. 이 prompt를 사용자 정의하려면 teacher_prompt_template을 설정하고, "privileged_context" 이외의 컬럼을 사용하려면 privileged_context_column을 설정합니다.

Teacher prompt은 절대로 잘리지 않으므로, teacher 모델의 컨텍스트 윈도우에 맞는지 확인하세요. 이 초기 지원은 의도적으로 텍스트, off-policy 표준 JSD 증류로 제한되어 있습니다: lmbda는 0이어야 하며, seq_kd=True, use_uld_loss=True, X-Token KD(xtoken_loss_type가 "none"이 아닌 경우), packing, VLM, Liger Kernel은 privileged context와 함께 지원되지 않습니다.

토큰 병합 작동 방식

student와 teacher가 서로 다른 tokenizer를 사용하는 경우, 동일한 텍스트가 다르게 분할될 수 있습니다:

  • Student: "Hugging Face" → 1개의 토큰
  • 교사: "Hugging", " Face" → 2개의 토큰

GOLD는 이러한 시퀀스를 정렬하고, 교사의 다중 토큰 확률을 학생의 단일 토큰 분포와 비교할 수 있는 단일 분포로 병합합니다.

확률 병합

단일 학생 토큰으로 매핑되는 토큰의 교사 시퀀스 [token₀, token₁, ..., tokenₖ]에 대해 GOLD는 다음을 계산합니다:

P_merged(y) = P(y | context) × P(token₁ | token₀, context) × ... × P(tokenₖ | ..., context)

여기서:

  • P(y | context)는 첫 번째 위치의 모든 어휘 토큰에 대한 주변 확률 분포입니다
  • P(tokenᵢ | ..., context)은 실제로 생성된 토큰의 스칼라 조건부 확률입니다

핵심 통찰: 실제 연속 토큰의 조건부 확률만 스칼라로 추출됩니다. 이후 첫 번째 위치의 전체 주변 분포에 이 스칼라 확률을 곱하여 스케일링합니다.

이를 통해 다음을 보장합니다:

  1. 실제 생성된 시퀀스에 대한 정확한 결합 확률(연쇄 법칙에 따라)
  2. 합리적 근사(동일한 연속 가능성으로 스케일링된) 반사실 토큰
  3. ULD 손실 계산에 필요한 올바른 상대 확률을 유지하는 정규화되지 않은 분포

예시

주어진:

P(x₀):         ["HF": 0.6,  "is": 0.3,  "cool": 0.1]
P(x₁ | "HF"):  ["HF": 0.05, "is": 0.9,  "cool": 0.05]

토큰 0과 1이 병합되고, 실제 시퀀스가 ["HF", "is"]인 경우:

P_merged("HF")   = 0.6 × 0.9 = 0.54  ✓ (correct joint probability)
P_merged("is")   = 0.3 × 0.9 = 0.27
P_merged("cool") = 0.1 × 0.9 = 0.09

병합된 분포는 정규화되지 않았습니다(합계가 0.81). 이는 정렬과 L1 거리를 사용하는 ULD 손실 계산에 의도적이고 올바른 방식입니다.

예제 스크립트

examples/gold_chatbot_arena/gold_chatbot_arena.py를 사용하여 명령줄에서 GOLD 학습을 시작할 수 있습니다. 이 스크립트는 표준 ModelConfig 플래그를 통해 전체 학습과 LoRA를 지원합니다.

python examples/gold_chatbot_arena/gold_chatbot_arena.py \
    --model_name_or_path meta-llama/Llama-3.2-1B-Instruct \
    --teacher_model_name_or_path Qwen/Qwen2-1.5B-Instruct \
    --dataset_name trl-lib/chatbot_arena_completions \
    --learning_rate 2e-5 \
    --per_device_train_batch_size 4 \
    --gradient_accumulation_steps 8 \
    --output_dir gold-model \
    --num_train_epochs 1 \
    --push_to_hub

비전 언어 모델 학습

experimental.gold.GOLDTrainer는 VLM-to-VLM 증류를 지원합니다. 학생 모델과 교사 모델 모두 비전-언어 모델이어야 합니다. VLM을 학습하려면 image 컬럼(샘플당 단일 이미지) 또는 images 컬럼(샘플당 이미지 목록)이 포함된 데이터셋을 제공해야 합니다. 예상되는 데이터셋 구조에 대한 자세한 내용은 Dataset Format — Vision datasets 섹션을 참조하세요.

student와 teacher가 동일한 아키텍처와 토크나이저를 공유하는 경우(예: Qwen3-VL-8B에서 Qwen3-VL-2B로), 표준 일반화 JSD 손실이 직접 적용됩니다. model_type가 다른 경우(예: Qwen3-VL에서 LFM2.5-VL로), use_uld_loss=True를 설정하여 Universal Logit Distillation을 통한 크로스 토크나이저 정렬을 활성화합니다. 이미지는 각 모델의 프로세서로 별도로 처리됩니다.

from datasets import load_dataset
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor
from trl.experimental.gold import GOLDConfig, GOLDTrainer

student_name = "Qwen/Qwen3-VL-2B-Instruct"
teacher_name = "Qwen/Qwen3-VL-8B-Instruct"

processor = AutoProcessor.from_pretrained(student_name, padding_side="left")
student_model = AutoModelForImageTextToText.from_pretrained(student_name, dtype=torch.bfloat16)
teacher_model = AutoModelForImageTextToText.from_pretrained(teacher_name, dtype=torch.bfloat16)

train_dataset = load_dataset("trl-lib/llava-instruct-mix", split="train")

trainer = GOLDTrainer(
    model=student_model,
    teacher_model=teacher_model,
    args=GOLDConfig(
        output_dir="gold-vlm-model",
        max_length=None,
        teacher_model_name_or_path=teacher_name,
        use_uld_loss=False,
    ),
    train_dataset=train_dataset,
    processing_class=processor,
)
trainer.train()

크로스 패밀리 디스틸레이션의 경우, use_uld_loss=True를 설정하고 teacher_tokenizer_name_or_path에 teacher 모델 이름을 지정하세요.

examples/gold_qwen3_vl/gold_qwen3_vl.py를 사용하여 명령줄에서 GOLD VLM 학습을 시작합니다:

# Same-family distillation (JSD loss, vLLM enabled)
torchrun --nproc_per_node 8 examples/gold_qwen3_vl/gold_qwen3_vl.py \
    --student_model_name Qwen/Qwen3-VL-2B-Instruct \
    --teacher_model_name Qwen/Qwen3-VL-8B-Instruct

# Cross-family distillation (ULD loss, local generation)
torchrun --nproc_per_node 8 examples/gold_qwen3_vl/gold_qwen3_vl.py \
    --student_model_name LiquidAI/LFM2.5-VL-1.6B \
    --teacher_model_name Qwen/Qwen3-VL-8B-Instruct \
    --use_uld_loss \
    --no-use_vllm

VLM의 경우, 이미지 토큰은 시퀀스의 프롬프트 부분에 위치하며 조용히 제거될 수 있으므로 truncation_mode='keep_end'는 지원되지 않습니다. 기본값인 truncation_mode='keep_start'를 사용하거나 experimental.gold.GOLDConfig에서 max_length=None으로 설정하세요. 이렇게 하면 이미지 토큰이 잘리지 않고 전체 시퀀스 길이를 처리할 수 있습니다.

GOLDConfig(max_length=None, ...)

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

Cross-architecture VLM distillation에는 use_uld_loss=True가 필요합니다. ULD loss 없이 cross-architecture distillation을 시도하면 trainer가 오류를 발생시킵니다.

GOLDTrainer

class trl.experimental.gold.GOLDTrainer

< >

( model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, str, NoneType] = Noneteacher_model: typing.Union[transformers.modeling_utils.PreTrainedModel, torch.nn.Module, str] = Noneargs: trl.experimental.gold.gold_config.GOLDConfig | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | dict[str, datasets.arrow_dataset.Dataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.image_processing_utils.BaseImageProcessor | transformers.feature_extraction_utils.FeatureExtractionMixin | 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[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR] = (None, None)preprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = Nonepeft_config: typing.Optional[ForwardRef('PeftConfig')] = None )

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

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

주요 학습 진입점.

generate_on_policy_outputs

< >

( modelinputsgeneration_config )

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를 🤗 모델 허브에 업로드합니다.

GOLDConfig

class trl.experimental.gold.GOLDConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-07lr_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 | None = Nonegradient_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 = Nonetemperature: float = 0.9top_p: float = 0.95top_k: int = 0lmbda: float = 0.5beta: float = 0.5max_completion_length: int = 128teacher_model_name_or_path: str | None = Noneteacher_model_revision: str | None = Noneteacher_model_init_kwargs: dict[str, typing.Any] | str | None = Noneteacher_tokenizer_name_or_path: str | None = Nonedisable_dropout: bool = Trueseq_kd: bool = Falseuse_privileged_context: bool = Falseteacher_prompt_template: str | None = Noneprivileged_context_column: str = 'privileged_context'num_generations: int = 1generation_batch_size: int | None = Noneuse_uld_loss: bool = Falseuld_token_merge_strategy: str = 'observed'use_extended_uld: bool = Trueuld_use_hybrid_loss: bool = Falseuld_hybrid_matched_weight: float | None = Noneuld_hybrid_unmatched_weight: float | None = Noneuld_crossentropy_weight: float = 0.0uld_distillation_weight: float = 1.0uld_student_temperature: float = 1.0uld_teacher_temperature: float = 1.0uld_skip_student_eos: bool = Trueuld_skip_teacher_eos: bool = Truextoken_loss_type: str = 'none'xtoken_projection_matrix_path: str | None = Nonextoken_temperature: float = 1.0xtoken_dynamic_scaling: bool = Truextoken_uncommon_topk: int = 8192xtoken_vocab_topk: int = 8192xtoken_kl_weight: float = 1.0xtoken_ce_scale: float = 0.1use_vllm: bool = Falsevllm_mode: str = 'colocate'vllm_server_base_url: str | None = Nonevllm_server_host: str = '0.0.0.0'vllm_server_port: int = 8001vllm_server_timeout: float = 240.0vllm_group_port: int = 51216vllm_gpu_memory_utilization: float = 0.9vllm_tensor_parallel_size: int = 1vllm_max_model_length: int | None = Nonevllm_model_impl: str = 'vllm'vllm_structured_outputs_regex: str | None = Nonevllm_sync_frequency: int = 1vllm_enable_sleep_mode: bool = Falselog_completions: bool = Falselog_completions_steps: int = 100num_completions_to_print: int | None = Nonewandb_log_unique_prompts: bool = Truecallbacks: list[str] = <factory> )

생성 및 학습 루프를 제어하는 매개변수

  • temperature (float, 선택 사항, 기본값 0.9) — 샘플링에 사용할 온도입니다. 온도가 높을수록 완성 결과가 더 무작위적으로 생성됩니다.
  • top_p (float, 선택 사항, 기본값 0.95) — float < 1로 설정하면, 확률의 합이 top_p 이상인 가장 확률이 높은 최소 토큰 집합만 생성에 유지됩니다.
  • top_k (int, 선택 사항, 기본값 0) — top-k-filtering을 위해 유지할 가장 높은 확률의 어휘 토큰 수입니다. 0인 경우 top-k-filtering이 비활성화되고 모든 토큰이 고려됩니다.
  • lmbda (float, 선택 사항, 기본값 0.5) — 학생 데이터 비율(즉, 온-폴리시 학생 생성 출력의 비율)을 제어하는 람다 파라미터입니다.
  • beta (float, 선택 사항, 기본값 0.5) — Generalized Jensen-Shannon Divergence 손실의 0.0과 1.0 사이의 보간 계수입니다. beta가 0.0이면 손실은 KL 발산이 됩니다. beta가 1.0이면 손실은 Inverse KL Divergence가 됩니다.
  • max_completion_length (int, 선택 사항, 기본값 128) — 각 completion당 생성할 최대 토큰 수.
  • teacher_model_name_or_path (str, 선택 사항) — 교사 모델의 이름 또는 경로입니다. None인 경우, 교사 모델은 학습 중인 모델과 동일합니다.
  • teacher_model_revision (str 또는 None, 선택 사항, 기본값 None) — 교사 모델의 리비전(예: 브랜치 이름, 태그, 커밋 해시)입니다. None인 경우 기본 리비전이 사용됩니다.
  • teacher_model_init_kwargs (dict[str, Any], 선택 사항) — 문자열에서 teacher model을 인스턴스화할 때 AutoModelForCausalLM.from_pretrained에 전달할 키워드 인수입니다. revision 값은 teacher processing class를 로드할 때에도 사용됩니다.
  • teacher_tokenizer_name_or_path (str, 선택 사항) — 교사 모델의 Tokenizer 이름 또는 경로입니다. ULD loss를 사용할 때 None이면 학생 모델과 동일한 tokenizer를 사용합니다(크로스 토크나이저 증류에는 권장되지 않음).
  • disable_dropout (bool, 선택 사항, 기본값 True) — 모델에서 dropout을 비활성화할지 여부입니다.
  • seq_kd (bool, 선택 사항, 기본값 False) — Sequence-Level KD 수행 여부를 제어하는 Seq_kd 매개변수입니다(교사가 생성한 출력에 대한 supervised FT로 볼 수 있습니다).
  • use_privileged_context (bool, 선택 사항, 기본값 False) — 학생 프롬프트는 변경하지 않고, 예제별 특권 컨텍스트를 조건으로 하여 교사를 학습할지 여부입니다. 이는 텍스트, 오프-폴리시 표준 JSD 증류에서만 지원됩니다.
  • teacher_prompt_template (str, 선택) — 교사 프롬프트를 구성하는 데 사용되는 템플릿입니다. {prompt}를 포함해야 하며 {privileged_context}를 포함할 수 있습니다. None인 경우 기본값은 "{prompt}\n\n{privileged_context}"입니다.
  • privileged_context_column (str, 선택 사항, 기본값 "privileged_context") — 교사 프롬프트를 구성하는 데 사용되는 예시별 특권 컨텍스트를 포함하는 데이터셋 열입니다.
  • num_generations (int, 선택 사항, 기본값 1) — 프롬프트당 생성 횟수. 각 프롬프트는 생성 배치에서 이 횟수만큼 반복됩니다.
  • generation_batch_size (int 또는 None, 선택 사항, 기본값 None) — 옵티마이저 스텝당 워커당 고유 프롬프트 수입니다. None인 경우 (per_device_train_batch_size * gradient_accumulation_steps) // num_generations에서 계산됩니다.

ULD 손실을 제어하는 매개변수

  • use_uld_loss (bool, 선택 사항, 기본값 False) — Generalized Jensen-Shannon Divergence loss 대신 Universal Logit Distillation (ULD) loss를 사용할지 여부입니다.
  • use_extended_uld (bool, 선택 사항, 기본값 True) — 토크나이저를 사용하여 학생과 교사의 토크나이제이션 간 토큰 확률을 정렬 및 병합하는 확장된 ULD 정렬을 활성화할지 여부입니다. True인 경우, 트레이너는 토큰 매핑을 계산하고 분할된 토큰의 확률을 병합합니다. False인 경우, ULD는 원래 ULD 논문과 동일한 간단한 위치 기반 절단을 사용합니다. ByteLevel이 아니거나 byte-fallback BPE가 아닌 토크나이저(예: Llama 2)의 경우 False로 설정하십시오.
  • uld_token_merge_strategy (str, 선택 사항, 기본값 "observed") — ULD 손실에서 정답 로짓을 정렬하고 토큰 확률을 병합하는 데 사용되는 전략입니다. "observed"의 경우, 정답 로짓은 정답 위치에서 슬라이스되고, 분할된 토큰(use_extended_uld=True인 경우)은 첫 번째 위치의 주변 분포를 실제 후속 토큰의 스칼라 조건부 확률과 곱하여 병합됩니다. "bayesian"의 경우, 정답 로짓 슬라이스는 한 위치 앞쪽으로 이동하여 probs[k]가 token_ids[k]를 예측하도록 합니다(연쇄 법칙). 분할된 토큰은 실제 접두사 토큰에 조건부화된 마지막 위치의 전체 분포를 이전 토큰의 스칼라 확률과 곱하여 병합됩니다. 로짓 정렬 이동은 use_extended_uld가 활성화되어 있든 없든 적용됩니다.
  • uld_use_hybrid_loss (bool, 선택 사항, 기본값 False) — ULD loss와 JSD loss를 결합한 hybrid loss를 사용할지 여부입니다. True인 경우, 최종 loss는 알려진 토큰 매핑에 대한 JSD와 알려지지 않은 토큰 매핑에 대한 ULD의 조합입니다.
  • uld_hybrid_matched_weight (float 또는 None, 선택 사항) — hybrid ULD + JSD loss를 사용할 때 matched token loss 구성 요소에 적용되는 가중치입니다. 이 가중치는 student와 teacher의 토큰화 사이에 직접적인 매핑이 있는 토큰에 대해 계산된 JSD loss를 스케일링합니다. None인 경우, 어휘 중복도에 기반한 적응형 가중치를 사용합니다. uld_hybrid_unmatched_weight와 함께 설정해야 합니다(둘 다 None이거나 둘 다 float이어야 합니다).
  • uld_hybrid_unmatched_weight (float 또는 None, 선택 사항) — hybrid ULD + JSD loss를 사용할 때 unmatched token loss 구성 요소에 대한 가중치입니다. 이 가중치는 student와 teacher의 tokenization 사이에 직접적인 매핑이 없는 토큰에 대해 계산된 ULD loss를 스케일링합니다. None인 경우 어휘 중복도에 기반한 적응형 가중치를 사용합니다. uld_hybrid_matched_weight와 함께 설정해야 합니다(둘 다 None이거나 둘 다 float이어야 합니다).
  • uld_crossentropy_weight (float, 선택 사항, 기본값 0.0) — ULD 손실에서 교차 엔트로피 손실 구성 요소의 가중치입니다. 0이면 ULD 증류 손실만 사용됩니다.
  • uld_distillation_weight (float, 선택 사항, 기본값 1.0) — ULD 손실에서 증류 손실 구성 요소의 가중치입니다.
  • uld_student_temperature (float, 선택 사항, 기본값 1.0) — ULD 손실 계산에 사용되는 학생 로짓의 온도입니다.
  • uld_teacher_temperature (float, 선택 사항, 기본값 1.0) — ULD 손실 계산에 사용되는 teacher logits의 temperature입니다.
  • uld_skip_student_eos (bool, 선택 사항, 기본값 True) — ULD 손실 계산 시 student의 EOS 토큰을 건너뛸지 여부.
  • uld_skip_teacher_eos (bool, 선택 사항, 기본값 True) — ULD 손실 계산 시 teacher의 EOS 토큰을 건너뛸지 여부.

X-Token cross-tokenizer KD용 매개변수 (https

  • xtoken_loss_type (str, 선택 사항, 기본값 "none") — Cross-tokenizer KD 변형: "none" (비활성화), "p_kl" (projection KL) 또는 "h_kl" (완화된 공통 집합을 사용하는 hybrid KL). teacher_tokenizer_name_or_path와 xtoken_projection_matrix_path가 필요합니다.
  • xtoken_projection_matrix_path (str, 선택 사항) — 사전 계산된 투영 행렬 파일의 경로입니다. xtoken_loss_type != "none"인 경우 필수입니다.
  • xtoken_temperature (float, 선택 사항, 기본값 1.0) — X-Token KD 손실의 온도 T입니다. 손실은 T²로 곱해집니다 (Hinton 2015).
  • xtoken_dynamic_scaling (bool, 선택 사항, 기본값 True) — 마이크로 배치별로 stop_gradient(abs(CE) / abs(KD))로 KD를 스케일링하여 손실 크기를 균형 있게 조정합니다(논문 식 7).
  • xtoken_uncommon_topk (int, 선택 사항, 기본값 8192) — H-KL: 정렬된 L1 uncommon 비교를 각 측면의 상위 k개 토큰으로 제한합니다.
  • xtoken_vocab_topk (int, 선택 사항, 기본값 8192) — P-KL: 최대 logit 기준 전역 top-k teacher 토큰으로 KL을 제한합니다. 투영 행렬 --top-k와 상호 작용합니다. 행렬의 범위를 벗어난 teacher 토큰은 거의 0에 가까운 투영된 student 질량을 가지며 KL을 지배하므로, 더 작은 값은 student가 일치시킬 수 있는 토큰에 손실을 집중시킵니다.
  • xtoken_kl_weight (float, 선택 사항, 기본값 1.0) — xtoken_dynamic_scaling=False일 때 X-Token KD 항에 적용할 가중치.
  • xtoken_ce_scale (float, 선택 사항, 기본값 0.1) — xtoken_dynamic_scaling=False일 때 X-Token 손실의 CE 항에 적용되는 스케일 팩터입니다.

vLLM 통합을 제어하는 매개변수

  • use_vllm (bool, 선택 사항, 기본값 False) — 학생 모델에서 completions을 생성할 때 vLLM을 사용할지 여부입니다. vllm이 설치되어 있어야 합니다.
  • vllm_mode (str, 선택 사항, 기본값 "colocate") — student vLLM 통합을 위한 모드입니다. "server"(실행 중인 vLLM 서버에 연결) 또는 "colocate"(동일 프로세스에서 vLLM 실행) 중 하나를 지정합니다.
  • vllm_server_host (str, 선택 사항, 기본값 "0.0.0.0") — 학생 모델용 vLLM 서버의 호스트입니다(vllm_mode="server"인 경우).
  • vllm_server_port (int, 선택 사항, 기본값 8001) — 학생 모델용 vLLM 서버 포트(vllm_mode="server"인 경우).
  • vllm_server_timeout (float, 선택 사항, 기본값 240.0) — vllm_mode="server"인 경우 student vLLM 서버에 연결하는 시간 초과 시간입니다.
  • vllm_gpu_memory_utilization (float, 선택 사항, 기본값 0.9) — 동일 GPU에 배치된 student vLLM 엔진의 GPU 메모리 사용률(vllm_mode="colocate"인 경우)입니다. student 모델과 teacher 모델이 동일한 GPU를 공유하는 경우 이 값을 낮은 값으로 설정하는 것이 권장됩니다.
  • vllm_tensor_parallel_size (int, 선택 사항, 기본값 1) — vllm_mode="colocate"인 경우, colocated student vLLM 엔진의 Tensor parallel size입니다.
  • vllm_structured_outputs_regex (str, 선택 사항) — 학생 모델에 대한 vLLM 구조화 출력을 위한 정규식입니다.
  • vllm_server_base_url (str, 선택 사항) — vLLM 서버의 기본 URL(예: "http://localhost:8001"). 지정된 경우 vllm_server_host 및 vllm_server_port는 무시됩니다.
  • vllm_group_port (int, 선택 사항, 기본값 51216) — vLLM 가중치 업데이트 그룹(NCCL communicator)에 사용할 포트입니다. 포트가 사용 중이 아니라면 변경할 필요가 없습니다.
  • vllm_max_model_length (int, 선택 사항) — vllm_mode="colocate"인 경우, colocated vLLM 엔진의 최대 모델 시퀀스 길이입니다. 기본값은 모델의 최대 컨텍스트 길이입니다.
  • vllm_model_impl (str, 선택 사항, 기본값 "vllm") — vLLM에서 사용할 모델 구현 백엔드입니다. "vllm"(기본값) 또는 "transformers"를 사용하세요.
  • vllm_sync_frequency (int, 선택 사항, 기본값 1) — vLLM 엔진에 학생 모델 가중치를 동기화할 주기(학습 스텝 단위). 모든 스텝마다 동기화하려면 1로 설정합니다.
  • vllm_enable_sleep_mode (bool, 선택 사항, 기본값 False) — 옵티마이저 단계에서 학생 모델의 가중치/캐시를 오프로드하기 위해 vLLM sleep mode를 활성화합니다. GPU 메모리 사용량을 낮게 유지하지만, 엔진을 깨우는 과정에서 호스트-디바이스 전송 지연이 발생합니다.

로깅을 제어하는 매개변수

  • log_completions (bool, 선택 사항, 기본값 False) — logging_steps 단계마다 (prompt, completion) 쌍의 샘플을 기록할지 여부입니다. rich가 설치되어 있으면 샘플을 출력합니다. wandb 로깅이 활성화되어 있으면 wandb에 기록합니다.
  • log_completions_steps (int, 선택 사항, 기본값 100) — (prompt, completion) 쌍을 로깅하는 간격(스텝 수). log_completions가 True로 설정된 경우에만 사용됩니다.
  • num_completions_to_print (int 또는 None, 선택 사항) — rich로 출력할 completions의 수입니다. None인 경우 모든 completions이 기록됩니다.
  • wandb_log_unique_prompts (bool, 선택 사항, 기본값 True) — wandb에 고유한 프롬프트를 기록할지 여부입니다. 이 옵션을 사용하면 고유한 프롬프트마다 새로운 run이 생성됩니다.
  • callbacks (list[str], 선택 사항, 기본값 []) — 학습 중에 실행할 콜백입니다.

experimental.gold.GOLDTrainer의 구성 클래스입니다.

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

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

  • learning_rate: 기본값이 5e-5 대신 1e-7입니다.
Update on GitHub