TRL documentation
IW-OPD
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
< 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 )
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
DistillationTrainerpré-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 noDistillationTrainerestá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
< 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
Parâmetros
- resume_from_checkpoint (
stroubool, opcional) — Se for umstr, caminho local para um checkpoint salvo por uma instância anterior deTrainer. Se for umboole for igual aTrue, carrega o último checkpoint em args.output_dir salvo por uma instância anterior deTrainer. Se presente, o treinamento será retomado a partir dos estados do modelo/otimizador/agendador carregados aqui. - trial (
optuna.Trialoudict[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.
Salvará o modelo, para que você possa recarregá-lo usando from_pretrained().
Salvará apenas a partir do processo principal.
push_to_hub
< source >( 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ãoTrue) — Se a função deve retornar apenas quando ogit pushtiver terminado. - token (
str, opcional, padrãoNone) — 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
< 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 | 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 paraAutoModelForCausalLM.from_pretrained, usados quando o argumentomodeldo trainer é fornecido como uma string. O valor derevisiontambém é usado ao carregar a classe de processamento. - trust_remote_code (
bool, opcional, padrãoFalse) — 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 (
intouNone, opcional, padrão1024) — 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ão1.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ão1.0) — Probabilidade de usar dados on-policy (gerados pelo aluno) para cada fatia de acúmulo de gradiente. Um valor de0.0significa totalmente off-policy (apenas conclusões do conjunto de dados),1.0significa totalmente on-policy. - beta (
float, opcional, padrão1.0) — Coeficiente de interpolação para a perda de Divergência Generalizada de Jensen-Shannon. Quando0.0, a perda é a divergência KL direta. Quando1.0, a perda é a divergência KL reversa. Quando0.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ão0.5) — Amplificação por ponderação de importância paradistillation_objective="iw_opd". - iw_opd_epsilon (
float, opcional, padrão1e-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 quandobeta > 0eloss_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 quandobeta == 0ouloss_top_k != 1. - max_completion_length (
int, opcional, padrão512) — Número máximo de tokens a serem gerados por conclusão durante a geração on-policy. - max_prompt_length (
intouNone, opcional) — Número máximo de tokens para o prompt. SeNone, é calculado automaticamente comomax_length - max_completion_length. Os prompts são truncados de acordo com a configuraçãotruncation_sidedo tokenizer. - disable_dropout (
bool, opcional, padrãoTrue) — Se deve desabilitar o dropout no modelo aluno durante o treinamento.
Parâmetros que controlam o modelo teacher
- teacher_model_name_or_path (
strouNone, opcional) — Nome ou caminho do modelo para o modelo teacher. Usado quando o teacher é carregado localmente. - teacher_model_revision (
strouNone, opcional) — Revisão do modelo do professor (por exemplo, nome da branch, tag ou hash do commit). - teacher_model_init_kwargs (
dict[str, Any]ouNone, opcional) — Argumentos de palavra-chave passados paraAutoModelForCausalLM.from_pretrainedao instanciar o modelo teacher a partir de uma string. - use_teacher_server (
bool, opcional, padrãoFalse) — Se deve usar um servidor de professor vLLM externo em vez de um modelo de professor local. - teacher_model_server_url (
strouNone, 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 quandouse_teacher_server=True. - loss_top_k (
int, opcional, padrão1) — 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. Quandobeta > 0eloss_top_k == 1, o suporte direto ainda usa o token top-1 do professor, enquanto o token top-1 reverso é controlado porreverse_kl_top_1_mode. Quandouse_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. Quandobeta > 0, a destilação baseada em servidor requerloss_top_k == 1e suporta apenas tokens top-1 reversos"sampled". - loss_add_tail (
bool, opcional, padrãoTrue) — 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ão1) — Número de conclusões a serem geradas por prompt durante a geração on-policy. - generation_batch_size (
intouNone, opcional) — Número de prompts únicos por worker por passo do otimizador. SeNone, calculado a partir de(per_device_train_batch_size * gradient_accumulation_steps) // num_generations. - top_p (
float, opcional, padrão0.95) — Parâmetro de amostragem Top-p (núcleo) para geração on-policy. - top_k (
int, opcional, padrão0) — Parâmetro de amostragem top-k para geração on-policy.0desativa o filtro top-k.
Parâmetros que controlam o vLLM para a geração do aluno
- use_vllm (
bool, opcional, padrãoFalse) — 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 (
strouNone, opcional) — URL base para o servidor vLLM do aluno. Se fornecida,vllm_server_hostevllm_server_portsã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ão8001) — Porta do servidor vLLM do aluno. - vllm_server_timeout (
float, opcional, padrão240.0) — Tempo limite para conectar ao servidor vLLM do aluno. - vllm_group_port (
int, opcional, padrão51216) — Porta para o grupo de atualização de pesos do vLLM (comunicador NCCL). - vllm_gpu_memory_utilization (
float, opcional, padrão0.3) — Utilização da memória de GPU para o motor vLLM do aluno co-localizado. - vllm_tensor_parallel_size (
int, opcional, padrão1) — Tamanho do paralelismo de tensor para o motor vLLM do aluno co-localizado. - vllm_max_model_length (
intouNone, 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 (
strouNone, opcional) — Padrão de expressão regular para saídas estruturadas do vLLM. - vllm_sync_frequency (
int, opcional, padrão1) — Frequência (em passos de treinamento) para sincronizar os pesos do modelo aluno com o mecanismo vLLM. - vllm_enable_sleep_mode (
bool, opcional, padrãoFalse) — 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ãoFalse) — Se deve registrar uma amostra de pares (prompt, completion) a cadalog_completions_stepsetapas. Se orichestiver instalado, ele imprime a amostra. Se o registro dowandbe/outrackioestiver habilitado, ele registra nowandbe/outrackio. - log_completions_steps (
int, opcional, padrão100) — Número de etapas entre o registro de completions. Usado apenas selog_completionsforTrue. - num_completions_to_print (
intouNone, opcional) — Número de conclusões a serem exibidas. SeNone, 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.