brev-etiquette

Brev のエチケット

/home/ubuntu/RL をソースチェックアウト、/ephemeral を生成される実験状態の作業ストレージとして扱ってください。リポジトリは小さく、再現可能で、確認しやすい状態に保ってください。負荷の高い処理を開始する前に、大きな実行出力を /ephemeral に移してください。

ストレージのルール

• コードの編集、小規模な設定変更、コミットする実験仮説、簡潔な再現記録は /home/ubuntu/RL に保存してください。
• チェックポイント、実行ログ、Ray の一時ディレクトリ、W&B のオフラインファイル、プロファイラートレース、評価ダンプ、ロールアウトサンプル、実験ごとの成果物など、生成される実験アセットは /ephemeral に保存してください。
• 再利用可能なキャッシュは、実験ごとではなく、ユーザーごとに共有する単一の /ephemeral キャッシュルートに保存してください。これには、Hugging Face モデル、データセットキャッシュ、PyTorch キャッシュ、Triton キャッシュ、uv キャッシュ、pip キャッシュが含まれます。
• キャンペーンや長時間の実行の前に df -h /home/ubuntu/RL /ephemeral で容量を確認し、/ephemeral がない場合や、空き容量がほとんどない場合は開始しないでください。
• /ephemeral/nemo-rl/${USER:-ubuntu}/auto-research/<campaign> のようなキャンペーンルートを作成し、実験ごとにサブディレクトリを1つ使用してください。
• 大きなファイル、キャッシュディレクトリ、生成された出力を 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

ログパス、チェックポイントパス、成果物、共有キャッシュルート、コマンドの各 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 のクリーンアップ後も結果を再現できるよう、少量のメタデータをリポジトリに残してください。