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

No artigo On the Position Bias of On-Policy Distillation, os autores introduzem a Importance-Weighted On-Policy Distillation (IW-OPD). A IW-OPD aborda o viés de posição na on-policy distillation ao reponderar as atualizações de tokens amostrados de acordo com a discrepância acumulada do prefixo entre o teacher e o student. Os tokens iniciais mantêm pesos maiores, enquanto os tokens posteriores, após um alto drift, têm seus pesos reduzidos.

Para usar o IW-OPD, você pode usar a classe experimental.iw_opd.IWOPDTrainer em trl.experimental.iw_opd.

IW-OPD atualmente faz parte do namespace trl.experimental. As APIs podem mudar sem aviso prévio enquanto o recurso estiver em desenvolvimento.

Uso

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 é um objetivo on-policy: distillation_objective="iw_opd" requer lmbda=1.0 (o padrão). iw_opd_gamma é a amplificação do peso de importância do Algoritmo 1 do artigo.

IWOPDTrainer

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

Trainer para Destilação On-Policy com Ponderação de Importância (IW-OPD).

IW-OPD (Sobre o viés de posição no destilamento on-policy) repondera o sinal de destilamento dos tokens amostrados pela discrepância acumulada de prefixo entre o professor e o aluno, reduzindo o peso dos tokens posteriores cuja supervisão se desviou da distribuição. Selecione-o com distillation_objective=“iw_opd”.

Este trainer é um snapshot congelado do DistillationTrainer pré-refatoração, mantido como a casa do IW-OPD (um método de gradiente de política guiado por um professor que não se encaixa no DistillationTrainer estável e de vocabulário completo). Ele não é mantido ativamente e não acompanhará as melhorias posteriores daquele trainer.

Suporta:

  • Perda JSD generalizada (KL direta, KL reversa ou JSD interpolada via beta)
  • Objetivo IW-OPD de token amostrado (distillation_objective=“iw_opd”)
  • Mistura on-policy / off-policy via lmbda (buffered across gradient accumulation)
  • Modelo de professor local ou professor externo via servidor vLLM
  • Geração on-policy do aluno via vLLM ou model.generate()

treino

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

Parâmetros

  • resume_from_checkpoint (str ou bool, opcional) — Se for um str, caminho local para um checkpoint salvo por uma instância anterior de Trainer. Se for um bool e for igual a True, carrega o último checkpoint em args.output_dir salvo por uma instância anterior de Trainer. Se presente, o treinamento será retomado a partir dos estados do modelo/otimizador/agendador carregados aqui.
  • trial (optuna.Trial ou dict[str, Any], opcional) — A execução do trial ou o dicionário de hiperparâmetros para a busca de hiperparâmetros.
  • ignore_keys_for_eval (list[str], opcional) — Uma lista de chaves na saída do seu modelo (se for um dicionário) que devem ser ignoradas ao coletar previsões para avaliação durante o treinamento.

Retorna

~trainer_utils.TrainOutput

Objeto contendo a contagem de etapas globais, a perda de treinamento e as métricas.

Ponto de entrada principal do treinamento.

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

Salvará o modelo, para que você possa recarregá-lo usando from_pretrained().

Salvará apenas a partir do processo principal.

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

Parâmetros

  • commit_message (str, opcional, padrão "End of training") — Mensagem a ser commitada durante o push.
  • blocking (bool, opcional, padrão True) — Se a função deve retornar apenas quando o git push tiver terminado.
  • token (str, opcional, padrão None) — Token com permissão de escrita para sobrescrever os argumentos originais do Trainer.
  • revision (str, opcional) — A revisão git de onde o commit será feito. O padrão é o topo do ramo “main”.
  • private (bool, opcional) — Se o repositório deve ser privado quando for criado. O padrão é args.hub_private_repo. Não tem efeito se o repositório já existir.
  • kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais passados para ~Trainer.create_model_card.

Envie self.model e self.processing_class para o hub de modelos do 🤗 no repositório self.args.hub_model_id.

IWOPDConfig

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

