解决LLaMA-Factory多GPU训练中的Bus error：Docker环境下/dev/shm内存不足实战指南

在分布式大模型训练中，Docker容器因其环境隔离和部署便捷性成为主流选择。但当你在LLaMA-Factory框架下使用deepspeed进行多GPU训练时，突然遭遇Bus error: nonexistent physical address这样的报错，往往会让人措手不及。这个看似硬件层面的错误，实际上很可能源于一个容易被忽视的容器配置细节——/dev/shm共享内存空间不足。

1. 理解Bus error与共享内存的关系

当你在终端看到Caught signal 7 (Bus error)这样的错误时，系统实际上是在告诉你：进程试图访问一个无效的物理内存地址。在多GPU训练场景下，这个错误经常与共享内存(/dev/shm)的配置直接相关。

/dev/shm是Linux系统的一个临时文件系统(tmpfs)，它使用内存作为存储介质，主要用途是提供进程间通信(IPC)的共享内存空间。在深度学习训练中，特别是使用deepspeed这样的分布式训练框架时：

• 数据加载器会利用共享内存加速数据在进程间的传输
• 多GPU通信需要共享内存作为缓冲区
• 某些Python库(如PyTorch的共享内存后端)会重度依赖这个空间

默认情况下，Docker容器的/dev/shm大小仅为64MB，这对于小规模实验可能足够，但在大模型训练场景下很快就会耗尽。当多个GPU进程同时尝试申请共享内存而空间不足时，就会触发Bus error。

2. 诊断共享内存问题的实用方法

遇到Bus error时，不要急于修改配置，先确认问题确实出在共享内存上。以下是诊断步骤：

# 进入运行中的容器
docker exec -it <container_id> /bin/bash

# 查看共享内存使用情况
df -h /dev/shm

典型的问题表现为：

Filesystem      Size  Used Avail Use% Mounted on
shm              64M   64M     0 100% /dev/shm

同时，检查dmesg日志也能发现相关线索：

dmesg | grep -i "bus error"

对于使用deepspeed的训练任务，还可以添加--log_level debug参数获取更详细的错误信息：

deepspeed --num_gpus 4 --log_level debug train_script.py ...

3. Docker环境下共享内存的配置方案

解决这个问题的核心是调整/dev/shm的大小。在非容器环境中，可以通过mount -o remount直接调整，但在Docker环境下需要采用不同的方法。

3.1 启动容器时指定shm-size

推荐方案是在docker run时通过--shm-size参数直接设置：

docker run -it --gpus all --shm-size=8G -v /path/to/data:/data your_image

这个命令将共享内存设置为8GB，通常能满足大多数大模型训练需求。实际大小应根据以下因素调整：

• GPU数量：每增加一个GPU，共享内存需求约增加1-2GB
• 批次大小：较大的batch size需要更多共享内存
• 模型规模：参数量越大的模型对共享内存需求越高

3.2 通过docker-compose配置

如果使用docker-compose管理容器，可以在配置文件中添加：

version: '3'
services:
  trainer:
    image: your_image
    shm_size: '8gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 4
              capabilities: [gpu]

3.3 替代方案：使用主机共享内存

对于某些无法修改容器配置的环境，可以考虑将主机的/dev/shm挂载到容器中：

docker run -it --gpus all -v /dev/shm:/dev/shm your_image

但这种方法存在潜在问题：

• 主机和容器的共享内存空间会相互影响
• 安全性考虑，不推荐在生产环境使用

4. LLaMA-Factory与deepspeed的最佳实践

结合LLaMA-Factory的特性和deepspeed的分布式训练需求，以下是避免共享内存问题的完整配置建议：

4.1 训练命令优化

在确保/dev/shm大小足够的前提下，还可以优化训练参数减轻共享内存压力：

deepspeed --num_gpus 4 --master_port=9901 src/train_bash.py \
  --deepspeed ds_config.json \
  --stage sft \
  --model_name_or_path models/chatglm3-6b \
  --do_train \
  --dataset aaa,bbb \
  --template chatglm3 \
  --finetuning_type lora \
  --lora_target query_key_value \
  --output_dir output/aaabbbccc/ \
  --per_device_train_batch_size 4 \
  --gradient_accumulation_steps 4 \
  --lr_scheduler_type cosine \
  --logging_steps 10 \
  --save_steps 200 \
  --learning_rate 5e-5 \
  --num_train_epochs 200 \
  --fp16

关键参数调整：

• 适当减少per_device_train_batch_size可降低共享内存需求
• 确保gradient_accumulation_steps与batch size合理配比
• 使用fp16精度可减少内存占用

4.2 deepspeed配置优化

在ds_config.json中添加以下配置可优化内存使用：

{
  "train_micro_batch_size_per_gpu": 4,
  "gradient_accumulation_steps": 4,
  "optimizer": {
    "type": "AdamW",
    "params": {
      "lr": 5e-5
    }
  },
  "fp16": {
    "enabled": true
  },
  "zero_optimization": {
    "stage": 2,
    "offload_optimizer": {
      "device": "cpu"
    }
  }
}

4.3 监控与调优

训练过程中实时监控资源使用情况：

# 在容器内安装监控工具
apt-get update && apt-get install -y htop

# 查看内存和共享内存使用
htop
df -h /dev/shm

如果发现共享内存使用接近上限，可以考虑：

1. 增加--shm-size值
2. 减少数据加载器的worker数量
3. 使用更高效的数据加载方式

5. 其他可能引发Bus error的原因及排查

虽然/dev/shm不足是常见原因，但Bus error也可能由其他因素引起。以下是完整的排查清单：

可能原因	排查方法	解决方案
硬件内存故障	运行memtest86	更换内存条
GPU显存不足	监控nvidia-smi	减小batch size
文件系统错误	检查dmesg日志	修复文件系统
内核模块问题	检查内核日志	更新驱动程序
容器权限不足	检查docker run --privileged	增加权限

对于Docker环境特有的问题，还可以检查：

• 容器cgroup限制
• 内核版本与Docker版本的兼容性
• 存储驱动配置

在最近的LLaMA-Factory项目中，有开发者发现当使用特定版本的CUDA时也会触发类似的Bus error。这时可以尝试：

# 检查CUDA与驱动兼容性
nvidia-smi
nvcc --version

# 必要时降级或升级CUDA版本