ChatGLM3微调实战：LLaMA-Factory中Segmentation fault报错的深度排查指南

最近在折腾LLaMA-Factory微调ChatGLM3时，不少朋友都踩到了同一个坑：训练脚本跑着跑着，突然给你来个“Segmentation fault (core dumped)”，然后整个进程就毫无征兆地崩溃了。这种错误最让人头疼的地方在于，它不像普通的Python异常会给你一个清晰的堆栈跟踪，而是直接由操作系统内核触发，往往只留下一句冷冰冰的提示，让你无从下手。我自己在项目中也反复遇到过这个问题，从环境配置到代码调试，几乎把能试的方法都试了一遍。这篇文章，我就把自己排查这类问题的完整思路和具体操作步骤梳理出来，希望能帮你快速定位并解决这个烦人的“段错误”。

1. 理解Segmentation fault的本质与常见诱因

在深入具体排查步骤之前，我们有必要先搞清楚“Segmentation fault”到底是个什么东西。简单来说，这是操作系统内存保护机制触发的错误。当一个进程试图访问它没有被授权访问的内存区域（比如访问空指针、访问已释放的内存、或者向只读内存区域写入数据）时，操作系统就会强制终止该进程，并产生一个“核心已转储”（core dumped）文件。在LLaMA-Factory这类深度学习框架的微调场景下，段错误很少是业务逻辑错误，绝大多数情况都指向底层环境或依赖的问题。

结合我遇到过的案例和社区反馈，在LLaMA-Factory微调ChatGLM3时，段错误通常由以下几类原因引发：

• CUDA与PyTorch版本不匹配：这是最经典也最常见的问题。PyTorch的CUDA版本必须与系统安装的NVIDIA驱动以及CUDA Toolkit版本严格兼容。
• 特定依赖库的版本冲突或缺陷：尤其是datasets、transformers、accelerate等Hugging Face生态的核心库，某些版本组合可能存在已知的、会导致段错误的Bug。
• 系统库或编译器问题：例如glibc版本过低、GCC编译器版本不兼容，或者在编译某些依赖项时使用了不恰当的优化标志。
• 内存访问越界（代码层面）：虽然较罕见，但框架或模型代码中潜在的Bug也可能导致非法内存访问。ChatGLM3的模型实现或LLaMA-Factory的某些数据加载逻辑在特定条件下可能触发此类问题。
• 硬件或驱动问题：极少数情况下，GPU显存故障、不稳定的超频设置或有缺陷的显卡驱动也可能表现为段错误。

理解这些潜在原因，就像拿到了一张排查地图。接下来，我们就按照从易到难、从外到内的顺序，一步步缩小问题范围。

2. 第一步：系统性环境检查与版本验证

当段错误发生时，盲目修改代码往往是效率最低的做法。首先应该对运行环境进行一次全面的“体检”。请打开你的终端，依次执行以下检查。

2.1 验证CUDA、驱动与PyTorch的兼容性

这是必须首先排除的“头号嫌疑犯”。运行以下命令来收集关键信息：

# 检查NVIDIA驱动版本
nvidia-smi

# 检查系统安装的CUDA Toolkit版本（如果已安装）
nvcc --version

# 在Python环境中检查PyTorch及其CUDA支持
python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA可用: {torch.cuda.is_available()}'); print(f'CUDA版本(PyTorch内置): {torch.version.cuda}'); print(f'当前设备: {torch.cuda.get_device_name(0)}')"

你需要将nvidia-smi输出的CUDA Version（这是驱动支持的最高CUDA版本）与torch.version.cuda输出的版本进行比对。它们不需要完全一致，但必须兼容。例如，驱动支持CUDA 12.2，那么PyTorch内置的CUDA 11.8或12.1通常是可以工作的，但反过来则不行。

注意：torch.cuda.is_available()返回True仅仅表示PyTorch检测到了CUDA环境，绝不代表版本完全兼容无问题。很多段错误的根源正是这种“看似可用”实则不匹配的状态。

如果发现版本不匹配，你需要重新安装对应版本的PyTorch。强烈建议从PyTorch官网获取精确的安装命令。

2.2 检查关键Python依赖库的版本

Hugging Face生态库的版本是另一个重灾区。创建一个简单的脚本来输出相关库的版本：

