TRL documentation
奖励建模
奖励建模
概述
TRL 支持结果监督奖励建模(ORM)训练器,用于训练奖励模型。
此训练后方法由 Younes Belkada 贡献。
快速入门
本示例演示了如何使用 TRL 中的 RewardTrainer 训练奖励模型。我们在 UltraFeedback dataset(一个大规模、细粒度、多样化的偏好数据集)上训练 Qwen 3 0.6B 模型。
from trl import RewardTrainer
from datasets import load_dataset
trainer = RewardTrainer(
model="Qwen/Qwen3-0.6B",
train_dataset=load_dataset("trl-lib/ultrafeedback_binarized", split="train"),
)
trainer.train()预期的数据集类型和格式
RewardTrainer 支持 preference 数据集类型(包括隐式和显式提示)。RewardTrainer 兼容 standard 和 conversational 两种数据集格式。当提供对话式数据集时,训练器会自动将聊天模板应用于该数据集。
# Standard preference (implicit prompt)
{"chosen": "The sky is blue.",
"rejected": "The sky is green."}
# Conversational preference (implicit prompt)
{"chosen": [{"role": "user", "content": "What color is the sky?"},
{"role": "assistant", "content": "It is blue."}],
"rejected": [{"role": "user", "content": "What color is the sky?"},
{"role": "assistant", "content": "It is green."}]}
# Standard preference (explicit prompt)
{"prompt": "The sky is",
"chosen": " blue.",
"rejected": " green."}
# Conversational preference (explicit prompt)
{"prompt": [{"role": "user", "content": "What color is the sky?"}],
"chosen": [{"role": "assistant", "content": "It is blue."}],
"rejected": [{"role": "assistant", "content": "It is green."}]}如果您的数据集不属于上述任何一种格式,您可以对其进行预处理,将其转换为预期的格式。以下是使用 lmarena-ai/arena-human-preference-55k 数据集的示例:
from datasets import load_dataset
import json
dataset = load_dataset("lmarena-ai/arena-human-preference-55k")
# Filter out ties
dataset = dataset.filter(lambda example: example["winner_tie"] == 0)
# Create 'chosen' and 'rejected' fields based on the winner column
def response_a_b_to_chosen_rejected(example):
if example["winner_model_a"] == 1:
example["chosen"] = example["response_a"]
example["rejected"] = example["response_b"]
else:
example["chosen"] = example["response_b"]
example["rejected"] = example["response_a"]
return example
dataset = dataset.map(response_a_b_to_chosen_rejected)
# Convert to conversational format
def make_conversation(example):
prompt = json.loads(example["prompt"])[0] # '["What color is the sky?"]' -> "What color is the sky?"
chosen = json.loads(example["chosen"])[0]
rejected = json.loads(example["rejected"])[0]
return {
"chosen": [{"role": "user", "content": prompt}, {"role": "assistant", "content": chosen}],
"rejected": [{"role": "user", "content": prompt}, {"role": "assistant", "content": rejected}],
}
dataset = dataset.map(make_conversation)
# Keep only necessary columns
dataset = dataset.select_columns(["chosen", "rejected"])
print(next(iter(dataset["train"]))){
"chosen": [
{"role": "user", "content": "Is it morally right to try to have a certain percentage of females on managerial positions?"},
{"role": "assistant", "content": "The question of whether it is morally right to aim for a certain percentage of females..."},
],
"rejected": [
{"role": "user", "content": "Is it morally right to try to have a certain percentage of females on managerial positions?"},
{"role": "assistant", "content": "As an AI, I don't have personal beliefs or opinions. However, ..."},
],
}深入了解训练方法
奖励模型(RMs)通常通过在包含偏好响应与非偏好响应对的数据集上进行监督学习来训练。其目标是学习一个函数,为偏好响应分配更高的分数,从而使模型能够基于偏好对输出进行排序。
本节详细解析奖励建模在实际应用中的工作原理,涵盖关键步骤:预处理和损失计算。
预处理和分词
在训练期间,每个样本预期包含 chosen 和 rejected 字段。有关预期格式的详细信息,请参阅 Dataset formats - Preference。 RewardTrainer 使用模型的 tokenizer 对每个输入进行分词。如果提示和补全(chosen 和 rejected)是分开提供的(显式提示情况),它们会在分词之前进行拼接。
计算损失
设 为输入序列(提示), 和 分别为被选中和被拒绝的序列。在 Bradley-Terry 模型(Bradley & Terry, 1952), )下,给定奖励函数 , 相对于 更受偏好的概率为 , 其中 是 sigmoid 函数。
奖励模型 经过训练,为优选响应 分配比非优选响应 . 更高的分数。损失函数定义为观测偏好的负对数似然:
Bradley-Terry 模型是不确定的,这意味着给所有奖励加上一个常数并不会改变偏好概率。为了解决这个问题,Helping or Herding? Reward Model Ensembles Mitigate but do not Eliminate Reward Hacking 提出添加一个辅助损失项,以鼓励奖励值围绕零居中。这由 RewardConfig 中的
center_rewards_coefficient参数控制。推荐值为1e-2。
记录的指标
在训练和评估过程中,我们记录以下指标:
global_step:迄今为止已执行的优化器步数总数。epoch:当前 epoch 编号,基于数据集迭代。num_tokens:迄今为止处理的 token 总数。loss:最近一个日志记录间隔内的平均损失。accuracy:正确预测的比例(即模型为选中的响应分配了比被拒绝的响应更高的分数),取最近一个日志记录区间的平均值。min_reward:模型分配的最小奖励分数。该值在日志记录区间内取平均值。mean_reward:模型在最近的日志记录间隔内分配的平均奖励分数。max_reward:模型分配的最大奖励分数。该值在日志记录区间内取平均值。margin:最近一个日志记录区间内的平均 margin(即 chosen 奖励与 rejected 奖励之间的差值)。learning_rate:当前学习率,如果使用调度器,该值可能会动态变化。grad_norm:梯度裁剪前计算的梯度 L2 范数。
自定义
模型初始化
您可以直接将from_pretrained()方法的kwargs传递给RewardConfig。例如,如果您想以不同的精度加载模型,类似于
model = AutoModelForSequenceClassification.from_pretrained("Qwen/Qwen3-0.6B", dtype=torch.bfloat16)您可以通过向 RewardConfig 传递 model_init_kwargs={"dtype": torch.bfloat16} 参数来实现此操作。
from trl import RewardConfig
training_args = RewardConfig(
model_init_kwargs={"dtype": torch.bfloat16},
)请注意,from_pretrained() 的所有关键字参数均受支持,但 num_labels 除外,该参数会自动设置为 1。
使用 PEFT 训练适配器
我们支持与 🤗 PEFT 库的紧密集成,允许任何用户方便地训练适配器并在 Hub 上共享,而无需训练整个模型。
from datasets import load_dataset
from trl import RewardTrainer
from peft import LoraConfig
dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
trainer = RewardTrainer(
"Qwen/Qwen3-4B",
train_dataset=dataset,
peft_config=LoraConfig(modules_to_save=["score"]) # important to include the score head when base model is not a sequence classification model
)
trainer.train()您还可以继续训练您的 PeftModel。为此,首先在 RewardTrainer 外部加载一个 PeftModel,然后直接将其传递给 trainer,而不传入 peft_config 参数。
from datasets import load_dataset
from trl import RewardTrainer
from peft import AutoPeftModelForCausalLM
model = AutoPeftModelForCausalLM.from_pretrained("trl-lib/Qwen3-4B-Reward-LoRA", is_trainable=True)
dataset = load_dataset("trl-lib/Capybara", split="train")
trainer = RewardTrainer(
model=model,
train_dataset=dataset,
)
trainer.train()在训练适配器时,由于只学习新参数,通常会使用更高的学习率(≈1e‑3)。
RewardConfig(learning_rate=1e-3, ...)
使用奖励模型进行工具调用
RewardTrainer 完全支持微调具有 tool calling 能力的模型。在这种情况下,每个数据集示例应包含:
- 对话消息,包括任何工具调用(
tool_calls)和工具响应(tool角色消息) tools列中可用工具列表,通常以 JSON 模式提供
有关预期数据集结构的详细信息,请参阅 Dataset Format — Tool Calling 部分。
RewardTrainer
类 trl.RewardTrainer
< source >( model: str | PreTrainedModel | PeftModelargs: trl.trainer.reward_config.RewardConfig | None = Nonedata_collator: collections.abc.Callable[[list[typing.Any]], dict[str, typing.Any]] | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneeval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = Nonecompute_metrics: collections.abc.Callable[[transformers.trainer_utils.EvalPrediction], dict] | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)optimizer_cls_and_kwargs: tuple[type[torch.optim.Optimizer], dict[str, typing.Any]] | None = Nonepreprocess_logits_for_metrics: collections.abc.Callable[[torch.Tensor, torch.Tensor], torch.Tensor] | None = Nonequantization_config: BitsAndBytesConfig | None = Nonepeft_config: PeftConfig | None = None )
参数
- model (
str或 PreTrainedModel 或PeftModel) — 要训练的模型。可以是以下之一:- 一个字符串,作为托管在 huggingface.co 模型仓库中的预训练模型的 model id,或指向使用 save_pretrained 保存模型权重的 目录 的路径,例如
'./my_model_directory/'。该模型使用AutoModelForSequenceClassification.from_pretrained加载,并传入args.model_init_kwargs中的关键字参数。如果未在args.model_init_kwargs中指定dtype,则默认为float32。这与 from_pretrained 不同,后者(自 Transformers v5 起)会从模型配置中推断 dtype。 - 用于序列分类的 PreTrainedModel 对象。
- 用于序列分类的
PeftModel对象。
- 一个字符串,作为托管在 huggingface.co 模型仓库中的预训练模型的 model id,或指向使用 save_pretrained 保存模型权重的 目录 的路径,例如
- args (RewardConfig,可选) —
此训练器的配置。如果为
None,则使用默认配置。 - data_collator (
DataCollator, 可选) — 用于将处理后的train_dataset或eval_dataset中的元素列表组合成一个批次的函数。 默认值为DataCollatorForPreference。 - train_dataset (Dataset 或 IterableDataset) —
用于训练的数据集。此 trainer 支持 preference 类型(包括隐式和显式提示)。样本的格式可以是以下两种之一:
只要包含
chosen_ids和rejected_ids字段,trainer 也支持已处理(已分词)的数据集。当
train_dataset是一个 IterableDataset(例如流式数据集)时,必须在训练参数中设置max_steps,因为其长度无法推断,而确定训练循环的上限并配置学习率调度器需要知道总的训练步数。 - eval_dataset (Dataset、IterableDataset、DatasetDict、IterableDatasetDict 或
dict[str, Dataset | IterableDataset]) — 用于评估的数据集。它必须满足与train_dataset相同的要求。 - processing_class (PreTrainedTokenizerBase, 可选) —
用于处理数据的分词器。如果为
None,则使用 from_pretrained 从模型名称加载分词器。必须设置填充标记processing_class.pad_token。如果处理类未设置填充标记,则默认使用processing_class.eos_token。 - compute_metrics (
Callable[[EvalPrediction], dict], 可选) — 用于在评估期间计算指标的函数。必须接受一个 EvalPrediction 并返回一个从字符串到指标值的字典。当传入的 RewardConfig 中batch_eval_metrics设置为True时,您的compute_metrics函数必须接受一个 布尔类型的compute_result参数。这将在最后一个评估批次之后触发,以指示该 函数需要计算并返回全局汇总统计量,而不是累积 批次级别的统计量。 - callbacks (列表 TrainerCallback, 可选) —
用于自定义训练循环的回调列表。这些回调将被添加到 此处.
如果要移除其中一个默认使用的回调,请使用 remove_callback 方法。
- optimizers (
tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None],可选,默认为(None, None)) — 一个包含要使用的优化器和调度器的元组。默认情况下,将在您的模型上使用AdamW的实例,并使用由args控制的、通过 get_linear_schedule_with_warmup 给出的调度器。 - optimizer_cls_and_kwargs (
tuple[Type[torch.optim.Optimizer], Dict[str, Any]], 可选) — 一个元组,包含要使用的优化器类和关键字参数。覆盖optim和optim_args中的args. 与optimizers参数不兼容。与
optimizers不同,此参数可避免在初始化 Trainer 之前将模型参数放置在正确设备上的需求。 - preprocess_logits_for_metrics (
Callable[[torch.Tensor, torch.Tensor], torch.Tensor], 可选) — 一个函数,用于在每次评估步骤缓存 logits 之前对其进行预处理。该函数必须接收两个张量(logits 和 labels),并返回处理后的 logits。此函数所做的修改将反映在传递给compute_metrics.请注意,如果数据集没有标签,则标签(第二个参数)将为
None。 - quantization_config (BitsAndBytesConfig, 可选) —
从模型标识符加载模型时使用的量化配置。与
peft_config结合用于 QLoRA 训练。如果模型已经实例化,或者args.model_init_kwargs中也设置了quantization_config,则忽略此参数。 - peft_config (
PeftConfig, 可选) — 用于包装模型的 PEFT 配置。如果为None,则不包装模型。请注意,如果加载的模型是因果语言模型(causal LM),强烈建议在 PEFT 配置中设置modules_to_save=["score"],以确保奖励头(reward head)得到正确训练。
用于结果监督奖励模型(ORM)的 Trainer。
此类是 Trainer 类的封装,并继承了其所有属性和方法。
示例:
>>> from trl import RewardTrainer
>>> from datasets import load_dataset
>>> dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
>>> trainer = RewardTrainer(
... model="Qwen/Qwen2.5-0.5B-Instruct",
... train_dataset=dataset,
... )
>>> trainer.train()训练
< 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。
RewardConfig
类 trl.RewardConfig
< source >( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 0.0001lr_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 = Falsechat_template_path: str | None = Nonedisable_dropout: bool = Truedataset_num_proc: int | None = Noneeos_token: str | None = Nonemax_length: int | None = 1024pad_to_multiple_of: int | str | None = 'auto'center_rewards_coefficient: float | None = Noneactivation_offloading: bool = Falsepad_token: str | None = None )
控制模型的参数
- model_init_kwargs (
dict[str, Any], 可选) — 用于 from_pretrained 的关键字参数,当 RewardTrainer 的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. - chat_template_path (
str, 可选) — 如果指定,将设置模型的聊天模板。它可以是 tokenizer 的路径(本地目录或 Hugging Face Hub 模型),也可以是直接指向 Jinja 模板文件的路径。使用 Jinja 文件时,必须确保模板中引用的任何特殊 token 都已添加到 tokenizer 中,并且模型的嵌入层已相应调整大小。 - disable_dropout (
bool,可选,默认为True) — 是否禁用模型中的 dropout。
控制数据预处理的参数
- dataset_num_proc (
int, 可选) — 用于处理数据集的进程数。 - eos_token (
str, 可选) — 用于指示轮次或序列结束标记的 Token。如果为None,则默认为processing_class.eos_token。 - max_length (
int或None,可选,默认为1024) — 标记化序列的最大长度。如果 chosen 或 rejected 序列中任意一个超过此值,该样本将被过滤掉。如果为None,则不应用过滤。 - pad_to_multiple_of (
int或str,可选,默认为"auto") — 如果设置,序列将被填充为该值的倍数。"auto"在 Neuron (AWS Trainium) 上填充为 128 的倍数,因为 Neuron 针对每个输入形状只编译一次,而在其他平台上不进行填充。
控制训练的参数
- center_rewards_coefficient (
float, 可选) — 用于激励奖励模型输出均值为零的奖励的系数(由这篇论文的公式 2 提出)。推荐值:0.01。 - activation_offloading (
bool,可选,默认为False) — 是否将激活值卸载到 CPU。
已弃用的参数
RewardTrainer 的配置类。
此类仅包含 Reward 训练特有的参数。有关完整的训练参数列表,请参阅 TrainingArguments 文档。请注意,此类中的默认值可能与 TrainingArguments 中的不同。
使用 HfArgumentParser,我们可以将该类转换为 argparse 参数,从而在命令行中指定。
这些参数的默认值与 TrainingArguments 不同:
logging_steps:默认值为10,而非500。gradient_checkpointing:默认值为True,而非False。bf16:如果未设置fp16,则默认值为True,而不是False。learning_rate:默认值为1e-4,而非5e-5。