【速写】formatting_func与target_modules的细节（peft）

文章目录

SFTTrainer的构造参数版本差异
怎么写formatting_func?
关于lora_config中的target_modules
能否在target_modules中指定特定某个模块？

以下面的示例pipeline为案：

# -*- coding: utf8 -*-
# @author: caoyang
# @email: caoyang@stu.sufe.edu.cn

from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig, TrainingArguments
from peft import LoraConfig, prepare_model_for_kbit_training, get_peft_model
from trl import SFTTrainer


def lora_pipeline(model_path,
				  dataset_path,
				  prompt_formatter,
				  lora_config,
				  trainer_arguments,
				  quantization_config = None,
				  ):
	tokenizer = AutoTokenizer.from_pretrained(model_path)
	dataset = load_dataset(dataset_path, split="train[:500]") 
	train_dataset = dataset.map(prompt_formatter)
	del dataset
	
	if quantization_config is not None:
		quantization_config = BitsAndBytesConfig(**quantization_config)
		model = AutoModelForCausalLM.from_pretrained(
			model_path,
			device_map = "auto",
			quantization_config = quantization_config,
		)
		model.config.pretraining_tp = 1
	else:
		model = AutoModelForCausalLM.from_pretrained(
			model_path,
			device_map = "auto",
		)
	model.config.use_cache = False
	tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
	lora_config = {
		"lora_alpha": 32,
		"lora_dropout": .1,
		'r': 64,
		"bias": "none",
		"task_type": "CASUAL_LM",
		"target_modules": ["k_proj", "v_proj", "q_proj"],
	}
	lora_config = LoraConfig(**lora_config)
	# If `prepare_model_for_kbit_training` is ignored, and `gradient_checkpointing = True` (for GPU memory saving)
	# Then you need set `model.enable_input_require_grads()`
	model = prepare_model_for_kbit_training(model)
	# model.enable_input_require_grads()
	model = get_peft_model(model, lora_config)
	training_arguments = TrainingArguments(**{
		"output_dir": output_dir,
		"per_device_train_batch_size": 2,
		"gradient_accumulation_steps": 4,
		"optim": "adamw_torch",
		"learning_rate": 2e-4,
		"lr_scheduler_type": "cosine",
		"num_train_epochs": 1,
		"logging_steps": 10,
		"fp16": True,
		"gradient_checkpointing": True,
	})
	trainer = SFTTrainer(
		model = model,
		train_dataset = train_dataset,
		args = training_arguments,
		peft_config = peft_config,
	)
	trainer.train()
	trainer.model.save_pretrained(output_dir)

关注两个问题：

SFTTrainer的构造参数（目前不同版本差异较大）
LoraConfig的构造参数

SFTTrainer的构造参数版本差异

目前存在版本差异，一些示例中会指出SFTTrainer可以设置dataset_text_field，max_seq_length，tokenizer等参数，下面是deepseek输出的参数说明：

核心的几个参数

model
- 类型：Union[PreTrainedModel, nn.Module, str]
- 说明：要训练的模型，可以是模型实例或Hub模型名称（如"gpt2"）。
args
- 类型：TrainingArguments
- 说明：训练配置参数（如学习率、批次大小、日志策略等）。
train_dataset
- 类型：Optional[Dataset]
- 说明：训练数据集，需是datasets.Dataset格式。
eval_dataset
- 类型：Optional[Dataset]
- 说明：验证数据集（可选）。

数据相关参数

dataset_text_field
- 类型：Optional[str]
- 说明：数据集中包含文本的字段名。如果未提供，需通过formatting_func自定义格式。
formatting_func
- 类型：Optional[Callable]
- 说明：自定义函数，用于将样本转换为模型所需的文本格式（如添加提示模板）。
max_seq_length
- 类型：Optional[int]
- 说明：文本的最大序列长度（超过部分会被截断）。
packing
- 类型：bool（默认False）
- 说明：是否将多个短样本打包到一个输入中以提高效率（类似fill_length）。

训练优化参数

peft_config
- 类型：Optional[PeftConfig]
- 说明：PEFT（参数高效微调）配置，例如LoRA、Adapter等。
neftune_noise_alpha
- 类型：Optional[float]
- 说明：NEFTune噪声的强度（用于防止过拟合）。

其他参数

