TRL documentation

IW-OPD

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 通过根据累积的教师-学生前缀差异对采样 token 的更新进行重新加权,来解决 on-policy distillation 中的位置偏差问题。早期 token 保留较大的权重,而高漂移之后的后期 token 权重会被降低。

要使用 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 是一种在策略(on-policy)目标: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 the Position Bias of On-Policy Distillation)通过累积的教师-学生前缀差异对采样 token 的蒸馏信号进行重新加权,从而降低那些监督信号已偏离分布的后续 token 的权重。使用 distillation_objective=“iw_opd” 进行选择。

此训练器是重构前 DistillationTrainer 的冻结快照,作为 IW-OPD(一种不适合稳定的全词表 DistillationTrainer 的教师引导策略梯度方法)的存放位置。它不再积极维护,也不会跟进该训练器后续的改进。

支持:

  • 广义 JSD 损失(前向 KL、反向 KL,或通过 beta 插值的 JSD)
  • 采样 token 的 IW-OPD 目标(distillation_objective=“iw_opd”)
  • 通过 lmbda 进行 on-policy / off-policy 混合(在梯度累积期间进行缓冲)
  • 本地教师模型或通过 vLLM 服务器使用外部教师
  • 通过 vLLM 或 model.generate() 进行 Student 的 on-policy 生成

训练

< >

( 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

包含全局步数、训练损失和指标的 Object。

主要训练入口。

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) — 具有写入权限的 Token,用于覆盖 Trainer 的原始参数。
  • revision (str, 可选) — 要从中提交内容的 git 版本。默认为 “main” 分支的头部。
  • private (bool,可选) — 创建仓库时是否将其设为私有。默认值为 args.hub_private_repo。如果仓库已存在,则此参数无效。
  • kwargs (dict[str, Any],可选) — 传递给 ~Trainer.create_model_card 的额外关键字参数。

将 self.model 和 self.processing_class 上传到 🤗 模型库中的仓库 self.args.hub_model_id。

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 = 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], 可选) — AutoModelForCausalLM.from_pretrained 的关键字参数,当训练器的 model 参数以字符串形式提供时使用。加载处理类时也会使用 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) — 每个梯度累积切片中使用 on-policy(学生生成)数据的概率。值为 0.0 表示完全 off-policy(仅使用数据集补全),1.0 表示完全 on-policy。
  • beta (float, 可选,默认为 1.0) — 广义 Jensen-Shannon 散度损失的插值系数。当 0.0 时,损失为前向 KL 散度。当 1.0 时,损失为反向 KL 散度。当 0.5 时,为标准 JSD。
  • distillation_objective (str, 可选,默认为 "iw_opd") — 要优化的目标。"iw_opd" 使用基于采样 token 的 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 时,用于选择反向 KL top-1 token 的规则。"sampled" 使用批次中实际的补全 token。"argmax" 使用学生模型概率最高的 token。此设置不影响前向 KL 的支持集,后者始终使用教师模型的 top-1 token。当 beta == 0 或 loss_top_k != 1 时,此参数将被忽略。
  • max_completion_length (int,可选,默认为 512) — 在 on-policy 生成过程中,每次补全生成的最大 token 数。
  • max_prompt_length (int 或 None,可选) — 提示词的最大 token 数。如果为 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 损失时使用的 top token 数量。学生和教师的分布都会被限制在这些 K 个 token 内,并在计算散度之前进行重新归一化。如果为 0,则使用完整的词表。对于本地教师,通用的支持集规则是:前向 KL 使用教师 top-k,反向 KL 使用学生 top-k,混合 JSD 使用两者的并集。当 beta > 0 且 loss_top_k == 1 时,前向支持集仍使用教师的 top-1 token,而反向 top-1 token 由 reverse_kl_top_1_mode 控制。当 use_teacher_server=True 时,纯前向路径(beta=0)要求此值为正数,并使用教师的 top-k logprobs 作为前向项。当 beta > 0 时,基于服务器的蒸馏要求 loss_top_k == 1,且仅支持 "sampled" 反向 top-1 token。
  • loss_add_tail (bool,可选,默认为 True) — 在计算损失时,是否添加一个尾部桶,用于表示所选 top-k 支撑集之外的剩余概率质量。

控制 on-policy 生成的参数

  • num_generations (int,可选,默认为 1) — 在 on-policy 生成期间,每个提示词生成的补全数量。
  • generation_batch_size (int 或 None,可选) — 每个优化器步骤中每个 worker 的唯一提示数量。如果为 None,则根据 (per_device_train_batch_size * gradient_accumulation_steps) // num_generations 计算得出。
  • top_p (float,可选,默认为 0.95) — 用于 on-policy 生成的 Top-p(核)采样参数。
  • top_k (int,可选,默认为 0) — 用于 on-policy 生成的 Top-k 采样参数。0 表示禁用 top-k 过滤。

控制 vLLM 用于学生模型生成的参数

  • use_vllm (bool,可选,默认为 False) — 是否使用 vLLM 从学生模型生成 on-policy 补全。
  • 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) — 用于共置学生 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 步记录一组 (prompt, completion) 对的样本。如果已安装 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