【大模型算法与工程 35】使用LLaMA-Factory完成小数据微调

本文基于LLaMA-Factory 0.9.1框架,在CPU环境下完成小规模监督微调(SFT)全流程验证:包括固定环境依赖、使用真实Qwen2分词器与随机缩小模型、规范数据注册与标签映射、框架内预处理校验、四步LoRA训练、适配器保存及合并导出,并通过logits数值比对(误差<1e-5)确认导出一致性。重点解决工程落地中的路径、版本、模板、标签和导出可复现性问题。

01 本篇要解决什么问题

原理看懂之后,真正使用训练框架还会遇到另一类问题:数据名称从哪里解析,模板到底怎样编码,哪些参数会更新,训练目录里保存的文件能不能单独使用,导出后又怎样确认模型没有加载错。

本篇实际使用固定发行版LLaMA-Factory 0.9.1,在CPU跑通四次SFT优化更新、适配器保存、合并导出和重载核对。模型是本机随机初始化的缩小Qwen2,分词器采用固定官方资产。这是可执行的框架流程验证,和第32篇已有小模型的任务适配实验分开,不宣称四步就获得了领域能力。

02 核心原理、公式与条件

1. 固定环境,避免沿用上篇库版本

本次实际版本为LLaMA-Factory 0.9.1、Transformers 4.46.1、PEFT 0.12.0、datasets 3.1.0、accelerate 1.0.1和TRL 0.9.6。CPU PyTorch为2.9.0。前面源码案例曾用Transformers 4.46.3,本篇按框架约束另建环境,不把不同部分的环境混装。固定版本依赖说明

历史框架依赖还需和底层库相容。本次固定NumPy 1.26.4与PyArrow 18.1.0,完整版本清单随包。安装成功不等于可以训练,至少应导入框架、加载本地数据并跑一次真实更新。

代码记录发行版版本及实际tuner文件SHA256,来源清单保存分词器资产哈希。版本号、仓库资料与本机执行文件分别提供证据,不把一个随时变化的main链接当成永久实现。

2. 使用真实分词器与缩小随机模型

分词器来自Qwen2.5-0.5B-Instruct固定revision 7ae557604adf67be50417f59c2c2f167def9a775。模型由官方Qwen2ForCausalLM类随机初始化,改为2层、隐藏16、中间32、4个Q头和2个KV头,保留151936词表及绑定输出权重,共2435728参数。

这不是加载0.5B预训练权重,也不是给随机网络赋予聊天能力。保留真实词表与模板,是为了验证实际框架路径;缩小内部宽度,则让CPU可以完成训练和导出。没有下载大型模型权重,运行时明确使用本地资产与离线模式。

3. 注册数据不只是放一个JSON

训练48条、验证12条仍来自前述合成任务,转为messages列表,每项含user和assistant。dataset_info.json声明文件名、formatting为sharegpt、消息列,以及role/content/user/assistant的标签映射。配置中的dataset与eval_dataset引用注册名称,不直接写随意的文件名。数据注册说明

完整样本、注册表和运行YAML都由入口生成。真实使用时,应按来源分组准备验证,避免直接随机拆开同一模板或同一原始文档。字段能解析只说明格式有效,不能证明标注正确或业务覆盖充分。

4. 通过框架自己的预处理检查标签

本次template设为qwen,train_on_prompt为false、mask_history为false,packing关闭,cutoff_len为96。程序调用本版真实监督编码函数,检查signal示例的非忽略目标解码为S和结束标记,实际共2个token。

这里传给框架的是未手工位移的标签,因果模型内部负责shift。不要把第31篇已经移动过的字节标签直接搬进来,也不要从字符串长度猜Qwen模板边界。预处理函数是内部接口,本篇固定版本用于审计,升级后需要重新定位。

检查回复未被截断后,再启动训练。只看控制台打印“加载了多少条数据”,无法排除监督目标被裁光或角色映射错误。

5. 四步训练用于验收执行链路

关键设置为stage=sft、finetuning_type=lora、lora_target=q_proj,v_proj、rank2、alpha4,LoRA dropout为0。每设备batch2、累计1、max_steps4,学习率0.001且常数调度;CPU FP32,不开AMP或梯度检查点。实际只有224个LoRA参数更新。

