TRL documentation

IW-OPD

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.18.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

< >

( 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

< >

( 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

グローバルステップ数、トレーニング損失、およびメトリクスを含むオブジェクト。

メインの学習エントリポイント。

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 にアップロードします。

IWOPDConfig

クラス trl.experimental.iw_opd.IWOPDConfig

< >

( 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 | 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 = 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 to False) — 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 の引数に変換できます。

Update on GitHub