第八章：常见疑难杂症 (Troubleshooting) 与进阶技巧

欢迎来到 Llama-factory 旅程的最后一站。你已经掌握了从环境搭建到模型部署的全流程。然而，理论与实践之间总有一段充满挑战的距离。在真实的“炼丹”过程中，你可能会遇到各种令人沮丧的错误和不尽如人意的结果。本章的目的，就是为你提供一份详尽的、经过实战检验的“故障排除指南”，并为你展示 Llama-factory 更强大的进阶能力。我们将像一位经验丰富的工程师一样，系统性地分析和解决问题，让你在面对挑战时不再束手无策。

8.1 显存 OOM (Out of Memory) 终极排查

“CUDA out of memory” 是每个深度学习从业者都必须面对的“成年礼”。当你看到这个错误时，不要惊慌。这只是意味着你试图装入 GPU 的“东西”超过了它的物理容量。解决 OOM 的核心思想是“节流”——通过一系列参数调整，在不严重牺牲性能的前提下，降低训练过程中的显存峰值。

请严格按照以下优先级清单进行排查和调整，因为它们的效力是依次递减的。

优先级	参数 / 技术	操作指南与核心原理
1 (王牌)	QLoRA (量化训练)	动作: 如果你未使用 QLoRA，请立即切换。在“方法”选项卡选择 qlora，并确保“量化 bit 数”为 4。 原理: 这是最有效的降显存手段。它将基座模型的权重从 16-bit 压缩到 4-bit，直接将模型本身的显存占用降低 75%！对于 7B 模型，这意味着从约 14GB 降至约 4GB，为你省出了海量的空间来容纳激活值和梯度。这是让消费级显卡（如 12GB 的 RTX 3060）能够微调 7B 甚至 13B 模型的根本。
2 (核弹)	cutoff_len (截断长度)	动作: 显著降低 --cutoff_len 的值。例如，从 4096 降到 1024。 原理: Transformer 的注意力机制显存占用与序列长度 N 的平方 (N²) 成正比。这意味着 cutoff_len 减半，显存峰值会降低接近四分之三！在调整此参数前，请务必先分析你的数据集（如第二章所述），找到一个能覆盖 95% 样本长度的、尽可能小的值。这是解决 OOM 的第二大杀器。
3 (常规)	per_device_train_batch_size (批处理大小)	动作: 将 --per_device_train_batch_size 设为 1。 原理: Batch Size 决定了单次前向传播处理的样本数，它与梯度和激活值的显存占用成正比。将其降到 1 是你在这个参数上能做的极限，它将单次计算的显存占用降到最低。
4 (补偿)	gradient_accumulation_steps (梯度累积)	动作: 在降低 batch_size 后，增大 --gradient_accumulation_steps 的值，以维持“有效批处理大小” (effective_batch_size = batch_size * grad_accum * num_gpus) 不变。 原理: 这是典型的“时间换空间”策略。它确保了虽然你每次只处理一个样本，但模型的参数更新是基于多个样本的累积梯度，从而保证了训练的稳定性。这个操作不会增加显存占用，但会延长训练时间。
5 (加速器)	flash_attn (FlashAttention)	动作: 确保开启了 FlashAttention-2 (--flash_attn fa2)。 原理: FlashAttention 是一种优化的注意力算法，它避免了在 GPU HBM（高带宽内存）中实例化巨大的注意力矩阵，从而在长序列下能显著节省显存并大幅提升计算速度。如果你的 GPU 支持（Ampere 架构及更新），开启它对解决 OOM 和加速训练都有益处。
6 (终极)	DeepSpeed ZeRO + CPU Offload	动作: 当以上所有方法都无效时（通常只在进行超大模型的全量微调时发生），启用 DeepSpeed ZeRO-3 并配置 CPU Offload。 原理: 如第四章所述，ZeRO-3 会将模型参数、梯度和优化器状态全部分片，并可以进一步将它们卸载到 CPU 的主内存中。由于 CPU 内存通常远大于 GPU 显存（例如 64GB vs 24GB），这允许你训练远超单卡显存容量的模型，代价是需要频繁的 CPU-GPU 数据通信，会降低训练速度。

---

8.2 训练速度慢

解决了 OOM，下一个挑战就是效率。训练一个模型耗时数日甚至数周是不可接受的。提升训练速度的关键在于识别并消除瓶颈。

第一步：诊断瓶颈 - nvidia-smi

在训练开始后，打开一个新的终端，反复运行 watch -n 1 nvidia-smi 命令来实时监控 GPU 状态。你需要重点关注：

• GPU-Util (GPU 利用率): 这个百分比反映了 GPU 的计算核心有多“忙碌”。
• Memory-Usage: 显示了显存的使用情况。

瓶颈分析与解决方案清单

