本地部署大模型，尤其是从微调环境导出到推理框架，整个过程堪称一场技术历劫。下面这些常见陷阱，每一位动手实践者大概率都会遇到——踩一个少一个，提前了解能大幅提升大模型本地化部署的成功率。先说说依赖环境的核心问题。
第一阶段：环境与依赖构建
1. 问题：核心依赖库版本冲突（依赖地狱）
现象：运行导出脚本时，报错 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 极不稳定，导致握手失败，阻碍大模型权重获取。
解决：配置国内镜像环境变量。在终端执行：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路径")，避免手动配置 LoraConfig 导致的参数冲突。
第三阶段：合并与导出的内存问题
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 强制重置密码，恢复 sudo 权限。
9. 问题：缺失编译环境
现象：编译 llama.cpp 时报错 cmake: command not found。
原因：纯净的 Ubuntu 镜像默认不包含开发工具链，需要手动安装编译依赖。
解决：手动补全地基：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 格式的选择题，甚至出现胡编乱造的现象。
原因：练过头了（过拟合）。Epoch 过高：15 个 Epoch 对于 32B 模型来说是毁灭性的，导致模型丧失了通用对话能力，死记硬背了训练数据的格式。模式坍缩：模型被训练数据中的问答模式带偏，触发了预训练记忆中的题库模式（如医疗题），产生幻觉。
解决：减量提质。大幅降低 Epoch（3-5 次）；清洗数据，去除选择题格式，改用纯对话格式；引入通用数据集（Alpaca）进行正则化训练，防止模型变傻，保持微调后的大模型泛化能力。
回顾整个微调模型本地化部署过程，其实是在做三件事：
1. 在不兼容的土壤上嫁接大树（Windows vs Linux）。
2. 用有限的容器装载无限的海洋（64G 内存 vs 32B 矩阵）。
3. 试图用一把锤子雕刻精密的神经网络（15 Epoch 暴力微调）。
大模型本地化部署的本质是工程妥协的艺术。所有的技术手段（WSL2、Swap、量化、LoRA），都是为了在这三组矛盾中，找到那个勉强可行的平衡点。掌握这些常见问题的解决方案，能让你在部署道路上少走弯路，更快跑通整个流程。
