TRL documentation
SFT Trainer
SFT Trainer
概述
TRL 支持用于训练语言模型的监督微调(SFT)Trainer。
SFTTrainer 并不原生支持 DiffusionGemma 等扩散模型,但可以轻松对其进行扩展以实现该功能,请参阅 block-diffusion SFT 示例。
此训练后方法由 Younes Belkada 贡献。
快速入门
本示例演示了如何使用 TRL 中的 SFTTrainer 来训练语言模型。我们在 Capybara dataset 上训练一个 Qwen 3 0.6B 模型,该数据集是一个紧凑且多样的多轮对话数据集,用于评估推理和泛化能力。
from trl import SFTTrainer
from datasets import load_dataset
trainer = SFTTrainer(
model="Qwen/Qwen3-0.6B",
train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()预期的数据集类型和格式
SFT 同时支持 语言建模 和 提示-补全 数据集。SFTTrainer 兼容 标准 和 对话 两种数据集格式。当提供对话数据集时,训练器会自动将聊天模板应用于该数据集。
# Standard language modeling
{"text": "The sky is blue."}
# Conversational language modeling
{"messages": [{"role": "user", "content": "What color is the sky?"},
{"role": "assistant", "content": "It is blue."}]}
# Standard prompt-completion
{"prompt": "The sky is",
"completion": " blue."}
# Conversational prompt-completion
{"prompt": [{"role": "user", "content": "What color is the sky?"}],
"completion": [{"role": "assistant", "content": "It is blue."}]}如果您的数据集不属于上述任何一种格式,您可以对其进行预处理,将其转换为预期的格式。以下是使用 FreedomIntelligence/medical-o1-reasoning-SFT 数据集的示例:
from datasets import load_dataset
dataset = load_dataset("FreedomIntelligence/medical-o1-reasoning-SFT", "en")
def preprocess_function(example):
return {
"prompt": [{"role": "user", "content": example["Question"]}],
"completion": [
{"role": "assistant", "content": f"<think>{example['Complex_CoT']}</think>{example['Response']}"}
],
}
dataset = dataset.map(preprocess_function, remove_columns=["Question", "Response", "Complex_CoT"])
print(next(iter(dataset["train"]))){
"prompt": [
{
"content": "Given the symptoms of sudden weakness in the left arm and leg, recent long-distance travel, and the presence of swollen and tender right lower leg, what specific cardiac abnormality is most likely to be found upon further evaluation that could explain these findings?",
"role": "user",
}
],
"completion": [
{
"content": "<think>Okay, let's see what's going on here. We've got sudden weakness [...] clicks into place!</think>The specific cardiac abnormality most likely to be found in [...] the presence of a PFO facilitating a paradoxical embolism.",
"role": "assistant",
}
],
}深入了解 SFT 方法
监督微调(SFT)是将语言模型适配到目标数据集最简单且最常用的方法。模型以完全监督的方式,使用输入和输出序列对进行训练。其目标是在给定输入的条件下,最小化目标序列的负对数似然(NLL)。
本节详细说明了 SFT 在实际中的工作原理,涵盖了关键步骤:预处理、分词和损失计算。
预处理和分词
在训练期间,根据数据集格式的不同,每个样本预期包含一个 text 字段 或一个 (prompt, completion) 对。有关预期格式的详细信息,请参阅 Dataset formats。 SFTTrainer 使用模型的 tokenizer 对每个输入进行分词。如果 prompt 和 completion 是分开提供的,它们会在分词之前进行拼接。
计算损失

SFT 中使用的损失是 token 级交叉熵损失, ,定义如下:
其中 是时间步 , 处的目标 token,模型被训练为根据前文预测下一个 token。在实际操作中,计算损失时会屏蔽填充 token。
论文 On the Generalization of SFT: A Reinforcement Learning Perspective with Reward Rectification 提出了一种替代损失函数,称为 Dynamic Fine-Tuning (DFT),旨在通过校正奖励信号来提升泛化能力。通过在 SFTConfig 中设置
loss_type="dft"即可启用该方法。更多详情请参阅 Paper Index - Dynamic Fine-Tuning。
标签移位和掩码
在训练过程中,损失的计算采用单 token 移位:模型被训练为基于序列中所有前序 token 来预测每个 token。具体而言,输入序列向右移动一个位置以形成目标标签。
填充 token(如果存在)在损失计算中会被忽略,方法是对相应位置应用忽略索引(默认值:-100)。这确保了损失仅关注有意义的、非填充的 token。
记录的指标
在训练和评估过程中,我们记录以下指标:
global_step:迄今为止已执行的优化器步数总数。epoch:当前 epoch 编号,基于数据集迭代。num_tokens:迄今为止处理的 token 总数。loss:在当前日志记录区间内,针对非掩码 token 计算的平均交叉熵损失。entropy:模型在未屏蔽 token 上的预测 token 分布的平均熵。aux_loss:混合专家(Mixture-of-Experts)模型的负载均衡辅助损失,在乘以router_aux_loss_coef并加到总损失之前。仅当模型为 MoE 模型且router_aux_loss_coef非零时记录。mean_token_accuracy:模型 top-1 预测与真实 token 匹配的非掩码 token 所占的比例。learning_rate:当前学习率,如果使用调度器,该值可能会动态变化。grad_norm:梯度裁剪前计算的梯度 L2 范数。
自定义
模型初始化
您可以直接将 from_pretrained() 方法的 kwargs 传递给 SFTConfig。例如,如果您想以不同的精度加载模型,类似于
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", dtype=torch.bfloat16)您可以通过向 SFTConfig 传递 model_init_kwargs={"dtype": torch.bfloat16} 参数来实现此操作。
from trl import SFTConfig
training_args = SFTConfig(
model_init_kwargs={"dtype": torch.bfloat16},
)请注意,from_pretrained() 的所有关键字参数均受支持。
打包
SFTTrainer 支持示例打包,即将多个示例打包到同一个输入序列中以提高训练效率。要启用打包,只需在 SFTConfig 构造函数中传入 packing=True。
training_args = SFTConfig(packing=True)有关打包的更多详细信息,请参阅 Packing。
仅针对助手消息进行训练
若仅针对助手消息进行训练,请使用conversational数据集,并在SFTConfig中设置assistant_only_loss=True。此设置确保损失仅在only助手回复上计算,忽略用户或系统消息。
training_args = SFTConfig(assistant_only_loss=True)
此功能要求聊天模板中包含
{% generation %}和{% endgeneration %}关键字。对于已知的模型系列(例如 Qwen3),当assistant_only_loss=True时,TRL 会自动修补模板。有关内置训练模板的完整列表,请参阅 Chat Templates。对于其他模型,请检查您的聊天模板是否包含这些关键字。示例参见 HuggingFaceTB/SmolLM3-3B。
仅在完成时训练
若仅针对补全部分进行训练,请使用 prompt-completion 数据集。默认情况下,训练器仅计算补全 token 的损失,忽略提示 token。若希望针对完整序列进行训练,请在 SFTConfig 中设置 completion_only_loss=False。
from trl import SFTConfig, SFTTrainer
from datasets import load_dataset
# Load a prompt-completion dataset; loss is computed on the completion only by default
dataset = load_dataset("trl-lib/kto-mix-14k", split="train")
trainer = SFTTrainer(
model="Qwen/Qwen2.5-0.5B-Instruct",
args=SFTConfig(completion_only_loss=True), # True by default for prompt-completion datasets
train_dataset=dataset,
)
trainer.train()
仅针对 completion 进行训练与仅针对 assistant 消息进行训练是兼容的。在这种情况下,请使用 conversational prompt-completion 数据集,并在 SFTConfig 中设置
assistant_only_loss=True。
使用 PEFT 训练适配器
我们支持与 🤗 PEFT 库的紧密集成,允许任何用户方便地训练适配器并在 Hub 上共享,而无需训练整个模型。
from datasets import load_dataset
from trl import SFTTrainer
from peft import LoraConfig
dataset = load_dataset("trl-lib/Capybara", split="train")
trainer = SFTTrainer(
"Qwen/Qwen3-0.6B",
train_dataset=dataset,
peft_config=LoraConfig(),
)
trainer.train()您还可以继续训练您的 PeftModel。为此,首先在 SFTTrainer 外部加载一个 PeftModel,然后直接将其传递给 trainer,而不传入 peft_config 参数。
from datasets import load_dataset
from trl import SFTTrainer
from peft import AutoPeftModelForCausalLM
model = AutoPeftModelForCausalLM.from_pretrained("trl-lib/Qwen3-4B-LoRA", is_trainable=True)
dataset = load_dataset("trl-lib/Capybara", split="train")
trainer = SFTTrainer(
model=model,
train_dataset=dataset,
)
trainer.train()在训练适配器时,由于只学习新参数,通常会使用更高的学习率(≈1e‑4)。
SFTConfig(learning_rate=1e-4, ...)
SFT 的快速实验
RapidFire AI 是一个构建在 TRL 之上的开源实验引擎,允许你同时启动多个 SFT 配置,即使只有一块 GPU 也是如此。与按顺序尝试配置不同,RapidFire 让你能够更早地查看所有配置的学习曲线,停止表现不佳的运行,并在运行过程中使用新设置克隆有前景的配置,而无需重启。有关更多信息,请参阅 RapidFire AI Integration。
使用 Unsloth 进行训练
Unsloth 是一个用于微调和强化学习的开源框架,可将 LLM(如 Llama、Mistral、Gemma、DeepSeek 等)的训练速度提升高达 2 倍,同时减少高达 70% 的 VRAM 占用,并提供简化的、与 Hugging Face 兼容的训练、评估和部署工作流。更多信息请参阅 Unsloth 集成。
指令微调示例
指令微调教会基础语言模型遵循用户指令并进行对话。这需要:
- 对话模板:定义如何将对话结构化为文本序列,包括角色标记(user/assistant)、特殊标记和轮次边界。有关对话模板的更多信息,请参阅 对话模板。
- 对话数据集:包含指令-响应对
本示例展示了如何使用 Capybara 数据集 和来自 HuggingFaceTB/SmolLM3-3B 的聊天模板,将 Qwen 3 0.6B Base 模型转换为指令遵循模型。SFT Trainer 会自动处理分词器更新和特殊标记配置。
from trl import SFTConfig, SFTTrainer
from datasets import load_dataset
trainer = SFTTrainer(
model="Qwen/Qwen3-0.6B-Base",
args=SFTConfig(
output_dir="Qwen3-0.6B-Instruct",
chat_template_path="HuggingFaceTB/SmolLM3-3B",
),
train_dataset=load_dataset("trl-lib/Capybara", split="train"),
)
trainer.train()一些基础模型(例如 Qwen 的模型)在其分词器中预定义了聊天模板。在这种情况下,无需应用
clone_chat_template(),因为分词器已经处理了格式化。但是,需要将 EOS token 与聊天模板对齐,以确保模型的响应正确终止。在这种情况下,请在 SFTConfig 中指定eos_token;例如,对于Qwen/Qwen2.5-1.5B,应将eos_token="<|im_end|>"设置为该值。
训练完成后,您的模型即可使用新的聊天模板遵循指令并进行对话。
>>> from transformers import pipeline
>>> pipe = pipeline("text-generation", model="Qwen3-0.6B-Instruct/checkpoint-5000")
>>> prompt = "<|im_start|>user\nWhat is the capital of France? Answer in one word.<|im_end|>\n<|im_start|>assistant\n"
>>> response = pipe(prompt)
>>> response[0]["generated_text"]
'<|im_start|>user\nWhat is the capital of France? Answer in one word.<|im_end|>\n<|im_start|>assistant\nThe capital of France is Paris.'或者,使用结构化对话格式(推荐):
>>> prompt = [{"role": "user", "content": "What is the capital of France? Answer in one word."}]
>>> response = pipe(prompt)
>>> response[0]["generated_text"]
[{'role': 'user', 'content': 'What is the capital of France? Answer in one word.'}, {'role': 'assistant', 'content': 'The capital of France is Paris.'}]使用 SFT 进行工具调用
SFTTrainer 完全支持对具有 tool calling 能力的模型进行微调。在这种情况下,每个数据集示例应包含:
- 对话消息,包括任何工具调用(
tool_calls)和工具响应(tool角色消息) tools列中可用工具列表,通常以 JSON 模式提供
有关预期数据集结构的详细信息,请参阅 Dataset Format — Tool Calling 部分。
训练视觉语言模型
SFTTrainer 完全支持训练视觉语言模型(VLM)。要训练 VLM,请提供一个包含 image 列(每个样本一张图像)或 images 列(每个样本一个图像列表)的数据集。有关预期数据集结构的更多信息,请参阅 数据集格式 — 视觉数据集 部分。
此类数据集的一个示例是 LLaVA Instruct Mix。
from trl import SFTConfig, SFTTrainer
from datasets import load_dataset
trainer = SFTTrainer(
model="Qwen/Qwen2.5-VL-3B-Instruct",
args=SFTConfig(max_length=None),
train_dataset=load_dataset("trl-lib/llava-instruct-mix", split="train"),
)
trainer.train()对于 VLM,截断可能会移除图像 token,从而导致训练过程中出现错误。为避免这种情况,请在 SFTConfig 中设置
max_length=None。这允许模型处理完整的序列长度,而不会截断图像 token。SFTConfig(max_length=None, ...)仅在确认截断不会移除整个数据集中的图像标记后,才使用
max_length。
SFTTrainer
类 trl.SFTTrainer
< source >( model: str | PreTrainedModel | PeftModelargs: trl.trainer.sft_config.SFTConfig | transformers.training_args.TrainingArguments | 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 | transformers.processing_utils.ProcessorMixin | None = Nonecompute_loss_func: collections.abc.Callable | 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 = Noneformatting_func: collections.abc.Callable[[dict], str] | None = None )
参数
- model (
str或 PreTrainedModel 或 PeftModel) — 要训练的模型。可以是以下之一:- 一个字符串,可以是托管在 huggingface.co 模型仓库中的预训练模型的 model id,也可以是包含使用 save_pretrained 保存的模型权重的 目录 的路径,例如
'./my_model_directory/'。该模型使用<ModelArchitecture>.from_pretrained加载(其中<ModelArchitecture>由模型配置推导得出),并传入args.model_init_kwargs中的关键字参数。如果未在args.model_init_kwargs中指定dtype,则默认为float32。这与 from_pretrained 不同,在后者中(自 Transformers v5 起),dtype 是从模型配置中推断得出的。 - 一个 PreTrainedModel 对象。仅支持因果语言模型。
- 一个 PeftModel 对象。仅支持因果语言模型。
- 一个字符串,可以是托管在 huggingface.co 模型仓库中的预训练模型的 model id,也可以是包含使用 save_pretrained 保存的模型权重的 目录 的路径,例如
- args (SFTConfig, 可选) —
此训练器的配置。如果为
None,则使用默认配置。 - data_collator (
DataCollator, 可选) — 用于将处理后的train_dataset或eval_dataset中的元素列表组合成一个批次的函数。 默认使用DataCollatorForLanguageModeling,如果数据集包含图像,则使用DataCollatorForVisionLanguageModeling。 - train_dataset (Dataset 或 IterableDataset) —
用于训练的 语言建模 类型或
提示-补全 类型。样本的格式可以是以下两种之一:
Trainer 还支持预分词数据集,通过必需的
input_ids列来识别。如果存在可选的labels列(在损失中排除的 token 上为-100),则直接使用该列;否则,标签将从可选的assistant_masks/completion_mask列构建(这些列随后会被合并并丢弃,completion_mask仅在completion_only_loss=True时如此),或者默认为input_ids的副本。在准备阶段,序列会被截断至max_length。当skip_prepare_dataset=True时,将跳过准备步骤,并预期 collator 按原样处理数据集。当
train_dataset是一个 IterableDataset(例如流式数据集)时,必须在训练参数中设置max_steps,因为其长度无法推断,而确定训练循环的上限并配置学习率调度器需要知道总的训练步数。 - eval_dataset (Dataset、IterableDataset、DatasetDict、IterableDatasetDict 或
dict[str, Dataset | IterableDataset]) — 用于评估的数据集。它必须满足与train_dataset相同的要求。 - processing_class (PreTrainedTokenizerBase、ProcessorMixin、可选) —
用于处理数据的处理类。如果为
None,则使用 from_pretrained 从模型名称加载处理类。必须设置填充标记tokenizer.pad_token。如果处理类未设置填充标记,则默认使用tokenizer.eos_token。 - compute_loss_func (
Callable, 可选) — 一个函数,接受模型输出、标签以及整个累积批次中的项目数量(batch_size * gradient_accumulation_steps),并返回损失值。此参数已弃用,并将在 v2.0.0 中移除:请改为子类化 SFTTrainer 并重写compute_loss。 - compute_metrics (
Callable[[EvalPrediction], dict], 可选) — 用于在评估期间计算指标的函数。必须接受一个 EvalPrediction 并返回一个从字符串到指标值的字典。当传入的 SFTConfig 中batch_eval_metrics设置为True时,您的compute_metrics函数必须接受一个布尔类型的compute_result参数。这将在最后一个评估批次之后触发,以指示该函数 需要计算并返回全局汇总统计量,而不是累积批次级别的 统计量。它接收的 logits 将通过额外的前向传播重新计算。此功能已弃用,并将在 v2.0.0 中移除。 - 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 训练。如果模型已经实例化,则忽略此配置。 - peft_config (PeftConfig,可选) —
用于包装模型的 PEFT 配置。如果为
None,则不包装模型。 - formatting_func (
Callable, 可选) — 在分词之前应用于数据集的格式化函数。显式应用格式化函数会将数据集转换为 语言建模 类型。
用于监督微调(SFT)方法的 Trainer。
此类是 Trainer 类的封装,并继承了其所有属性和方法。
示例:
>>> from trl import SFTTrainer
>>> from datasets import load_dataset
>>> dataset = load_dataset("roneneldan/TinyStories", split="train[:1%]")
>>> trainer = SFTTrainer(
... 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。
SFTConfig
类 trl.SFTConfig
< source >( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 2e-05lr_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 = None )
控制模型的参数
- model_init_kwargs (
dict[str, Any], 可选) — 用于 from_pretrained 的关键字参数,当 SFTTrainer 的model参数以字符串形式提供时使用。加载处理类时也会使用revision的值。 - trust_remote_code (
bool,可选,默认为False) — 是否允许加载附带自定义 Python 代码的模型和分词器。该参数会转发给 from_pretrained 和 from_pretrained。 - router_aux_loss_coef (
float, 可选) — 混合专家(MoE)模型中负载均衡辅助损失的系数,以该权重添加到训练损失中。如果未设置,则使用模型配置中声明的值。设置为0.0可将其禁用。与非 MoE 模型一起使用时会失败。 - chat_template_path (
str, 可选) — 如果指定,将设置模型的聊天模板。它可以是 tokenizer 的路径(本地目录或 Hugging Face Hub 模型),也可以是直接指向 Jinja 模板文件的路径。使用 Jinja 文件时,必须确保模板中引用的任何特殊 token 都已添加到 tokenizer 中,并且模型的嵌入层已相应调整大小。
控制数据预处理的参数
- dataset_text_field (
str,可选,默认为"text") — 数据集中包含文本数据的列名。 - dataset_kwargs (
dict[str, Any], 可选) — 用于数据集准备的可选关键字参数字典。唯一支持的键是skip_prepare_dataset。当数据集包含图像时,无论提供的值是什么,skip_prepare_dataset都会自动被视为True,因为预处理是即时执行的。 - dataset_num_proc (
int, 可选) — 用于处理数据集的进程数。 - eos_token (
str, 可选) — 用于指示轮次或序列结束标记的 Token。如果为None,则默认为processing_class.eos_token。 - max_length (
int或None,可选,默认为1024) — 标记化序列的最大长度。长度超过max_length的序列将根据truncation_mode从左侧或右侧截断。如果为None,则不应用截断。当启用打包时,此值用于设置序列长度。 - truncation_mode (
str,可选,默认为"keep_start") — 当序列长度超过max_length时使用的截断模式。唯一支持的值为"keep_start"。"keep_end"值已弃用,并将在 v2.0.0 中移除。 - shuffle_dataset (
bool,可选,默认为False) — 是否对数据集进行洗牌。 - packing (
bool,可选,默认为False) — 是否将多个序列分组为固定长度的块,以提高计算效率并减少填充。使用max_length来定义序列长度。 - packing_strategy (
str,可选,默认为"bfd") — 序列打包策略。可以是"bfd"(最佳适应递减,截断溢出部分)、"bfd_split"(最佳适应递减,拆分溢出序列)或"wrapped"(激进策略,在序列中间截断)。 - padding_free (
bool,可选,默认为False) — 是否通过展平批次中的所有序列为单个连续序列,来执行无填充的前向传播。这通过消除填充开销来减少内存使用。目前,这仅支持 FlashAttention 2 或 3,它们可以高效处理展平后的批次结构。对于包含循环层或卷积层的模型(例如 Qwen3.5)的 BFD 打包批次,无论此参数如何,都会被展平。 - pad_to_multiple_of (
int或str,可选,默认为"auto") — 如果设置,序列将被填充为该值的倍数。"auto"在 Neuron (AWS Trainium) 上填充为 128 的倍数,因为 Neuron 针对每个输入形状只编译一次,而在其他平台上不进行填充。 - eval_packing (
bool, 可选) — 是否对评估数据集进行打包。如果为None,则使用与packing相同的值。
控制训练的参数
- completion_only_loss (
bool, 可选) — 是否仅对序列的补全部分计算损失。如果设置为True,则仅对补全部分计算损失,此功能仅支持 prompt-completion 数据集。如果 为False,则对整个序列计算损失。如果为None(默认值),行为取决于数据集: 对于 prompt-completion 数据集,损失在补全部分上计算;对于 language modeling 数据集,损失在完整序列上计算。 - assistant_only_loss (
bool,可选,默认为False) — 是否仅针对序列中的助手部分计算损失。如果设置为True,则仅针对助手的回复计算损失,此功能仅支持 对话式 数据集。如果为False,则针对整个序列计算损失。 - loss_type (
str, 可选, 默认为"nll") — 要使用的损失类型。可能的值包括:"nll":标准负对数似然。"dft":动态微调,如这篇论文中所述。"chunked_nll":"nll"的已弃用别名,其计算损失的方式相同。将在 v2.0.0 中移除。
- activation_offloading (
bool,可选,默认为False) — 是否将激活值卸载到 CPU。
已弃用的参数
SFTTrainer 的配置类。
此类仅包含 SFT 训练特有的参数。完整的训练参数列表,请参阅 TrainingArguments 文档。请注意,此类中的默认值可能与 TrainingArguments 中的不同。
使用 HfArgumentParser,我们可以将该类转换为 argparse 参数,从而在命令行中指定。
这些参数的默认值与 TrainingArguments 不同:
logging_steps:默认值为10,而非500。gradient_checkpointing:默认值为True,而非False。bf16:如果未设置fp16,则默认值为True,而不是False。learning_rate:默认值为2e-5,而非5e-5。