故障排除指南¶

本指南旨在帮助您诊断并解决在使用 LightRFT 过程中遇到的常见问题。

快速诊断¶

使用以下流程图快速定位您的问题：

问题类型？
├─ 安装与设置 → 参见 [安装问题](#安装问题)
├─ 显存不足 (OOM) → 参见 [显存问题](#显存问题)
├─ 训练问题 → 参见 [训练问题](#训练问题)
├─ 性能问题 → 参见 [性能问题](#性能问题)
└─ 分布式训练 → 参见 [分布式训练问题](#分布式训练问题)

安装问题¶

问题：包导入错误¶

现象：

ModuleNotFoundError: No module named 'lightrft'

解决方案：

# 确保您处于正确的目录
cd /path/to/LightRFT
pip install -r requirements.txt
pip install -e .

问题：CUDA 版本不匹配¶

现象：

RuntimeError: CUDA error: no kernel image is available for execution

解决方案：

# 检查 CUDA 版本
nvcc --version
python -c "import torch; print(torch.version.cuda)"

# 使用正确的 CUDA 版本重新安装 PyTorch
pip install torch==2.9.1+cu128 --index-url https://download.pytorch.org/whl/cu128

问题：vLLM 安装失败¶

现象：

ERROR: Failed building wheel for vllm

解决方案：

# 安装构建依赖
pip install ninja packaging wheel

# 从源码安装 vLLM
pip install vllm --no-build-isolation

# 或者使用预编译的 wheel 包
pip install vllm==0.13.3

显存问题¶

问题：显存不足 (Out of Memory, OOM) 错误¶

现象：

RuntimeError: CUDA out of memory
torch.cuda.OutOfMemoryError

解决策略（建议按顺序尝试）：

1. 减小 Batch Size

# 修改前
--micro_train_batch_size 2
--micro_rollout_batch_size 4

# 修改后
--micro_train_batch_size 1
--micro_rollout_batch_size 2

2. 启用梯度检查点 (Gradient Checkpointing)

--gradient_checkpointing

以约 20% 的速度损失换取约 50% 的显存节省。

3. 降低推理引擎显存占用

# 修改前
--engine_mem_util 0.9

# 修改后
--engine_mem_util 0.5  # 对于极低显存设备可尝试 0.4

4. 使用 FSDP 并开启 CPU 卸载 (Offload)

--fsdp \
--fsdp_cpu_offload \
--use_mp_opt

5. 启用 Adam 状态卸载 (Offload)

--adam_offload

6. 使用 ZeRO-3

--zero_stage 3

7. 减小模型/序列长度

--max_len 2048  # 代替 4096
--prompt_max_len 1024

完整的低显存配置示例：

python train.py \
    --micro_train_batch_size 1 \
    --micro_rollout_batch_size 1 \
    --gradient_checkpointing \
    --engine_mem_util 0.4 \
    --fsdp \
    --fsdp_cpu_offload \
    --adam_offload \
    --max_len 2048 \
    --use_mp_opt

问题：vLLM 引擎引发的 OOM¶

现象：

Failed to allocate memory for KV cache

解决方案：

# 减少用于 KV 缓存的显存比例
--engine_mem_util 0.3

# 增加张量并行 (Tensor Parallelism) 大小
--engine_tp_size 2  # 或 4

# 启用引擎休眠模式
--enable_engine_sleep

# 使用较小的最大长度
--max_len 2048

问题：训练过程中的显存泄漏¶

现象：

显存占用随时间逐渐增加
在训练数个 episode 后最终导致 OOM

解决方案：

# 启用 NCCL 优化
export TORCH_NCCL_AVOID_RECORD_STREAMS=1

# 定期清理缓存
# 在训练代码中添加：
torch.cuda.empty_cache()

# 使用引擎休眠模式
--enable_engine_sleep

训练问题¶

问题：训练不收敛¶

现象：

奖励值不增加
Loss 剧烈震荡
模型表现无提升

诊断与解决方案：

1. 检查学习率

# 如果过高（Loss 飙升）：
--actor_learning_rate 1e-7  # 调低

# 如果过低（无进展）：
--actor_learning_rate 1e-6  # 调高

2. 启用奖励归一化

--reward_running_norm \
--reward_running_norm_minus_mean \
--advantages_norm

3. 检查 KL 惩罚系数

# 如果 KL 过大（策略更新过慢）：
--init_kl_coef 0.0001  # 调低

# 如果 KL 过小（训练不稳定）：
--init_kl_coef 0.01  # 调高

4. 尝试不同的算法架构

# 从 GRPO 切换到 CPGD
--advantage_estimator cpgd \
--kl_target 0.01

问题：训练极其缓慢¶

现象：

在 8 张 A100 上每分钟处理样本数 < 100
每个 episode 需要耗费数小时

解决方案：

1. 定位性能瓶颈

# 使用 profiler 进行性能分析
with torch.profiler.profile() as prof:
    trainer.fit()
print(prof.key_averages())

2. 检查数据加载

# 增加 worker 数量
--num_workers 8

# 使用更快的 dataloader 配置
--dataloader_pin_memory

3. 优化生成阶段

# 使用 FP8 推理
--engine_type vllm  # vLLM 支持 FP8 推理

# 增加生成阶段的张量并行 (TP)
--engine_tp_size 2

# 如果可能，减小最大长度
--max_len 2048

4. 减少日志记录频率

# 不要每步都记录日志
--log_interval 100

分布式训练问题¶

问题：NCCL 超时¶

现象：

RuntimeError: NCCL timeout
[E ProcessGroupNCCL.cpp] Caught collective operation timeout

解决方案：

# 增加超时时间
export NCCL_TIMEOUT=1800

# 开启 NCCL 调试日志
export NCCL_DEBUG=INFO

# 尝试使用不同的网络接口
export NCCL_SOCKET_IFNAME=eth0

# 如果存在 IB 问题，尝试禁用 InfiniBand
export NCCL_IB_DISABLE=1

# 使用 GLOO 模式进行调试
export NCCL_BACKEND=gloo

问题：分布式初始化进程卡住¶

现象：

脚本停在 “Initializing process group”
无任何错误提示

解决方案：

# 1. 检查网络连通性
ping $MASTER_ADDR

# 2. 检查端口可用性
nc -zv $MASTER_ADDR $MASTER_PORT

# 3. 设置正确的环境变量
export MASTER_ADDR=192.168.1.1
export MASTER_PORT=29500
export WORLD_SIZE=8
export RANK=0  # 每张 GPU 分别设置为 0 到 7

# 4. 使用显式的初始化方法
torchrun --nproc_per_node=8 \
    --master_addr=$MASTER_ADDR \
    --master_port=$MASTER_PORT \
    train.py

# 5. 开启详细的调试日志
export TORCH_DISTRIBUTED_DEBUG=DETAIL

问题：GPU 利用率不均衡¶

现象：

部分 GPU 负载 100%，其余处于空闲
即使有多个 GPU，训练依然缓慢

解决方案：

# 1. 检查 batch size 的整除性
# 确保 batch_size % world_size == 0

# 2. 使用张量并行 (Tensor Parallelism)
--engine_tp_size 2  # 将模型拆分到多张 GPU

# 3. 检查流水线气泡
# 确保 train_batch_size 足够大

# 4. 监控 GPU 实时负载
nvidia-smi dmon -i 0,1,2,3,4,5,6,7 -s u

# 5. 针对长序列开启序列并行 (Sequence Parallelism)
--sp_size 2

问题：多节点训练失败¶

现象：

单节点运行正常
跨节点运行时失败

解决方案：

# 1. 使用 SLURM 调度器
srun -N2 --gres=gpu:8 --ntasks-per-node=8 bash train.sh

# 2. 使用显式的 torchrun 命令
# 在每个节点上执行：
torchrun \
    --nproc_per_node=8 \
    --nnodes=2 \
    --node_rank=$SLURM_NODEID \
    --master_addr=$MASTER_ADDR \
    --master_port=29500 \
    train.py

# 3. 检查防火墙规则
# 确保节点间的通信端口已开放

# 4. 使用共享文件系统
# 确保所有节点都能访问相同的模型/数据路径

性能问题¶

问题：GPU 利用率低¶

现象：

GPU 利用率 < 80%
训练速度慢于预期

解决方案：

1. 增加批量大小 (Batch Size)

--micro_train_batch_size 2  # 翻倍
--micro_rollout_batch_size 4

2. 减少 CPU 瓶颈

--num_workers 8
--prefetch_factor 2

3. 启用 Flash Attention

--flash_attn

4. 使用融合算子 (Fused Kernels)

--fused_linear_logprob

问题：生成速度过慢¶

现象：

生成 (rollout) 阶段占据了绝大部分训练时间
生成速度 < 100 tokens/sec

解决方案：

1. 使用 vLLM 推理引擎

--engine_type vllm  # 代替传统的 Transformers 推理
--engine_tp_size 2

2. 优化 KV 缓存

--engine_mem_util 0.9  # 在显存允许的情况下

3. 使用 FP8 推理 (如硬件支持)

# vLLM 在 H100 等卡上会自动尝试使用 FP8
--engine_type vllm

4. 减少采样样本数

--n_samples_per_prompt 4  # 代替默认的 8

推理引擎问题¶

问题：vLLM 引擎初始化失败¶

现象：

Failed to initialize vLLM engine
RuntimeError: Cannot allocate memory

解决方案：

# 1. 检查 GPU 显存
nvidia-smi

# 2. 降低显存分配比例 (engine_mem_util)
--engine_mem_util 0.5

# 3. 减小张量并行 (TP) 大小
--engine_tp_size 1

# 4. 检查模型兼容性
# 某些模型可能需要特定的 vLLM 版本

# 5. 更新 vLLM
pip install -U vllm

问题：引擎权重未能同步更新¶

现象：

策略模型 (Policy Model) 已更新，但生成的文本内容无变化
奖励值保持恒定

解决方案：

# 确保调用了 update_engine_weights
self.strategy.update_engine_weights(self.actor)

# 在训练循环中检查：
def ppo_train(self):
    ...
    # 训练结束后
    self.strategy.update_engine_weights(self.actor)

问题：引擎休眠/唤醒失败¶

现象：

训练在生成结束后卡住
报错 “Engine already sleeping”

解决方案：

# 1. 调试时可尝试禁用引擎休眠
--disable_engine_sleep

# 2. 或使用自动化管理
# gather_and_generate 函数会自动处理休眠与唤醒
all_outputs = self.strategy.gather_and_generate(
    ...,
    sleep_engine=True  # 启用自动管理
)

检查点 (Checkpoint) 问题¶

问题：保存检查点失败¶

现象：

OSError: Disk quota exceeded
RuntimeError: Cannot save checkpoint

解决方案：

# 1. 检查磁盘剩余空间
df -h

# 2. 限制保存的检查点数量
--max_ckpt_num 3

# 3. 设置最大存储占用的限制
--max_ckpt_mem 1000  # 单位：GB

# 4. 更换保存路径
--save_path /path/with/space

调试技巧¶

开启详细调试日志¶

# PyTorch 分布式调试
export TORCH_DISTRIBUTED_DEBUG=DETAIL

# NCCL 调试
export NCCL_DEBUG=INFO

# 强制同步执行（精确定位 CUDA 错误）
export CUDA_LAUNCH_BLOCKING=1

显存画像分析 (Memory Profiling)¶

import torch

# 记录显存分配历史
torch.cuda.memory._record_memory_history()

# 训练循环
...

# 导出快照文件
torch.cuda.memory._dump_snapshot("memory.pickle")

性能画像分析 (Performance Profiling)¶

with torch.profiler.profile(
    activities=[
        torch.profiler.ProfilerActivity.CPU,
        torch.profiler.ProfilerActivity.CUDA,
    ],
    record_shapes=True,
    with_stack=True
) as prof:
    trainer.fit()

# 查看耗时分布
print(prof.key_averages().table(sort_by="cuda_time_total"))

问题反馈清单¶

在报告 Bug 时，请提供以下信息：

硬件设备：GPU 型号、数量、显存容量
软件版本：CUDA、PyTorch、vLLM 版本号
运行命令：包含所有启动参数的完整命令
运行日志：完整的错误堆栈追踪 (Traceback)
环境变量：已生效的相关环境变量设置
最小复现脚本
您已尝试过的解决方法

获取更多帮助¶

如果上述方法无法解决您的问题：

查阅 FAQ：常见问题
搜索 Issues：GitHub Issues
社区交流：GitHub Discussions
提交 Bug：提交带有调试信息的新 Issue

常见错误信息快速索引¶

错误信息	对应章节	快速修复
`CUDA out of memory`	显存问题	减小 batch size，开启梯度检查点
`num_rollouts_per_episodes = 0`	训练问题	增大 `train_batch_size`
`NCCL timeout`	分布式训练问题	`export NCCL_TIMEOUT=1800`
`Failed to initialize vLLM`	推理引擎问题	调低 `engine_mem_util`
`NaN loss`	训练问题	调低学习率，开启梯度裁剪

另请参阅¶

常见问题 (FAQ) - 汇总的常见问题解答
配置指南 - 全量参数说明
最佳实践 - 框架优化建议