TRL documentation
IW-OPD
IW-OPD
論文 On the Position Bias of On-Policy Distillation において、著者らは Importance-Weighted On-Policy Distillation (IW-OPD) を提案しています。IW-OPD は、蓄積された教師モデルと生徒モデルのプレフィックスの乖離に基づいてサンプリングされたトークンの更新を再重み付けすることで、オンポリシー蒸留における位置バイアスに対処します。初期のトークンはより大きな重みを保ち、大きなドリフトが発生した後の後続のトークンは重みが低減されます。
IW-OPDを使用するには、trl.experimental.iw_opd内のexperimental.iw_opd.IWOPDTrainerクラスを使用できます。
IW-OPD は現在、
trl.experimental名前空間の一部です。この機能が反復的に改善されている間、API は予告なく変更される場合があります。
使用方法
from trl.experimental.iw_opd import IWOPDConfig, IWOPDTrainer
training_args = IWOPDConfig(
distillation_objective="iw_opd",
iw_opd_gamma=0.5,
)
trainer = IWOPDTrainer(
model="Qwen/Qwen3-0.6B",
teacher_model="...",
train_dataset=...,
args=training_args,
)
trainer.train()IW-OPD はオンポリシーの目的関数です: distillation_objective="iw_opd" は lmbda=1.0(デフォルト値)を必要とします。 iw_opd_gamma は、論文のアルゴリズム 1 における重要度重みの増幅係数です。
IWOPDTrainer
クラス trl.experimental.iw_opd.IWOPDTrainer
< source >( 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.iw_opd.iw_opd_config.IWOPDConfig | 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 )
重要度重み付きオンポリシー蒸留(IW-OPD)用のTrainer。
IW-OPD(On-Policy Distillation の位置バイアスについて)は、蓄積された教師モデルと生徒モデルのプレフィックスの乖離によって、サンプリングされたトークンの蒸留シグナルを再重み付けします。これにより、教師信号が分布から逸脱した後のトークンの重みを低減します。distillation_objective=“iw_opd” を指定して選択します。
このトレーナーは、リファクタリング前の
DistillationTrainerの凍結スナップショットであり、IW-OPD(安定した全語彙のDistillationTrainerには適合しない、教師モデルによるガイダンス付きのポリシーグラデーション手法)の置き場として保持されています。アクティブなメンテナンスは行われておらず、そのトレーナーの後の改善に追従することはありません。
サポート:
- 汎用化JSD損失(フォワードKL、リバーサルKL、またはbetaによる補間JSD)
- サンプリングトークンIW-OPD目的関数(distillation_objective=“iw_opd”)
- lmbda によるオンポリシー/オフポリシーの混合(グラデーション蓄積にわたってバッファリング)
- ローカル教師モデルまたはvLLMサーバー経由の外部教師
- vLLMまたはmodel.generate()によるStudentのオンポリシー生成
train
< source >( 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
グローバルステップ数、トレーニング損失、およびメトリクスを含むオブジェクト。
メインの学習エントリポイント。
モデルを保存するため、from_pretrained()を使用して再読み込みできます。
メインプロセスからのみ保存します。
push_to_hub
< source >( 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 にアップロードします。
IWOPDConfig
クラス trl.experimental.iw_opd.IWOPDConfig
< source >( 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 = Falsemax_length: int | None = 1024temperature: float = 1.0lmbda: float = 1.0beta: float = 1.0distillation_objective: str = 'iw_opd'iw_opd_gamma: float = 0.5iw_opd_epsilon: float = 1e-08reverse_kl_top_1_mode: str = 'sampled'max_completion_length: int = 512max_prompt_length: int | None = Nonedisable_dropout: bool = Trueteacher_model_name_or_path: str | None = Noneteacher_model_revision: str | None = Noneteacher_model_init_kwargs: dict[str, typing.Any] | str | None = Noneuse_teacher_server: bool = Falseteacher_model_server_url: str | None = Noneloss_top_k: int = 1loss_add_tail: bool = Truenum_generations: int = 1generation_batch_size: int | None = Nonetop_p: float = 0.95top_k: int = 0use_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.3vllm_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 = None )
モデルを制御するパラメータ
- model_init_kwargs (
dict[str, Any]、省略可) —model引数が文字列として指定された場合、AutoModelForCausalLM.from_pretrainedに渡すキーワード引数です。revisionの値は、処理クラスの読み込み時にも使用されます。 - trust_remote_code (
bool, optional, defaults toFalse) — Whether to allow loading models and tokenizers that ship custom Python code from the Hub. Forwarded to from_pretrained and from_pretrained, for both the student and teacher. - max_length (
intまたはNone、任意、デフォルトは1024) — トークン化および切り詰めにおける、プロンプトと補完の合計シーケンス長の最大値。
蒸留を制御するパラメータ
- temperature (
float、任意、デフォルトは1.0) — 生成時のサンプリングおよび蒸留損失の計算に使用される温度です。値を高くすると、より柔らかい確率分布が得られます。 - lmbda (
float、任意、デフォルト値は1.0) — 各グラデーション蓄積スライスにおいて、オンポリシー(学生が生成した)データを使用する確率です。0.0は完全にオフポリシー(データセットの補完のみ)を意味し、1.0は完全にオンポリシーを意味します。 - beta (
float、任意、デフォルトは1.0) — Generalized Jensen-Shannon Divergence損失の補間係数です。0.0の場合、損失はforward KL分散になります。1.0の場合、損失はreverse KL分散になります。0.5の場合、標準的なJSDになります。 - distillation_objective (
str, 任意、デフォルトは"iw_opd") — 最適化する目的関数です。"iw_opd"は、サンプリングされたトークンを用いた Importance-Weighted On-Policy Distillation の目的関数を使用します。"jsd"は、汎用 JSD/KL の目的関数を維持します。 - iw_opd_gamma (
float、任意、デフォルト値は0.5) —distillation_objective="iw_opd"における重要度重みによる増幅係数。 - iw_opd_epsilon (
float, 省略可能、デフォルト値は1e-8) — IW-OPDプレフィックス重みの正規化時に使用される安定化項です。 - reverse_kl_top_1_mode (
str、任意、デフォルトは"sampled") —beta > 0かつloss_top_k == 1の場合の、reverse-KLにおけるtop-1トークンの選択ルールです。"sampled"はバッチ内の実際のcompletionトークンを使用します。"argmax"はstudentの確率が最も高いトークンを使用します。この設定はforward-KLのサポートには影響せず、常にteacherのtop-1トークンが使用されます。beta == 0またはloss_top_k != 1の場合は無視されます。 - max_completion_length (
int、任意、デフォルトは512) — オンポリシー生成時に、1回のコンプリーションで生成するトークンの最大数。 - max_prompt_length (
intまたはNone、任意) — プロンプトの最大トークン数。Noneの場合、max_length - max_completion_lengthとして自動計算されます。 プロンプトは、トークナイザーのtruncation_side設定に従って切り詰められます。 - disable_dropout (
bool、任意、デフォルトはTrue) — 学習中に学生モデルのdropoutを無効にするかどうかを指定します。
教師モデルを制御するパラメータ
- teacher_model_name_or_path (
strまたはNone、任意) — 教師モデルのモデル名またはパス。教師モデルをローカルで読み込む場合に使用します。 - teacher_model_revision (
strまたはNone、省略可能) — 教師モデルのモデルリビジョン(例:ブランチ名、タグ、またはコミットハッシュ)。 - teacher_model_init_kwargs (
dict[str, Any]またはNone、省略可) — 文字列から教師モデルをインスタンス化する場合に、AutoModelForCausalLM.from_pretrainedに渡されるキーワード引数 - use_teacher_server (
bool、省略可、デフォルトはFalse) — ローカルの教師モデルではなく、外部のvLLM教師サーバーを使用するかどうかを指定します。 - teacher_model_server_url (
strまたはNone、省略可能) — 教師モデルをホストする vLLM サーバーのベース URL(例:"http://localhost:8000")。設定すると、use_teacher_server=Trueの場合、ローカルでのフォワードパスを実行する代わりに、サーバーから教師の logprobs を取得します。 - loss_top_k (
int、任意、デフォルトは1) — JSD/KL ロスの計算に使用する上位トークンの数です。学生モデルと教師モデルの両方の分布は、これらの K 個のトークンに制限され、分散を計算する前に再正規化されます。0 の場合、語彙全体が使用されます。ローカル教師の場合、一般的なサポートのルールは、前方 KL には教師の top-k、後方 KL には学生の top-k、混合 JSD にはそれらの和集合です。beta > 0かつloss_top_k == 1の場合、前方サポートは引き続き教師の top-1 トークンを使用しますが、後方の top-1 トークンはreverse_kl_top_1_modeによって制御されます。use_teacher_server=Trueの場合、純粋な前方パス (beta=0) では、この値が正であることが必要であり、前方項には教師の top-k logprobs が使用されます。beta > 0の場合、サーバーベースの蒸留ではloss_top_k == 1が必要であり、後方の top-1 トークンとして"sampled"のみサポートされます。 - loss_add_tail (
bool、任意、デフォルトはTrue) — 損失を計算する際に、選択された top-k サポートの外側の残りの確率質量を表する tail バケットを追加するかどうか。
オンポリシー生成を制御するパラメータ
- num_generations (
int、任意、デフォルトは1) — オンポリシー生成時に、各プロンプトに対して生成する補完の数を指定します。 - generation_batch_size (
intまたはNone、任意) — 1 つのワーカーあたり、1 ステップのオプティマイザ更新ごとに使用するユニークなプロンプトの数。Noneの場合、(per_device_train_batch_size * gradient_accumulation_steps) // num_generationsから計算されます。 - top_p (
float、任意、デフォルトは0.95) — オンポリシー生成におけるトップp (ニュークリア) サンプリングのパラメータです。 - top_k (
int、任意、デフォルトは0) — オンポリシー生成におけるTop-kサンプリングのパラメータです。0を指定すると、Top-kフィルタリングが無効になります。
生徒の生成を制御する vLLM のパラメータ
- use_vllm (
bool、省略可、デフォルトはFalse) — 学生モデルからのオンポリシー補完の生成に vLLM を使用するかどうか。 - vllm_mode (
str、任意、デフォルトは"colocate") — 学生モデルの vLLM 統合モード。"server"または"colocate"のいずれかです。 - vllm_server_base_url (
strまたはNone、省略可能) — 学生 vLLM サーバーのベース URL です。指定された場合、vllm_server_hostとvllm_server_portは無視されます。 - vllm_server_host (
str, 任意, デフォルトは"0.0.0.0") — 学生 vLLM サーバーのホストです。 - vllm_server_port (
int, 任意, デフォルトは8001) — 学生 vLLM サーバーのポートです。 - vllm_server_timeout (
float, 任意, デフォルト値は240.0) — 学生 vLLM サーバーへの接続のタイムアウトです。 - vllm_group_port (
int、任意、デフォルトは51216) — vLLM の重み更新グループ(NCCL コミュニケーター)に使用するポート。 - vllm_gpu_memory_utilization (
float、任意、デフォルト値は0.3) — 同一マシンに配置された student vLLM エンジン用の GPU メモリ使用率。 - vllm_tensor_parallel_size (
int, 任意、デフォルトは1) — コロケーションされた student vLLM エンジンのテンソル並列サイズです。 - vllm_max_model_length (
intまたはNone、任意) — コロケーションされた vLLM エンジン用のモデルの最大シーケンス長です。 - vllm_model_impl (
str、任意、デフォルトは"vllm") — vLLM のモデル実装バックエンドです。"vllm"または"transformers"を使用します。 - vllm_structured_outputs_regex (
strまたはNone、省略可能) — vLLMの構造化出力用の正規表現パターンです。 - vllm_sync_frequency (
int、任意、デフォルトは1) — vLLM エンジンに学生モデルの重みを同期する頻度(トレーニングステップ数)。 - vllm_enable_sleep_mode (
bool、任意、デフォルトはFalse) — vLLM のスリープモードを有効にし、オプティマイザーステップ中に学生モデルの重みをオフロードします。
ログ出力を制御するパラメータ
- log_completions (
bool、任意、デフォルトはFalse) —log_completions_stepsステップごとに、(プロンプト、補完) のペアのサンプルをログに記録するかどうか。richがインストールされている場合、サンプルが出力されます。wandbおよび/またはtrackioのログ出力が有効な場合、wandbおよび/またはtrackioに記録されます。 - log_completions_steps (
int、任意、デフォルトは100) — completionsのログ出力の間隔(ステップ数)。log_completionsがTrueの場合にのみ使用されます。 - num_completions_to_print (
intまたはNone、任意) — 出力する補完の数を指定します。Noneの場合、すべての補完がログに記録されます。
experimental.iw_opd.IWOPDTrainer用の設定クラスです。
TrainingArgumentsを継承し、知識蒸留に固有のパラメータを追加します。この設定はSFTConfigとは独立しており、必要なフィールドはすべてここで宣言されています。
HfArgumentParser を使用すると、このクラスをコマンドラインで指定できる argparse の引数に変換できます。