# check_versions.py
import transformers
import datasets
import accelerate
import peft
import torch
print(f"torch: {torch.__version__}")
print(f"transformers: {transformers.__version__}")
print(f"datasets: {datasets.__version__}")
print(f"accelerate: {accelerate.__version__}")
print(f"peft: {peft.__version__}")

运行它并记录输出。然后，前往LLaMA-Factory项目的requirements.txt或pyproject.toml文件，核对官方推荐的版本范围。你也可以在项目的Issue页面或讨论区搜索“Segmentation fault”，看看是否有特定版本组合被标记为有问题。

一个常见的策略是尝试将datasets库回退到一个更稳定的旧版本（例如从2.15.0回退到2.14.0），因为该库在数据加载和内存映射处理上的变动有时会引入不稳定性。

3. 第二步：问题复现与精准定位

在完成基础环境检查后，如果问题依旧，我们需要更精确地定位错误发生的具体位置。段错误日志通常不会指向Python代码行，但我们可以通过一些技巧来获取更多信息。

3.1 使用调试器捕获更详细的信号

在运行训练命令时，可以通过CUDA_LAUNCH_BLOCKING=1环境变量来让CUDA操作同步执行，这有时能让错误堆栈更清晰。更重要的是，我们可以使用faulthandler模块，它在Python崩溃时能打印出Python层面的堆栈信息。

在你的训练脚本的最开头（通常是train_bash.py的第一行之后）添加以下代码：

import faulthandler
faulthandler.enable()

然后再次运行训练命令。当段错误发生时，你可能会在控制台看到Python线程的堆栈跟踪，这能极大帮助你判断错误是在前向传播、反向传播还是数据加载阶段触发的。

3.2 最小化复现与隔离测试

根据原始资料中的线索，错误发生在datasets库的load_dataset()函数调用时。这是一个非常宝贵的定位信息。我们可以设计一个最小的测试脚本来隔离这个问题：

# test_datasets.py
from datasets import load_dataset
import sys

print("Testing datasets loading...")
try:
    # 尝试加载你训练时使用的相同数据集
    dataset = load_dataset('json', data_files='path/to/your/self_cognition.json')
    print("load_dataset succeeded.")
    # 进一步尝试一些可能触发问题的操作，如数据切片
    print(dataset['train'][0])
except Exception as e:
    print(f"Python exception caught: {e}")
except BaseException as e:
    print(f"Critical error (likely segfault precursor): {e}")

如果这个简单的脚本也能触发段错误，那么问题几乎肯定出在datasets库本身、其底层依赖（如pyarrow、dill）或者系统环境上。这排除了训练循环中其他复杂逻辑的影响。

3.3 分析Core Dump文件（Linux系统）

如果系统启用了core dump，错误发生时会在当前目录或指定目录生成一个core或core.<pid>文件。我们可以用gdb工具分析它，这需要一些C/C++调试经验。

# 首先确保系统允许生成core文件
ulimit -c unlimited

# 运行你的训练脚本，等待段错误发生
# 假设生成的文件是 core.12345
gdb python core.12345

在gdb中，输入bt（backtrace）命令来查看崩溃时的C级别调用堆栈。堆栈信息可能非常底层（涉及libc、CUDA运行时等），但如果你看到反复出现的与libarrow、mmap或某个特定.so库相关的调用，就能为问题定性提供关键线索。例如，堆栈指向libarrow，那么问题很可能与Apache Arrow（datasets库用于内存处理的核心组件）有关。

4. 第三步：针对性解决方案与尝试

基于上述定位，我们可以尝试以下几种针对性的解决策略。

4.1 依赖库的降级、升级与纯净安装

这是最直接的方法。如果怀疑是datasets库的问题，尝试以下命令：

# 尝试降级到一个广泛使用的稳定版本
pip install 'datasets==2.14.0'

# 或者升级到最新版本（可能已修复相关bug）
pip install -U datasets

# 更彻底的做法：在全新的虚拟环境中，严格按LLaMA-Factory要求安装
python -m venv fresh_venv
source fresh_venv/bin/activate
pip install torch ... # 严格安装匹配的PyTorch
git clone https://github.com/hiyouga/LLaMA-Factory
cd LLaMA-Factory
pip install -e . # 或按照项目文档的安装指南

