TRL documentation

汎用オンラインロジット蒸留(GOLD)トレーナー

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からオンポリシーとオフポリシーのスケジューリングを継承しているため、シーケンスレベルの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は、トークンのアラインメントに教師モデルのトークナイザーを使用します。
  • 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 のプロンプトを変更せずに、teacher に例ごとの追加コンテキストを表示させることができます。現在、これはテキスト、オフポリシー、標準 JSD トレーニングに限定されています。
  • num_generations、generation_batch_size – グラデーション蓄積ウィンドウにわたるバッファリングされたロールアウト生成を制御します。generation_batch_size は、ワーカーごとにオプティマイザーステップごとに処理されるユニークなプロンプトの数です。

最小限のエンドツーエンドの例:

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 は、1 つの完全なオプティマイザーウィンドウの生成バッチ(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コラクターが正しい境界でプロンプトと補完を構築できるように、生のメッセージを保持します。

特権コンテキスト

Privileged-context distillationでは、推論時に学生モデルには利用できない追加の情報を教師モデルに提供します。通常のprompt/completionデータセットにcontext列を追加し、その後、この機能を明示的に有効にします。

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 はチャットテンプレートを再適用する前に最終的な user ターンのみを書き換えます。system、tool、assistant ターンは変更されません。この prompt をカスタマイズするには teacher_prompt_template を設定し、"privileged_context" 以外の列を使用するには privileged_context_column を設定します。

教師プロンプトは決して切り詰められないため、教師モデルのコンテキストウィンドウ内に収まることを確認してください。この初期サポートは意図的にテキスト、オフポリシーの標準JSD蒸留に限定されています: lmbdaは0でなければならず、seq_kd=True、use_uld_loss=True、X-Token KD(xtoken_loss_typeが"none"以外の場合)、パッキング、VLM、Liger Kernelは、特権コンテキストではサポートされていません。

トークンマージングの仕組み

studentとteacherが異なるトークナイザーを使用する場合、同じテキストが異なる方法で分割される可能性があります:

  • 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 から VLM への蒸留をサポートしています。学生モデルと教師モデルの両方がビジョン・言語モデルである必要があります。VLM を学習するには、image 列(サンプルごとに1枚の画像)または images 列(サンプルごとに画像のリスト)を含むデータセットを指定してください。データセットの構造に関する詳細は、Dataset Format — Vision datasets セクションを参照してください。

学生モデルと教師モデルが同じアーキテクチャとトークナイザーを共有している場合(例: 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 に教師モデルの名前を指定します。

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は、データセット全体で切り詰めによって画像トークンが削除されないことを確認した場合にのみ使用してください。

アーキテクチャ間のVLM蒸留にはuse_uld_loss=Trueが必要です。ULD損失なしでアーキテクチャ間の蒸留を試みると、トレーナーはエラーを発生させます。

GOLDTrainer

クラス 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()を使用して再読み込みできます。

メインプロセスからのみ保存します。

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 の元の引数を上書きするための書き込み権限を持つトークン。
  • revision (str, 省略可) — コミット元の git リビジョンです。“main” ブランチのヘッドがデフォルトです。
  • private (bool、省略可) — リポジトリ作成時にプライベートにするかどうか。デフォルトはargs.hub_private_repoです。リポジトリが既に存在する場合は、この引数は無効です。
  • kwargs (dict[str, Any]、省略可) — ~Trainer.create_model_card に渡される追加のキーワード引数。

self.args.hub_model_id のリポジトリに、self.model と self.processing_class を 🤗 model hub にアップロードします。

GOLDConfig

クラス 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 = 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 = 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) — 1 未満の float に設定した場合、生成には、確率の合計が top_p 以上となる最も確率の高いトークンの最小集合のみが保持されます。
  • top_k (int、任意、デフォルトは0) — トップkフィルタリングのために保持する、確率の高い語彙トークンの数。0の場合、トップkフィルタリングは無効になり、すべてのトークンが対象となります。
  • lmbda (float、任意、デフォルトは 0.5) — 学生データ比率(つまり、オンポリシーの学生生成出力の割合)を制御する Lambda パラメータです。
  • beta (float, 任意、デフォルトは 0.5) — Generalized Jensen-Shannon Divergence ロスの 0.0 と 1.0 の間の補間係数です。 0.0 の場合、ロスは KL 分散になります。1.0 の場合、ロスは Inverse KL Divergence になります。
  • max_completion_length (int、任意、デフォルトは128) — 1回の補完で生成するトークンの最大数。
  • teacher_model_name_or_path (str, 任意) — 教師モデルのモデル名またはパス。None の場合、教師モデルは学習対象のモデルと同じになります。
  • teacher_model_revision (str または None、任意、デフォルトは None) — 教師モデルのモデルリビジョン(例: ブランチ名、タグ、コミットハッシュ)。None の場合、デフォルトのリビジョンが使用されます。
  • teacher_model_init_kwargs (dict[str, Any]、省略可) — 文字列から教師モデルをインスタンス化する場合にAutoModelForCausalLM.from_pretrainedに渡すキーワード引数です。revisionの値は、教師の処理クラスを読み込む際にも使用されます。
  • teacher_tokenizer_name_or_path (str, 任意) — 教師モデルのトークナイザー名またはパス。ULD loss を使用する場合に None である場合、生徒モデルと同じトークナイザーが使用されます(クロス トークナイザー蒸留には非推奨)。
  • disable_dropout (bool、任意、デフォルトはTrue) — モデル内で dropout を無効にするかどうかを指定します。
  • seq_kd (bool、任意、デフォルトは False) — Sequence-Level KD を実行するかどうかを制御する Seq_kd パラメータです(教師モデルが生成した出力に対する教師あり 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) — 1 つのワーカーあたり、1 ステップのオプティマイザ更新ごとに使用されるユニークなプロンプトの数。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損失において、回答のlogitsをアラインし、トークンの確率をマージするために使用される戦略です。"observed"の場合、回答のlogitsは回答の位置でスライスされ、分割されたトークン(use_extended_uld=Trueの場合)は、最初の位置の周辺分布に、実際の後続トークンのスカラー条件付き確率を乗算することでマージされます。"bayesian"の場合、回答logitsのスライスが1位置早くシフトされ、probs[k]がtoken_ids[k]を予測するようになります(連鎖律)。分割されたトークンは、実際のプレフィックストークンを条件とする最後の位置の完全な分布に、それより前のトークンのスカラー確率を乗算することでマージされます。このlogitsアラインメントのシフトは、use_extended_uldが有効かどうかに関わらず適用されます。
  • uld_use_hybrid_loss (bool、省略可能、デフォルトは False) — ULD loss と JSD loss を組み合わせたハイブリッド 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 のトークン化の間に直接のマッピングが存在しないトークンに対して計算される 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損失の計算における、学生モデルのlogitsの温度です。
  • uld_teacher_temperature (float、任意、デフォルト値は1.0) — ULD損失の計算における教師モデルのlogitsの温度です。
  • uld_skip_student_eos (bool、任意、デフォルトは True) — ULD の損失計算において、student の EOS トークンをスキップするかどうか。
  • uld_skip_teacher_eos (bool、省略可、デフォルトはTrue) — ULD損失の計算において、教師モデルのEOSトークンをスキップするかどうか。

X-Token クロス トークナイザー KD のパラメータ (https

  • xtoken_loss_type (str、任意、デフォルトは"none") — クロス・トークナイザー KD のバリアント: "none" (無効)、"p_kl" (射影 KL)、または"h_kl" (緩和された共通セットを持つハイブリッド 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: KL を、最大 logit によるグローバルな top-k の教師トークンに制限します。射影行列 --top-k と相互作用します。行列の範囲外の教師トークンは、射影された学生側の質量がほぼゼロになり、KL を支配してしまいます。そのため、値を小さくすることで、学生が一致できるトークンに損失を集中させることができます。
  • 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) — 学生モデルからの補完生成に vLLM を使用するかどうか。vllm のインストールが必要です。
  • vllm_mode (str、省略可、デフォルトは"colocate") — 学生モデルの 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に配置された学生モデルのvLLMエンジン(vllm_mode="colocate"の場合)のGPUメモリ使用率です。学生モデルと教師モデルが同じGPUを共有している場合は、この値を低く設定することをお勧めします。
  • vllm_tensor_parallel_size (int、任意、デフォルトは 1) — vllm_mode="colocate" の場合、colocate された student vLLM エンジンのテンソル並列サイズ。
  • 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 コミュニケーター)用のポートです。ポートが占有されていない限り、変更する必要はありません。
  • 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 のスリープモードを有効にし、オプティマイザーステップ中に学生モデルの重みやキャッシュをオフロードします。GPU メモリ使用率を低く保つことができますが、エンジンの復帰時にホストとデバイス間の転送遅延が発生します。

ログ出力を制御するパラメータ

  • log_completions (bool、任意、デフォルトはFalse) — logging_steps ステップごとに、(プロンプト、補完) のペアのサンプルをログに記録するかどうか。rich がインストールされている場合、サンプルを出力します。wandb のログ出力が有効な場合、wandb に記録します。
  • log_completions_steps (int、任意、デフォルトは 100) — (prompt, completion) のペアをログに記録する間隔のステップ数。log_completions が True に設定されている場合のみ使用されます。
  • num_completions_to_print (int または None、任意) — rich で表示する補完の数を指定します。None の場合、すべての補完がログに記録されます。
  • wandb_log_unique_prompts (bool、任意、デフォルトはTrue) — wandb にユニークなプロンプトをログ出力するかどうか。これにより、各ユニークなプロンプトごとに新しいランが作成されます。
  • callbacks (list[str]、任意、デフォルトは[]) — 学習中に実行するコールバック。

experimental.gold.GOLDTrainerの設定クラスです。

このクラスには、GOLD 学習に固有のパラメータのみが含まれます。学習引数の完全なリストについては、TrainingArguments および SFTConfig のドキュメントを参照してください。

これらのパラメータは、TrainingArgumentsとは異なるデフォルト値を持っています:

  • learning_rate: 5e-5ではなく、デフォルト値が1e-7に変更されています。
Update on GitHub