大模型云端微调Debug总结

一、 存储架构与磁盘治理 (Storage & Disk)

1. 问题：系统盘崩溃

• 现象：训练或下载中途报错 OSError: [Errno 28] No space left on device。
• 原因：AutoDL 系统盘仅 30GB，默认缓存路径 ~/.cache 在系统盘。32B 模型权重（20GB）加环境（8GB）瞬间顶破天花板。
• 解决： -- mkdir 在数据盘（/root/autodl-tmp），然后建立软链接 ln -s 把系统盘的缓存目录指向数据盘。 -- 修改 YAML 里的 output_dir 为数据盘绝对路径。

2. 问题：数据盘容量耗尽

• 现象：200GB 数据盘迅速被占满，且数值持续增加。
• 原因：32B 模型巨大，多次断点续传产生了大量 *.incomplete 垃圾文件；且训练时 save_steps 过小，每个 Checkpoint 包含巨型优化器状态，积少成多。
• 解决： -- 手动清理：find /root/autodl-tmp/hf_cache -name "*.incomplete" -delete。 -- 配方限流：在 YAML 中加入 save_total_limit: 2，强制滚动删除旧存档。

3. 问题：持久化网盘权限受阻

• 现象：向 /autodl-fs 写入或创建目录报 Operation not permitted。
• 原因：/autodl-fs 是公用挂载点，根目录无写权限，且不建议在网络挂载盘上运行高频 I/O 训练任务。
• 解决：回归本地高速 SSD 数据盘 /root/autodl-tmp。

二、 环境复刻与版本冲突 (Dependencies & Logic)

4. 问题：基础库损坏/缺失导致导入失败

• 现象：ImportError: cannot import name 'PreTrainedModel' from 'transformers'。
• 原因：云端安装过程中网络抖动，导致 Transformers 库文件下载不全或损坏。
• 解决：执行强制重装：pip install transformers --force-reinstall --no-deps。

5. 问题：版本冲突导致的接口消失

• 现象：ImportError: cannot import name 'Int4WeightOnlyConfig' from 'torchao'。
• 原因：手动安装了旧版 torchao，而新版 transformers 检测到该库存在，试图调用新接口导致冲突。
• 解决：做减法，卸载不必要的 torchao，让框架回归 Bitsandbytes 默认逻辑。

6. 问题：环境危机

• 现象：ImportError: Please install Unsloth。
• 原因：多次降级/升级操作导致 Python 的包索引（Metadata）混乱，unsloth_zoo 认不出已装好的 unsloth。
• 解决：pip install unsloth unsloth_zoo --force-reinstall --no-deps。

三、 显存与计算资源攻坚 (GPU & VRAM)

7. 问题：32B 模型导致的 OOM (显存溢出)

• 现象：模型加载至 71% 时报 torch.OutOfMemoryError。
• 原因： -- 精度陷阱：YAML 漏填 quantization_bit: 4，导致 48G 显存试图全精度加载 64G 的模型。 -- Rank 过载：32B 层数极多，lora_rank: 64 带来的额外参数量在初始化时瞬时撑爆显存。
• 解决： -- YAML 显式锁定 quantization_bit: 4。 -- 减重：降 Rank 至 16，缩短 cutoff_len 至 1024。

8. 问题：显存碎片堆积

• 现象：明明改小了参数，点火还是报 OOM。
• 原因：之前的崩溃进程没有释放 GPU 句柄，显存被垃圾数据占据。
• 解决：暴力清理：pkill -9 python 或 wsl --shutdown。

四、 模型导出与撤退行动 (Export & GGUF)

9. 问题：导出时的数据不足

• 现象：ValueError: Quantization dataset is necessary for exporting.。
• 原因：转换 GGUF 时需要数据进行权重分布校准，配置文件未指定。
• 解决：在导出 YAML 中补齐 export_quantization_dataset: clean_room_expert。

10. 问题：Unsloth 自动化导出时网络不佳

• 现象：转换 GGUF 时报 ConnectTimeoutError 指向 GitHub。
• 原因：Unsloth 源码强行使用 requests.get 去 GitHub 拉取最新的 convert_hf_to_gguf.py，无法在离线环境下运行。
• 解决： -- 手动替代法：利用镜像拉取 llama.cpp，手动执行 cmake 编译。 -- 脚本补丁法：编写 Python 补丁函数 dummy_download 拦截联网请求。

11. 问题：内存（RAM）太小导致进程被杀

• 现象：32B 合并 16-bit 阶段，终端显示 Killed 但无具体报错。
• 原因：32B 模型合并需 60GB+ RAM，72GB 的物理内存扣除系统占用后已触底，被 Linux 内核 OOM Killer 强杀。
• 解决：降维导出。跳过 16-bit 环节，直接执行 save_pretrained_merged(..., save_method="merged_4bit")，内存占用瞬间降至 20GB。