zhangsiyuan
bd1f51c496
Merged code repo (CompanionGuard-RL) into single project-level git. Reorganized root: docs/, reference/, experiments/, tmp/active|archives/. Gitignored: data/, checkpoints/, .venv, experiment logs, tmp/archives. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
477 lines
13 KiB
Markdown
477 lines
13 KiB
Markdown
# CompanionGuard-RL — 可复用经验库
|
||
**创建时间：2026-05-12**
|
||
**来源：Module B + Module C 训练调试过程中积累的真实踩坑记录**
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [RTX 5090 / NCCL 通信问题](#1-rtx-5090--nccl-通信问题)
|
||
2. [HuggingFace Accelerate 多 GPU 分布式训练](#2-huggingface-accelerate-多-gpu-分布式训练)
|
||
3. [PyYAML 配置文件陷阱](#3-pyyaml-配置文件陷阱)
|
||
4. [服务器文件传输（无 rsync 环境）](#4-服务器文件传输无-rsync-环境)
|
||
5. [SSH 连接与持久会话管理](#5-ssh-连接与持久会话管理)
|
||
6. [Python 依赖与包缺失处理](#6-python-依赖与包缺失处理)
|
||
7. [分布式训练中的 Tensor 设备一致性](#7-分布式训练中的-tensor-设备一致性)
|
||
8. [DataLoader 与分布式训练的兼容](#8-dataloader-与分布式训练的兼容)
|
||
9. [离线服务器的模型加载](#9-离线服务器的模型加载)
|
||
10. [Shell 脚本跨平台问题（CRLF）](#10-shell-脚本跨平台问题crlf)
|
||
11. [Python 模块路径（PYTHONPATH）](#11-python-模块路径pythonpath)
|
||
12. [可选依赖的优雅处理（wandb 等）](#12-可选依赖的优雅处理wandb-等)
|
||
|
||
---
|
||
|
||
## 1. RTX 5090 / NCCL 通信问题
|
||
|
||
### 症状
|
||
```
|
||
[rank0]: CUDA error: an illegal memory access was encountered
|
||
```
|
||
在多 GPU 训练中，某一阶段（如 BC warmup 后进入 PPO，或切换数据集后）突发崩溃，单 GPU 无此问题。
|
||
|
||
### 根因
|
||
RTX 5090 的 NVLink/P2P 拓扑与 NCCL 默认的共享内存（SHM）和 P2P 直连通信不兼容，导致跨 GPU 内存访问越界。
|
||
|
||
### 解决方案
|
||
```bash
|
||
# 同时禁用 SHM 和 P2P，强制 NCCL 走 socket 通信
|
||
export NCCL_SHM_DISABLE=1
|
||
export NCCL_P2P_DISABLE=1
|
||
```
|
||
|
||
**在 accelerate launch 前设置（推荐写法）：**
|
||
```bash
|
||
CUDA_VISIBLE_DEVICES=0,1,2,3 NCCL_SHM_DISABLE=1 NCCL_P2P_DISABLE=1 \
|
||
accelerate launch --num_processes=4 --mixed_precision=bf16 \
|
||
scripts/train_xxx.py ...
|
||
```
|
||
|
||
### 排查顺序
|
||
1. 先加 `NCCL_SHM_DISABLE=1` → 若仍崩溃
|
||
2. 再加 `NCCL_P2P_DISABLE=1` → 通常可解
|
||
3. 若仍有问题，尝试 `NCCL_DEBUG=INFO` 查看具体哪个集合通信操作出错
|
||
|
||
### 性能影响
|
||
禁用 P2P 后 GPU 间通信走 PCIe，带宽略降，但对 batch_size=256 量级的训练影响不超过 10%。
|
||
|
||
---
|
||
|
||
## 2. HuggingFace Accelerate 多 GPU 分布式训练
|
||
|
||
### accelerate 路径问题
|
||
服务器有多个 conda 环境时，直接敲 `accelerate` 可能用到错误环境的版本，或报 `command not found`。
|
||
|
||
**正确做法：用 conda 环境的完整路径**
|
||
```bash
|
||
# 查找正确路径
|
||
find /opt/conda/envs -name "accelerate" -type f 2>/dev/null
|
||
|
||
# 使用完整路径启动
|
||
/opt/conda/envs/dlapo-py310-cu128/bin/accelerate launch ...
|
||
```
|
||
|
||
### PYTHONPATH 设置
|
||
使用 `accelerate launch` 时，各 rank 子进程不继承当前 shell 的 `sys.path`，自定义 `src/` 包会报 `ModuleNotFoundError`。
|
||
|
||
```bash
|
||
PYTHONPATH=/path/to/project accelerate launch ...
|
||
```
|
||
|
||
### 推荐完整启动命令模板
|
||
```bash
|
||
cd /path/to/project
|
||
PYTHONPATH=$(pwd) \
|
||
CUDA_VISIBLE_DEVICES=0,1,2,3 \
|
||
NCCL_SHM_DISABLE=1 \
|
||
NCCL_P2P_DISABLE=1 \
|
||
/opt/conda/envs/<env>/bin/accelerate launch \
|
||
--num_processes=4 \
|
||
--mixed_precision=bf16 \
|
||
scripts/train_xxx.py \
|
||
--config configs/xxx.yaml \
|
||
> experiments/train_$(date +%Y%m%d_%H%M%S).log 2>&1 &
|
||
echo "PID: $! LOG: $LOG"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. PyYAML 配置文件陷阱
|
||
|
||
### 症状
|
||
```
|
||
TypeError: '<=' not supported between instances of 'float' and 'str'
|
||
```
|
||
明明写的是数字，PyYAML 却解析成字符串。
|
||
|
||
### 根因
|
||
**PyYAML 6.x 将科学计数法（如 `1e-3`、`3e-4`）解析为字符串，而非浮点数。**
|
||
|
||
PyYAML 5.x 以下正常，6.x 以上需要避免。
|
||
|
||
### 解决方案
|
||
将所有科学计数法改为小数形式：
|
||
```yaml
|
||
# ❌ 会被解析为字符串
|
||
lr: 1e-3
|
||
lr: 3e-4
|
||
|
||
# ✅ 正确写法
|
||
lr: 0.001
|
||
lr: 0.0003
|
||
```
|
||
|
||
### 快速检查
|
||
```python
|
||
import yaml
|
||
cfg = yaml.safe_load(open("config.yaml"))
|
||
print(type(cfg["lr"])) # 应为 <class 'float'>，若为 <class 'str'> 则有问题
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 服务器文件传输（无 rsync 环境）
|
||
|
||
### 背景
|
||
- 本地 Windows，目标 Linux GPU 服务器
|
||
- 本地 WSL 无 `rsync`，PowerShell 无原生 rsync
|
||
- 文件较多，直接 `scp -r` 速度慢且不方便增量同步
|
||
|
||
### 推荐方案：tar 打包 + scp 单文件传输
|
||
|
||
**本地打包（PowerShell）：**
|
||
```powershell
|
||
# 打包项目代码（排除数据集、checkpoint、缓存）
|
||
tar -czf sync_v4.tar.gz `
|
||
-C "D:\Myresearch\CompanionGuard-RL\code\CompanionGuard-RL" `
|
||
--exclude=".git" --exclude="__pycache__" `
|
||
--exclude="checkpoints" --exclude="experiments" `
|
||
src scripts configs requirements.txt
|
||
|
||
# 使用 WSL sshpass 上传
|
||
wsl -d Ubuntu-24.04 -- sshpass -p 'PASSWORD' scp -P PORT \
|
||
/mnt/d/Myresearch/CompanionGuard-RL/sync_v4.tar.gz \
|
||
root@HOST:/remote/path/
|
||
```
|
||
|
||
**服务器解压（覆盖更新）：**
|
||
```bash
|
||
cd /remote/project/dir
|
||
tar -xzf ../sync_v4.tar.gz --strip-components=0
|
||
```
|
||
|
||
### Windows 路径转 WSL 路径
|
||
```
|
||
D:\Myresearch\... → /mnt/d/Myresearch/...
|
||
```
|
||
|
||
### sshpass 在 WSL 中使用
|
||
```bash
|
||
# 安装
|
||
sudo apt-get install sshpass
|
||
|
||
# 密码直接传参（注意在脚本中要保护密码）
|
||
sshpass -p 'PASSWORD' ssh -p PORT user@host 'command'
|
||
sshpass -p 'PASSWORD' scp -P PORT local_file user@host:/remote/path/
|
||
```
|
||
|
||
---
|
||
|
||
## 5. SSH 连接与持久会话管理
|
||
|
||
### nohup vs tmux
|
||
| 方式 | 优点 | 缺点 |
|
||
|------|------|------|
|
||
| `nohup ... &` | 简单 | 非交互式 SSH 中 nohup 进程在连接断开后有时会收到 SIGHUP 而退出；无法重新 attach 查看输出 |
|
||
| `tmux` | 会话持久，可 attach/detach，输出可随时查看 | 需要服务器安装 tmux |
|
||
|
||
**推荐用 tmux：**
|
||
```bash
|
||
# 创建新会话并启动训练
|
||
tmux new-session -d -s train 'PYTHONPATH=... accelerate launch ...'
|
||
|
||
# 查看所有会话
|
||
tmux ls
|
||
|
||
# 重新连接查看输出
|
||
tmux attach -t train
|
||
|
||
# 在会话中执行命令（不 attach）
|
||
tmux send-keys -t train 'tail -f experiments/latest.log' Enter
|
||
```
|
||
|
||
### SSH 连接被拒绝但 ping 通（kex_exchange_identification）
|
||
症状：TCP 端口开放，ping 通，但 SSH 在握手前被关闭：
|
||
```
|
||
kex_exchange_identification: Connection closed by remote host
|
||
```
|
||
|
||
可能原因及处理：
|
||
1. **sshd 崩溃/重启中** → 通过网页控制台（VNC）执行 `systemctl restart sshd`
|
||
2. **MaxStartups 限制** → sshd_config 中 `MaxStartups 10:30:60` 可临时调高
|
||
3. **fail2ban 封 IP** → `fail2ban-client status sshd`，`fail2ban-client set sshd unbanip <IP>`
|
||
|
||
---
|
||
|
||
## 6. Python 依赖与包缺失处理
|
||
|
||
### 服务器无网络时安装包
|
||
|
||
**方法一：从已有 conda 环境复制**
|
||
```bash
|
||
# 查找其他环境中的包位置
|
||
find /opt/conda/envs -name "gymnasium" -type d 2>/dev/null
|
||
|
||
# 直接复制到目标环境
|
||
cp -r /opt/conda/envs/other-env/lib/python3.10/site-packages/gymnasium \
|
||
/opt/conda/envs/target-env/lib/python3.10/site-packages/
|
||
```
|
||
|
||
**方法二：本地下载 wheel，scp 传输，离线安装**
|
||
```powershell
|
||
# 本地下载（PowerShell）
|
||
pip download -d D:\wheels --platform linux_x86_64 --python-version 310 \
|
||
--only-binary=:all: gymnasium
|
||
# scp 传到服务器后：
|
||
pip install --no-index --find-links=/path/to/wheels gymnasium
|
||
```
|
||
|
||
### 检查包是否可用
|
||
```bash
|
||
python -c "import gymnasium; print(gymnasium.__version__)"
|
||
python -c "import torch; print(torch.cuda.device_count())"
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 分布式训练中的 Tensor 设备一致性
|
||
|
||
### 症状
|
||
```
|
||
RuntimeError: No backend type associated with device type cpu
|
||
```
|
||
在 `torch.distributed.broadcast()` 等集合通信操作中，传入了 CPU tensor。
|
||
|
||
### 根因
|
||
**NCCL 后端只支持 CUDA tensor**，所有参与 `broadcast/all_reduce/gather` 的 tensor 必须在 GPU 上。
|
||
|
||
### 修复模式
|
||
```python
|
||
dev = accelerator.device # 当前 rank 的 CUDA device
|
||
|
||
# 广播 size
|
||
size_tensor = torch.tensor([data.shape[0]], dtype=torch.long, device=dev)
|
||
torch.distributed.broadcast(size_tensor, src=0)
|
||
n = size_tensor.item()
|
||
|
||
# 广播数据
|
||
if accelerator.is_main_process:
|
||
data = data.to(dev)
|
||
else:
|
||
data = torch.zeros(n, data_dim, device=dev) # 必须在 GPU 上
|
||
|
||
torch.distributed.broadcast(data, src=0)
|
||
# 使用后如需 CPU，再 .cpu()
|
||
```
|
||
|
||
### 关键原则
|
||
- 集合通信（broadcast/all_reduce/scatter）→ **必须 CUDA tensor**
|
||
- DataLoader 输入 → **CPU tensor**（除非 `pin_memory=False`）
|
||
- 在 GPU 计算完成后，如需放入 CPU DataLoader，显式 `.cpu()`
|
||
|
||
---
|
||
|
||
## 8. DataLoader 与分布式训练的兼容
|
||
|
||
### pin_memory 陷阱
|
||
```
|
||
RuntimeError: cannot pin torch.cuda.FloatTensor
|
||
```
|
||
`DataLoader(pin_memory=True)` 要求数据必须是 **CPU tensor**，若传入已在 GPU 上的 tensor 则报错。
|
||
|
||
**修复：构建 TensorDataset 前先移到 CPU**
|
||
```python
|
||
# ❌ 若 obs_tensor 在 GPU 上会崩溃
|
||
dataset = TensorDataset(obs_tensor, action_tensor)
|
||
loader = DataLoader(dataset, pin_memory=True)
|
||
|
||
# ✅ 先 .cpu()
|
||
dataset = TensorDataset(obs_tensor.cpu(), action_tensor.cpu())
|
||
loader = DataLoader(dataset, pin_memory=True)
|
||
```
|
||
|
||
### set_epoch 守卫
|
||
```
|
||
AttributeError: 'SequentialSampler' object has no attribute 'set_epoch'
|
||
```
|
||
`set_epoch` 只有 `DistributedSampler` 有，`SequentialSampler` 没有。
|
||
|
||
**修复：加 hasattr 守卫**
|
||
```python
|
||
# ❌ 直接调用
|
||
loader.sampler.set_epoch(epoch)
|
||
|
||
# ✅ 安全写法
|
||
if hasattr(loader.sampler, "set_epoch"):
|
||
loader.sampler.set_epoch(epoch)
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 离线服务器的模型加载
|
||
|
||
### 症状
|
||
```
|
||
OSError: Can't load tokenizer for 'hfl/chinese-macbert-large'.
|
||
```
|
||
服务器无法访问 HuggingFace，在线下载失败。
|
||
|
||
### 解决方案
|
||
|
||
**方法一：本地下载后 scp**
|
||
```powershell
|
||
# 本地下载
|
||
python -c "
|
||
from huggingface_hub import snapshot_download
|
||
snapshot_download('hfl/chinese-macbert-large', local_dir='D:/models/macbert-large')
|
||
"
|
||
# 上传到服务器
|
||
scp -P PORT -r D:\models\macbert-large root@HOST:/remote/models/macbert-large
|
||
```
|
||
|
||
**方法二：用国内镜像（若服务器能访问）**
|
||
```bash
|
||
HF_ENDPOINT=https://hf-mirror.com \
|
||
python -c "from transformers import AutoTokenizer; AutoTokenizer.from_pretrained('hfl/chinese-macbert-large')"
|
||
```
|
||
|
||
**更新配置文件：**
|
||
```yaml
|
||
# 将 HuggingFace model id 改为本地绝对路径
|
||
model_name: "/root/path/to/macbert-large"
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Shell 脚本跨平台问题（CRLF）
|
||
|
||
### 症状
|
||
```
|
||
/bin/bash^M: bad interpreter: No such file or directory
|
||
```
|
||
或脚本执行后立即退出，没有任何错误信息。
|
||
|
||
### 根因
|
||
Windows 上编辑/保存的 `.sh` 文件使用 CRLF（`\r\n`）换行，Linux 只认 LF（`\n`），`^M`（即 `\r`）被当作命令的一部分。
|
||
|
||
### 修复方案
|
||
|
||
**PowerShell 写入时强制 LF：**
|
||
```powershell
|
||
$content = @'
|
||
#!/bin/bash
|
||
cd /project/dir
|
||
ACCEL=/path/to/accelerate
|
||
nohup $ACCEL launch ... > log.txt 2>&1 &
|
||
echo "PID: $!"
|
||
'@
|
||
# 关键：用 Replace 去掉 \r，用 UTF8NoBOM 编码
|
||
[System.IO.File]::WriteAllText(
|
||
"D:\path\to\script.sh",
|
||
$content.Replace("`r`n", "`n"),
|
||
[System.Text.UTF8Encoding]::new($false)
|
||
)
|
||
```
|
||
|
||
**事后修复（在 Linux 服务器上）：**
|
||
```bash
|
||
sed -i 's/\r//' script.sh
|
||
# 或
|
||
dos2unix script.sh
|
||
```
|
||
|
||
**验证：**
|
||
```bash
|
||
file script.sh # 应显示 "ASCII text" 而非 "CRLF line terminators"
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Python 模块路径（PYTHONPATH）
|
||
|
||
### 症状
|
||
```
|
||
ModuleNotFoundError: No module named 'src'
|
||
```
|
||
项目结构是 `src/models/`，但脚本中 `from src.models import ...` 找不到。
|
||
|
||
### 根因
|
||
`accelerate launch` / `torchrun` 启动的子进程工作目录不一定是项目根目录，`sys.path` 不包含项目根目录。
|
||
|
||
### 解决方案
|
||
|
||
**方案一：启动时设置 PYTHONPATH（推荐）**
|
||
```bash
|
||
PYTHONPATH=/root/path/to/project accelerate launch scripts/train.py
|
||
```
|
||
|
||
**方案二：在脚本开头动态添加**
|
||
```python
|
||
import sys, os
|
||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||
```
|
||
|
||
**方案三：项目根目录加 `__init__.py`（不推荐，污染命名空间）**
|
||
|
||
---
|
||
|
||
## 12. 可选依赖的优雅处理（wandb 等）
|
||
|
||
### 背景
|
||
`wandb` 有复杂的依赖树（`sentry-sdk`、`setproctitle` 等），在受限环境中难以安装。
|
||
|
||
### 推荐模式：try/except 导入 + 功能开关
|
||
|
||
**导入部分：**
|
||
```python
|
||
try:
|
||
import wandb
|
||
WANDB_AVAILABLE = True
|
||
except ImportError:
|
||
wandb = None
|
||
WANDB_AVAILABLE = False
|
||
```
|
||
|
||
**使用部分：**
|
||
```python
|
||
if use_wandb and WANDB_AVAILABLE:
|
||
wandb.log({"loss": loss})
|
||
elif use_wandb and not WANDB_AVAILABLE:
|
||
if step == 0:
|
||
print("[WARN] wandb not available, skipping logging")
|
||
```
|
||
|
||
**配置文件：**
|
||
```yaml
|
||
# 生产/受限环境
|
||
use_wandb: false
|
||
|
||
# 开发环境
|
||
use_wandb: true
|
||
```
|
||
|
||
这样即使 wandb 未安装，训练也能正常运行，不会因为一行 `import wandb` 而整个崩溃。
|
||
|
||
---
|
||
|
||
## 附：本项目服务器快速参考
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| SSH | `ssh -p 22657 root@connected.svt.net.cn` |
|
||
| 备用 SSH | `ssh -p 20083 root@10.82.3.180` |
|
||
| 密码 | `yx123456` |
|
||
| conda 环境 | `dlapo-py310-cu128` |
|
||
| accelerate 路径 | `/opt/conda/envs/dlapo-py310-cu128/bin/accelerate` |
|
||
| 项目目录 | `/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/CompanionGuard-RL` |
|
||
| MacBERT 本地路径 | `/root/siton-data-2849d4ce327c4ccfb233ce33868fe7fe/zsy/macbert-large` |
|