brev-etiquette

Brev 礼仪规范

请将 /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}/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

自动研究模式

使用 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/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

在 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 后复现结果。