简介这是一份基于STM32F103C8T6微控制器与LoRa模块的无线传感器数据采集与传输完整工程面向嵌入式开发学习者尤其适合正在入门物联网长距离通信的读者。压缩包内共189个文件以C语言源文件.c/.h和Keil工程配置为主同时包含编译生成的.hex/.axf固件及调试记录整体大小仅1.96MB便于快速打开和移植。对应项目展示了从ADC采集传感器模拟信号、STM32外设初始化到通过SPI/UART驱动LoRa模块、实现最远约3公里无线发送的完整链路。查阅工程者可跟着代码理解LPWAN通信机制、中断服务与低功耗设计还能参考作者的调试日志、链接映射文件等排错痕迹。资源已有4191人学习对于想动手搭建LoRa节点、扩展物联网感知项目的开发者具有直接借鉴价值。1. 收到一个“LORA完成.rar”先别急着解压先想清楚里面该有什么收到一个“LORA完成.rar”很多人的第一反应是双击解压、看目录、找权重文件。但作为跑过几十次 lora 微调的人我拿到这种交付包的第一动作不是解压而是先测包。这个标题背后是一类典型场景lora 训练跑完把配置、脚本、adapter 权重和训练日志打成 rar 包移交。它要回答的问题是训练是否真的完成、权重能否直接加载、参数配置能不能复现。适合需要验收或复跑别人 lora 微调结果的 NLP 工程师、算法同学和数据集制作方。反直觉的是这里用 rar 不是随手选的——恢复记录和固实压缩对 safetensors 这种大权重文件偶发损坏的兜底能力比 zip 可靠得多。先把“rar 的校验能力”用起来再谈训练和部署。2. 从 rar 到可复现训练完整性验证、解压与目录落地的三个步骤2.1 rar 为什么总出现在 lora 交付里恢复记录、固实压缩与二进制权重一个 lora 训练完成后的交付物核心是 adapter_model.safetensors大小从十几 MB 到几十 MB 不等搭配 adapter_config.json、训练脚本、配置文件和一串日志。这些文件看起来不多但混着二进制权重和大量 json、yaml 小文件。rar 在工程交付里的一个核心优势是恢复记录rr%网盘中转、U 盘拷贝途中出现位翻转时unrar 能基于恢复记录把损坏块修回来zip 没有这种机制。第二个优势是固实压缩把大量小文件作为一个连续数据流压缩整体体积会比 zip 更小。第三个是分卷超大包可以切成 LORA完成.part1.rar、part2.rar 这样分批传很多交付习惯都这么来。所以“LORA完成.rar”里的 rar 不只是压缩格式它暗示这是一个带校验能力、准备长期保存的最终存档。解压之前要先想清楚目的是为了复跑训练、为了验证权重质量还是为了合并权重去部署。目的不同目录落地的姿势就不同。我一般会把“一个包 一个独立项目目录”来放路径类似~/projects/lora_finished/xxx而不是解到桌面。否则后面跑训练、看日志、对比版本时全乱套。提示如果拿到的是 zip 包就没有恢复记录可用只能靠额外的 md5 或 sha256 文件校验。所以“完成.rar”这类带状态字的交付优先保留 rar 原包不要为了省事转成 zip。2.2 解压前先测包unrar t 与 7z t 怎么用、参数怎么带验收的第一步不是解压是测包。Linux 下我用 unrarWindows 下用 WinRAR 或 7-Zip命令逻辑一样。# 测试整个包不实际解压-p- 表示即使包有密码也先不输入避免交互卡住 unrar t -p- LORA完成.rar # 输出里每个文件一行末尾是 OK 表示 CRC 校验通过 # 出现 CRC failed 表示文件已经损坏不要继续解压7z 的写法也顺手列一下很多服务器上默认只有 7z 没有 unrar7z t LORA完成.rar两者差别在于unrar 对 rar 专有格式支持更完整能识别恢复记录并参与校验7z t 走的是通用解压校验文件块损坏时能报出来但不会利用 rr 信息做修复判断。测包是完整读一遍包内所有文件几十 GB 的权重包要等一段时间这个时间别省。确认包是好的后面所有问题都只剩“代码和配置层面的问题”包是坏的解压出来的权重哪怕能加载也是定时炸弹。常用命令对比操作unrar7z测试完整性unrar t7z t列出文件清单unrar lb7z l -ba解压并保留目录结构unrar x7z x解压并平铺文件unrar e7z e修复带恢复记录的包unrar r不支持2.3 解压到约定目录文件清单核对、中文名编码与目录隔离测包通过后再执行解压。我一般在项目根目录下建一个以压缩包命名的文件夹避免二次移动。mkdir -p ~/projects/lora_finished cd ~/projects/lora_finished unrar x -o -p- ../LORA完成.rarx保留包内原始目录结构这是关键。如果用了e所有文件会被摊平到一个目录config、scripts、output 层级全丢后面对照配置会非常痛苦。-o表示覆盖同名文件适合重跑验收场景首次解压时可以不加让它在遇到同名文件时停下来问你。解压之后先列清单核对而不是直接进目录找权重unrar lb LORA完成.rar | sort一个常见的“完成”包内部结构长这样路径作用config/lora_config.yamllora 参数配置训练和复现的核心scripts/train_lora.py训练入口脚本scripts/merge_lora.py权重合并脚本output/checkpoint-500/adapter_model.safetensorslora 权重最关键产物output/checkpoint-500/adapter_config.jsonpeft 加载必需元数据output/checkpoint-500/trainer_state.json训练进度与全局步数logs/train.log训练日志README.md作者写的说明adapter_config.json 和 adapter_model.safetensors 必须成对出现缺一个都不能用 peft 加载。如果包内只有脚本和配置、没有 output 目录那这个包只是“训练工程”不是“训练完成物”。中文文件名在这里是个常见坑Linux 下 unrar 解压带中文名的文件容易乱码README.md 变成一串“锟斤拷”。我一般用 7z 指定字符集解压或者先在 Windows 上用 WinRAR 解压再改名。命令可以这样写7z x ../LORA完成.rar -o$HOME/projects/lora_finished -scsUTF-8这个坑不影响权重本身但会影响验收时读说明文档遇到乱码先怀疑编码不要怀疑包坏了。3. 把 lora 配置读透base_model、train_data、val_data、output_dir 逐项填法3.1 一份最小 lora 配置的逐行拆解base_model、train_data、val_data、output_dir热词里那串base_model train_data val_data output_dir 是 lora 微调脚本最常见的参数骨架很多训练脚本就是用这一组参数决定“训练什么、在哪训练、结果放哪”。在包内落到配置文件时通常是 yaml 或 json下面是一份很常见的 qwen lora 配置几乎每个“完成”包都会有同款。# config/lora_config.yaml base_model: Qwen/Qwen2-7B-Instruct # 基础模型HuggingFace 路径或本地路径 model_type: causal_lm # 模型类型因果语言模型 train_data: data/train_alpaca.jsonl # 训练数据每行一个 JSON val_data: data/val_alpaca.jsonl # 验证数据格式同训练数据 output_dir: output/checkpoint-500 # checkpoint 和 adapter 保存目录 lora_r: 16 # LoRA 秩影响可训练参数量 lora_alpha: 32 # LoRA 缩放系数常见取 2 * r lora_dropout: 0.05 # 防止过拟合一般 0~0.1 target_modules: - q_proj - k_proj - v_proj - o_proj learning_rate: 2e-4 # LoRA 学习率通常比全参微调高一个量级 per_device_train_batch_size: 4 # 单卡 batch size per_device_eval_batch_size: 8 gradient_accumulation_steps: 8 # 累积步数等效 batch 4 * 8 32 max_seq_length: 2048 # 单样本最大 token 长度超出直接截断 gradient_checkpointing: true # 用计算换显存训练大模型建议开 logging_steps: 10 eval_strategy: steps eval_steps: 100 save_strategy: steps save_steps: 500base_model 是最容易出问题的一项。交付包里作者写的往往是一个 HuggingFace 仓库名但不代表你本地已经缓存了这个模型。如果你本地只有同名不同版本的模型比如用Qwen/Qwen2-7B替代了配置里的Qwen/Qwen2-7B-Instruct后面加载 adapter 时大概率 key 对不上这个在避坑章单独展开。train_data 和 val_data 建议在复跑时改成绝对路径因为相对路径换机器最容易断。数据格式通常是 alpaca 风格的 jsonl每行包含 instruction、input、output 三个字段代码里按这个结构解析。output_dir 是训练过程保存 checkpoint 的地方最终 lora 权重也在里面名字一般就是 checkpoint-500 这种“全局步数”命名。lora_r 决定可训练参数量常用值是 8、16、32。对 7B 模型来说 r16 的 adapter 权重大约几十 MBr64 会明显变大但没有等比例的效果提升。lora_alpha 是缩放系数常见取 2 倍 r这不是硬性规则但按这个配不会出大问题。提示复跑别人的配置时不要直接改 lora_r。先原样跑通再调参。跳过“能跑通”直接“调更好”是翻车高发区。3.2 跑通第一个 lora 微调入口命令、日志判读与产出物配置读懂后跑通第一个 lora 微调的工作量其实很小。包内 scripts 里通常已经写好了训练脚本依赖也就是 transformers、peft、accelerate、datasets 这几个。cd ~/projects/lora_finished # 安装依赖requirements.txt 里一般已经锁了版本 pip install -r scripts/requirements.txt # 指定用哪张卡单机多卡时这里写成 0 或 1 export CUDA_VISIBLE_DEVICES0 # 跑训练同时用 tee 把输出完整留到 logs 里 python scripts/train_lora.py --config config/lora_config.yaml 21 | tee logs/reproduce.logCUDA_VISIBLE_DEVICES 必须显式指定。不指定时如果机器上有多张卡transformers 的 Trainer 可能默认把模型摊到所有卡上显存小的卡直接 OOM。tee logs/reproduce.log是把终端输出同时写到文件后面判断训练过程和排查问题全靠这份日志。训练日志关注三个信号。第一是train_loss正常会逐步下降如果跑了几百步还在原地或者上升就是配置有问题。第二是eval_loss每 eval_steps 步打印一次它跟着 train_loss 一起降是健康状态train_loss 降但 eval_loss 涨说明过拟合。第三是保存输出类似Saved model to output/checkpoint-500出现它才意味着 adapter 文件真正落盘。日志里如果出现CUDA out of memory立即停调参而不是等它继续跑。训练完成后检查 output_dir 下是否生成了三件套ls output/checkpoint-500/ # adapter_model.safetensors adapter_config.json trainer_state.jsonadapter_model.safetensors 是权重本体adapter_config.json 是 peft 加载时读取的元数据trainer_state.json 记录全局步数和最优指标。三件套齐了训练才算“完成”。有日志但没这三件套说明训练是被中断或后处理失败的。3.3 qwen 的 target_modules 选法命中结构才算数别只抄默认值target_modules 是 lora 配置里最像玄学的一项。不同模型、不同版本、甚至不同剪枝处理后的模型层名都可能不一样。qwen2 系列是标准 decoder 结构attention 层有 q_proj、k_proj、v_proj、o_projmlp 层有 gate_up_proj、down_proj。常见做法是把 attention 四个投影全部上 lora效果稳定、可训练参数量适中也有人把 mlp 层也加进去能提升一点能力但权重文件和显存都变大。判断 target_modules 到底有没有命中模型结构不要靠猜用代码直接打印from peft import LoraConfig, get_peft_model from transformers import AutoModelForCausalLM model AutoModelForCausalLM.from_pretrained( Qwen/Qwen2-7B-Instruct, torch_dtypebfloat16 ) peft_config LoraConfig( r16, lora_alpha32, target_modules[q_proj, k_proj, v_proj, o_proj], ) model get_peft_model(model, peft_config) # 打印可训练参数量命中正常时 7B 模型大约有几百万到几千万参数 model.print_trainable_parameters()输出类似trainable params: 8,388,608 || all params: 7,045,087,232才算正常。如果 trainable params 是 0 或者小到离谱说明 target_modules 里的名字和模型实际的 key 对不上。对剪枝或蒸馏过的模型比如 minimax-h3 剪枝版 lora结构 key 可能被改过名字必须用model.named_parameters()先列一遍再填 target_modules。这个步骤不报错、能训练但 lora 没作用在任何层上loss 怎么跑都不降是很隐蔽的坑。4. 验证权重而不是验证文件加载 adapter、合并权重与判读训练日志4.1 用 peft 加载 adapter 做一次最小推理验证“完成”不是文件存在而是能用解压目录里躺着一份 adapter_model.safetensors只能说明文件在不能说明权重能用。验证“完成”的标准动作是加载 base 模型挂上 adapter跑一句推理看输出是否合理且带训练痕迹。import torch from transformers import AutoModelForCausalLM, AutoTokenizer from peft import PeftModel base_path Qwen/Qwen2-7B-Instruct adapter_path output/checkpoint-500 # 指到包含 adapter_config.json 的目录 model AutoModelForCausalLM.from_pretrained( base_path, torch_dtypebfloat16, device_mapauto, ) model PeftModel.from_pretrained(model, adapter_path) tokenizer AutoTokenizer.from_pretrained(base_path) # 注意prompt 模板必须和训练时一致qwen 用的是 chatml 模板 inputs tokenizer( |im_start|user\n用一句话解释 LoRA 微调|im_end|\n|im_start|assistant\n, return_tensorspt, ) with torch.no_grad(): out model.generate( **inputs, max_new_tokens128, temperature0.7, top_p0.9, ) print(tokenizer.decode(out[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue))torch_dtype 建议和训练时保持一致训练日志里能查到用的 bf16 还是 fp16。device_mapauto 在单卡上就是整卡多卡会自动切分。PeftModel.from_pretrained 只挂 adapter不修改 base 模型加载错了随时卸载重来这是 lora 路线最大的“后悔药”。验证推理输出时看两点。第一是通顺度输出应该是完整中文句子而不是乱码第二是领域痕迹训练数据是某个垂直领域的输出应该带出该领域的表达风格说明 adapter 真的起了作用。如果回答和 base 模型几乎一样即使文件存在这个 adapter 也大概率没训练好。4.2 合并 lora 权重什么时候 merge、怎么合并且不踩精度坑替换到生产环境时挂 adapter 的方式不够方便部署服务端要同时管 base 和 adapter 两份配置。常见做法是训练结束后直接合并生成一个独立模型目录。from peft import PeftModel model AutoModelForCausalLM.from_pretrained(base_path, torch_dtypebfloat16) model PeftModel.from_pretrained(model, adapter_path) # 把 lora 增量写回 base 权重并卸载 adapter merged_model model.merge_and_unload() # 保存成完整模型目录可以直接用 transformers 或 vllm 加载 merged_model.save_pretrained(output/merged-7b-lora) tokenizer.save_pretrained(output/merged-7b-lora)merge_and_unload 的语义是“把低秩矩阵增量合并到原权重然后移除 lora 包装”。合并后的模型不再依赖 adapter 文件给别人部署只需要传一份。合并后必须重新加载验证一次跑和 adapter 模式完全相同的 prompt回答应当基本一致。如果两个模式输出差异很大优先查 dtype 是否一致base 加载用的是 fp16adapter 训练时是 bf16合并时数值会有偏差量化模型4bit合并时误差会被放大建议加载时保持和训练相同的 quantization 配置合并后单独保存一份 fp16 版本。4.3 训练日志与 eval_loss 判读什么叫训练“完成”了拿到一份包里的 logs/train.log怎么快速判断这个训练是“真完成”还是“跑了一半被掐断”看几个标志位日志特征状态判断后续动作train_loss 逐步下降eval_loss 同步低位正常收敛按包内的 checkpoint 产出验收train_loss 和 eval_loss 都偏高且还在缓慢下降欠拟合训练不充分继续训练或调大 lora_r 和学习率train_loss 很低eval_loss 先降后升过拟合提前停止下次调大 dropout 或加数据日志最后出现 CUDA out of memory训练中断不是“完成包”见避坑章 5.3有日志但没有 adapter_model.safetensors后处理失败找训练进程或重新生成权重“完成”的定义应该是日志无 error、adapter 三件套齐全、eval_loss 达到你预期基线、最小推理输出通顺。四者缺一都只能算“半成品包”。如果包内日志只写了训练过程、没有任何 eval 输出这个包很可能只是“跑过”而不是“验收过”需要自己补一次验证。5. LORA 完成.rar 验收避坑从解压密码到加载翻车的 5 个现场5.1 密码明明对却报错中文密码与文件名编码现象unrar x解压时反复提示Incorrect password密码自己确认没记错Windows 上用 WinRAR 却能正常解开。原因包作者用中文或特殊符号设了密码。Linux 终端输入非 ASCII 字符时shell 编码和压缩包创建时的编码不一致导致密码比对失败。还有一种情况是包里文件名是简体中文 GBK 编码解压环境是 UTF-8文件名显示乱码被误以为包有问题。解决先在 Windows 上用 WinRAR 验证密码本身没问题。Linux 下导出 UTF-8 语言环境再试export LANGzh_CN.UTF-8 unrar x -p密码原文 ../LORA完成.rar如果密码是中文建议直接让作者把密码改成纯 ASCII 重新打包这是最省事的方式。网上那些“advanced rar password recovery”式的工具先别动真密码对不上时它们帮不上忙还可能引入额外风险。这个坑的数据教训是密码问题里有七成是编码问题不是真正忘记密码。5.2 adapter 加载报 key 不匹配base_model 与训练时不一致现象PeftModel.from_pretrained报size mismatch、unexpected keys或者能加载但推理输出明显异常。原因adapter_config.json 里记录了训练时用的 base_model_name_or_path但它只是字符串不会校验你当前加载的是不是同一个模型。你本地可能用Qwen/Qwen2-7B替代了配置里的Qwen/Qwen2-7B-Instruct参数量一样但中间层表示完全不同。lora 权重是“增量修正”修正量只对原来的基础模型有意义换 base 等于把修正在错误对象上。解决先读 adapter_config.jsoncat output/checkpoint-500/adapter_config.json找到 base_model_name_or_path严格按这个路径下载对应模型一个字符都不能差。Instruct 版和 base 版不能互换bf16 版和 fp16 版也尽量对齐。找不到原版模型时联系作者要 base 模型的 md5 比对文件不要自己“找个差不多的”。5.3 一训练就爆显存序列长度、lora_r 与剪枝模型的叠加压力现象复跑训练时进程启动几秒后报CUDA out of memory或者训练到第 N 步被系统 kill。原因lora 虽然只训练少量参数但推理和反向传播的过程仍然要过完整 base 模型显存占用大头在激活值不在 lora 权重。包内配置如果写了max_seq_length: 4096、per_device_train_batch_size: 4、lora_r: 64单张 24G 卡基本扛不住。还有一个隐蔽点minimax-h3 剪枝版这类模型结构和原版不同某些层的缓存策略也不一样直接套原版 lora 训练代码可能额外吃显存。解决按顺序降配每次只动一个变量。max_seq_length: 2048 # 先砍一半 per_device_train_batch_size: 2 gradient_accumulation_steps: 16 # 维持等效 batch size 不变 lora_r: 8 # 再不行就降秩gradient_checkpointing 保持 true这是性价比最高的显存优化。如果单卡仍然不够用 accelerate 或 deepspeed 的 ZeRO 跑不要硬扛。判断是否生效看日志里的allocated memory稳定在卡显存 80% 以内才算安全。5.4 loss 不降反升target_modules 没打中模型结构现象训练跑了几百步train_loss 从 1.2 开始横在 1.8 不降eval_loss 还在缓慢上涨。原因这是最隐蔽的坑。target_modules 里写的层名和实际模型 state_dict 对不上时peft 不会报错而是“找不到就跳过”结果 lora 没有作用在任何层上等于原模型原地训练。常见触发条件是把 llama 的层名套在 qwen 上或者对剪枝版模型用了原版模型的 key。解决训练启动时盯住两样东西。第一是print_trainable_parameters()的输出7B 模型一般有几百万可训练参数如果只有几千或者 0target_modules 肯定写错了。第二是跑一次print(list(model.named_parameters()))核对实际 key 名。对剪枝版模型先加载 base把它的 key 列表导出来再填 target_modules。5.5 解压到一半 CRC 错误恢复记录才是 rar 的后悔药现象unrar x 解压到output/checkpoint-500/adapter_model.safetensors时中断报CRC failed。原因网盘下载、U 盘拷贝过程导致二进制文件某一段损坏压缩包本身不完整。safetensors 是纯二进制格式损坏哪怕一小块训练时都可能出现诡异 nan 或者推理乱码。解决先用unrar t定位哪些文件损坏再用unrar r尝试修复unrar r ../LORA完成.rar修复前提是作者打包时加了恢复记录rr 参数。如果加了修复后重新unrar t通过再解压作者没加 rr这个包基本只能重新下载。这也是为什么验收顺序必须是“先 t 后 x”——跳到 x 直接解压CRC 错误会在解压中途爆出来浪费时间还容易被误判成配置问题。养成这个习惯之后我手里基本没再出现过“解压出来的权重训练到一半才翻车”的情况。6. 把验收做成脚本批量处理完成包并留下后悔药6.1 一个 60 秒的批量验收脚本解压、冒烟、留痕当手里不止一个“LORA完成.rar”而是按日期命名的十几个版本时手动逐个解压验证就不现实了。我现在的做法是写一个成熟的小脚本循环完成三件事测包、解压到独立目录、跑冒烟验证。#!/bin/bash for rar in ./*完成*.rar; do echo $rar unrar t -p- $rar || { echo FAILED: $rar; continue; } unrar x -o -p- $rar python scripts/smoke_test.py --adapter ${rar%.rar}/output/checkpoint-500 done逻辑是每个压缩包解到以其名字命名的独立目录天然实现版本隔离。unrar t失败的直接跳过不进入训练流程。smoke_test.py 就是第 4 章的加载推理脚本只生成一句最短输出检查输出非空且不含乱码返回 0 就算通过。这一步能拦截掉大部分“文件在了但权重坏了”的包。再把每个包的配置哈希记下来防止后面改来改去不知道哪个包是哪个状态sha256sum ${rar%.rar}/config/lora_config.yaml manifest.txt这个习惯帮我省过很多事。版本多了以后对比 manifest 里两个包的配置差异比人眼翻文件快得多。曾经有一次我不先跑 unrar t直接把一个 CRC 损坏的包解压拿去训练结果跑了两小时 loss 开始跳 nan回头看才发现是权重文件损坏。那之后我定下规矩任何“完成”包到手先 t 再 x再冒烟最后才谈训练和部署。这套流程十分钟以内换来的是不浪费半天训练时间。希望帮到你。本文还有配套的精品资源点击获取