程序核对trainer_state中的global_step确实为4,并确认adapter_model.safetensors已生成。CSV和图直接来自框架日志,四个点只说明执行了对应优化,不作为收敛、领域质量或方法效果的证据。

同一引擎也可用llamafactory-cli train读取入口生成的YAML。文件中的模型、数据与输出路径必须对应当前目录;随包原始运行YAML用于追溯,换位置后应运行入口重建,不能照搬旧绝对路径。

6. 保存适配器之后继续完成导出

适配器推理先加载同一份随机底座,再加载adapter,得到一份参照logits。随后调用框架export_model,以CPU float32合并到新目录,再用AutoModelForCausalLM重载,对相同输入比较输出。本次最大误差约8.94e-8,低于预设1e-5阈值。

合并配置包含model_name_or_path、adapter_name_or_path、template、finetuning_type、export_dir和infer_dtype。实际底座未量化,所以这不是QLoRA合并测量。官方导出配置示例

导出模型还应保存分词器、特殊token、生成配置及来源身份。只看到一个safetensors文件,不足以确认推理协议一致;重载后的数值比较,才补上了本篇流程的最后一步。

请添加图片描述

03 手写实现、实验与真实结果

完整实验入口

在解压根目录运行python examples/lesson_35.py。按README安装依赖,保留examples、base、data、fixtures及两个来源清单;运行不联网,不下载大型预训练权重,不使用关闭断言的python -O。35需要固定Factory环境;Windows按README设置短缓存路径。36默认读取随包实验结果/lesson_32,也可用–training-dir指定本轮训练目录。

import os,json,hashlib,importlib.metadata,inspect
from pathlib import Path
ROOT=Path(__file__).resolve().parent.parent
os.environ.setdefault('HF_HOME',str(ROOT/'artifacts/.hf'))
os.environ.setdefault('HF_HUB_OFFLINE','1'); os.environ.setdefault('HF_DATASETS_OFFLINE','1'); os.environ.setdefault('TRANSFORMERS_OFFLINE','1'); os.environ.setdefault('TOKENIZERS_PARALLELISM','false')
os.environ.setdefault('OMP_NUM_THREADS','1'); os.environ.setdefault('MKL_NUM_THREADS','1')
import torch,yaml
from transformers import AutoTokenizer,Qwen2Config,Qwen2ForCausalLM,AutoModelForCausalLM
from peft import PeftModel
from ft_common import output_dir,finish,table,figure,plt
from finetune_core import records