Parâmetros que controlam o modelo

  • model_init_kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave para AutoModelForCausalLM.from_pretrained, usados quando o argumento model do trainer é fornecido como uma string. O valor de revision também é usado ao carregar a classe de processamento.
  • trust_remote_code (bool, opcional, padrão False) — Se permite carregar modelos e tokenizers que incluem código Python personalizado do Hub. Encaminhado para from_pretrained e from_pretrained, para o aluno e o professor.
  • max_length (int ou None, opcional, padrão 1024) — Comprimento máximo total da sequência (prompt + completion) para tokenização e truncamento.

Parâmetros que controlam a destilação

  • temperature (float, opcional, padrão 1.0) — Temperatura para amostragem durante a geração e para o cálculo da perda de destilação. Valores maiores produzem distribuições de probabilidade mais suaves.
  • lmbda (float, opcional, padrão 1.0) — Probabilidade de usar dados on-policy (gerados pelo aluno) para cada fatia de acúmulo de gradiente. Um valor de 0.0 significa totalmente off-policy (apenas conclusões do conjunto de dados), 1.0 significa totalmente on-policy.
  • beta (float, opcional, padrão 1.0) — Coeficiente de interpolação para a perda de Divergência Generalizada de Jensen-Shannon. Quando 0.0, a perda é a divergência KL direta. Quando 1.0, a perda é a divergência KL reversa. Quando 0.5, é a JSD padrão.
  • distillation_objective (str, opcional, padrão "iw_opd") — Objetivo a ser otimizado. "iw_opd" usa o objetivo de Destilação On-Policy com Ponderação de Importância (Importance-Weighted On-Policy Distillation) para tokens amostrados. "jsd" mantém o objetivo generalizado de JSD/KL.
  • iw_opd_gamma (float, opcional, padrão 0.5) — Amplificação por ponderação de importância para distillation_objective="iw_opd".
  • iw_opd_epsilon (float, opcional, padrão 1e-8) — Estabilizador usado ao normalizar os pesos de prefixo do IW-OPD.
  • reverse_kl_top_1_mode (str, opcional, padrão "sampled") — Regra de seleção para o token top-1 do reverse-KL quando beta > 0 e loss_top_k == 1. "sampled" usa o token de conclusão real no lote. "argmax" usa o token de maior probabilidade do student. Essa configuração não afeta o suporte do forward-KL, que sempre usa o token top-1 do teacher. Ignorado quando beta == 0 ou loss_top_k != 1.
  • max_completion_length (int, opcional, padrão 512) — Número máximo de tokens a serem gerados por conclusão durante a geração on-policy.
  • max_prompt_length (int ou None, opcional) — Número máximo de tokens para o prompt. Se None, é calculado automaticamente como max_length - max_completion_length. Os prompts são truncados de acordo com a configuração truncation_side do tokenizer.
  • disable_dropout (bool, opcional, padrão True) — Se deve desabilitar o dropout no modelo aluno durante o treinamento.

Parâmetros que controlam o modelo teacher

  • teacher_model_name_or_path (str ou None, opcional) — Nome ou caminho do modelo para o modelo teacher. Usado quando o teacher é carregado localmente.
  • teacher_model_revision (str ou None, opcional) — Revisão do modelo do professor (por exemplo, nome da branch, tag ou hash do commit).
  • teacher_model_init_kwargs (dict[str, Any] ou None, opcional) — Argumentos de palavra-chave passados para AutoModelForCausalLM.from_pretrained ao instanciar o modelo teacher a partir de uma string.
  • use_teacher_server (bool, opcional, padrão False) — Se deve usar um servidor de professor vLLM externo em vez de um modelo de professor local.
  • teacher_model_server_url (str ou None, opcional) — URL base de um servidor vLLM que hospeda o modelo teacher (por exemplo, "http://localhost:8000"). Quando definido, os logprobs do teacher são obtidos do servidor em vez de executar uma passagem local para frente quando use_teacher_server=True.
  • loss_top_k (int, opcional, padrão 1) — Número de tokens principais a serem usados ao calcular a perda JSD/KL. As distribuições do aluno e do professor são restritas a esses K tokens e renormalizadas antes de calcular a divergência. Se for 0, o vocabulário completo é usado. Para professores locais, a regra geral de suporte é top-k do professor para KL direta, top-k do aluno para KL reversa e a união para JSD mista. Quando beta > 0 e loss_top_k == 1, o suporte direto ainda usa o token top-1 do professor, enquanto o token top-1 reverso é controlado por reverse_kl_top_1_mode. Quando use_teacher_server=True, o caminho puramente direto (beta=0) requer que este valor seja positivo e usa os logprobs top-k do professor para o termo direto. Quando beta > 0, a destilação baseada em servidor requer loss_top_k == 1 e suporta apenas tokens top-1 reversos "sampled".
  • loss_add_tail (bool, opcional, padrão True) — Se deve adicionar um bucket de cauda que representa a massa de probabilidade restante fora do suporte top-k selecionado ao calcular a perda.