症状 (Symptom)	可能的瓶颈	解决方案
GPU-Util 持续低于 80%，波动剧烈	数据 I/O 或预处理瓶颈	这是最常见的原因。GPU 大部分时间在“空等”，等待 CPU 读取数据、处理成 token、然后发送过来。 1. 检查数据格式: 确保你的数据是 .jsonl 格式，而不是单个巨大的 JSON 文件，这有利于流式读取。 2. 升级硬件: 如果数据存放在机械硬盘 (HDD)，考虑升级到固态硬盘 (SSD)，特别是 NVMe SSD。 3. 预处理与缓存: Llama-factory 会对处理后的数据进行缓存。确保 --overwrite_cache 参数只在数据集变更时使用。对于大规模数据集，首次预处理可能很慢，但后续加载会很快。 4. 增加 num_workers: 在 training_args 中可以设置 dataloader_num_workers，增加数据加载的并行进程数 (需在代码层面修改或检查是否有 CLI 参数支持)。
GPU-Util 很高 (90%以上)，但训练仍然很慢	计算效率瓶颈	GPU 已经在全力计算，但计算本身效率不高。 1. 启用 FlashAttention-2: 这是最重要的加速手段。--flash_attn fa2 可以为注意力计算带来数倍的性能提升。 2. 启用 FP16/BF16: 确保 --fp16 或 --bf16 已开启。半精度训练不仅省显存，而且在现代 GPU 的 Tensor Core 上计算速度远快于 FP32。 3. 使用 TF32 (Ampere GPU 及以上): PyTorch 默认在支持的硬件上启用 TF32，它能加速 FP32 矩阵运算，无需修改代码。
一切正常，但就是想更快	优化批处理大小	在不 OOM 的前提下，尽可能增大 per_device_train_batch_size 并减小 gradient_accumulation_steps。更大的 batch_size 能更好地利用 GPU 的并行计算能力，减少通信和计算开销的比例，从而提升整体吞吐量 (tokens/sec)。

---

8.3 模型效果差 (不收敛、胡言乱语)

这是最令人困惑也最具挑战性的问题。它通常不是硬件或配置问题，而是数据和超参数的问题。你需要像侦探一样，系统性地排查。

排查清单：从数据到算法

1. 第一嫌疑人：数据质量 (Data Quality)

   • 原则: “Garbage In, Garbage Out.” 这是 AI 领域的铁律。再好的模型和算法也无法从低质量的数据中学习到有用的知识。
   • 检查清单:
     • 格式错误: 你的 .jsonl 文件是否严格符合格式？用脚本抽查几行，看 json.loads() 是否能成功解析。
     • 空值或异常值: output 或 conversations 中是否存在空字符串、null 或无意义的占位符？模型会如实学习这些“坏习惯”。
     • 内容污染: 数据是否混杂了大量的 HTML 标签、JavaScript 代码、Markdown 格式符或其他噪声？这些都需要在预处理阶段清洗干净。
     • 不一致性: 数据标注风格是否一致？例如，同样是总结任务，有的 output 是“本文介绍了A、B、C”，有的是“A、B、C”，这种不一致会干扰模型的学习。
     • SFT vs. DPO 数据泄露: 在构造 DPO 的偏好对时，确保 chosen 和 rejected 都是模型可能生成的回答。如果 chosen 的回答风格或知识是SFT阶段从未见过的，DPO 训练会非常困难。

2. 第二嫌疑人：学习率 (Learning Rate)

   • 原则: 学习率是决定模型能否成功收敛的最关键超参数。
   • 检查清单:
     • Loss 不下降或 NaN: 学习率过高。这是最常见的现象。立即将学习率降低一个数量级（例如，从 5e-5 降到 5e-6）再试。
     • Loss 下降极其缓慢: 学习率可能过低。可以尝试适当调高（例如，从 1e-6 升到 5e-6）。
     • 参考经验值:
       • Full-tuning: 1e-5 ~ 5e-6
       • LoRA (SFT): 1e-4 ~ 5e-5 (例如 2e-4)
       • LoRA (DPO/RM): 1e-5 ~ 5e-6 (比SFT更小)

3. 第三嫌疑人：训练时长 (Epochs)

   • 原则: 训练需要给模型足够的时间来“消化”数据，但时间过长也会“吃撑”。
   • 检查清单:
     • 欠拟合 (Underfitting): 训练结束后，loss 曲线仍然呈现明显的下降趋势，并且模型在验证集上表现很差（“学傻了”）。这说明训练不充分。解决方案: 增加 --num_train_epochs 的值，例如从 3.0 增加到 5.0。
     • 过拟合 (Overfitting): 训练 loss 很低，但模型在回答训练集之外的问题时开始“胡言乱语”，或者只会死记硬背训练数据中的原话。如果你开启了 --eval_steps 和 --evaluation_strategy steps，你会观察到 eval_loss 在下降一段时间后开始回升。解决方案: 减少 --num_train_epochs，或者引入正则化技术（如 weight_decay），或者增加数据量。

