TRL documentation
IW-OPD
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
< 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 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 生成
训练
< 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
包含全局步数、训练损失和指标的 Object。
主要训练入口。
将保存模型,以便您可以使用 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) — 具有写入权限的 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
< 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], 可选) —AutoModelForCausalLM.from_pretrained的关键字参数,当训练器的model参数以字符串形式提供时使用。加载处理类时也会使用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) — 每个梯度累积切片中使用 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 参数,从而在命令行中指定。