TRL documentation

通用在线 Logit 蒸馏(GOLD)训练器

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

通用在线 Logit 蒸馏(GOLD)训练器

All_models-GOLD-blue

概述

通用在线 Logit 蒸馏(GOLD)是通用 Logit 蒸馏(ULD)的扩展,支持使用不同分词器(tokenizer)的学生/教师模型对。它会对齐两个分词器生成的文本片段,并合并相关的 logits,以确保不丢失任何补全 token。这使得跨分词器的知识蒸馏成为可能,包括混合模型家族(例如,使用 LLaMA 作为学生模型,Qwen 作为教师模型)。

主要功能:

  1. 跨分词器对齐 – GOLD 增量解码学生模型和教师模型的 token,将具有相同可见文本的片段分组,并在每个组内合并概率。这确保了即使 token 边界不同,损失项也能在完整的补全内容上计算。
  2. 混合 ULD 损失 – 当启用 uld_use_hybrid_loss 时,GOLD 会直接比较精确的词汇表匹配项,并对未匹配的 token 回退到原始的排序概率 ULD 损失。这提升了学生模型在词汇表与教师模型仅部分重叠情况下的稳定性。
  3. 与 GKD 无缝集成 – GOLD 继承了 experimental.gkd.GKDTrainer 中的 on-policy 与 off-policy 调度机制,因此您可以在单次训练运行中结合序列级 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 使用教师分词器来对齐 token。
  • uld_use_hybrid_loss、uld_hybrid_matched_weight、uld_hybrid_unmatched_weight – 启用并加权混合匹配/不匹配损失。
  • beta、lmbda、seq_kd – 继承自 experimental.gkd.GKDConfig,用于控制广义 JSD 插值和 on-policy 采样比例。
  • use_privileged_context、teacher_prompt_template、privileged_context_column – 允许教师模型查看每个样本的额外上下文,同时学生模型的提示词保持不变。目前此功能仅限于文本、off-policy、标准 JSD 训练。
  • num_generations、generation_batch_size – 控制跨梯度累积窗口的缓冲 rollout 生成。generation_batch_size 是每个 worker 在每个优化器步骤中处理的唯一提示数量。

一个最小的端到端示例:

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 会缓冲一个完整的优化器窗口生成批次(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 collator 能够以正确的边界构建提示和补全。

特权上下文

特权上下文蒸馏为教师模型提供了在推理时学生模型无法获取的额外信息。在常规的提示/补全数据集中添加一个上下文列,然后显式启用该功能:

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,
)

学生模型在原始的提示词和补全内容上进行训练。教师模型默认接收一个由 "{prompt}\n\n{privileged_context}" 构建的独立提示词,然后对完全相同的补全内容进行评分。对于对话数据,GOLD 仅重写最后一个用户轮次,然后重新应用聊天模板;系统、工具和助手轮次保持不变。设置 teacher_prompt_template 以自定义此提示词,并设置 privileged_context_column 以使用除 "privileged_context" 以外的列。

教师提示词永远不会被截断,因此请确保其长度在教师模型的上下文窗口之内。此初始支持有意仅限于文本和离策略标准 JSD 蒸馏:lmbda 必须为 0,且 seq_kd=True、use_uld_loss=True、X-Token KD(xtoken_loss_type 不为 "none")、packing、VLM 以及 Liger Kernel 均不支持特权上下文。

Token Merging 的工作原理

当学生模型和教师模型使用不同的分词器时,相同的文本可能会被以不同的方式切分:

  • 学生:"Hugging Face" → 1 个 token
  • 教师:"Hugging"、" Face" → 2 个标记

GOLD 将这些序列进行对齐,并将教师模型的多 token 概率合并为一个单一分布,以便与学生模型的单 token 分布进行比较。

概率合并

对于映射到单个学生 token 的教师 token 序列 [token₀, token₁, ..., tokenₖ],GOLD 计算:

P_merged(y) = P(y | context) × P(token₁ | token₀, context) × ... × P(tokenₖ | ..., context)

其中:

  • P(y | context) 是第一个位置上所有词汇表标记的边缘概率分布
  • P(tokenᵢ | ..., context) 是实际生成的 token 的标量条件概率

关键洞察:仅将实际延续 token的条件概率提取为标量。随后,通过将首位置的完整边缘分布乘以这些标量概率来进行缩放。

这确保了:

  1. 实际生成序列的正确联合概率(通过链式法则)
  2. 针对反事实 token 的合理近似(按相同的续写似然进行缩放)
  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]

如果 token 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),但这是有意为之,且对于 ULD 损失计算而言是正确的,因为该计算使用排序和 L1 距离。

示例脚本

使用 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 列(每个样本一张图像)或 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',因为图像 token 位于序列的提示部分,可能会被静默丢弃。请使用 truncation_mode='keep_start'(默认值),或在 experimental.gold.GOLDConfig 中设置 max_length=None。这允许模型处理完整的序列长度,而不会截断图像 token。

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 )

训练

< >