tokenizer
- 类型：Optional[PreTrainedTokenizer]
- 说明：分词器实例。若未提供且model为字符串，会自动加载。
data_collator
- 类型：Optional[DataCollator]
- 说明：自定义数据整理器（默认使用DataCollatorForLanguageModeling）。
callbacks
- 类型：Optional[List[TrainerCallback]]
- 说明：训练回调函数列表（如早停、日志等）。
compute_metrics
- 类型：Optional[Callable]
- 说明：计算评估指标的函数。

继承自Trainer的参数
SFTTrainer还支持Trainer类的所有参数，例如：

optimizers、lr_scheduler、logging_dir、resume_from_checkpoint等。

示例代码

from trl import SFTTrainer
from transformers import TrainingArguments

trainer = SFTTrainer(
    model="gpt2",
    args=TrainingArguments(output_dir="./output", per_device_train_batch_size=4),
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=512,
    packing=True,
    peft_config=lora_config,
)

详细参数请参考trl官方文档。

但是实际上在 trl 0.16.0版本中，显然是没有dataset_text_field，max_seq_length，tokenizer等参数，如果设置会报Unexpected keyword arguments错误：

class SFTTrainer(transformers.trainer.Trainer)
 |  SFTTrainer(model: Union[str, torch.nn.modules.module.Module, transformers.modeling_utils.PreTrainedModel], args: Union[trl.trainer.sft_config.SFTConfig, transformers.training_args.TrainingArguments, NoneType] = None, data_collator: Optional[transformers.data.data_collator.DataCollator] = None, train_dataset: Union[datasets.arrow_dataset.Dataset, datasets.iterable_dataset.IterableDataset, NoneType] = None, eval_dataset: Union[datasets.arrow_dataset.Dataset, dict[str, datasets.arrow_dataset.Dataset], NoneType] = None, processing_class: Union[transformers.tokenization_utils_base.PreTrainedTokenizerBase, transformers.image_processing_utils.BaseImageProcessor, transformers.feature_extraction_utils.FeatureExtractionMixin, transformers.processing_utils.ProcessorMixin, NoneType] = None, compute_loss_func: Optional[Callable] = None, compute_metrics: Optional[Callable[[transformers.trainer_utils.EvalPrediction], dict]] = None, callbacks: Optional[list[transformers.trainer_callback.TrainerCallback]] = None, optimizers: tuple = (None, None), optimizer_cls_and_kwargs: Optional[tuple[Type[torch.optim.optimizer.Optimizer], dict[str, Any]]] = None, preprocess_logits_for_metrics: Optional[Callable[[torch.Tensor, torch.Tensor], torch.Tensor]] = None, peft_config: Optional[ForwardRef('PeftConfig')] = None, formatting_func: Union[Callable[[dict], str], Callable[[dict], list[str]], NoneType] = None)
 |  
 |  Trainer for Supervised Fine-Tuning (SFT) method.
 |  
 |  This class is a wrapper around the [`transformers.Trainer`] class and inherits all of its attributes and methods.
 |  
 |  Example:
 |  
 |  ```python
 |  from datasets import load_dataset
 |  from trl import SFTTrainer
 |  
 |  dataset = load_dataset("roneneldan/TinyStories", split="train[:1%]")
 |  
 |  trainer = SFTTrainer(model="Qwen/Qwen2-0.5B-Instruct", train_dataset=dataset)
 |  trainer.train()
 |  ```
 |  
 |  Args:
 |      model (`Union[str, PreTrainedModel]`):
 |          Model to be trained. Can be either:
 |  
 |          - A string, being the *model id* of a pretrained model hosted inside a model repo on huggingface.co, or
 |            a path to a *directory* containing model weights saved using
 |            [`~transformers.PreTrainedModel.save_pretrained`], e.g., `'./my_model_directory/'`. The model is
 |            loaded using [`~transformers.AutoModelForCausalLM.from_pretrained`] with the keywork arguments
 |            in `args.model_init_kwargs`.
 |          - A [`~transformers.PreTrainedModel`] object. Only causal language models are supported.
 |      args ([`SFTConfig`], *optional*, defaults to `None`):
 |          Configuration for this trainer. If `None`, a default configuration is used.
 |      data_collator (`DataCollator`, *optional*):
 |          Function to use to form a batch from a list of elements of the prcessed `train_dataset` or `eval_dataset`.
 |          Will default to [`~transformers.default_data_collator`] if no `processing_class` is provided, an instance
 |          of [`~transformers.DataCollatorWithPadding`] otherwise if the processing_class is a feature extractor or
 |          tokenizer.
 |      train_dataset ([`~datasets.Dataset`] or [`~datasets.IterableDataset`]):
 |          Dataset to use for training. SFT supports both [language modeling](#language-modeling) type and
 |          [prompt-completion](#prompt-completion) type. The format of the samples can be either:
 |  
 |          - [Standard](dataset_formats#standard): Each sample contains plain text.
 |          - [Conversational](dataset_formats#conversational): Each sample contains structured messages (e.g., role
 |            and content).
 |  
 |          The trainer also supports processed datasets (tokenized) as long as they contain an `input_ids` field.
 |      eval_dataset ([`~datasets.Dataset`], [`~datasets.IterableDataset`] or `dict[str, Union[Dataset, IterableDataset]]`):
 |          The trainer also supports processed datasets (tokenized) as long as they contain an `input_ids` field.
 |      eval_dataset ([`~datasets.Dataset`], [`~datasets.IterableDataset`] or `dict[str, Union[Dataset, IterableDataset]]`):
 |          Dataset to use for evaluation. It must meet the same requirements as `train_dataset`.
 |      processing_class ([`~transformers.PreTrainedTokenizerBase`], *optional*, defaults to `None`):
 |          Processing class used to process the data. If `None`, the processing class is loaded from the model's name
 |          with [`~transformers.AutoTokenizer.from_pretrained`].
 |      callbacks (list of [`~transformers.TrainerCallback`], *optional*, defaults to `None`):
 |          List of callbacks to customize the training loop. Will add those to the list of default callbacks
 |          detailed in [here](https://huggingface.co/docs/transformers/main_classes/callback).
 |  
 |          If you want to remove one of the default callbacks used, use the [`~transformers.Trainer.remove_callback`]
 |          method.
 |      optimizers (`tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR]`, *optional*, defaults to `(None, None)`):
 |          A tuple containing the optimizer and the scheduler to use. Will default to an instance of [`AdamW`] on your
 |          model and a scheduler given by [`get_linear_schedule_with_warmup`] controlled by `args`.
 |      optimizer_cls_and_kwargs (`Tuple[Type[torch.optim.Optimizer], Dict[str, Any]]`, *optional*, defaults to `None`):
 |          A tuple containing the optimizer class and keyword arguments to use.
 |          Overrides `optim` and `optim_args` in `args`. Incompatible with the `optimizers` argument.
 |  
 |          Unlike `optimizers`, this argument avoids the need to place model parameters on the correct devices before initializing the Trainer.
 |      preprocess_logits_for_metrics (`Callable[[torch.Tensor, torch.Tensor], torch.Tensor]`, *optional*, defaults to `None`):
 |          A function that preprocess the logits right before caching them at each evaluation step. Must take two
 |          tensors, the logits and the labels, and return the logits once processed as desired. The modifications made
 |          by this function will be reflected in the predictions received by `compute_metrics`.
 |  
 |          Note that the labels (second parameter) will be `None` if the dataset does not have them.
 |      peft_config ([`~peft.PeftConfig`], *optional*, defaults to `None`):
 |          PEFT configuration used to wrap the model. If `None`, the model is not wrapped.
 |      formatting_func (`Optional[Callable]`):
 |          Formatting function applied to the dataset before tokenization.
 |  
 |  Method resolution order:
Help on class SFTTrainer in module trl.trainer.sft_trainer:

class SFTTrainer(transformers.trainer.Trainer)
 |  SFTTrainer(model: Union[str, torch.nn.modules.module.Module, transformers.modeling_utils.PreTrainedModel], args: Union[trl.trainer.sft_config.SFTConfig, transformers.training_args.TrainingArguments, NoneType] = None, data_collato
r: Optional[transformers.data.data_collator.DataCollator] = None, train_dataset: Union[datasets.arrow_dataset.Dataset, datasets.iterable_dataset.IterableDataset, NoneType] = None, eval_dataset: Union[datasets.arrow_dataset.Dataset, d
ict[str, datasets.arrow_dataset.Dataset], NoneType] = None, processing_class: Union[transformers.tokenization_utils_base.PreTrainedTokenizerBase, transformers.image_processing_utils.BaseImageProcessor, transformers.feature_extraction
_utils.FeatureExtractionMixin, transformers.processing_utils.ProcessorMixin, NoneType] = None, compute_loss_func: Optional[Callable] = None, compute_metrics: Optional[Callable[[transformers.trainer_utils.EvalPrediction], dict]] = Non
e, callbacks: Optional[list[transformers.trainer_callback.TrainerCallback]] = None, optimizers: tuple = (None, None), optimizer_cls_and_kwargs: Optional[tuple[Type[torch.optim.optimizer.Optimizer], dict[str, Any]]] = None, preprocess
_logits_for_metrics: Optional[Callable[[torch.Tensor, torch.Tensor], torch.Tensor]] = None, peft_config: Optional[ForwardRef('PeftConfig')] = None, formatting_func: Union[Callable[[dict], str], Callable[[dict], list[str]], NoneType] 
= None)
 |  
 |  Trainer for Supervised Fine-Tuning (SFT) method.
 |  
 |  This class is a wrapper around the [`transformers.Trainer`] class and inherits all of its attributes and methods.
 |  
 |  Example:
 |  
 |  ```python
 |  from datasets import load_dataset
 |  from trl import SFTTrainer
 |  
 |  dataset = load_dataset("roneneldan/TinyStories", split="train[:1%]")
 |  
 |  trainer = SFTTrainer(model="Qwen/Qwen2-0.5B-Instruct", train_dataset=dataset)
 |  trainer.train()
 |  ```
 |  
 |  Args:
 |      model (`Union[str, PreTrainedModel]`):
 |          Model to be trained. Can be either:
 |  
 |          - A string, being the *model id* of a pretrained model hosted inside a model repo on huggingface.co, or
 |            a path to a *directory* containing model weights saved using
 |            [`~transformers.PreTrainedModel.save_pretrained`], e.g., `'./my_model_directory/'`. The model is
 |            loaded using [`~transformers.AutoModelForCausalLM.from_pretrained`] with the keywork arguments
 |            in `args.model_init_kwargs`.
 |          - A [`~transformers.PreTrainedModel`] object. Only causal language models are supported.
 |      args ([`SFTConfig`], *optional*, defaults to `None`):
 |          Configuration for this trainer. If `None`, a default configuration is used.
 |      data_collator (`DataCollator`, *optional*):
 |          Function to use to form a batch from a list of elements of the prcessed `train_dataset` or `eval_dataset`.
 |          Will default to [`~transformers.default_data_collator`] if no `processing_class` is provided, an instance
 |          of [`~transformers.DataCollatorWithPadding`] otherwise if the processing_class is a feature extractor or
 |          tokenizer.
 |      train_dataset ([`~datasets.Dataset`] or [`~datasets.IterableDataset`]):
 |          Dataset to use for training. SFT supports both [language modeling](#language-modeling) type and
 |          [prompt-completion](#prompt-completion) type. The format of the samples can be either:
 |  
 |          - [Standard](dataset_formats#standard): Each sample contains plain text.
 |          - [Conversational](dataset_formats#conversational): Each sample contains structured messages (e.g., role
 |            and content).
 |  
 |          The trainer also supports processed datasets (tokenized) as long as they contain an `input_ids` field.
 |      eval_dataset ([`~datasets.Dataset`], [`~datasets.IterableDataset`] or `dict[str, Union[Dataset, IterableDataset]]`):
 |          Dataset to use for evaluation. It must meet the same requirements as `train_dataset`.
 |      processing_class ([`~transformers.PreTrainedTokenizerBase`], *optional*, defaults to `None`):
 |          Processing class used to process the data. If `None`, the processing class is loaded from the model's name
 |          with [`~transformers.AutoTokenizer.from_pretrained`].
 |      callbacks (list of [`~transformers.TrainerCallback`], *optional*, defaults to `None`):
 |          List of callbacks to customize the training loop. Will add those to the list of default callbacks
 |          detailed in [here](https://huggingface.co/docs/transformers/main_classes/callback).
 |  
 |          If you want to remove one of the default callbacks used, use the [`~transformers.Trainer.remove_callback`]
 |          method.
 |      optimizers (`tuple[torch.optim.Optimizer, torch.optim.lr_scheduler.LambdaLR]`, *optional*, defaults to `(None, None)`):
 |          A tuple containing the optimizer and the scheduler to use. Will default to an instance of [`AdamW`] on your
 |          model and a scheduler given by [`get_linear_schedule_with_warmup`] controlled by `args`.
 |      optimizer_cls_and_kwargs (`Tuple[Type[torch.optim.Optimizer], Dict[str, Any]]`, *optional*, defaults to `None`):
 |          A tuple containing the optimizer class and keyword arguments to use.
 |          Overrides `optim` and `optim_args` in `args`. Incompatible with the `optimizers` argument.
 |  
 |          Unlike `optimizers`, this argument avoids the need to place model parameters on the correct devices before initializing the Trainer.
 |      preprocess_logits_for_metrics (`Callable[[torch.Tensor, torch.Tensor], torch.Tensor]`, *optional*, defaults to `None`):
 |          A function that preprocess the logits right before caching them at each evaluation step. Must take two
 |          tensors, the logits and the labels, and return the logits once processed as desired. The modifications made
 |          by this function will be reflected in the predictions received by `compute_metrics`.
 |  
 |          Note that the labels (second parameter) will be `None` if the dataset does not have them.
 |      peft_config ([`~peft.PeftConfig`], *optional*, defaults to `None`):
 |          PEFT configuration used to wrap the model. If `None`, the model is not wrapped.
 |      formatting_func (`Optional[Callable]`):
 |          Formatting function applied to the dataset before tokenization.
 |  
 |  Method resolution order:
 |      SFTTrainer
 |      transformers.trainer.Trainer
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |  __init__(self, model: Union[str, torch.nn.modules.module.Module, transformers.modeling_utils.PreTrainedModel], args: Union[trl.trainer.sft_config.SFTConfig, transformers.training_args.TrainingArguments, NoneType] = None, data_col
lator: Optional[transformers.data.data_collator.DataCollator] = None, train_dataset: Union[datasets.arrow_dataset.Dataset, datasets.iterable_dataset.IterableDataset, NoneType] = None, eval_dataset: Union[datasets.arrow_dataset.Datase
t, dict[str, datasets.arrow_dataset.Dataset], NoneType] = None, processing_class: Union[transformers.tokenization_utils_base.PreTrainedTokenizerBase, transformers.image_processing_utils.BaseImageProcessor, transformers.feature_extrac
tion_utils.FeatureExtractionMixin, transformers.processing_utils.ProcessorMixin, NoneType] = None, compute_loss_func: Optional[Callable] = None, compute_metrics: Optional[Callable[[transformers.trainer_utils.EvalPrediction], dict]] =
 None, callbacks: Optional[list[transformers.trainer_callback.TrainerCallback]] = None, optimizers: tuple = (None, None), optimizer_cls_and_kwargs: Optional[tuple[Type[torch.optim.optimizer.Optimizer], dict[str, Any]]] = None, prepro
cess_logits_for_metrics: Optional[Callable[[torch.Tensor, torch.Tensor], torch.Tensor]] = None, peft_config: Optional[ForwardRef('PeftConfig')] = None, formatting_func: Union[Callable[[dict], str], Callable[[dict], list[str]], NoneTy
pe] = None)
 |      Initialize self.  See help(type(self)) for accurate signature.

对此，在 trl==0.16.0 版本中，SFTTrainer 的实现逻辑可能与更新版本有所不同。如果你没有指定 dataset_text_field 或 formatting_func，SFTTrainer 仍然可以运行，但它的默认行为可能依赖于以下机制：

1. 默认的数据处理逻辑

在旧版 SFTTrainer 中，如果没有显式指定 dataset_text_field 或 formatting_func，训练器可能会尝试以下方式处理数据：

(1) 直接使用 dataset 的 "text" 字段

默认假设数据集有一个名为 "text" 的字段，包含输入文本。
例如，如果你的数据集是 {"text": "Hello, world!", ...}，它会自动使用 "text" 作为输入。

(2) 如果没有 "text" 字段，尝试其他常见字段名

可能会尝试 "input"、"content"、"sentence" 等常见字段名。
如果找不到匹配的字段，可能会报错。

(3) 如果数据集是 datasets.Dataset 且只有一个文本列

直接使用唯一的文本列作为输入。

2. 标签（Target）的处理
在监督微调（SFT）中，通常输入和标签是相同的文本（即模型学习预测下一个 token，类似于语言模型训练）。因此：

不需要显式指定标签字段，因为输入文本本身会被用作标签（通过移位实现）。
例如，输入 "Hello, world!" 的标签是 "Hello, world!" 的下一个 token 序列。

如果数据集中有单独的标签字段（如 "output"），则需要通过 formatting_func 显式组合输入和标签：

def formatting_func(sample):
    return f"Input: {sample['input']}\nOutput: {sample['output']}"

trainer = SFTTrainer(
    ...,
    formatting_func=formatting_func,
)

3. 为什么没有 max_seq_length 也能运行？

在旧版中：

如果没有指定 max_seq_length，可能会使用模型的默认最大长度（如 tokenizer.model_max_length）。
或者直接处理完整文本（不截断），但可能因显存不足而报错。

4. 验证默认行为的实验方法

如果不确定 SFTTrainer 如何处理数据，可以通过以下方式调试：

(1) 打印分词后的输入

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("your_model")
dataset = ...  # 你的数据集

# 模拟 SFTTrainer 的数据处理
tokenized_input = tokenizer(dataset[0]["text"], truncation=True, max_length=512)
print(tokenized_input)

(2) 检查数据集字段名

print(dataset.column_names)  # 查看所有字段名

(3) 自定义 formatting_func 显式控制输入

def formatting_func(sample):
    # 明确组合输入和标签（如有）
    return f"{sample['input']} {sample['output']}"

trainer = SFTTrainer(..., formatting_func=formatting_func)

总结

旧版 trl==0.16.0 可能默认使用 "text" 字段作为输入，或尝试自动推断输入文本。
标签通常是输入文本本身（自回归训练），除非通过 formatting_func 自定义。
如果不确定逻辑，建议显式定义 formatting_func。

怎么写formatting_func?

如果你的数据集已经是 {"text": "Hello world!", ...} 这样的格式（即每个样本直接包含一个 "text" 字段，且文本已经是预处理好的输入），那么 formatting_func 可以非常简单，甚至不需要额外定义，因为 SFTTrainer 默认会直接使用 "text" 字段（或通过 dataset_text_field 指定字段名）。

但如果你希望显式定义一个 formatting_func（比如为了更灵活地控制输入格式，或者未来可能扩展字段），可以按以下方式实现：

1. 直接返回 "text" 字段（最简情况）
如果数据集已经是 {"text": "..."} 格式，且无需修改文本内容：

def formatting_func(sample):
    return sample["text"]  # 直接返回 "text" 字段的内容

# 初始化 SFTTrainer
trainer = SFTTrainer(
    ...,
    formatting_func=formatting_func,  # 显式指定
    # dataset_text_field="text",       # 如果未定义 formatting_func，可以用这个替代
)

2. 添加提示模板（Prompt Template）
如果你想为文本添加固定的提示词（例如对话模板）：

def formatting_func(sample):
    return f"### Instruction: Write a sentence.\n### Output: {sample['text']}"

# 输出示例：
# ### Instruction: Write a sentence.
# ### Output: Hello world!

3. 多字段组合
如果数据集中有多个字段（例如 "input" 和 "output"），需要组合成单一文本：

def formatting_func(sample):
    return f"Input: {sample['input']}\nOutput: {sample['output']}"

# 输出示例：
# Input: Say hello.
# Output: Hello world!

4. 处理特殊标记（如 EOS）
如果需要为文本添加结束标记（如 <|endoftext|>）：

def formatting_func(sample):
    return sample["text"] + "<|endoftext|>"  # 假设分词器能识别此标记

验证 formatting_func 的输出
在训练前，可以先手动检查格式化后的文本是否符合预期：

sample = {"text": "Hello world!"}
print(formatting_func(sample))  # 输出: Hello world!

关键注意事项

字段名必须匹配：
sample["text"] 中的 "text" 必须和你的数据集字段名一致（例如你的数据集可能是 {"content": ...}，则需要改为 sample["content"]）。
避免冗余处理：
如果数据已经是预处理的完整文本，直接返回 sample["text"] 即可，无需额外修改。
分词器的兼容性：
如果添加了自定义标记（如 ### Instruction:），确保分词器能正确编码它们（不会被拆分成无意义的子词）。

完整示例代码

from datasets import Dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
from trl import SFTTrainer

# 示例数据集
data = {"text": ["Hello world!", "How are you?"]}
dataset = Dataset.from_dict(data)

# 模型和分词器
model_name = "gpt2"
model = AutoModelForCausalLM.from_pretrained(model_name)
tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token  # 设置填充标记

# 定义 formatting_func
def formatting_func(sample):
    return sample["text"]

# 训练配置
training_args = TrainingArguments(
    output_dir="./results",
    per_device_train_batch_size=4,
    num_train_epochs=1,
)

# 初始化 SFTTrainer
trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
    formatting_func=formatting_func,  # 显式指定
    # dataset_text_field="text",     # 或直接指定字段名（新版trl支持）
)

trainer.train()

关于lora_config中的target_modules

显然它不太像是model.named_parameters中的命名法，那么具体应该怎么设置，以及指定对自己想要微调的模块进行lora呢？

在 peft.LoraConfig 中，target_modules 指定的模块名称 并不直接等同于 model.named_parameters() 中的参数名称，而是需要匹配模型内部的 子模块（Layer）的名称（通常是线性层、注意力投影层等）。以下是具体解析和操作方法：

1. target_modules 的命名规则
target_modules 需要匹配模型 内部子模块的变量名（通常是 nn.Linear 层的名称），而非参数路径（如 model.layers.0.self_attn.q_proj.weight）。例如：

对于 LLaMA、GPT-2 等 Transformer 模型，常见的模块名称为：
- q_proj、k_proj、v_proj（注意力层的查询、键、值投影）
- o_proj（注意力输出投影）
- gate_proj、up_proj、down_proj（MLP 层，如 LLaMA 的 FFN）
对于 其他模型（如 BERT），可能是 query、key、value 等。

2. 如何确定模型的模块名称？
方法 1：直接打印模型结构
运行以下代码查看模型的所有子模块名称：

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("your_model_name")
for name, module in model.named_modules():
    if isinstance(module, nn.Linear):  # 只打印线性层
        print(name)

输出示例（以 LLaMA 为例）：

model.layers.0.self_attn.q_proj
model.layers.0.self_attn.k_proj
model.layers.0.self_attn.v_proj
model.layers.0.self_attn.o_proj
model.layers.0.mlp.gate_proj
model.layers.0.mlp.up_proj
model.layers.0.mlp.down_proj
...

此时 target_modules 应取 最后一级的名称（如 q_proj、gate_proj）。

方法 2：查阅模型文档

HuggingFace 模型的文档通常会说明注意力层和 MLP 层的命名（例如 LLaMA 结构）。
参考官方示例代码（如 peft 的 LORA 配置）。

3. 编写 target_modules 的规则

通用 Transformer 模型（如 LLaMA、GPT-2）：

target_modules = ["q_proj", "k_proj", "v_proj"]  # 仅注意力层
# 或扩展至 MLP 层
target_modules = ["q_proj", "k_proj", "v_proj", "gate_proj", "up_proj", "down_proj"]

BERT 类模型：

target_modules = ["query", "key", "value"]  # 注意名称可能不同

自定义模型：根据 named_modules() 的输出选择。

4. 常见模型的 target_modules 示例

模型类型	推荐 `target_modules`
LLaMA-7B/13B	`["q_proj", "k_proj", "v_proj", "o_proj"]`
GPT-2	`["c_attn"]`（需特殊处理，见下方说明）
Mistral	同 LLaMA
BERT	`["query", "key", "value"]`

特殊情况：GPT-2 的 c_attn
GPT-2 的注意力层将 q_proj、k_proj、v_proj 合并为一个 c_attn 层，因此需要单独处理：

target_modules = ["c_attn"]  # 会同时对 q,k,v 应用 LoRA

5. 验证 LoRA 是否应用成功
初始化后，检查模型的可训练参数：

model = AutoModelForCausalLM.from_pretrained("your_model")
peft_config = LoraConfig(target_modules=["q_proj", "v_proj"], ...)
model = get_peft_model(model, peft_config)
model.print_trainable_parameters()  # 查看可训练参数数量

如果输出显示可训练参数远小于原始参数，说明 LoRA 已正确应用。

6. 完整代码示例（LLaMA 微调）

from peft import LoraConfig
from transformers import AutoModelForCausalLM
from trl import SFTTrainer

# 定义 LoRA 配置
peft_config = LoraConfig(
    r=8,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj"],  # 关键参数
    lora_dropout=0.1,
    bias="none",
    task_type="CAUSAL_LM",
)

# 加载模型
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")

# 初始化 SFTTrainer
trainer = SFTTrainer(
    model=model,
    peft_config=peft_config,
    ...  # 其他参数
)

总结

target_modules 的名称来自 模型子模块的变量名，而非 named_parameters() 的路径。
通过 named_modules() 或文档确定正确的模块名称。
不同模型的模块命名可能不同（如 LLaMA 的 q_proj vs BERT 的 query）。
初始化后务必检查 print_trainable_parameters() 确认 LoRA 生效。

能否在target_modules中指定特定某个模块？

在 peft.LoraConfig 中，如果你直接指定 完整的模块路径（如 model.layers.0.self_attn.q_proj），会报错。因为 target_modules 需要的是 模块的通用名称（如 q_proj），而不是具体层级的路径名称。

1. 为什么不能直接写完整路径？

target_modules 的设计目的是 匹配所有同名模块（例如所有层的 q_proj），而不是单个特定层。
如果你强行写入完整路径（如 model.layers.0.self_attn.q_proj），peft 会尝试在所有模块中查找完全匹配的名称，但实际模块名称是 q_proj（不带路径前缀），因此会报错：
```
ValueError: Target modules ['model.layers.0.self_attn.q_proj'] not found in the model.
```

2. 如何正确指定单个模块？

方法 1：用通用名称（如 q_proj）

peft_config = LoraConfig(
    target_modules=["q_proj"],  # 对所有层的 q_proj 应用 LoRA
    ...
)

效果：会对模型中所有名为 q_proj 的模块（如第0层、第1层…的 q_proj）应用 LoRA。

方法 2：通过自定义修改模型（不推荐）
如果非要针对某一层的特定模块，需要直接修改模型结构（例如给目标模块单独命名）：

# 不推荐！仅演示逻辑
model.layers[0].self_attn.q_proj.custom_name = "my_special_q_proj"  # 假设可以这样改
peft_config = LoraConfig(target_modules=["my_special_q_proj"])

问题：这种操作需要侵入式修改模型，可能破坏预训练权重，且不符合 LoRA 的设计初衷。

3. 验证模块名称是否匹配
运行以下代码检查模型的所有线性层名称：

from torch import nn
for name, module in model.named_modules():
    if isinstance(module, nn.Linear):
        print(name)  # 输出如 "model.layers.0.self_attn.q_proj"

在 target_modules 中只需取 最后一级名称（如 q_proj）。

4. 如果只想微调特定层怎么办？
LoRA 的设计初衷是轻量化微调所有相关层。如果一定要限制层数，可以通过以下方式间接实现：

(1) 手动冻结其他层

# 先对所有 q_proj 应用 LoRA
peft_config = LoraConfig(target_modules=["q_proj"])

# 然后手动冻结不需要的层
for name, param in model.named_parameters():
    if "layers.1." in name:  # 例如冻结第1层及之后的参数
        param.requires_grad = False

(2) 使用不同的 r 或 lora_alpha
通过调整秩（r）和缩放系数（lora_alpha），控制不同层的重要性：

peft_config = LoraConfig(
    target_modules=["q_proj"],
    r=8,          # 其他层用默认秩
    layers_to_transform=[0],  # 某些版本的 peft 支持此参数
)

注意：layers_to_transform 仅在部分 peft 版本中支持，需检查文档。

5. 完整代码示例（正确用法）

from peft import LoraConfig
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")

# 正确：用通用名称指定模块
peft_config = LoraConfig(
    target_modules=["q_proj"],  # 对所有层的 q_proj 应用 LoRA
    r=8,
    lora_alpha=32,
    lora_dropout=0.1,
)

# 错误：尝试用完整路径（会报错）
# peft_config = LoraConfig(target_modules=["model.layers.0.self_attn.q_proj"])

总结

不要在 target_modules 中写完整路径（如 model.layers.0.self_attn.q_proj），只需提供模块的通用名称（如 q_proj）。
LoRA 会 自动匹配所有同名模块，无法直接指定单个特定层（除非修改模型结构或手动冻结其他层）。
通过 named_modules() 确认模块名称，优先遵循 peft 的默认设计逻辑。