LoRA微调交付包验货指南：从解压到跑通Qwen推理

简介面向嵌入式开发者与物联网初学者这份基于STM32F103C8T6和LoRa模块的无线传感器数据传输工程源码包是一套可编译可烧录的完整项目范例。工程覆盖传感器数据采集、ADC转换、LoRa芯片初始化、SPI与UART接口收发控制以及无线发送与接收完整链路可在理想条件下达到最远三千米传输距离适用于智能农业、环境监测、远程抄表等低功耗广域物联网场景。RAR压缩包内含一百八十九个文件大小约一点九六兆字节以Keil MDK工程为主包含标准外设库C语言头文件与源文件、启动文件、工程配置文件以及编译生成的中间文件、可执行与十六进制固件同时附带文本与文档格式说明目录结构清晰方便按模块查阅。已有四千一百九十一人学习下载。学习后能够掌握LoRa扩频调制原理、微控制器外设初始化流程、串口与SPI通信协议、中断服务与低功耗设计并能直接基于现有代码修改参数、验证通信效果加快后续项目开发进度。1. 收到一份“LORA完成.rar”先别急着解压先搞清它到底是不是你想要的 LoRA同事丢过来一个压缩包命名“LORA完成.rar”。在模型微调这个圈子里这种命名十有八九是一次 LoRA 微调跑完之后打好的交付包里面装着的是 adapter 权重、训练配置和日志。它要解决的是“微调结果怎么交付、怎么复用”的问题训练端把产物打包使用端拿到包之后能验货、能加载、能复现推理。适合正在跑第一个 LoRA 微调、或者要接手别人微调产物的人读。但先泼一盆冷水这个 LORA 不是做无线通信的 LoRa就是经常和蓝牙、ZigBee、WiFi 放一起对比的那个 LoRa。虽然拼写一样技术栈毫无关系。看到“LORA完成.rar”的第一步是拿文件清单确认它到底属于哪个领域别解压完才发现是个射频工程包。这篇文就按“大模型 LoRA 微调交付包”来拆里面该有什么、怎么验货、怎么加载到 Qwen 上跑通、以及我在这类包上踩过的坑。2. 看懂“完成包”里的文件LoRA 微调原理与交付物结构2.1 LoRA 为什么能省显存低秩分解不是黑匣子LoRA 的核心思路是冻结预训练模型的原始权重只在每层线性投影旁边挂两个小矩阵 A 和 B用 A×B 的结果去模拟权重更新量。假设某层权重 W 的形状是 d×d传统全参微调要训练 d² 个参数而 LoRA 只需要训练 d×r 加 r×d 个参数。r 一般取 8 到 64比 d 小一到两个数量级。训练完成后把 A×B 加回 W 就得到微调后的权重推理路径没有任何额外开销。真正吃显存的是梯度和优化器状态不是模型参数本身。一个 7B 模型FP16 权重约 14GB全参微调时每个参数要额外存 Adam 的一阶动量、二阶动量和梯度算下来需要上百 GB 显存池才能跑得动。LoRA 把可训练参数压到总参数的 0.1% 到 1% 量级优化器状态随之缩到几百 MB 到几 GB一张 24GB 的消费级显卡就能扛住 7B 模型的微调。这也是 LoRA 能成为“单卡微调默认方案”的根本原因不是魔法是冻结主干之后显存账面上就算得过来。微调方式可训练参数量显存需求量级产出物适用场景全参微调100%8 卡 H 级集群完整权重百 GB基座模型改造LoRA0.1% ~ 1%单卡 24GBadapter几十 MB风格/能力微调QLoRA0.1% ~ 1%单卡 12~16GBadapter几十 MB显存受限环境2.2 一个标准的“完成包”里该有哪些文件按 PEFT 库保存 LoRA 的标准流程训练完调用 model.save_pretrained(output_dir)产出物是 adapter_model.safetensors或旧版 pytorch_model.bin加 adapter_config.json。如果打包的人顺手把训练日志、tokenizer 文件、README 也塞进来那是加分项但前两个文件是硬性要求。列一个常见文件清单照着核对就能判断这个包是不是残的文件/目录作用缺失时的风险adapter_config.json记录 r、lora_alpha、target_modules、base_model_name_or_path 等超参数完全无法加载adapter_model.safetensors训练得到的增量权重即 A×B 矩阵只剩配置是残包tokenizer/ 或单独 tokenizer 文件训练时用的分词器副本需回 base 模型仓库补training_log/ 或 events.out.tfevents训练 loss 记录无法判断是否真收敛过README.md数据集、prompt 模板、复现说明难以复现效果adapter_config.json 里最值得看的不是 r 和 alpha而是 base_model_name_or_path。这一项写的是训练时的底座模型加载时你选的 base 必须和它对得上否则后面所有报错都是从这里引出来的。另一个重点是 target_modules它决定 LoRA 挂在模型的哪些子模块上写错或写法过旧训练能跑但权重根本没生效。一个 Qwen 系列模型常见的配置长这样{ peft_type: LORA, base_model_name_or_path: Qwen/Qwen2-1.5B-Instruct, r: 16, lora_alpha: 32, target_modules: [q_proj, k_proj, v_proj, o_proj], bias: none, task_type: CAUSAL_LM, lora_dropout: 0.05 }这里 r 是低秩矩阵的秩lora_alpha 是缩放系数推理时实际生效的缩放是 lora_alpha 除以 r。target_modules 里的 q_proj、k_proj 这些名字必须和底座模型 state_dict 里的键严格一致多一个下划线或者少一个前缀都会在加载时报 key mismatch。拿到包先对着这份 JSON 读一遍能省掉后面一小时的排查。2.3 用文件清单和时间戳反推训练是否真的“完成”“完成”两个字是打包人写的不代表训练真的收敛。我拿到任何交付包第一步不是解压而是直接在不解压的情况下列包内清单用文件大小和时间戳反推训练过程。Python 的 rarfile 库能干这事只读头信息不落地速度快密码错误也不会在第一步就卡死你import rarfile rf rarfile.RarFile(LORA完成.rar) for info in rf.infolist(): print( info.filename, info.file_size, info.date_time, 加密 if info.flags rarfile.RAR_FILE_ENCRYPTED else 未加密 )运行这段脚本之前先 pip install rarfile另外注意 rarfile 本身只是个解析器解压动作需要系统里有 unrar 或 bsdtar 可执行文件。打印结果里重点看三件事有没有 adapter_model.safetensors文件大小是否在几十 MB 量级有没有 training_log 或 events 文件adapter_config.json 的修改时间是否和 safetensors 接近。只有 config 没有权重的是空包权重才几 KB 的说明 A×B 矩阵没训起来大概率是训练中断后强行保存的产物。如果连文件列表都打不开那可能是头加密的包这个放到下一章说。3. 解包与验货rar 加密、中文乱码和权重完整性3.1 拿到加密的 rar先判断是加密还是损坏解压时报“需要密码”和报“CRC 校验错误”是两回事。我见过有人把加密包当成损坏包直接删了也见过有人把损坏包当加密包去试密码两个方向都浪费时间。先用上一章的 rarfile 脚本列清单如果连文件名都看不到说明打包时开了头加密整个文件目录树都被锁了如果文件名能看到、解压时才开始要密码那只是文件内容加密。rarfile 里可以用 rf.needs_password() 快速判断。密码问题的正规解法是先找打包人要密码交付场景下这只是一条消息的事。自己历史项目的包忘了密码回忆一下你惯用的压缩包密码格式位数短、纯数字的话可以试官方的恢复工具扫描几小时有结果超过 6 位混合字符穷举的时间成本远超重新训练直接放弃。网上搜“rar密码移除”能找到一堆工具但说实话它们能有效处理的只有你很确定密码是 4 到 6 位纯数字的情况拿来解别人的包基本不现实也别指望。注意头加密的包连文件大小都看不到没法判断里面是不是 LoRA。碰见这种情况直接找打包人确认内容比任何技巧都靠谱。3.2 不急着解压先建目录再释放解压 LoRA 交付包最忌讳直接往当前目录一扔。adapter_config.json 是个通用文件名你桌面上可能躺着一堆同名文件释放时互相覆盖回头加载的到底是哪个都说不清。我习惯建一个独立工作目录每次解压一个新包都隔离进去目录名直接用lora_delivery_日期。macOS 上我用 unar它对中文文件名的处理比 7z 默认行为好很多Linux 上则用 7z 加编码参数mkdir -p ~/work/lora_delivery_20250601 cd ~/work/lora_delivery_20250601 unar -o ./ LORA完成.rar # 或者 Linux 下 # 7z x -mcpGBK LORA完成.rarunar 的 -o 参数指定输出目录不传默认解到当前目录并自动建一个以压缩包命名的文件夹。7z 的 -mcpGBK 是把文件名按 GBK 编码解释专门对付 Windows 下打包的中文文件名。解压完成之后立刻做一次清单核对文件数、总大小、目录结构和 2.3 节列出来的不一致就停手先搞清楚差异在哪。这一步花两分钟能避免后面拿着缺文件的包折腾半天。3.3 权重完整性验证safetensors 的 JSON 头和 SHA256解压完不等于文件是好的。压缩包传输过程中断、网盘同步没完成、甚至打包人自己上传的就是个半截文件这些情况我都碰见过。safetensors 格式有个好处文件头部是一段 JSON 元数据每个张量的 dtype、shape、data_offsets 都写在里面只读头不加载权重就能发现文件截断。我到了一个新包先跑一个十分钟写好的验货脚本import json from safetensors import safe_open cfg_path adapter_config.json weights_path adapter_model.safetensors # 1. 配置文件必须是合法 JSON with open(cfg_path, r, encodingutf-8) as f: cfg json.load(f) print(base_model:, cfg.get(base_model_name_or_path)) print(r:, cfg.get(r), alpha:, cfg.get(lora_alpha)) print(target_modules:, cfg.get(target_modules)) # 2. 只读 safetensors 头部不加载权重 with safe_open(weights_path, frameworkpt, devicecpu) as f: keys list(f.keys()) print(tensor 数量:, len(keys)) for k in keys[:5]: t f.get_slice(k) print(k, t.get_shape(), t.get_dtype())safe_open 打开文件后f.keys() 就能拿到所有张量名不需要把权重读进显存。如果这段代码在打开阶段就抛异常说明文件头就已经损坏后面不用再试了。如果头部正常但张量数量少得离谱比如一个 7B 模型的 LoRA 只有两三个 key那也是异常正常的 LoRA 包至少覆盖 target_modules 里声明的所有模块数量在几十个到上百个。配置和权重都过了再顺手对一下 README 里有没有附 SHA256 校验值有就拿sha256sum adapter_model.safetensors比对两边不一致说明文件被动过或传坏了。4. 把 LoRA 真正用起来加载到 Qwen 并跑通第一次推理4.1 环境核对transformers / peft / 模型版本要配得上LoRA 加载报错一半以上是环境版本问题。Qwen2 系列模型对 transformers 版本有硬性要求低于某个基线版本连 base 模型都加载不了更别提挂 adapter 了。我建议直接建一个新的虚拟环境把依赖装到最新主线避免被其他项目的旧版本拖住。安装命令很简单python -m venv venv_lora source venv_lora/bin/activate pip install --upgrade pip pip install torch transformers accelerate peft safetensors装完之后先看一眼版本号python -c import peft, transformers; print(peft.__version__, transformers.__version__)。peft 版本太老的时候对 Qwen 这种新模型结构的 target_modules 匹配经常出问题报错还特别隐晦表现为“加载成功但推理没效果”。我一般会顺手把 peft 升到当前主线版本不纠结具体小版本号因为修复都是向前兼容的。另外注意 model 的加载路径adapter_config.json 里 base_model_name_or_path 如果是仓库名本地没有缓存的话会自动去拉权重建议提前确认网络可达或者预先手动下载到本地目录。如果拿到的是剪枝或量化过的底座配的 LoRA比如 Minimax-H3 剪枝版那个方向的东西必须把 base 路径指向剪枝后的权重而不是原版。训练脚本里的参数配置也是同一个套路base_model、train_data、val_data、output_dir 这几项是骨架lora_rank、lora_alpha、target_modules 是微调效果的关键旋钮from peft import LoraConfig, get_peft_model from transformers import AutoModelForCausalLM, AutoTokenizer base_model Qwen/Qwen2-1.5B-Instruct train_data data/train.jsonl val_data data/val.jsonl output_dir output/lora_checkpoint model AutoModelForCausalLM.from_pretrained(base_model, torch_dtypeauto) config LoraConfig( r16, lora_alpha32, target_modules[q_proj, k_proj, v_proj, o_proj], lora_dropout0.05, task_typeCAUSAL_LM, ) peft_model get_peft_model(model, config) peft_model.print_trainable_parameters()print_trainable_parameters 打印出来的可训练参数量如果占比为 0说明 target_modules 没匹配上任何层这时候训练再久都是白费。参数上 r 决定低秩空间的宽度r 太小拟合能力不足r 太大又失去 LoRA 省显存的意义lora_alpha 和 r 的比例影响更新量幅度我一般按 alpha 取 r 的两倍起步但这个值不是死规矩要结合验证集 loss 调。4.2 加载 adapter 并做一次最小推理跑通最小推理是验货的临门一脚。我的做法是加载 base 模型之后马上挂 adapter然后用一条和该 LoRA 训练主题强相关的 prompt 测试。这里不合并权重保持 adapter 的独立状态方便后面对比和卸载import torch from peft import PeftModel from transformers import AutoModelForCausalLM, AutoTokenizer base_model_name Qwen/Qwen2-1.5B-Instruct lora_path ./LORA完成_adapter_dir # 解压出来的 adapter 目录 tokenizer AutoTokenizer.from_pretrained(base_model_name, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( base_model_name, torch_dtypetorch.float16, device_mapauto, ) model PeftModel.from_pretrained(model, lora_path) model.eval() messages [{role: user, content: 用一句话解释什么是 LoRA 微调}] text tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) inputs tokenizer(text, return_tensorspt).to(model.device) with torch.inference_mode(): out model.generate( **inputs, max_new_tokens256, do_sampleTrue, temperature0.7, top_p0.9, ) print(tokenizer.decode(out[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue))apply_chat_template 是走对话模型的标准姿势它会按底座模型的模板把 messages 拼成带特殊 token 的输入。generate 参数里 max_new_tokens 控制生成长度温度 0.7、top_p 0.9 是中等探索度的设置想要更确定性的输出就把 do_sample 改成 False。加载后确认 adapter 生效的方法是打印 model.active_adapter返回的应该是你传入的 lora_path而不是 None。4.3 效果验证同样的 prompt对比 base 模型和 LoRA 输出的差异最小推理跑通之后下一步是验证 LoRA 是不是真的改变了模型行为。这一步太容易被跳过但恰恰是最能暴露问题的一步。我用一个脚本同时加载底座和挂上 adapter 的模型对同一组 prompt 分别生成然后对比输出。如果两者几乎一模一样说明 LoRA 权重虽然加载了但没有对模型产生实质影响import torch from peft import PeftModel from transformers import AutoModelForCausalLM, AutoTokenizer base_name Qwen/Qwen2-1.5B-Instruct lora_path ./LORA完成_adapter_dir prompts [ 写一句抱怨加班的冷笑话, 请用武侠小说的风格描述一次代码评审, ] # 底座模型不挂 adapter tokenizer AutoTokenizer.from_pretrained(base_name, trust_remote_codeTrue) base_model AutoModelForCausalLM.from_pretrained( base_name, torch_dtypetorch.float16, device_mapauto ).eval() # 挂了 adapter 的模型 lora_model PeftModel.from_pretrained(base_model, lora_path).eval() def generate(model, prompt: str) - str: messages [{role: user, content: prompt}] text tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) inputs tokenizer(text, return_tensorspt).to(model.device) with torch.inference_mode(): out model.generate(**inputs, max_new_tokens128, do_sampleFalse) return tokenizer.decode(out[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue) for p in prompts: print(prompt:, p) print(base:, generate(base_model, p)) print(lora:, generate(lora_model, p)) print(- * 50)对比时注意 do_sampleFalse这样才能保证差异是权重导致的而不是采样随机性造成的。如果 base 和 lora 的输出连标点都一样回到 adapter_config.json 和 safetensors 头去查八成是 target_modules 没命中或者训练时 loss 根本没降下来。如果差异大但质量明显变差要怀疑是不是训练数据主题和当前 prompt 不匹配换几条贴近训练场景的 prompt 再测一轮。5. 避坑我在这种“完成包”上翻过的 5 次车5.1 现象加载时报 key mismatchadapter 里的张量名和底座对不上原因训练时 target_modules 里的模块名没对上底座模型或者底座模型版本换过比如 Qwen 从 1.x 换到 2.x注意力层的命名从 q_proj 改成了 qkv_proj 之类的结构变化。这类报错往往在 load 阶段直接崩溃提示某个 key 找不到。解决先打印底座模型的 state_dict 键名和 adapter_config.json 里的 target_modules 一一对照。直接用model.state_dict().keys()可能太多筛出含 proj 的键看一眼命名规则。如果确实不一致用 LoRA 训练方的原始 base 模型重新加载。adapter 和 base 的版本必须严格同源没有通融余地。5.2 现象显存不够一加载就 OOM尤其在剪枝量化版底座上原因同时加载了完整 FP16 底座和 adapter又把 max_new_tokens 拉得很长KV cache 膨胀吃掉剩余显存。剪枝版或量化版底座叠加 LoRA 时有些推理框架会先把权重还原成高精度再计算显存瞬间爆掉Minimax-H3 剪枝版这类的包特别容易出现“加速 LoRA 反而爆显存”的现象。解决先 load_in_4bit 量化底座再挂 adapter推理阶段不要 merge。把 max_new_tokens 控制在 512 以内batch size 从 1 开始。如果还爆检查是不是推理框架对量化权重做了反量化换用支持 4bit 计算的原生路径。5.3 现象adapter 加载成功输出和底座一模一样原因最典型的是训练时 target_modules 没命中任何层训练脚本跑完了但可训练参数为零保存下来的是一个“空 LoRA”。其次是训练中断但保存逻辑没拦住保存了随机初始化或接近零的权重。还有一种情况是 lora_alpha 设得极小而 r 设得很大导致缩放系数小到可以忽略。解决不加载权重直接读 safetensors 里的张量做统计。safe_open拿到某个 key 的切片后用torch.max(torch.abs(tensor))看绝对值量级。正常 LoRA 权重的绝对值在 1e-3 到 1e-2 之间如果全是 0 或者小于 1e-6这个包基本是废的回去重新训练。5.4 现象rar 解压后中文文件名乱码训练日志和 README 全变成乱码文件名原因rar 打包时编码用的是 Windows 本地代码页常见 GBK而解压工具默认按 UTF-8 或 cp437 解码两边对不上就产生乱码。文件内容本身没坏坏的是文件名映射。解决macOS 用 unar自动识别编码我解压中文 rar 包很少翻车Linux 用 7z 加-mcpGBK。如果已经解压乱了别手动一个一个改直接删掉重新解压。乱码文件名不影响 adapter 加载但会影响你读训练日志和复现说明值得多花一步处理。5.5 现象tokenizer 加载报错或者生成的文本大量重复、格式混乱原因LoRA 包里没有带 tokenizer 文件而你用了别的模型的 tokenizer 去加载词表 id 对不上。另一种情况是 base 模型是基础版而不是指令微调版apply_chat_template 找不到对应的 chat 模板生成的文本没有 system、user 结构。解决tokenizer 一律从 adapter_config.json 里 base_model_name_or_path 指定的路径加载不要贪方便随便拿一个相近模型顶替。如果目标底座是基础版模型就放弃 chat 模板用最原始的文本拼接方式构造输入。这个问题在“完成包”里几乎每个都会遇到一次。6. 让这份 LoRA 能复用下去合并回 base、多 LoRA 切换和验证台账验证完 adapter 能跑、有效果接下来要决定它怎么被反复使用。最省事的办法是合并回底座模型得到一份完整权重以后推理不用再带着 adapter 目录和 PeftModel 这套加载逻辑merged lora_model.merge_and_unload() merged.save_pretrained(./merged_model_full) tokenizer.save_pretrained(./merged_model_full)merge 会直接在内存里把 A×B 加回 W然后卸载 adapter 结构。合并前保留原 adapter 目录因为 merge 是不可逆操作我吃过这个亏合并后不满意又拿不回原来的 adapter。合并后的模型可以正常跑推理也可以用 transformers 的 pipeline 直接加载不用再装 peft。如果你想把多个 LoRA 用在同一份底座上动态切换就不要 merge用 load_adapter 和 set_adapter 切来切去切换只换几十 MB 的权重底座不用重复加载。最后养一个习惯每个包验完货记一份验证台账。我一般记四行base 模型、r/alpha、验证 prompt、输出效果和复现条件。见过太多“完成包”过两周自己都看不懂当时怎么跑的有时间戳的记录能省下大量回头查的时间。跑第一个 LoRA 微调的时候我就吃过这个亏当时有个包训练日志里 loss 还在高位就被打了“完成”标接手的人是我自己对着一个没收敛的 adapter 排查了半天。后来每次收包先看 config、再跑对比验证这套流程走顺了翻车概率直线下降。希望帮到你。本文还有配套的精品资源点击获取