大模型本地微调Debug总结

一、 基础设施与底层驱动 (Infrastructure)

1. 问题：WSL 系统错位

• 现象：输入 wsl 后报 conda: command not found，且提示符为 # (root) 目录在 Windows 路径下。
• 原因：Windows 默认启动了 Docker-Desktop 镜像，而非配置好的 Ubuntu。
• 解决：强制指定分发版和用户：wsl -d Ubuntu-22.04 -u magicyuan；并执行 wsl --set-default 夺回默认权。

2. 问题：底层二进制库冲突 (ABI Mismatch)

• 现象：ImportError: undefined symbol: __nvJitLinkAddData_12_5 或 RuntimeError: operator torchvision::nms does not exist。
• 原因：Pip 与 Conda 混用，导致 GPU 版 PyTorch 链接到了 CPU 版的底层动态库（如 nvidia-cusparse）。
• 解决：彻底重建环境，强制指定官方 +cu121 源，并在安装上层框架时严禁安装依赖（--no-deps）。

二、 核心算法框架安装 (Unsloth & Torch)

3. 问题：PyTorch 内部属性缺失

• 现象：AttributeError: module 'torch._inductor' has no attribute 'config'。
• 原因：PyTorch 2.4.0 某些 Build 版本未显式暴露编译器内部属性，Unsloth Zoo 无法扫描源代码。
• 解决：在脚本最顶端加入补丁，手动向 torch._inductor 注入 config 属性。

4. 问题：硬件精度不匹配

• 现象：TypeError: Model is in bfloat16 precision but you want to use float16。
• 原因：RTX 3090 显卡原生支持性能更好的 BF16，Unsloth 为了稳定性强制禁止在 3090 上使用 FP16。
• 解决：在训练参数中修改 fp16 = False, bf16 = True。

5. 问题：网络环境导致安装失败

• 现象：git clone 报错 curl 16 Error，wget 代理超时。
• 原因：GitHub 源码包过大，国内镜像代理不稳定。
• 解决：放弃克隆源码，改用国内 PyPI 镜像站安装发布版（pip install unsloth），或利用 Gitee 码云镜像。

三、 生产工具链集成 (LLaMA-Factory & WebUI)

6. 问题：Web 层级联依赖冲突

• 现象：TypeError: argument of type 'bool' is not iterable。
• 原因：最隐蔽的 Bug。最新版 Pydantic (2.9+) 生成的 JSON 格式包含布尔值，导致旧版 Gradio (4.x) 的客户端无法解析。
• 解决：同时锁定 FastAPI==0.112.2、Pydantic==2.8.2、Gradio==4.44.1。

7. 问题：Gradio 组件接口变更

• 现象：TypeError: Chatbot.__init__() got an unexpected keyword argument 'type'。
• 原因：Gradio 6.x 彻底移除了 4.x 的 type="messages" 参数，而 LLaMA-Factory 源码尚未适配最新版。
• 解决：强制将 Gradio 降级回 4.44.1 稳定版。

8. 问题：WSL 网络穿透失败

• 现象：WebUI 启动成功但浏览器无法访问，或报 localhost not accessible。
• 原因：WSL2 的 IP 映射机制导致其默认绑定的 127.0.0.1 无法穿透到宿主机 Windows。
• 解决：强制启动参数：export GRADIO_SERVER_NAME="0.0.0.0"。

四、 数据工程与训练逻辑 (Data & Training)

9. 问题：微调数据的“结构化污染”

• 现象：训练结果包含 confidence: 1.0, ner: [...] 等大量 JSON 标签。
• 原因：利用 AI 提炼 Q&A 时，AI 将思维链和中间抽取结构一并输出了。
• 解决：编写 clean_jsonl.py 专用清洗脚本，仅保留 instruction/input/output 三个纯净字段。

10. 问题：严重的“数值幻觉”

• 现象：问 4 级洁净度限值，模型回答 “3500” 或 “1,000,000”，而非真值 “1020”。
• 原因：底座模型惯性太强，且表格数据在微调样本中占比太低。
• 解决：靶向过采样（Data Flooding）。针对表格真值手动构造数据，并疯狂重复粘贴 20~50 遍，强行在训练权重中占据主导地位。

11. 问题：显存吃紧导致的 Loss 计算崩溃

• 现象：RuntimeError: No or negligible GPU memory available for fused cross entropy。
• 原因：LoRA Rank (秩) 设为 128 导致参数量暴增至 3.2 亿，瞬时 Batch 为 2 时吃光了最后一点呼吸空间。
• 解决：执行“降压操作”：Batch Size 设为 1，Gradient Accumulation 设为 8。

五、 自动化与脚本化 (Automation)

12. 问题：YAML 配置格式不兼容

• 现象：报 ValueError: Please provide model_name_or_path。
• 原因：WebUI 导出的 YAML 带有 top. 或 train. 前缀，CLI 命令行工具无法识别这种非扁平格式。
• 解决：手动重写纯净版 YAML 配置文件，删除所有 top. 等中间态前缀。

13. 问题：模型加载时的网络“反扑”

• 现象：启动聊天（Chat）模式时报 OSError: Failed to load tokenizer。
• 原因：即使本地有缓存，transformers 依然会联网检测 Tokenizer 模板是否有更新。
• 解决：脚本中加入 export HF_ENDPOINT=https://hf-mirror.com，或直接给模型地址填入 snaphosts 的绝对路径。

Debug的全过程，其本质是在一个快速进化的、版本不稳定的软件生态中，用有限的物理算力，去强行扭转一个庞大统计学系统的概率分布，使其产生出一种接近确定性的专业认知。

修环境，是在对抗软件熵。

调参数，是在对抗物理限值。

注数据，是在对抗统计惯性。