nemo-rl-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}/nemo-rl-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

自動研究のパターン

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 の絶対パスを記録してください。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 をクリーンアップした後も結果を再現できるよう、リポジトリには十分な量の小さなメタデータを残してください。