模型合并与导出：Unsloth保存适配器完整流程

在使用Unsloth完成LoRA微调后，最关键的工程落地环节不是训练本身，而是如何把训练好的适配器（adapter）与原始基座模型正确合并、导出为可独立部署的完整模型。很多开发者卡在这一步：训练成功了，但导出的模型无法加载、推理报错、显存占用异常，甚至生成结果完全失真。本文将带你从零走完Unsloth模型合并与导出的全流程——不讲原理堆砌，不套用模板，只聚焦你真正需要的、能立刻复现的每一步操作、每个易错点、每处隐藏坑。

这不是一篇“理论上可行”的教程，而是一份基于真实Qwen2-7B医学微调项目（medical-o1-reasoning-SFT数据集）验证过的、带完整路径和错误反馈的实操指南。你将看到：为什么model.save_pretrained()不能直接用、什么时候必须调用merge_and_unload()、如何验证合并后模型是否真正生效、以及导出模型在Streamlit中加载失败时的5种典型原因与对应解法。

1. 理解Unsloth的模型保存机制：LoRA ≠ 完整模型

1.1 Unsloth默认保存的是什么？

当你执行以下代码时：

model.save_pretrained("./Medical-COT-Qwen-7B")

Unsloth实际保存的并非一个可直接推理的完整模型，而是一个LoRA适配器权重 + 基座模型引用的混合结构。它包含：

• adapter_model.bin：仅含LoRA层（如q_proj.lora_A、v_proj.lora_B等）的增量参数
• config.json：记录了该模型是PEFT格式，peft_type: "LORA"，base_model_name_or_path: "/opt/chenrui/qwq32b/base_model/qwen2-7b"
• pytorch_model.bin：为空或不存在（因为基座权重未被复制）

这意味着：这个目录不能脱离原始基座模型路径独立运行。一旦你把./Medical-COT-Qwen-7B拷贝到另一台机器，或删除了/opt/chenrui/qwq32b/base_model/qwen2-7b，加载就会报错：

OSError: Can't load config for '/opt/chenrui/chatdoctor/Medical-COT-Qwen-7B'. Make sure that: - '/opt/chenrui/chatdoctor/Medical-COT-Qwen-7B' is a correct model identifier - or '/opt/chenrui/chatdoctor/Medical-COT-Qwen-7B' is the correct path to a directory containing a config.json file

更隐蔽的问题是：即使路径存在，FastLanguageModel.from_pretrained()在加载时仍会尝试从原始路径读取基座权重，若权限不足或网络不通，同样失败。

1.2 正确做法：先合并，再保存

Unsloth提供了明确的合并接口——merge_and_unload()。它的作用是：将LoRA权重永久注入基座模型的对应层，并移除LoRA结构，返回一个标准的Hugging FacePreTrainedModel对象。

关键特性：

• 合并后模型不再依赖PEFT库，纯transformers即可加载
• 所有参数变为原生nn.Linear层，无额外wrapper
• 显存占用与原始基座模型一致（无LoRA overhead）
• 可直接用于pipeline、TextGenerationPipeline等标准工具

注意：merge_and_unload()是不可逆操作。执行后，原LoRA适配器将被销毁。务必在确认训练效果达标后再执行。

2. 完整合并与导出流程：6步精准执行

以下代码基于你已完成的训练脚本（trainer.train()之后），严格按顺序执行。所有路径、参数均来自你提供的实际环境。

2.1 步骤1：确保模型处于训练模式并加载最新权重

# 在trainer.train()之后立即执行 # 确保LoRA权重已更新到最新状态 model.train() # 切回训练模式（trainer.train()结束时可能为eval） model = model.merge_and_unload() # 关键！合并LoRA到基座

验证点：执行后控制台应输出类似信息
Merging LoRA weights into base model... Done.
若卡住或报错，请检查GPU显存是否充足（合并需临时额外显存）。

2.2 步骤2：保存合并后的完整模型

# 创建目标目录（确保父目录存在） import os new_model_local = "./Medical-COT-Qwen-7B-merged" os.makedirs(new_model_local, exist_ok=True) # 保存为标准Hugging Face格式 model.save_pretrained( new_model_local, safe_serialization=True, # 推荐：使用safetensors格式，更安全且加载快 ) tokenizer.save_pretrained(new_model_local) # 同时保存分词器

生成的目录结构应为：

