微调模型本地部署Debug总结

第一阶段：环境与依赖构建

1. 问题：核心依赖库版本冲突 (Dependency Hell)

• 现象： 在运行导出脚本时，报错 AttributeError: module 'torch._inductor' has no attribute 'config'，或者提示 transformers、peft 版本不兼容。
• 原因： LLaMA-Factory 需要极其稳定的旧版本依赖（如 transformers<4.38），而 Unsloth 为了极致加速，强依赖最新版的 Torch 和 Triton。在一个 Conda 环境中强行安装两者，导致底层代码相互覆盖，环境逻辑崩塌。
• 解决： 实施环境隔离。 -- 保留 qwen_train 环境专门用于 LLaMA-Factory 训练。 -- 新建 qwen_export_env 环境，只安装 Unsloth 及其依赖，专门用于导出。

2. 问题：Pip 安装包的“幽灵版本”

• 现象： 在安装 Unsloth 时，Pip 报错 Could not find a version that satisfies the requirement unsloth_zoo>=2026.2.1。
• 原因： 源码与镜像源的时间差。Unsloth 的 GitHub 源码刚刚更新了依赖版本号，但 PyPI 官方仓库（以及国内的清华/阿里镜像源）还没有同步这个最新的包。直接用 git+https 安装会因为找不到配套依赖而失败。
• 解决： 放弃源码安装，改用 pip install unsloth（不指定 [colab-new] 等激进标签），强制安装当前镜像源中已存在的稳定发行版。

第二阶段：网络与资源调度

3. 问题：WSL2 网络连接不可达

• 现象： 脚本运行时频繁报错 MaxRetryError，提示 Network is unreachable 或 Connection refused，无法下载 Hugging Face 的模型配置文件。
• 原因： 网络屏障。WSL2 的网络经过了一层虚拟 NAT，且国内环境直连 Hugging Face 极不稳定，导致握手失败。
• 解决： 配置国内镜像环境变量。 在终端执行：Bash export HF_ENDPOINT=https://hf-mirror.com 强制将流量导向国内镜像站。

4. 问题：LoRA 挂载脚本参数错误

• 现象： 运行 local_export.py 时报错 TypeError: LoraConfig.__init__() got an unexpected keyword argument 'model_name'。
• 原因： 函数误用。在推理/导出模式下，不应该使用训练时的 get_peft_model 函数来初始化，而应该利用 Unsloth 的特性，直接在 from_pretrained 中传入 LoRA 路径，让它自动识别并挂载。
• 解决： 修改脚本，直接使用 FastLanguageModel.from_pretrained(model_name = "LoRA路径")。

第三阶段：合并与导出的内存问题

5. 问题：合并时的二次下载

• 现象： 本地明明已经有了 4-bit 的底座模型，但运行导出脚本时，系统又开始下载 60GB 的文件。
• 原因： 精度保真机制。Unsloth 的 save_pretrained_gguf 默认为了保证量化质量，会自动拉取 16-bit (BF16) 的全精度原版模型进行合并，而不是在有损的 4-bit 模型上修补。
• 解决： 接受这个机制（为了精度），预留充足的硬盘空间（100GB+），利用镜像站下载全量权重。

6. 问题：全量合并时的“假死”状态

• 现象： 进度条卡在 7%（1/14 shards）长达十几分钟不动，CPU 占用极低，看似程序崩溃。
• 原因： 跨系统 I/O 瓶颈。32B 模型全量合并需要处理 65GB 数据，超过了物理内存（50G）。系统被迫频繁使用 Swap（虚拟内存），且数据是在 WSL2（Linux）和 E盘（Windows）之间跨文件系统搬运，导致 I/O 极其缓慢。
• 解决：只要没报错退出，依靠我们配置的 64GB Swap，系统最终能慢慢磨过去（耗时约 1.5 小时）。

7. 问题：导出脚本显存溢出 (OOM)

• 现象： 在合并完成后，尝试进行量化时报错 ValueError: Some modules are dispatched on the CPU or the disk...。
• 原因： 显存不足。Unsloth 的 Python 脚本试图将合并好的 65GB 全精度模型加载到显存（24GB）中进行处理，导致显存瞬间爆满。
• 解决：放弃 Python 脚本量化，转而使用 C++ 原生工具 llama.cpp。它能直接利用系统内存（RAM）进行量化，绕过显卡限制。

第四阶段：底层编译与工具链

8. 问题：Sudo 密码遗忘

• 现象： Unsloth 试图自动安装编译工具时提示输入 [sudo] password，但因为 WSL2 长期免密登录，不记得密码了。
• 原因： WSL2 的默认用户配置机制导致。
• 解决： 在 Windows PowerShell 中使用 wsl -u root 登入 root 账户，使用 passwd magicyuan 强制重置密码。

9. 问题：缺失编译环境

• 现象： 编译 llama.cpp 时报错 cmake: command not found。
• 原因： 纯净的 Ubuntu 镜像默认不包含开发工具链。
• 解决： 手动补全地基： Bash sudo apt update sudo apt install cmake build-essential -y

第五阶段：模型效果与微调策略

10. 问题：Ollama 命令找不到

• 现象： 在 WSL2 终端执行 ollama create 报错 Command 'ollama' not found。
• 原因： 宿主隔离。Ollama 安装在 Windows 上，WSL2 内部无法直接调用 Windows 的环境变量/程序。
• 解决： 回到 Windows PowerShell 执行 Ollama 相关指令。

11. 问题：模型过拟合与幻觉

• 现象： 最终导出的 32B 模型在回答规范问题时，开始背诵医疗考试题，或者输出 A/B/C/D 格式的选择题，甚至在那胡说八道。
• 原因： 练过头了（Overfitting）。 -- Epoch 过高： 15 个 Epoch 对于 32B 模型来说是毁灭性的，导致模型丧失了通用对话能力，死记硬背了训练数据的格式。 -- 模式坍缩： 模型被训练数据中的问答模式带偏，触发了预训练记忆中的题库模式（如医疗题）。
• 解决： 减量提质。 -- 大幅降低 Epoch（3-5 次）。 -- 清洗数据，去除选择题格式，改用纯对话。引入通用数据集（Alpaca）进行正则化训练，防止变傻。

回顾整个微调模型本地化部署过程，我们其实是在做三件事：

1. 在不兼容的土壤上嫁接大树（Windows vs Linux）。

2. 用有限的容器装载无限的海洋（64G 内存 vs 32B 矩阵）。

3. 试图用一把锤子雕刻精密的神经网络（15 Epoch 暴力微调）。

本地化部署的本质是工程妥协的艺术。

我们所有的技术手段（WSL2、Swap、量化、LoRA），都是为了在这三组矛盾中，找到那个勉强可行的平衡点。