4. 第四嫌疑人：提示模板 (Prompt Template)

   • 原则: 模板是模型理解指令的“语法”。语法错了，模型自然无法理解。
   • 检查清单:
     • 模板与模型不匹配: 你是否为一个 Qwen 模型错误地使用了 Llama-2 的 [INST] 模板？这会导致灾难性的后果。解决方案: 在 Web UI 或 CLI 中，将 --template 设置为 default，让 Llama-factory 自动为你的模型选择最匹配的模板。只有在需要高度定制时才手动指定，并确保你完全理解该模型的官方对话格式。

---

8.4 (进阶) 多模态 (LLaVA) 微调

当你已经熟练掌握了文本模型的微调后，Llama-factory 还能带你进入更激动人心的多模态领域。LLaVA (Large Language and Vision Assistant) 是一个代表性的视觉语言模型（VLM）架构，它通过将一个视觉编码器（如 CLIP ViT）与一个大语言模型连接起来，赋予了 LLM “看懂图片”的能力。

LLaVA 的数据格式 (图片 + 文本)

这是多模态微调的第一个核心难点。数据不再是纯文本，而是图片和文本的结合。

• 文件结构:

  • 你的所有图片文件需要放在一个文件夹里，例如 data/llava_images/。
  • 你的数据文件（例如 llava_data.jsonl）仍然是文本文件，但它会通过文件名来引用这些图片。

• JSONL 格式 (ShareGPT 风格):
  LLaVA 的数据通常采用包含特殊标记的 ShareGPT 格式。

  {
    "id": "image_001",
    "image": "llava_images/cat_on_sofa.jpg",
    "conversations": [
      {
        "from": "human",
        "value": "这张图里有什么？\n<image>"
      },
      {
        "from": "gpt",
        "value": "这张图里有一只姜黄色的猫，它正舒适地躺在灰色的沙发上。"
      }
    ]
  }
  

• 关键点解析:

  • "image": "llava_images/cat_on_sofa.jpg": 必需。这个字段的值是相对于项目根目录的图片路径。
  • <image>: 特殊占位符。在 human 的对话中，你必须插入这个特殊的 <image> 标记。Llama-factory 的数据处理器在看到这个标记时，会自动将对应的图片特征注入到文本序列的这个位置。这个标记的位置决定了图片信息何时被模型“看到”。

多模态训练的特定配置

在 Web UI 或 CLI 中进行 LLaVA 微调，你需要关注一些额外的、多模态特有的配置项。

参数	作用	示例 / 常用设置
--vision_tower	指定用于编码图片的视觉编码器。	openai/clip-vit-large-patch14-336 (这是 LLaVA 1.5 的标准配置)
--projector_type	指定连接视觉编码器和语言模型的“投影层”类型。	mlp (多层感知机)
--mm_module_name	在 LoRA 训练中，除了文本模块，还需要将 LoRA 应用于多模态相关的模块。	`.*(w_pack
--freeze_vision_tower	是否冻结视觉编码器。	True (通常情况下，我们只微调投影层和LLM部分，而不动视觉编码器)
--freeze_llm_module	除了LoRA模块外，是否冻结语言模型。	True

Web UI 操作流程:

1. 模型名称: 选择一个支持 LLaVA 的基座模型，或者你希望扩展的普通 LLM。
2. 高级设置: 勾选“启用高级设置”。
3. 多模态设置:
   • 填入 vision_tower 的路径或 Hugging Face 名称。
   • 选择 projector_type。
4. 方法: 选择 lora。
5. lora_target: 除了常规的 q_proj, v_proj，还需手动添加多模态模块的名称，如 vision_projector。
6. 数据与训练: 和常规SFT类似，选择你准备好的 LLaVA 数据集，设置学习率等参数。

结论

至此，我们已经完成了 Llama-factory 的深度学习之旅。从最初的环境搭建，到精细的数据准备，再到 SFT、DPO 等核心技术的实战，以及最终的模型部署、评估和故障排查，你已经构建起了一套完整而强大的 LLM 微调知识体系。

记住，模型微调是一门科学，更是一门艺术。本笔记为你提供了坚实的理论基础和丰富的实践工具，但真正的精髓在于不断的尝试、细致的观察和创造性的思考。愿你在大语言模型的广阔世界中，打造出属于自己的、卓越的 AI 应用。旅途愉快！

Llama-factory 详细学习笔记 目录

以下是整个系列的8章目录，点击章节标题即可跳转阅读，可直接访问：

• Llama-factory 详细学习笔记 第一章：环境搭建与“Hello World” (入门与排错)
• Llama-factory 详细学习笔记 第二章：数据准备(决定成败的关键)
• Llama-factory 详细学习笔记 第三章：核心配置项详解(Web UI 篇)
• Llama-factory 详细学习笔记 第四章：命令行(CLI) 训练实战
• Llama-factory 详细学习笔记 第五章：SFT 与RM 微调实践
• Llama-factory 详细学习笔记 第六章：DPO (直接偏好优化) 实战(难点)
• Llama-factory 详细学习笔记 第七章：模型评估、合并与推理(应用落地)
• Llama-factory 详细学习笔记 第八章：常见疑难杂症(Troubleshooting) 与进阶技巧