简介：这是一份基于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 下我用 unrar，Windows 下用 WinRAR 或 7-Zip，命令逻辑一样。
# 测试整个包，不实际解压；-p- 表示即使包有密码也先不输入，避免交互卡住 unrar t -p- "LORA完成.rar" # 输出里每个文件一行，末尾是 OK 表示 CRC 校验通过 # 出现 CRC failed 表示文件已经损坏，不要继续解压7z 的写法也顺手列一下，很多服务器上默认只有 7z 没有 unrar：
7z t "LORA完成.rar"两者差别在于：unrar 对 rar 专有格式支持更完整，能识别恢复记录并参与校验；7z t 走的是通用解压校验，文件块损坏时能报出来，但不会利用 rr 信息做修复判断。测包是完整读一遍包内所有文件，几十 GB 的权重包要等一段时间，这个时间别省。确认包是好的，后面所有问题都只剩“代码和配置层面的问题”；包是坏的，解压出来的权重哪怕能加载也是定时炸弹。
常用命令对比：
| 操作 | unrar | 7z |
|---|---|---|
| 测试完整性 | unrar t | 7z t |
| 列出文件清单 | unrar lb | 7z l -ba |
| 解压并保留目录结构 | unrar x | 7z x |
| 解压并平铺文件 | unrar e | 7z e |
| 修复带恢复记录的包 | unrar r | 不支持 |
2.3 解压到约定目录：文件清单核对、中文名编码与目录隔离
测包通过后，再执行解压。我一般在项目根目录下建一个以压缩包命名的文件夹，避免二次移动。
mkdir -p ~/projects/lora_finished cd ~/projects/lora_finished unrar x -o+ -p- "../LORA完成.rar"x保留包内原始目录结构，这是关键。如果用了e，所有文件会被摊平到一个目录，config、scripts、output 层级全丢，后面对照配置会非常痛苦。-o+表示覆盖同名文件，适合重跑验收场景；首次解压时可以不加，让它在遇到同名文件时停下来问你。
解压之后先列清单核对，而不是直接进目录找权重：
unrar lb "LORA完成.rar" | sort一个常见的“完成”包内部结构长这样：
| 路径 | 作用 |
|---|---|
| config/lora_config.yaml | lora 参数配置，训练和复现的核心 |
| scripts/train_lora.py | 训练入口脚本 |
| scripts/merge_lora.py | 权重合并脚本 |
| output/checkpoint-500/adapter_model.safetensors | lora 权重，最关键产物 |
| output/checkpoint-500/adapter_config.json | peft 加载必需元数据 |
| 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 模型来说 r=16 的 adapter 权重大约几十 MB，r=64 会明显变大，但没有等比例的效果提升。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_DEVICES=0 # 跑训练，同时用 tee 把输出完整留到 logs 里 python scripts/train_lora.py --config config/lora_config.yaml 2>&1 | 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_proj，mlp 层有 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_dtype="bfloat16" ) peft_config = LoraConfig( r=16, lora_alpha=32, 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_dtype="bfloat16", device_map="auto", ) 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_tensors="pt", ) with torch.no_grad(): out = model.generate( **inputs, max_new_tokens=128, temperature=0.7, top_p=0.9, ) print(tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))torch_dtype 建议和训练时保持一致，训练日志里能查到用的 bf16 还是 fp16。device_map="auto" 在单卡上就是整卡，多卡会自动切分。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_dtype="bfloat16") 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 加载用的是 fp16，adapter 训练时是 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 LANG=zh_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.json：
cat 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 模型一般有几百万可训练参数，如果只有几千或者 0，target_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，再冒烟，最后才谈训练和部署。
这套流程十分钟以内，换来的是不浪费半天训练时间。希望帮到你。
本文还有配套的精品资源，点击获取