4.2 调整数据加载方式

有时，问题出在数据文件本身或加载参数上。可以尝试修改数据加载的代码，以更保守的方式进行：

1. 关闭内存映射：datasets库默认使用内存映射文件以提高性能，但在某些文件系统或环境下可能不稳定。尝试在load_dataset中禁用：

   dataset = load_dataset('json', data_files='data.json', keep_in_memory=True)  # 直接加载到内存
   

   或者在LLaMA-Factory的数据配置中寻找相关选项。

2. 简化数据集：创建一个极小的、格式绝对正确的测试数据集（比如只有10条样本），看错误是否依然发生。这可以排除数据文件损坏或格式异常的问题。

3. 更换数据格式：如果使用JSON，尝试将其转换为parquet或arrow格式再加载，有时能绕过JSON解析器的某些边界情况。

4.3 系统级检查与调整

如果所有软件层面的尝试都失败，我们需要审视操作系统环境。

• 检查系统库：运行ldd命令检查Python解释器或关键库是否链接了缺失或版本冲突的系统库。

  ldd `which python` | grep -E "libc|libstdc++"
  

  对比开发环境与生产环境的输出。

• 内存与交换空间：虽然ChatGLM3-6B微调对内存要求不是极高，但确保系统有足够的可用内存和交换空间。在数据加载时，如果系统内存不足，也可能引发异常。

• 终极方案：调整操作系统或Docker镜像。正如原始资料中提到的，从Ubuntu 18.04切换到20.04就解决了问题。这通常是因为新版本的系统提供了更新、更兼容的底层库（如glibc、GCC运行时库）。如果你在使用Docker，尝试更换一个基于更新版本Linux发行版的官方PyTorch镜像，例如：

  FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
  

  这能保证一个经过良好测试的、一致的基础环境。

5. 第四步：深入代码与社区资源

当常规手段用尽时，我们需要更深入地挖掘。

5.1 在LLaMA-Factory框架内寻找线索

仔细阅读LLaMA-Factory在加载ChatGLM3模型和处理其对应模板时的代码。关注src/llmtuner/data/loader.py和src/llmtuner/model/loader.py。是否有针对ChatGLM3的特殊处理？这些处理逻辑是否与你使用的版本匹配？有时，框架的某个commit可能引入了对特定模型结构的调整，而你的环境没有完全同步更新。

可以尝试在load_dataset调用前后，以及模型加载时，插入更多的日志，甚至尝试用try-except包裹更小的代码块，以进一步缩小崩溃发生的精确行号范围。

5.2 利用社区与开源情报

你遇到的问题很可能别人也遇到过。积极利用以下资源：

1. GitHub Issues：在LLaMA-Factory、ChatGLM3（THUDM）、HuggingFace Transformers和Datasets的GitHub仓库中，用“Segmentation fault”、“core dumped”、“ChatGLM3”等关键词搜索已关闭和未关闭的Issue。仔细阅读其中的讨论和解决方案。

2. 检查项目依赖的已知问题：访问关键依赖库的发布页面（如PyTorch、Datasets的GitHub Release），查看已知问题和修复。有时，一个库的版本说明中会明确提到“修复了可能导致段错误的bug”。

3. 社区讨论：在诸如Stack Overflow、Reddit的r/MachineLearning、知乎、相关技术社群中描述你的问题。提供尽可能详细的信息：

   • 完整的错误信息。
   • 你的环境版本（使用pip list或conda list导出）。
   • 你已尝试过的排查步骤。
   • 最小复现脚本。

提供一个清晰、信息量大的问题描述，能大大提高你获得有效帮助的几率。

排查Segmentation fault的过程，就像一场耐心的侦探游戏。它考验的是你对技术栈分层结构的理解，以及系统性排除故障的能力。从最外层的版本兼容性开始，逐步深入到数据流、框架代码，最后触及操作系统底层，这条路径在大多数情况下都是有效的。记住，每次改变一个变量进行测试，并做好记录，最终你不仅能解决眼前的问题，更能积累下宝贵的、针对复杂深度学习运维环境的调试经验。当你的环境最终稳定运行起来，看着损失曲线平稳下降时，之前所有的折腾都会变得值得。