def main():
    out=output_dir(35).resolve(); torch.manual_seed(3535); torch.set_num_threads(1)
    expected={'llamafactory':'0.9.1','transformers':'4.46.1','peft':'0.12.0','datasets':'3.1.0','accelerate':'1.0.1','trl':'0.9.6'}
    versions={k:importlib.metadata.version(k) for k in expected}
    if versions!=expected: raise RuntimeError('Use the pinned Factory environment: '+str(versions))
    from llamafactory.train.tuner import run_exp,export_model
    from llamafactory.data.template import get_template_and_fix_tokenizer
    from llamafactory.data.processors.supervised import _encode_supervised_example
    from llamafactory.hparams import DataArguments
    import llamafactory.train.tuner as tuner
    manifest=json.loads((ROOT/'source_manifest.json').read_text(encoding='utf-8'))
    for entry in manifest['files']: assert hashlib.sha256((ROOT/entry['file']).read_bytes()).hexdigest()==entry['sha256']
    tokenizer=AutoTokenizer.from_pretrained(ROOT/'fixtures/qwen',local_files_only=True)
    tiny=out/'tiny_random_qwen2'; tiny.mkdir(exist_ok=True)
    config=Qwen2Config(vocab_size=151936,hidden_size=16,intermediate_size=32,num_hidden_layers=2,num_attention_heads=4,num_key_value_heads=2,max_position_embeddings=256,tie_word_embeddings=True,bos_token_id=151643,eos_token_id=151645,attention_dropout=0.)
    model=Qwen2ForCausalLM(config); model.save_pretrained(tiny,safe_serialization=True); tokenizer.save_pretrained(tiny)
    local_data=out/'factory_data'; local_data.mkdir(exist_ok=True); data=records()
    for split in ['train','val']:
        items=[{'messages':[{'role':'user','content':r['prompt']},{'role':'assistant','content':r['answer']}]} for r in data[split]]
        (local_data/(split+'.json')).write_text(json.dumps(items,ensure_ascii=False,indent=2),encoding='utf-8')
    registry={f'codes_{split}':{'file_name':split+'.json','formatting':'sharegpt','columns':{'messages':'messages'},'tags':{'role_tag':'role','content_tag':'content','user_tag':'user','assistant_tag':'assistant','system_tag':'system'}} for split in ['train','val']}
    (local_data/'dataset_info.json').write_text(json.dumps(registry,ensure_ascii=False,indent=2),encoding='utf-8')
    # Audit the actual framework preprocessing function, not a guessed character boundary.
    template=get_template_and_fix_tokenizer(tokenizer,DataArguments(template='qwen'))
    input_ids,labels=_encode_supervised_example(prompt=[{'role':'user','content':'term=signal; case=0'}],response=[{'role':'assistant','content':'S'}],system='',tools=None,images=[],videos=[],template=template,tokenizer=tokenizer,processor=None,cutoff_len=96,train_on_prompt=False,mask_history=False)
    supervised=[i for i in labels if i!=-100]; assert len(supervised)>0 and tokenizer.decode(supervised).startswith('S')
    (out/'framework_label_audit.json').write_text(json.dumps({'input_ids':input_ids,'labels':labels,'supervised_text':tokenizer.decode(supervised)},ensure_ascii=False,indent=2),encoding='utf-8')
    # Datasets 3.1 builds a lock FILE NAME from its cache path; keep that path short on Windows.
    cache=Path(os.environ.get('SFT_CACHE_DIR',Path.cwd()/'.sft_cache')).resolve(); cache.mkdir(parents=True,exist_ok=True)
    cfg={'model_name_or_path':str(tiny),'cache_dir':str(cache),'stage':'sft','do_train':True,'do_eval':True,'finetuning_type':'lora','lora_target':'q_proj,v_proj','lora_rank':2,'lora_alpha':4,'lora_dropout':0.,'dataset_dir':str(local_data),'dataset':'codes_train','eval_dataset':'codes_val','template':'qwen','cutoff_len':96,'train_on_prompt':False,'mask_history':False,'packing':False,'preprocessing_num_workers':1,'output_dir':str(out/'factory_adapter'),'overwrite_output_dir':True,'per_device_train_batch_size':2,'per_device_eval_batch_size':2,'gradient_accumulation_steps':1,'max_steps':4,'learning_rate':.001,'lr_scheduler_type':'constant','logging_steps':1,'save_strategy':'steps','save_steps':4,'eval_strategy':'steps','eval_steps':4,'report_to':'none','use_cpu':True,'fp16':False,'bf16':False,'gradient_checkpointing':False,'dataloader_num_workers':0,'dataloader_pin_memory':False,'optim':'adamw_torch','seed':3535,'disable_tqdm':True,'flash_attn':'disabled'}
    (out/'factory_cpu_sft.yaml').write_text(yaml.safe_dump(cfg,sort_keys=False,allow_unicode=True),encoding='utf-8')
    run_exp(cfg,callbacks=[])
    adapter=out/'factory_adapter'; trainer=json.loads((adapter/'trainer_state.json').read_text(encoding='utf-8')); assert trainer['global_step']==4
    assert (adapter/'adapter_model.safetensors').is_file()
    base=AutoModelForCausalLM.from_pretrained(tiny,local_files_only=True,attn_implementation='eager'); adapted=PeftModel.from_pretrained(base,adapter,local_files_only=True).eval()
    ids=torch.tensor([input_ids]); mask=torch.ones_like(ids)
    with torch.inference_mode(): before=adapted(input_ids=ids,attention_mask=mask).logits
    merge={'model_name_or_path':str(tiny),'adapter_name_or_path':str(adapter),'template':'qwen','finetuning_type':'lora','export_dir':str(out/'factory_merged'),'export_device':'cpu','export_size':1,'export_legacy_format':False,'infer_dtype':'float32'}
    (out/'factory_export.yaml').write_text(yaml.safe_dump(merge,sort_keys=False),encoding='utf-8'); export_model(merge)
    merged=AutoModelForCausalLM.from_pretrained(out/'factory_merged',local_files_only=True,attn_implementation='eager').eval()
    with torch.inference_mode(): after=merged(input_ids=ids,attention_mask=mask).logits
    error=(before-after).abs().max().item(); assert error<1e-5
    log=[r for r in trainer['log_history'] if 'loss' in r]; table(out/'factory_loss.csv',['step','loss'],[[r['step'],r['loss']] for r in log])
    fig,ax=plt.subplots(figsize=(7,4)); ax.plot([r['step'] for r in log],[r['loss'] for r in log],marker='o'); ax.set(xlabel='CPU smoke-test optimizer update',ylabel='Framework reported training loss',title='Tiny random Qwen2, four updates; no capability conclusion'); figure(fig,out)
    source=Path(inspect.getfile(tuner)); adapted_count=sum(p.numel() for n,p in adapted.named_parameters() if 'lora_' in n)
    finish(out,{'versions':versions,'tiny_random_base_parameters':sum(p.numel() for p in model.parameters()),'lora_parameters':adapted_count,'actual_optimizer_updates':trainer['global_step'],'framework_supervised_token_count':len(supervised),'framework_supervised_text':tokenizer.decode(supervised),'adapter_export_present':True,'merged_reload_max_logit_error':error,'source_tuner_sha256':hashlib.sha256(source.read_bytes()).hexdigest(),'scope':'actual LLaMA-Factory CPU SFT+merge on tiny random Qwen2; real tokenizer, no downloaded pretrained model weights; no GPU/QLoRA/semantic-quality benchmark'})
