LLaMA-Factory微调ChatGLM3报错：Segmentation fault (core dumped) 的排查与解决

三十六陂

295人浏览 · 2026-02-16 00:19:06

三十六陂 · 2026-02-16 00:19:06 发布

1. 当“段错误”突然降临：一次真实的微调翻车现场

那天下午，我正兴致勃勃地准备用LLaMA-Factory对ChatGLM3-6B进行一轮LoRA微调。环境都检查过了，torch.cuda.is_available()返回了令人安心的True，模型文件也确认是从官方渠道下载的，一切看起来都那么完美。我敲下了那条经典的训练命令，参数都是社区里验证过无数遍的“黄金配置”，满怀期待地按下了回车。

命令窗口开始滚动，熟悉的日志信息一行行蹦出来。看到“Loading dataset self_cognition.json...”时，我心里还想着，数据加载完就该开始训练了。然而，下一秒，终端就陷入了死寂，紧接着弹出一行冰冷的、让所有开发者心头一紧的提示：Segmentation fault (core dumped)。程序就像撞上了一堵无形的墙，瞬间崩溃，留下一个名为core的“尸体”文件和一脸懵的我。

Segmentation fault，中文常叫“段错误”或“核心已转储”，是C/C++这类底层语言程序运行时可能遇到的最棘手错误之一。简单来说，就是程序试图访问一块不属于它的内存区域，被操作系统这个“内存警察”当场抓获并强制终止。在Python的深度学习项目中遇到它，通常意味着某个底层依赖的C/C++扩展库（比如PyTorch的CUDA后端、Hugging Face datasets库的某些组件）内部发生了严重错误。它不像Python的Exception会给你清晰的堆栈跟踪，它的出现往往意味着问题藏得更深，排查起来也更像侦探破案。

如果你也遇到了同样的问题，先别慌。这个错误虽然吓人，但并非无解。我花了整整两天时间，从环境检查、代码调试到最终“换系统”解决，踩遍了几乎所有能踩的坑。下面我就把这次完整的排查思路、调试过程和最终解决方案分享给你，希望能帮你省下那宝贵的两天时间。

2. 第一步：系统性环境检查与问题复现

遇到“段错误”，第一反应不应该是盲目地重试命令或重启机器。我们需要像医生一样，先做一套系统的“体检”，排除最显而易见的病因。

2.1 基础环境健康诊断

首先，确认你的PyTorch和CUDA环境是正确匹配且健康的。光看torch.cuda.is_available()返回True是不够的，它只说明PyTorch能“看到”CUDA驱动。我们还需要更细致的检查。

打开一个Python交互环境，逐条运行以下命令：

import torch
# 检查CUDA是否真正可用
print(f"CUDA available: {torch.cuda.is_available()}")
# 检查当前使用的CUDA工具包版本（与安装的PyTorch对应）
print(f"CUDA Toolkit Version (PyTorch built with): {torch.version.cuda}")
# 检查当前GPU的驱动支持的CUDA版本
print(f"GPU Driver CUDA Version: {torch.cuda.get_device_properties(0).major}.{torch.cuda.get_device_properties(0).minor}")
# 检查当前使用的GPU型号和内存
print(f"GPU Name: {torch.cuda.get_device_name(0)}")
print(f"GPU Memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.2f} GB")

重点对比torch.version.cuda和驱动支持的版本。比如，你的PyTorch是用CUDA 11.8编译的，但你的NVIDIA驱动版本太老，只支持到CUDA 11.0，那运行时就可能出现各种诡异问题，包括段错误。

接下来，检查关键库的版本。LLaMA-Factory、ChatGLM3、Transformers、Datasets、Accelerate这些库之间的版本兼容性至关重要。创建一个requirements_check.txt文件，记录下你当前环境的主要版本：

pip list | grep -E "torch|transformers|datasets|accelerate|peft|llama-factory"

然后，去LLaMA-Factory的官方GitHub仓库，查看其requirements.txt或pyproject.toml文件，核对推荐的版本范围。特别是datasets库，在我遇到的案例中，它就是罪魁祸首。

2.2 精确复现问题，缩小包围圈

环境检查无误后，我们需要精确地复现问题，并尝试将问题范围缩小到最小可复现单元。从原始报错日志看，错误发生在datasets库的load_dataset()函数被调用时。

我们可以写一个最简单的测试脚本test_load.py，来单独验证数据加载环节：

from datasets import load_dataset
import sys

print(f"Python version: {sys.version}")
print(f"Datasets version: {__import__('datasets').__version__}")

