LoRA 数据字段怎么配置或排查

LoRA 微调里最容易被忽略的，不是 r 设成多少，而是训练数据到底有没有变成 Trainer 认识的字段。原始 JSONL 可能叫 instruction、input、output，TRL 的 SFTTrainer 却主要按 text、messages 或 prompt/completion 读取。解决办法是先选定一种标准形状，再在进入 Trainer 前做一次显式转换。

官方地址：https://huggingface.co/docs/trl/sft_trainer

先把数据字段变成 Trainer 认识的形状

TRL 当前支持标准文本和对话文本，也支持标准或对话式的 prompt-completion。最稳妥的判断方式是看任务目标：只有一段已经拼好的训练文本，就用 text；希望保留用户与助手角色，让 tokenizer 根据聊天模板组织输入，就用 messages；需要明确区分输入和期望答案，才用 prompt 与 completion。

用一层转换函数接住 instruction、input、output

假设 JSONL 的业务字段是 instruction、input、output。不要在训练循环里临时拼接，直接用 Datasets 的 map 生成新列，并用 remove_columns 移除旧列。这样后续换数据整理器时，输入契约仍然清楚。

from datasets import load_dataset

# 读取 JSONL；每行包含 instruction、input、output 三个业务字段
dataset = load_dataset("json", data_files="train.jsonl", split="train")

def to_messages(row):
    # input 为空时不额外制造一段空上下文，避免样本格式漂移
    task = row["instruction"].strip()
    extra = row.get("input", "")
    if extra and extra.strip():
        task = f"{task}\n\n补充输入：{extra.strip()}"
    return {
        "messages": [
            {"role": "user", "content": task},
            {"role": "assistant", "content": row["output"].strip()},
        ]
    }

# 删除未使用的原始列，只保留 Trainer 能识别的 messages
train_dataset = dataset.map(to_messages, remove_columns=dataset.column_names)

# 先看一条结构，排查列名和角色，不在这里运行模型训练
print(train_dataset[0]["messages"])

这里的关键不是函数名字，而是输出契约：messages 必须是列表，列表元素要有合法角色和字符串内容。若原数据已经是问答对，也可以转换成对话式 prompt/completion，但不要同时保留两套互相矛盾的答案列。

模板、截断和损失目标要一起检查

对话数据交给 SFTTrainer 后，tokenizer 的 chat template 会影响最终 token 序列。模板缺失时，常见现象是角色标记不对、答案和问题粘在一起，或者模型学会复述用户输入。先确认底模的 tokenizer 能处理当前角色结构，再根据样本长度设置 max_length；超长样本被截断后，可能只剩问题没有答案。

如果任务只想让助手答案贡献损失，应检查 completion_only_loss 或对应的 assistant mask 是否真的存在。字段名正确不等于监督目标正确：能成功启动训练，只说明样本通过了准备阶段。

from peft import LoraConfig
from trl import SFTConfig, SFTTrainer

# 让 SFTTrainer 从 messages 识别对话，不再把业务列名当成 text
args = SFTConfig(
    output_dir="./lora-output",
    max_length=1024,
    completion_only_loss=True,
)

# 这些参数属于 LoRA 适配层，不是数据集字段
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "v_proj"],
    bias="none",
    task_type="CAUSAL_LM",
)

# processing_class 负责模板与分词，train_dataset 负责样本字段
trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=train_dataset,
    processing_class=tokenizer,
    peft_config=lora_config,
)

字段正确但仍报错时，按三层排查

第一层看列名：print(train_dataset.column_names)，确认是否真的有 messages 或 text。第二层看首条数据：检查 messages[0] 是否为 user、最后是否有 assistant，内容是否为空。第三层看模型适配：target_modules 是模块名匹配，不是数据字段；常见架构可能有默认目标，未知架构则需要按模型实际模块名显式指定。

如果报错类似“找不到 text”，不要先改 LoRA 的 r 或学习率；先决定是把数据改成 text，还是把 Trainer 配成能处理 messages 的路径。如果出现模板相关异常，再检查 tokenizer；如果出现 target module 未匹配，才去查看模型层名。

常见问题

只有 instruction 和 output，必须补 input 吗？

不必。把 instruction 作为 user 内容、output 作为 assistant 内容即可；空 input 不要硬拼成无意义的分隔文本。

能不能直接把字段名改成 text？

只有当你已经把问题和答案按目标模板拼成完整字符串时才可以。单纯把 instruction 重命名为 text，不会自动带上回答。

target_modules 写错会影响数据字段吗？

不会直接影响数据列，但会导致 LoRA 没有匹配到预期模块或初始化失败。它应依据模型结构单独排查。