( 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。

主要训练入口。

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) — 具有写入权限的 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。

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 | 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 = 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 的浮点数,则仅保留概率之和达到或超过 top_p 的最小最可能 token 集合用于生成。
  • top_k (int,可选,默认为 0) — 用于 top-k 过滤时保留的最高概率词汇表 token 数量。如果为 0,则禁用 top-k 过滤,并考虑所有 token。
  • lmbda (float,可选,默认为 0.5) — Lambda 参数,用于控制学生数据比例(即 on-policy 学生生成输出的占比)。
  • beta (float, 可选,默认为 0.5) — 广义 Jensen-Shannon 散度损失在 0.0 和 1.0 之间的插值系数。当 beta 为 0.0 时,损失为 KL 散度。当 beta 为 1.0 时,损失为逆 KL 散度。
  • max_completion_length (int,可选,默认为 128) — 每次补全生成的最大 token 数。
  • 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, 可选) — 教师模型的 Tokenizer 名称或路径。如果在使用 ULD loss 时为 None,将使用与学生模型相同的 tokenizer(不推荐用于跨 tokenizer 蒸馏)。
  • disable_dropout (bool,可选,默认为 True) — 是否禁用模型中的 dropout。
  • seq_kd (bool,可选,默认为 False) — Seq_kd 参数,用于控制是否执行序列级 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) — 每个优化器步骤中每个 worker 的唯一提示数量。如果为 None,则根据 (per_device_train_batch_size * gradient_accumulation_steps) // num_generations 计算得出。

控制 ULD 损失的参数

  • use_uld_loss (bool, 可选, 默认为 False) — 是否使用 Universal Logit Distillation (ULD) 损失,而不是 Generalized Jensen-Shannon Divergence 损失。
  • use_extended_uld (bool,可选,默认为 True) — 是否启用扩展的 ULD 对齐,该功能使用分词器来对齐并合并学生模型与教师模型分词结果中的 token 概率。当 True 时,训练器将计算 token 映射并合并被拆分 token 的概率;当 False 时,ULD 将使用类似原始 ULD 论文中的简单位置截断。对于既不是 ByteLevel 也不是字节回退 BPE 的分词器(例如 Llama 2),请将其设置为 False。
  • uld_token_merge_strategy (str, 可选,默认为 "observed") — 用于对齐答案 logits 并在 ULD 损失中合并 token 概率的策略。使用 "observed" 时, 答案 logits 会在答案位置处进行切片,且拆分 token(当 use_extended_uld=True 时)会通过将第一个位置的边缘分布 乘以实际后续 token 的标量条件概率来合并。使用 "bayesian" 时,答案 logits 切片会向前移动一个位置,使得 probs[k] 预测 token_ids[k](链式法则),并且拆分 token 会使用最后一个位置的完整 分布(以实际前缀 token 为条件)乘以较早 token 的标量概率来合并。无论是否启用 use_extended_uld, logits 对齐移位都会应用。
  • uld_use_hybrid_loss (bool,可选,默认为 False) — 是否使用结合 ULD 损失和 JSD 损失的混合损失。当 True 时,最终损失是已知 token 映射的 JSD 与未知 token 映射的 ULD 的组合。
  • uld_hybrid_matched_weight (float 或 None,可选) — 在使用混合 ULD + JSD 损失时,匹配 token 损失分量的权重。该权重用于缩放在学生和教师分词之间存在直接映射的 token 上计算的 JSD 损失。如果为 None,则基于词汇表重叠度使用自适应加权。必须与 uld_hybrid_unmatched_weight 一起设置(两者均为 None 或均为 float)。
  • uld_hybrid_unmatched_weight (float 或 None,可选) — 在使用混合 ULD + JSD 损失时,未匹配 token 损失分量的权重。该权重用于缩放针对学生与教师分词之间没有直接映射关系的 token 计算出的 ULD 损失。如果为 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 损失时,是否跳过学生模型的 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) — 按微批次将 KD 缩放为 stop_gradient(abs(CE) / abs(KD)),以平衡损失量级(论文公式 7)。
  • xtoken_uncommon_topk (int,可选,默认值为 8192) — H-KL:将排序后的 L1 不常见比较限制为每侧的前 k 个 token。
  • xtoken_vocab_topk (int,可选,默认值为 8192) — P-KL:通过最大 logit 将 KL 限制在全局 top-k 教师 token 上。与投影矩阵 --top-k 相互作用:超出矩阵覆盖范围的教师 token 会获得接近零的投影学生质量,从而主导 KL,因此较小的值会将损失集中在学生能够匹配的 token 上。
  • 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 服务器的超时时间(如果 vllm_mode="server")。
  • vllm_gpu_memory_utilization (float,可选,默认值为 0.9) — 用于共置学生 vLLM 引擎的 GPU 内存利用率(如果 vllm_mode="colocate")。如果学生模型和教师模型共享同一 GPU,建议将此值设置为较低的值。
  • vllm_tensor_parallel_size (int,可选,默认为 1) — 用于共置学生 vLLM 引擎的张量并行大小(如果 vllm_mode="colocate")。
  • 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" 时,共置 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 步记录一组 (prompt, completion) 对的样本。如果已安装 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。这将为每个唯一的提示词创建一个新的 run。
  • callbacks (list[str],可选,默认为 []) — 训练期间要运行的回调。

experimental.gold.GOLDTrainer 的配置类。

此类仅包含 GOLD 训练特有的参数。有关完整的训练参数列表,请参阅 TrainingArguments 和 SFTConfig 的文档。

这些参数的默认值与 TrainingArguments 不同:

  • learning_rate:默认值为 1e-7,而非 5e-5。
Update on GitHub