try:
    # 尝试加载你训练时用的数据集，这里以`self_cognition`为例，你需要替换为你的数据集路径或名称
    print("Attempting to load dataset...")
    # 如果是本地文件
    # dataset = load_dataset('json', data_files='path/to/your/self_cognition.json')
    # 如果是hub上的数据集，用名称
    dataset = load_dataset('your_username/self_cognition')
    print("Dataset loaded successfully!")
    print(dataset)
except Exception as e:
    print(f"An exception occurred: {type(e).__name__}: {e}")
except SystemExit:
    print("Program exited with SystemExit (unlikely).")
except:
    print("A critical error occurred (likely Segmentation Fault).")

运行这个脚本：python test_load.py。如果它同样触发了Segmentation fault (core dumped)，那么恭喜（或者说遗憾），你成功地将问题从庞大的训练流程隔离到了一个单一的库函数调用上。这极大地简化了后续的调试工作，我们可以将火力集中到datasets库及其依赖上。

3. 深入调试：定位内存访问的“罪魁祸首”

当问题被锁定在datasets库后，光看表面错误信息已经没用了。我们需要一些“外科手术”级别的工具来深入程序内部。

3.1 使用调试器进行动态追踪

像PyCharm或VSCode这类现代IDE的调试器是首选。以PyCharm为例，你需要：

将LLaMA-Factory项目作为根目录打开。
在src/train_bash.py的main()函数入口处打上断点。
根据原始错误日志，在src/llmtuner/data/loader.py文件大约第56行附近（即调用load_dataset的地方）打上关键断点。原始代码行可能是这样的：dataset = load_dataset(...)。
配置运行配置（Run/Debug Configuration），将你的训练命令参数（--stage sft --model_name_or_path ...）填入“Parameters”字段。
以调试模式（Debug）运行。

程序会一步步执行，当运行到load_dataset那一行时，单步步入（Step Into）。这时调试器可能会跳转到datasets库的源码中。继续单步，观察在哪一步之后程序突然崩溃，调试器失去连接（通常伴随着IDE弹出一个“进程已结束”的提示）。这个过程可能很耗时，因为datasets库的加载逻辑可能很深。但你的目标不是理解每一行代码，而是观察崩溃发生的精确位置，哪怕它是在某个.so动态链接库的内部。

3.2 利用系统工具进行底层分析

如果IDE调试不够直观，或者问题发生在更底层的C扩展中，我们可以求助系统自带的强大工具。

GDB (GNU Debugger)：这是分析Segmentation fault的终极利器。我们可以让Python在GDB中运行。
```
gdb --args python src/train_bash.py --stage sft ...（你的所有参数）
```
在gdb提示符(gdb)下，输入run执行程序。当段错误发生时，GDB会自动暂停。此时输入backtrace或bt命令，它会打印出程序崩溃时的完整调用堆栈。这个堆栈是C/C++层面的，你会看到很多类似libc.so.6、libpython3.10.so.1.0、_pyarrow_xxx.so这样的库名和内存地址。虽然看起来晦涩，但其中往往隐藏着关键信息。比如，如果堆栈最顶部的函数来自_pyarrow（Apache Arrow是datasets库用于高效数据处理的底层依赖），那么问题很可能与Arrow库的版本或编译有关。
检查Core Dump文件：如果系统启用了core dump（ulimit -c unlimited），错误发生时会在当前目录生成一个core或core.<pid>文件。同样可以用GDB加载这个文件进行分析：
```
gdb python core.2551  # 2551是崩溃进程的PID
```
在GDB中再次使用bt命令查看崩溃现场。

通过调试，我最终将问题锚定在：在Ubuntu 18.04系统上，特定版本的datasets库与系统底层库（很可能是glibc或libstdc++）存在不兼容，导致在加载或处理某些数据格式（尤其是Arrow格式）时发生非法内存访问。

4. 尝试常规修复方案：你可能走过的弯路

在确定根本原因前，我尝试了几乎所有网上能找到的与datasets库段错误相关的解决方案。虽然它们最终没能解决我的特定问题，但仍然是值得记录和尝试的步骤，因为你的问题可能就在其中。

4.1 升级或降级关键库版本

版本冲突是开源世界的永恒主题。我尝试了以下组合拳：

升级datasets到最新版：pip install -U datasets
升级/降级pyarrow：Arrow是datasets的后端引擎。尝试pip install -U pyarrow或安装一个特定版本，如pip install pyarrow==12.0.1。
同步升级transformers和accelerate：确保整个Hugging Face生态的版本兼容。
检查tokenizers库：这也是一个包含Rust/C扩展的库，有时也会引发问题。pip install -U tokenizers

每次变更版本后，都运行前面的test_load.py脚本进行验证。记得使用虚拟环境（如conda或venv）来隔离这些尝试，避免把基础环境搞乱。

4.2 排查数据文件本身

