nemo-rl-brev-etiquette

Brev Etiquette

将 /home/ubuntu/RL 视为源代码检出目录，将 /ephemeral 视为存放生成的实验状态的工作存储。保持仓库精简、可复现且易于检查。启动任何高开销任务前，先将大型运行输出移至 /ephemeral。

存储规则

• 将代码修改、小型配置更改、已提交的实验假设和简洁的复现记录保存在 /home/ubuntu/RL 下。
• 将生成的实验资源放在 /ephemeral 下，包括检查点、运行日志、Ray 临时目录、W&B 离线文件、分析器跟踪记录、评估转储、 rollout 样本和各实验的产物。
• 将可复用缓存放在每位用户共用的单个 /ephemeral 缓存根目录下，而不是放在每个实验目录中。包括 Hugging Face 模型、数据集缓存、PyTorch 缓存、Triton 缓存、uv 缓存和 pip 缓存。
• 在开展实验活动或长时间运行前，使用 df -h /home/ubuntu/RL /ephemeral 检查容量；如果 /ephemeral 不存在或几乎已满，请勿启动。
• 创建一个实验活动根目录，例如 /ephemeral/nemo-rl/${USER:-ubuntu}/nemo-rl-auto-research/<campaign>，并为每个实验使用一个子目录。
• 不要在 git 检出目录中留下大文件、缓存目录或生成的输出。如果工具默认将内容写入仓库，请在运行前覆盖其输出或缓存路径。

环境密钥

• 将 /home/ubuntu/RL/.env 视为本地密钥存储。它可能包含 WANDB_API_KEY、HF_TOKEN 或 HUGGING_FACE_HUB_TOKEN 等密钥。
• 对于可能需要外部身份验证的运行，如果 /home/ubuntu/RL/.env 存在，请先加载它。切勿打印、cat、记录、提交或概述密钥值。
• 如果 /home/ubuntu/RL/.env 不存在，或者加载后仍未设置必需的密钥，请提醒用户在启动需要身份验证的任务前将所需密钥添加到该文件中。

if [ -f /home/ubuntu/RL/.env ]; then
  set -a
  . /home/ubuntu/RL/.env
  set +a
else
  echo "Missing /home/ubuntu/RL/.env; add required keys such as WANDB_API_KEY or HF_TOKEN before authenticated runs."
fi

自动研究模式

使用 nemo-rl-auto-research 时，将 git 记录保留在仓库中，将大型证据文件放在 /ephemeral。

if [ -f /home/ubuntu/RL/.env ]; then
  set -a
  . /home/ubuntu/RL/.env
  set +a
fi

BREV_ROOT=/ephemeral/nemo-rl/${USER:-ubuntu}
CACHE_ROOT=$BREV_ROOT/cache
CAMPAIGN_ROOT=$BREV_ROOT/nemo-rl-auto-research/<campaign>
EXP_DIR=$CAMPAIGN_ROOT/<experiment>
mkdir -p "$EXP_DIR"/{logs,checkpoints,artifacts,ray,tmp,wandb}
mkdir -p "$CACHE_ROOT"/{huggingface,torch,triton,uv,pip,xdg,wandb}

export HF_HOME=$CACHE_ROOT/huggingface
export HF_HUB_CACHE=$HF_HOME/hub
export HF_DATASETS_CACHE=$HF_HOME/datasets
export TRANSFORMERS_CACHE=$HF_HOME/transformers
export TORCH_HOME=$CACHE_ROOT/torch
export TRITON_CACHE_DIR=$CACHE_ROOT/triton
export UV_CACHE_DIR=$CACHE_ROOT/uv
export PIP_CACHE_DIR=$CACHE_ROOT/pip
export XDG_CACHE_HOME=$CACHE_ROOT/xdg
export WANDB_CACHE_DIR=$CACHE_ROOT/wandb
export RAY_TMPDIR=$EXP_DIR/ray
export TMPDIR=$EXP_DIR/tmp
export WANDB_DIR=$EXP_DIR/wandb

在 nemo-rl-auto-research TSV 字段中记录日志路径、检查点路径、产物、共享缓存根目录和命令的绝对 /ephemeral 路径。如果 TSV 文件本身可能变得很大，请将完整 TSV 存放在 /ephemeral，并在仓库中保留一个简短的指针文件或摘要。

启动检查清单

• 先检查磁盘：df -h /home/ubuntu/RL /ephemeral。
• 编辑配方或启动作业前，先选择一个唯一的 /ephemeral 运行根目录。
• 在各实验间复用共享缓存根目录，例如 /ephemeral/nemo-rl/${USER:-ubuntu}/cache，除非某次运行明确要求使用干净缓存。
• 覆盖配方输出路径、日志记录器路径、检查点路径和临时路径，使其指向实验目录下的位置。
• 覆盖缓存路径，使其指向共享缓存根目录。
• 将标准输出和标准错误流写入 $EXP_DIR/logs/run.log，或 /ephemeral 下的等效文件。
• 长时间运行期间，定期使用 df -h /ephemeral 检查磁盘；如果卷即将耗尽，请平稳停止运行。
• 结束时，在仓库记录中总结重要指标和路径；不要将大型产物复制回 /home/ubuntu/RL。

清理

• 只清理属于当前实验活动或实验的文件。
• 优先清理 /ephemeral/nemo-rl/... 下名称明确的实验目录；未经明确指示，切勿删除共享缓存或其他用户的运行目录。
• 在仓库中保留足够的少量元数据，以便在清理 /ephemeral 后复现实验结果。