简介这份资源面向使用 MicroPython 的嵌入式开发者与物联网入门者提供一份可直接参考的 LoRa 通信驱动实现帮助在资源受限的单片机上完成远距离、低功耗的数据收发。压缩包内共 1 个文件为单个 py 脚本整体约 1KB体量轻巧便于快速阅读与移植到 ESP32、Arduino 等支持 LoRa 模块的硬件平台。脚本内容围绕 LoRa 驱动展开涵盖模块初始化与频率、扩频因子等参数配置网络参数设置数据收发函数定义以及网络状态与收发事件处理、空闲时关闭模块的能耗管理等环节读者可借此理解 MicroPython 下通过 SPI 控制 LoRa 模块、接入 LoRaWAN 的基本思路。目前已有 481 人学习下载适合希望将 LoRa 与 Python 结合用于智能农业、环境监测、物流跟踪等远程传感场景的开发者作为驱动参考与二次开发起点。1. 从 lora_lora_python_ 说起一个被名字耽误的微调入口第一次看到lora_lora_python_这个标题很多人会以为是某个 LoRA 通信库的 Python 绑定或者是一份随手丢在仓库里的脚本合集。但把 lora 训练、lora 微调、lora 参数配置这几个热搜词摆在一起看方向其实很清楚它指向的是用 Python 做 LoRA 微调这条链路而不是 LoRa 射频通信。名字里重复的 lora 更像是仓库命名时的随手拼接真正有价值的是后半段——Python 生态下把低秩适配跑起来的那套流程。我见过太多人卡在第一步模型权重下好了数据也标了几百条结果卡在base_model、train_data、val_data、output_dir这四个参数上不知道该填路径还是填模型名不知道该用 HuggingFace 的peft还是自己写训练循环。这篇就把这条链路拆开从环境、数据格式、参数配置到显存排查给一套能直接抄的落地路径。适合已经会写 Python、想动手做一次 LoRA 微调但还没跑通全流程的人也适合跑通过一次但显存老是爆、效果不稳定的熟手对照排查。2. 环境与依赖把 Python 侧的 LoRA 微调底座搭稳2.1 为什么优先用 peft transformers 而不是手写 LoRA 层LoRA 的核心是在原始权重旁挂一对低秩矩阵 A 和 B前向时把B A乘上缩放系数加到原输出上。原理不复杂但真要在 Transformer 的注意力层里正确注入、正确冻结原权重、正确保存和加载适配器手写很容易在merge和unmerge上翻车。常见做法是直接用 HuggingFace 的peft它把LoraConfig、get_peft_model、merge_and_unload都封装好了和transformers的Trainer能直接对接。选型上我一般这样分如果只是做一次 SFT 微调pefttransformerstrl的SFTTrainer是最短路径如果要做 RLHF 或 DPO再考虑trl里对应的 trainer如果模型结构特殊peft不支持目标层才考虑自己写注入逻辑。对绝大多数人来说第一条路就够了。2.2 用 conda 建一个干净的 Python 环境Python 安装教程和 vscode python 环境配置是热搜里出现频率最高的词说明很多人第一步就卡在环境上。LoRA 微调对版本敏感尤其是torch、transformers、peft三者的兼容性混装系统 Python 很容易出问题。我一般用 conda 建独立环境# 建一个 Python 3.10 的环境3.10 是目前兼容性最好的版本 conda create -n lora_ft python3.10 -y conda activate lora_ft # 先装 torch按 CUDA 版本选这里以 CUDA 12.1 为例 pip install torch2.1.2 torchvision0.16.2 --index-url https://download.pytorch.org/whl/cu121 # 再装微调三件套 pip install transformers4.38.2 peft0.9.0 accelerate0.27.2 datasets2.18.0 trl0.7.11逻辑说明先装 torch 再装 transformers是因为 pip 解析依赖时如果先装 transformers可能会拉一个和 CUDA 不匹配的 torch 版本。参数上python3.10是经验值3.11 在部分bitsandbytes版本上还有坑torch2.1.2配cu121是当前比较稳的组合。装完用下面这段验证import torch, transformers, peft print(torch.__version__, torch.cuda.is_available()) print(transformers.__version__, peft.__version__)如果cuda.is_available()返回 False先别急着往下走检查驱动和 CUDA 版本是否匹配这一步不解决后面全是白费。2.3 数据格式train_data 和 val_data 到底该长什么样train_data和val_data这两个参数在配置里经常被写成路径但路径指向的文件格式决定了你能不能跑通。常见做法是用 JSONL每行一个样本字段名要和训练脚本里的text_field对应。比如做指令微调{instruction: 把下面这句话翻译成英文, input: 今天天气不错, output: The weather is nice today.} {instruction: 解释什么是 LoRA, input: , output: LoRA 是一种低秩适配方法通过冻结原权重并训练低秩矩阵来降低微调成本。}如果用的是SFTTrainer它会按dataset_text_field指定的字段取文本所以要么把 instruction/input/output 拼成一个字段要么在DataCollator里自己拼。我一般直接预处理成单字段from datasets import load_dataset def format_sample(ex): if ex[input]: return {text: f### 指令\n{ex[instruction]}\n### 输入\n{ex[input]}\n### 输出\n{ex[output]}} return {text: f### 指令\n{ex[instruction]}\n### 输出\n{ex[output]}} ds load_dataset(json, data_files{train: train.jsonl, val: val.jsonl}) ds ds.map(format_sample)参数说明data_files用字典区分 train 和 val这样val_data就有来源了map里的函数负责把多字段拼成单字段。注意 JSONL 里不要有空行空行会让load_dataset报解析错误这是最常见的翻车点之一。3. 参数配置base_model、output_dir 和 LoRA 超参怎么定3.1 base_model 填本地路径还是模型名base_model 这个热搜词说明很多人不知道这里填什么。两种写法都行填 HuggingFace 模型名如Qwen/Qwen2-1.5B会联网拉取填本地路径如/data/models/Qwen2-1.5B则直接读本地。生产环境我建议先git clone或snapshot_download到本地再填绝对路径避免训练中途网络抖动导致加载失败。from transformers import AutoModelForCausalLM, AutoTokenizer model_path /data/models/Qwen2-1.5B # 本地路径也可以是 Qwen/Qwen2-1.5B tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypeauto, device_mapauto, trust_remote_codeTrue, )参数说明torch_dtypeauto会按权重文件里的 dtype 自动选省显存device_mapauto让 accelerate 自动分配多卡trust_remote_codeTrue对 Qwen 这类带自定义代码的模型是必须的不加会报找不到类。3.2 LoraConfig 里 r、alpha、dropout、target_modules 怎么设这是 LoRA 参数配置里最核心的一段。r是低秩矩阵的秩alpha是缩放系数实际缩放是alpha / r。经验上参数常用值说明r8 / 16 / 32任务越复杂越大1.5B 模型 8~16 够用lora_alpha16 / 32一般设为 r 的 2 倍lora_dropout0.05 / 0.1数据少时调大防过拟合target_modulesq_proj,k_proj,v_proj,o_proj注意力四件套也可加 gate_proj 等 MLP 层biasnone一般不动 biasfrom peft import LoraConfig, get_peft_model lora_config LoraConfig( r16, lora_alpha32, lora_dropout0.05, target_modules[q_proj, k_proj, v_proj, o_proj], biasnone, task_typeCAUSAL_LM, ) model get_peft_model(model, lora_config) model.print_trainable_parameters()print_trainable_parameters()会打印可训练参数占比正常在 0.1%~1% 之间。如果占比过高检查target_modules是不是写宽了如果为 0说明目标层名没匹配上不同模型的层名不一样Qwen 用q_projLLaMA 也是但有些模型用query要用model.named_modules()先看一眼。3.3 output_dir 与训练超参别让 checkpoint 撑爆磁盘output_dir是适配器和 checkpoint 的落盘位置。很多人设了output_dir但没管save_steps和save_total_limit结果训练到一半磁盘满了。我一般这样配from transformers import TrainingArguments training_args TrainingArguments( output_dir/data/output/lora_qwen, per_device_train_batch_size2, gradient_accumulation_steps8, learning_rate2e-4, num_train_epochs3, logging_steps10, save_steps200, save_total_limit3, evaluation_strategysteps, eval_steps200, fp16True, report_tonone, )参数说明per_device_train_batch_size2配gradient_accumulation_steps8等效 batch size 16显存不够就降前者升后者learning_rate2e-4是 LoRA 的常用起点比全量微调高一个量级save_total_limit3只保留最近 3 个 checkpoint这是防磁盘爆的关键fp16True在支持 BF16 的卡上可以换成bf16True更稳。4. 训练与验证把 lora 微调代码跑通并确认没白跑4.1 用 SFTTrainer 跑通最小训练循环把前面的模型、数据、配置拼起来最小可运行脚本大概是这样from trl import SFTTrainer trainer SFTTrainer( modelmodel, argstraining_args, train_datasetds[train], eval_datasetds[val], tokenizertokenizer, dataset_text_fieldtext, max_seq_length512, peft_configlora_config, ) trainer.train() trainer.model.save_pretrained(/data/output/lora_qwen/final) tokenizer.save_pretrained(/data/output/lora_qwen/final)逻辑说明SFTTrainer会自动处理 padding、label 对齐和 LoRA 注入peft_config传进去就不用自己调get_peft_model。max_seq_length512按你的数据长度调太长显存涨得快。训练日志里重点看loss是否稳定下降、eval_loss是否跟着降如果 train loss 降但 eval loss 涨就是过拟合回去调lora_dropout或减 epoch。4.2 加载适配器做推理验证训练完不能只看 loss要实际生成几条看效果from peft import PeftModel base AutoModelForCausalLM.from_pretrained(model_path, torch_dtypeauto, device_mapauto) model PeftModel.from_pretrained(base, /data/output/lora_qwen/final) model.eval() prompt ### 指令\n解释什么是 LoRA\n### 输出\n inputs tokenizer(prompt, return_tensorspt).to(model.device) out model.generate(**inputs, max_new_tokens128, do_sampleFalse) print(tokenizer.decode(out[0], skip_special_tokensTrue))参数说明do_sampleFalse用贪心解码方便对比不同 checkpoint 的稳定性max_new_tokens控制生成长度。如果输出和微调前没区别先确认适配器路径对不对再确认target_modules是否真的命中了层。4.3 合并权重导出方便后续部署适配器单独存体积小但部署时多一次加载。要合并成完整权重merged model.merge_and_unload() merged.save_pretrained(/data/output/lora_qwen/merged)merge_and_unload会把B A * (alpha/r)加回原权重并卸载 LoRA 层导出的就是普通模型可以直接用 vLLM 或 transformers 加载。注意合并要在 CPU 或单卡上做多卡device_mapauto状态下合并可能报错。5. 避坑与排查minimaxh3 加速 lora 爆显存这类问题怎么定位5.1 显存爆了但 nvidia-smi 显示还有余量现象训练报 OOM但nvidia-smi看显存还剩不少。原因通常是 PyTorch 的缓存分配器碎片化或者max_seq_length设太大导致单样本激活值暴涨。解决先降per_device_train_batch_size到 1再降max_seq_length同时开gradient_checkpointingTrue。如果还不行用bitsandbytes做 4bit 量化加载from transformers import BitsAndBytesConfig bnb BitsAndBytesConfig(load_in_4bitTrue, bnb_4bit_compute_dtypebfloat16) model AutoModelForCausalLM.from_pretrained(model_path, quantization_configbnb, device_mapauto)5.2 loss 一直是 0 或者不下降现象训练几十步 loss 纹丝不动。原因多半是标签没对齐或者dataset_text_field指到了空字段。解决先打印一条ds[train][0]看text字段有没有内容再检查 tokenizer 的pad_token是否设置很多模型默认没有 pad token要手动tokenizer.pad_token tokenizer.eos_token。5.3 保存的适配器加载后效果和训练时不一致现象训练时 eval 正常重新加载适配器推理却变差。原因通常是保存时只存了适配器但没存 tokenizer或者加载时target_modules和训练时不一致。解决保存时tokenizer.save_pretrained一起存加载时用同一个LoraConfig或者直接读adapter_config.json里的配置。5.4 多卡训练时只有一张卡在跑现象device_mapauto配Trainer后 GPU 利用率不均。原因是Trainer默认用 DataParallel 而不是 DistributedDataParallel。解决用accelerate launch启动或者在TrainingArguments里不要手动设device_map让 accelerate 接管。5.5 中文数据微调后输出夹杂英文现象微调后模型回答中英混杂。原因是基座模型本身中文能力弱或者训练数据里中英比例失衡。解决换中文能力更强的基座或者在数据里增加纯中文样本比例同时把learning_rate稍微调低避免把原模型的语言能力冲掉。6. 进阶技巧用 adapter 热插拔做多任务切换跑通单任务后真正省事的是把多个 LoRA adapter 挂到同一个基座上做热插拔。比如你有一个客服 adapter、一个翻译 adapter推理时按请求切换不用加载多份基座权重。peft支持这种用法from peft import PeftModel base AutoModelForCausalLM.from_pretrained(model_path, torch_dtypeauto, device_mapauto) model PeftModel.from_pretrained(base, /data/output/lora_qa, adapter_nameqa) model.load_adapter(/data/output/lora_trans, adapter_nametrans) # 切换任务 model.set_adapter(trans)参数说明adapter_name是自定义标识load_adapter可以挂多个set_adapter切换。注意每个 adapter 的target_modules要一致否则切换时会报层不匹配。显存上adapter 本身很小多挂几个对显存影响有限但基座只加载一份这是它比多模型部署省资源的地方。验证 adapter 是否真的生效我习惯做一个对照实验同一 prompt 分别用set_adapter(qa)和set_adapter(trans)生成看输出风格是否明显不同。如果一样多半是 adapter 没挂上或者被覆盖了。最后说个我自己的习惯每次跑新配置前先用 100 条数据跑 50 步确认 loss 在降、显存没爆、保存加载都正常再上全量。这个「小步快跑」的习惯帮我省过很多次通宵重跑的时间。LoRA 微调这条链路坑大多不在原理而在版本、路径和显存这些细节上把细节抠住剩下的就是调参的耐心活了。希望帮到你。本文还有配套的精品资源点击获取