Medical-COT-Qwen-7B-merged/ ├── config.json ├── pytorch_model-00001-of-00002.bin # 或 .safetensors ├── pytorch_model-00002-of-00002.bin ├── tokenizer_config.json ├── tokenizer.model └── special_tokens_map.json

❌ 常见错误：忘记保存tokenizer。没有分词器，模型加载后无法处理输入文本。

2.3 步骤3：本地加载验证（脱离训练环境）

新建一个干净Python脚本（如verify_merge.py），不导入unsloth，仅用transformers验证：

from transformers import AutoModelForCausalLM, AutoTokenizer import torch # 仅用transformers加载（证明已脱离Unsloth依赖） model_path = "./Medical-COT-Qwen-7B-merged" model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.bfloat16, # 与训练时dtype一致 device_map="auto", # 自动分配到GPU ) tokenizer = AutoTokenizer.from_pretrained(model_path) # 构造一个极简prompt测试 prompt = "### Question:\n一位61岁的女性，长期存在咳嗽或打喷嚏时不自主尿失禁。请分析最可能的诊断。\n\n### Response:\n<think>" inputs = tokenizer(prompt, return_tensors="pt").to(model.device) # 生成10个token快速验证 outputs = model.generate( **inputs, max_new_tokens=10, do_sample=False, temperature=0.1, ) response = tokenizer.decode(outputs[0], skip_special_tokens=True) print(" 合并模型加载成功，生成片段：", response[-50:])

成功标志：无ImportError、无PEFT相关报错、能正常输出文本。
❌ 失败信号：ValueError: Expected model name to be a string或KeyError: 'q_proj'—— 说明合并未生效或保存路径错误。

2.4 步骤4：量化导出（可选但强烈推荐）

你的训练使用了load_in_4bit=True，但合并后模型是全精度（bfloat16）。若需部署到资源受限环境，可对合并模型进行4-bit量化导出：

from transformers import BitsAndBytesConfig from peft import prepare_model_for_kbit_training # 注意：此处需重新加载未量化的合并模型 model = AutoModelForCausalLM.from_pretrained( "./Medical-COT-Qwen-7B-merged", torch_dtype=torch.bfloat16, ) # 配置4-bit量化 bnb_config = BitsAndBytesConfig( load_in_4bit=True, bnb_4bit_quant_type="nf4", bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True, ) # 应用量化 model_4bit = AutoModelForCausalLM.from_pretrained( "./Medical-COT-Qwen-7B-merged", quantization_config=bnb_config, device_map="auto", ) # 保存量化模型（注意：此模型仍需bitsandbytes库） model_4bit.save_pretrained("./Medical-COT-Qwen-7B-4bit") tokenizer.save_pretrained("./Medical-COT-Qwen-7B-4bit")

提示：4-bit模型体积约为原模型的25%，但首次加载稍慢（需解压）。生产环境建议用safetensors+4-bit组合。

2.5 步骤5：Hugging Face Hub上传（可选）

若需团队共享或版本管理，可一键推送到HF Hub：

from huggingface_hub import login login(token="your_hf_token") # 替换为你的token model.push_to_hub("your-username/Medical-COT-Qwen-7B-merged") tokenizer.push_to_hub("your-username/Medical-COT-Qwen-7B-merged")

上传后，他人可直接用：

model = AutoModelForCausalLM.from_pretrained("your-username/Medical-COT-Qwen-7B-merged")

2.6 步骤6：Streamlit部署前的终极校验

你提供的Streamlit脚本中，加载路径为"/opt/chenrui/chatdoctor/Medical-COT-Qwen-7B"。这必须指向合并后的模型目录，而非训练输出的LoRA目录。

修改load_model_and_tokenizer()函数中的路径：

# ❌ 错误：加载LoRA目录（会失败） # model_path = "/opt/chenrui/chatdoctor/Medical-COT-Qwen-7B" # 正确：加载合并后目录 model_path = "/opt/chenrui/chatdoctor/Medical-COT-Qwen-7B-merged" # 注意后缀

并在Streamlit启动前，手动运行一次验证脚本，确保该路径下存在pytorch_model*.bin和config.json。

3. 5大高频问题与解决方案（来自真实排障记录）

3.1 问题：AttributeError: 'PeftModel' object has no attribute 'save_pretrained'

原因：在调用merge_and_unload()前，直接对PeftModel对象执行save_pretrained()。
解法：

# 错误写法 model.save_pretrained("./output") # model仍是PeftModel类型 # 正确写法 model = model.merge_and_unload() # 先转为PreTrainedModel model.save_pretrained("./output") # 再保存