有时问题出在数据上。检查你的self_cognition.json文件：

格式是否严格符合JSON规范？可以使用python -m json.tool your_file.json验证。
文件编码是否为UTF-8？特别是如果数据中包含中文。
文件路径是否包含特殊字符或空格？
尝试创建一个极简的、只有几条样本的测试JSON文件，看问题是否依然存在，以排除数据复杂度的干扰。

4.3 环境变量与内存相关设置

设置一些环境变量，有时能避免某些内存分配问题：

export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1

对于CUDA相关的问题，可以尝试设置：

export CUDA_LAUNCH_BLOCKING=1  # 让CUDA操作同步，便于定位错误点
export PYTHONFAULTHANDLER=1    # 让Python在崩溃时打印更多信息

然后再次运行训练命令。

5. 终极解决方案：操作系统的抉择与验证

在尝试了所有软件层面的修复方案均告失败后，我开始怀疑问题出在操作系统的基础环境上。Ubuntu 18.04（Bionic Beaver）是一个已经结束标准支持的系统，其自带的系统库版本可能相对较老。

5.1 为什么是Ubuntu 20.04？

我最终将环境切换到了Ubuntu 20.04 LTS（Focal Fossa），问题迎刃而解。这背后有几个可能的原因：

更新的系统库：Ubuntu 20.04提供了更新的glibc、libstdc++6等基础C/C++运行库。datasets和pyarrow的二进制wheel包很可能是在一个较新的系统环境（比如基于manylinux2014或manylinux_2_28标准）下构建的，这些构建环境与Ubuntu 20.04的兼容性更好。在Ubuntu 18.04上，这些较新的二进制包可能调用了旧版系统库中不存在的API，或者存在细微的ABI（应用二进制接口）不兼容，从而在运行时导致内存错误。
更稳定的驱动和CUDA支持：虽然CUDA Toolkit是我们自己安装的，但GPU驱动与内核的集成、以及一些底层系统服务在更新的LTS版本上通常有更好的支持和稳定性。
社区支持重心转移：主流的深度学习框架和库的持续集成测试环境，会逐渐向更新的操作系统版本迁移。这意味着Ubuntu 20.04成为了一个被更广泛测试和验证的平台。

5.2 迁移与验证操作指南

如果你也决定升级系统，以下是一些实操建议：

全新安装 vs 原地升级：对于生产或稳定的开发环境，强烈建议备份数据后，进行Ubuntu 20.04的全新安装，而不是从18.04原地升级。全新安装能保证系统环境的纯净，避免因升级过程引入的复杂依赖问题。
环境重建清单：在新系统上，你需要按顺序安装：
1. NVIDIA驱动：使用ubuntu-drivers devices查看推荐版本，或直接从NVIDIA官网下载对应版本安装。
2. CUDA Toolkit：根据PyTorch官方安装命令推荐的版本安装（如pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118对应CUDA 11.8）。
3. Python环境：使用miniconda或pyenv管理Python版本（推荐3.9或3.10）。
4. 项目依赖：在虚拟环境中，根据LLaMA-Factory的最新requirements.txt安装所有Python包。
验证步骤：
1. 运行nvidia-smi确认驱动和GPU识别正常。
2. 在Python中验证torch.cuda.is_available()为True，并测试一个简单的CUDA张量运算。
3. 运行之前编写的test_load.py脚本，确保数据加载不再报错。
4. 最后，用一两条数据样本，以最小的num_train_epochs（比如设为1）运行一次完整的LLaMA-Factory微调命令，观察是否能顺利走完一个训练循环。

5.3 替代方案：容器化部署

如果你无法更换宿主操作系统，或者需要在多环境中保持一致，那么使用Docker容器是最优雅的解决方案。你可以寻找包含CUDA和PyTorch的基础镜像（如nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04），或者直接使用Hugging Face官方维护的transformers-pytorch-gpu镜像。在容器内构建你的开发环境，可以完美复现一个与宿主系统隔离的、版本可控的Ubuntu 20.04环境，从根本上杜绝因系统库版本导致的各种诡异问题。

那次从Ubuntu 18.04切换到20.04后，同样的代码、同样的数据、同样的命令，训练流程丝滑地启动了，再也没见过那个恼人的Segmentation fault。这件事给我的深刻教训是：在深度学习工程中，当你在应用层（Python代码、库版本）穷尽一切手段仍无法解决问题时，不妨将目光向下移动一层，审视一下操作系统和基础运行环境。保持开发环境与主流社区的支持版本同步，往往能提前避开许多深水区里的暗礁。现在，我的所有重要深度学习项目都跑在Ubuntu 20.04或更新版本的稳定LTS系统上，这成了我保证开发效率的一条隐性准则。