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.0).
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