
名称	nemo-rl-brev-etiquette
开源协议	Apache-2.0
描述	为在 /home/ubuntu/RL 中工作的 NeMo-RL 智能体提供的 Brev 实例操作指南，工作区磁盘有限，但有较大的 /ephemeral 卷，以及可选的 /home/ubuntu/RL/.env 密钥。在运行 nemo-rl-auto-research 活动、实验、训练任务、模型或数据集下载、共享缓存密集型命令、生成日志的运行、检查点生成、需要 W&B 或 Hugging Face 认证的工作流，或任何可能在 Brev 上创建大文件的工作流时使用。 when_to_use: 在 Brev 实例上运行；启动 nemo-rl-auto-research 活动或长时间任务；管理大型日志、检查点、缓存、数据集、Ray 临时文件、W&B 文件或 Brev 上的 Hugging Face 认证。

Brev 工作规范

将 /home/ubuntu/RL 视为源代码检出目录，将 /ephemeral 视为生成的实验状态的工作存储。保持仓库小型、可复现且易于检查。在启动任何耗资源的操作前，将庞大的运行输出移至 /ephemeral。

存储规则

将代码编辑、小规模配置更改、已提交的实验假设和简洁的可复现性记录保存在 /home/ubuntu/RL 下。
将生成的实验资产放在 /ephemeral 下，包括检查点、运行日志、Ray 临时目录、W&B 离线文件、性能分析器跟踪、评估转储、回滚样本以及每个实验的产物。
将可复用缓存放在每个用户共享的 /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

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

启动清单

首先检查磁盘：df -h /home/ubuntu/RL /ephemeral。
在编辑配方或启动任务前，选择唯一的 /ephemeral 运行根目录。
除非运行明确要求干净缓存，否则在实验之间重复使用共享缓存根目录，例如 /ephemeral/nemo-rl/${USER:-ubuntu}/cache。
覆盖配方中的输出路径、记录器路径、检查点路径和临时路径，使其指向实验目录下。
覆盖缓存路径，使其指向共享缓存根目录下。
将 stdout/stderr 流式传输到 $EXP_DIR/logs/run.log 或 /ephemeral 下的等效文件。
在长时间运行期间定期使用 df -h /ephemeral 检查磁盘，如果卷接近耗尽则正常停止。
结束时，在仓库台账中总结重要指标和路径；不要将庞大的产物复制回 /home/ubuntu/RL。

清理

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