3.2 问题：合并后模型生成结果与训练时完全不一致

原因：合并前未将模型设为eval()模式，或未关闭dropout。
解法：在merge_and_unload()前强制设置：

model.eval() # 关闭dropout/batchnorm for param in model.parameters(): param.requires_grad = False # 确保无梯度计算干扰 model = model.merge_and_unload()

3.3 问题：OSError: Unable to load weights from pytorch checkpoint

原因：save_pretrained()时未指定safe_serialization=True，且模型含特殊层（如Qwen的RMSNorm）。
解法：始终启用safetensors：

model.save_pretrained("./output", safe_serialization=True) # 并确保已安装：pip install safetensors

3.4 问题：Streamlit中FastLanguageModel.from_pretrained()报KeyError: 'model_type'

原因：你试图用Unsloth的加载器加载一个非Unsloth格式的模型（即已合并的模型）。FastLanguageModel专为LoRA/QLoRA设计，不兼容标准模型。
解法：在Streamlit中改用原生transformers加载：

# 替换原Streamlit中的加载逻辑 # from unsloth import FastLanguageModel # model, tokenizer = FastLanguageModel.from_pretrained(...) # 改为： from transformers import AutoModelForCausalLM, AutoTokenizer model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.bfloat16, device_map="auto", ) tokenizer = AutoTokenizer.from_pretrained(model_path)

3.5 问题：合并后显存占用反而比训练时更高

原因：merge_and_unload()后未释放原LoRA模型变量，导致GPU内存泄漏。
解法：显式删除并清空缓存：

model = model.merge_and_unload() del model # 删除原变量 import gc gc.collect() # 触发垃圾回收 torch.cuda.empty_cache() # 清空CUDA缓存

4. 工程化建议：构建可复现的导出流水线

避免每次手动执行6步。将导出封装为可复用函数：

def export_merged_model( peft_model, # 训练完成的PeftModel tokenizer, # 对应分词器 output_dir, # 输出路径 quantize_4bit=False, # 是否导出4-bit push_to_hub=False, # 是否推送到HF repo_id=None, # HF仓库ID ): """ 一键导出Unsloth训练模型为生产就绪格式 """ import os os.makedirs(output_dir, exist_ok=True) # 步骤1：合并 print("🔧 正在合并LoRA权重...") merged_model = peft_model.merge_and_unload() # 步骤2：保存 print("💾 正在保存合并模型...") merged_model.save_pretrained( output_dir, safe_serialization=True ) tokenizer.save_pretrained(output_dir) # 步骤3：量化（可选） if quantize_4bit: print("⚡ 正在导出4-bit量化模型...") from transformers import BitsAndBytesConfig bnb_config = BitsAndBytesConfig(load_in_4bit=True) quant_model = AutoModelForCausalLM.from_pretrained( output_dir, quantization_config=bnb_config, device_map="auto" ) quant_model.save_pretrained(f"{output_dir}-4bit") tokenizer.save_pretrained(f"{output_dir}-4bit") # 步骤4：推送（可选） if push_to_hub and repo_id: print(" 正在推送到Hugging Face...") merged_model.push_to_hub(repo_id) tokenizer.push_to_hub(repo_id) print(f" 导出完成！模型位于：{output_dir}") return output_dir # 使用示例 export_merged_model( model, # 训练完成的model tokenizer, output_dir="./Medical-COT-Qwen-7B-merged", quantize_4bit=True, push_to_hub=False, )

5. 总结：模型导出不是终点，而是部署的起点

你已经走完了Unsloth微调最关键的收尾一环：从训练完成的LoRA适配器，到一个可独立部署、可版本管理、可跨平台运行的标准Hugging Face模型。这个过程看似简单，却隐藏着至少5个足以让项目停滞的陷阱——从路径引用错误、加载器误用，到量化配置冲突、显存泄漏。

记住三个核心原则：

• 合并先行：merge_and_unload()是必经之路，不要跳过；
• 验证闭环：每次导出后，必须用transformers原生API加载验证，而非仅信unsloth文档；
• 路径洁癖：Streamlit、API服务、Docker镜像中所有模型路径，必须指向-merged目录，而非训练输出目录。

现在，你可以放心地将./Medical-COT-Qwen-7B-merged交给运维部署，或集成进任何支持Hugging Face模型的系统。下一步，就是用这个模型去解决真实的临床推理问题——而那，才是真正价值的开始。

--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。