if __name__=='__main__': main()

本次实际结果

本次实际执行LLaMA-Factory 0.9.1的4步CPU SFT,随机小Qwen2有2435728参数,LoRA更新224个参数。真实预处理监督S与结束符共2个token;适配器、合并模型保存成功,重载最大logits误差约8.94e-8。该结果只支持框架流程验收。

{
  "versions": {
    "llamafactory": "0.9.1",
    "transformers": "4.46.1",
    "peft": "0.12.0",
    "datasets": "3.1.0",
    "accelerate": "1.0.1",
    "trl": "0.9.6"
  },
  "tiny_random_base_parameters": 2435728,
  "lora_parameters": 224,
  "actual_optimizer_updates": 4,
  "framework_supervised_token_count": 2,
  "framework_supervised_text": "S<|im_end|>",
  "adapter_export_present": true,
  "merged_reload_max_logit_error": 8.940696716308594e-08,
  "source_tuner_sha256": "ff672f5b49fb245894665c9bc7641970f38a9eae167982681d00ec817367e133",
  "scope": "actual LLaMA-Factory CPU SFT+merge on tiny random Qwen2; real tokenizer, no downloaded pretrained model weights; no GPU/QLoRA/semantic-quality benchmark"
}

本次框架标签核对

{
  "supervised_ids": [
    50,
    151645
  ],
  "supervised_text": "S<|im_end|>"
}

实际生成的factory_cpu_sft.yaml和factory_export.yaml连同数据注册表均在实验结果目录。运行入口会以当前路径重建,迁移到其他目录后不要复用原记录里的旧绝对路径。

请添加图片描述

图直接来自对应程序或日志,CSV、JSON与SVG保留。没有补造GPU内存、NF4结果或任务分数;量化缓冲、梯度检查与领域任务评价分别解释。

04 工程场景与排错思路

本机遇到的一个实际问题是Windows缓存路径过长:datasets会用缓存目录拼出锁文件名,过深目录可能超过文件系统限制。入口支持SFT_CACHE_DIR,整套运行器也支持–cache-dir;选一个有写权限的短路径即可,不需要修改框架源码或全局系统设置。

如果要迁移到真正的预训练Qwen与GPU,先准备固定revision的完整本地模型快照,再修改模型路径与任务数据,重新核对模板、长度和可训练层。随包GPU配置仅作迁移模板,未在本机执行;需要安装与目标设备匹配的PyTorch,不能把CPU轮子当成CUDA环境。

实际项目还需延长训练、按验证选择模型、运行独立任务测试和能力保留检查。四步CPU流程验证解决的是框架能否处理数据、更新并导出,不能替代那些工作。下一篇会用已经完成的第32篇实验展示完整的评价逻辑与失败分析。

05 面试问答与追问

问题1:这篇真的运行了LLaMA-Factory吗?