Parâmetros que controlam a geração on-policy

  • num_generations (int, opcional, padrão 1) — Número de conclusões a serem geradas por prompt durante a geração on-policy.
  • generation_batch_size (int ou None, opcional) — Número de prompts únicos por worker por passo do otimizador. Se None, calculado a partir de (per_device_train_batch_size * gradient_accumulation_steps) // num_generations.
  • top_p (float, opcional, padrão 0.95) — Parâmetro de amostragem Top-p (núcleo) para geração on-policy.
  • top_k (int, opcional, padrão 0) — Parâmetro de amostragem top-k para geração on-policy. 0 desativa o filtro top-k.

Parâmetros que controlam o vLLM para a geração do aluno

  • use_vllm (bool, opcional, padrão False) — Se deve usar o vLLM para gerar completions on-policy a partir do modelo aluno.
  • vllm_mode (str, opcional, padrão "colocate") — Modo para a integração do vLLM do aluno. Pode ser "server" ou "colocate".
  • vllm_server_base_url (str ou None, opcional) — URL base para o servidor vLLM do aluno. Se fornecida, vllm_server_host e vllm_server_port são ignorados.
  • vllm_server_host (str, opcional, padrão "0.0.0.0") — Host do servidor vLLM do aluno.
  • vllm_server_port (int, opcional, padrão 8001) — Porta do servidor vLLM do aluno.
  • vllm_server_timeout (float, opcional, padrão 240.0) — Tempo limite para conectar ao servidor vLLM do aluno.
  • vllm_group_port (int, opcional, padrão 51216) — Porta para o grupo de atualização de pesos do vLLM (comunicador NCCL).
  • vllm_gpu_memory_utilization (float, opcional, padrão 0.3) — Utilização da memória de GPU para o motor vLLM do aluno co-localizado.
  • vllm_tensor_parallel_size (int, opcional, padrão 1) — Tamanho do paralelismo de tensor para o motor vLLM do aluno co-localizado.
  • vllm_max_model_length (int ou None, opcional) — Comprimento máximo da sequência do modelo para o mecanismo vLLM co-localizado.
  • vllm_model_impl (str, opcional, padrão "vllm") — Backend de implementação do modelo para vLLM. Use "vllm" ou "transformers".
  • vllm_structured_outputs_regex (str ou None, opcional) — Padrão de expressão regular para saídas estruturadas do vLLM.
  • vllm_sync_frequency (int, opcional, padrão 1) — Frequência (em passos de treinamento) para sincronizar os pesos do modelo aluno com o mecanismo vLLM.
  • vllm_enable_sleep_mode (bool, opcional, padrão False) — Ativa o modo de suspensão do vLLM para descarregar os pesos do aluno durante o passo do otimizador.

Parâmetros que controlam o registro de logs

  • log_completions (bool, opcional, padrão False) — Se deve registrar uma amostra de pares (prompt, completion) a cada log_completions_steps etapas. Se o rich estiver instalado, ele imprime a amostra. Se o registro do wandb e/ou trackio estiver habilitado, ele registra no wandb e/ou trackio.
  • log_completions_steps (int, opcional, padrão 100) — Número de etapas entre o registro de completions. Usado apenas se log_completions for True.
  • num_completions_to_print (int ou None, opcional) — Número de conclusões a serem exibidas. Se None, todas as conclusões são registradas.

Classe de configuração para o experimental.iw_opd.IWOPDTrainer.

Estende TrainingArguments com parâmetros específicos para destilação de conhecimento. Esta configuração é independente de SFTConfig — todos os campos necessários são declarados aqui.

Usando HfArgumentParser, podemos transformar essa classe em argumentos argparse que podem ser especificados na linha de comando.

Update on GitHub