运行了固定发行版的SFT和导出接口,核对4次更新、适配器文件与合并重载误差。模型是缩小的随机Qwen2,所以流程通过不代表语义质量达标。

问题2:dataset_info与训练YAML是什么关系?

注册表把名称映射到本地文件、格式和字段,YAML使用该名称选择数据。两边名称或列映射不一致,可能加载失败或错误解释消息。

问题3:为什么要打印非忽略标签?

它直接显示哪些token真正接受监督,能发现回复截断、角色映射或模板边界错误。本次真实框架示例监督S和结束标记共2个token。

问题4:adapter_model文件能直接当完整模型加载吗?

通常还需要同一底座与适配器配置。可以保留分支推理,也可以在适用条件下合并为完整模型,再验证重载输出。

问题5:为什么四步loss变化不能说明微调成功?

步数极少、底座随机且任务小,指标只支持执行链路检查。任务适配仍需合理训练预算、验证选择、自由生成与独立测试。

问题6:换GPU后能直接照抄CPU配置吗?

应重新安装匹配设备的训练环境,确认dtype和后端,调整预算与路径并做短跑检查。随包GPU模板未执行,不含真实性能或显存承诺。

06 本篇回顾与练习

复习时沿着“数据与目标、可训练参数、部署身份、任务与保留证据”讲清楚。运行成功、数值一致、损失下降和业务达标是不同结论,应各自验收,不用一个指标替代全部。

练习思路与验收重点
核对框架产物定位注册表、运行YAML、trainer_state、adapter与merged目录,说明每项作用。
更换字段映射在新目录改变messages的列名并同步注册表,用实际预处理打印监督目标。
迁移真实模型前写验收表列revision、设备、模板、目标层、验证划分、导出参照和任务指标,再开始正式训练。

延伸阅读:固定框架资料。固定资料、教学简化与本机实测分别注明,练习表提供方向和验收点。

下一篇:36|微调效果评估:能力提升、遗忘与失败案例。

贝叶斯(Bayes)统计是近几十年来迅速发展起来的数理统计的一个重要分支。贝叶斯方法与经典统计方法的主要不同之处是进行统计推断时除了利用样本信息外,还要利用参数的先验信息,因此可以提高统计推断或统计决策的效果。它在经济、金融、生物、医学、自然科学和社会科学等许多领域具有广泛的应用。贝叶斯方法的研究已渗透到了统计学的几乎所有领域。作者在给中国科学技术大学概率论与数理统计专业本科生开设的“数理统计”课程中有一章专门讲授“贝叶斯方法和统计决策理论”,近十年来也给中国科学技术大学概率统计专业研究生开设过几次“贝叶斯分析”课。本书是在对过去讲稿的内容作了适当的增减和调整的基础上完成的。  本书共分六章。第1章是绪论,介绍了贝叶斯统计的若干基本概念,同时对必要的数理统计的基础知识有重点地作了回顾。第二章介绍了确定先验分布的若干可供选择的方法。第三章介绍了几类常见统计模型参数的后验分布的主要结果和计算方法。第四章和第五章分别介绍了“贝叶斯统计推断”和“贝叶斯统计决策”的内容。第六章介绍了贝叶斯统计计算的若干方法,包括蒙特卡洛方法和马尔可夫链蒙特卡洛(MCMC)方法以及相关统计软件的简介。本书的每一章附右大量的例题和习题,书末附有常用的几个表格和部分习题解答供读者查用。  大约可在54学时内讲授本书的第1章至第六章的主要内容,教师可根据学时需要选讲本书第1章至第六章的部分内容。书中标“*”号的章节可略去不讲,留给读者作为阅读材料。第六章例题中的R代码和部分例题的数据文件等可从作者个人主页下载。  作者在编写本书的过程中参考了J.O.Berger教授的《统计决策论及贝叶斯分析》和茆诗松教授编写的《贝叶斯统计》等书中的一些内容,以及《贝叶斯分析》一书中由张伟平博士编写的有关贝叶斯统计计算的一些内容。在此表示衷心感谢。  本书编写准备过程中,中国科学技术大学统计与金融系的几个研究生帮助完成了本书部分中文的录入和排版,作者对他们的辛勤工作表示真诚的感谢。高等教育出版社为本书的出版给予了大力支持。在此一并致谢。
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

电科_银尘

你的鼓励将是我最大的创作动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值
⌂ 换网址