tao-run-on-brev

Brev

NVIDIA Brev は、複数のクラウドプロバイダーにわたってオンデマンドの GPU インスタンスを提供します。インスタンスには、NVIDIA ドライバー、CUDA、Docker、NVIDIA Container Toolkit があらかじめインストールされています。

Brev はインスタンスベースです（Lepton のようなジョブベースではありません）。インスタンスを作成し、brev exec でコマンドを実行して、完了したら削除します。TAO SDK の BrevHandler は、これを標準的なジョブインターフェースにラップします。

事前確認

このスキルには brev CLI、その関連エージェントスキル（brev-cli）、および有効なログインが必要です。続行する前に確認してください。

# 1. brev CLI installed
command -v brev >/dev/null 2>&1 || {
  echo "MISSING: brev CLI not installed. Install:"
  echo "  https://docs.nvidia.com/brev/"
  exit 1
}

# 2. brev-cli agent skill installed — provides the brev CLI's command reference to the agent
[ -d "$HOME/.claude/skills/brev-cli" ] || [ -d ".claude/skills/brev-cli" ] || {
  echo "MISSING: brev-cli agent skill not installed. Run:"
  echo "  brev agent-skill install"
  exit 1
}

# 3. brev login active — always token-login first when running headless.
#    Plain `brev ls` will hit an interactive auth prompt (read: EOF on stdin)
#    even when BREV_API_TOKEN is set, so refresh the session up front.
if [ -n "$BREV_API_TOKEN" ]; then
  brev login --token "$BREV_API_TOKEN" >/dev/null 2>&1 || {
    echo "MISSING: brev token login failed. Verify BREV_API_TOKEN."
    exit 1
  }
fi
# Retry once after a forced re-login: cached creds occasionally desync and the
# first `brev ls` returns auth EOF until the session is rebuilt.
brev ls >/dev/null 2>&1 || {
  [ -n "$BREV_API_TOKEN" ] && brev login --token "$BREV_API_TOKEN" >/dev/null 2>&1
  brev ls >/dev/null 2>&1 || {
    echo "MISSING: not logged in to brev. Run:"
    echo "  brev login                                    # interactive (opens browser)"
    echo "  # or set BREV_API_TOKEN in ~/.config/tao/.env (then 'brev login --token \$BREV_API_TOKEN')"
    exit 1
  }
}

いずれかの手順に失敗した場合、エージェントは Bash 経由で修正を許可するようユーザーに求め、その後、続行する前に事前確認を再実行します。Brev では TAO SDK は必須ではありません。brev exec docker run … で十分です。ジョブハンドル、script_runner による S3 I/O のラップ、または状態の永続化が必要な場合に限り SDK を使用してください。nvidia-tao-sdk は公開 PyPI から入手できます。versions.yaml で指定された Brev 用追加パッケージをインストールしてください：pip install "$("${TAO_SKILL_BANK_PATH:?}/scripts/resolve_versions_key.py" wheels.tao_sdk_brev)"。SDK を使用する場合は、BrevSDK のキーワード引数リファレンス、build_entrypoint、ActionWorkflow のパターンについて、tao-skill-bank:tao-run-platform をお読みください。

認証

選択肢は 2 つあります。

1. 自動（推奨）：Brev コンソールの設定ページから API トークンを取得します。BREV_API_TOKEN を環境変数として設定します（例：~/.config/tao/.env）。ハンドラーは初回使用時に brev login --token で自動認証します。Lepton と同じ操作感です。

2. 手動：brev login を実行します（ブラウザーが開きます）。トークンは 1 時間ごとに期限切れになりますが、ハンドラーが自動的に更新します。

データ転送には、別途 S3 認証情報（ACCESS_KEY、SECRET_KEY）が必要です。

ヘッドレス／非対話モード

CI シェル、コンテナー、または制御用 TTY のないエージェントセッションでは、他の brev 呼び出しを行う前に必ず brev login --token "$BREV_API_TOKEN" を実行してください。トークンがエクスポート済みの場合も同様です。そうしないと、CLI が標準入力でプロンプトを表示し、brev ls、brev create、brev exec などのコマンドで EOF 認証エラーを返します。呼び出しで認証の EOF エラーが返された場合は、トークンでのログインを再実行してください。通常は 1 回の更新で十分です。

起動前の確認

スクリプトを生成したりジョブを送信したりする前に、次のことを確認してください。

1. BREV_API_TOKEN が設定されていることを確認します。
2. brev CLI がインストールされ、インスタンスを一覧表示できることを確認します。例：brev ls --json。必要に応じて brev login --token で認証します。
3. s3:// のデータセット／結果を使用する場合、ACCESS_KEY と SECRET_KEY が設定されており、対象のパスを aws s3 ls で読み取れることを確認します。
4. 対象のパスが Brev インスタンス上に存在する、またはインスタンスにマウントされていることをユーザーが証明していない限り、Brev へのローカル /path 入力を受け付けないでください。
5. 起動前に、HF_TOKEN などモデル固有の認証情報を確認します。

インスタンスのライフサイクル

エージェントがインスタンスのライフサイクルを制御します。

• 再利用：backend_details に instance_id を渡すと、同じインスタンスで複数のジョブを実行できます。複数ステップのワークフローに効率的です。
• 一時的なインスタンス：instance_id を省略すると、ハンドラーはジョブごとに新しいインスタンスを作成します。環境はクリーンですが、時間がかかります（インスタンスの起動に約 2～5 分）。

インスタンスの作成 — 配置情報

複数のクラウド認証情報またはワークスペースグループが設定されているアカウントでは、brev create を単独で実行すると配置エラーになります。アカウント固有の ID を明示的に渡してください。

brev create my-instance \
  --gpu L40S:1 \
  --cloud-cred-id <cloudCredId> \
  --workspace-group-id <workspaceGroupId>

値を一度確認し、~/.config/tao/.env に保存してください。

brev ls --json | jq -r '.workspaces[0].workspaceGroupId'   # default group
brev orgs --json | jq -r '.[0].cloudCredentials[].id'      # cloud credential

SDK を使用する場合は、backend_details を通じて値を渡してください。

BrevSDK().create_job(
    ...,
    backend_details={
        "cloud_cred_id": "<cloudCredId>",
        "workspace_group_id": "<workspaceGroupId>",
    },
)

マルチ GPU とマルチノード

Brev はマルチノードに対応していません。 Brev はインスタンスベースです。1 つのジョブは 1 つのインスタンスで実行され、インスタンス間の連携機能はありません。

単一インスタンス上のマルチ GPU には対応しています（最大 8 基の H100／A100／L40S を利用できるインスタンスがあります）。gpu_count はインスタンス上の GPU 数に対応します。torchrun --nproc-per-node=N または PyTorch DDP はインスタンス内で動作します。

GPU の種類

brev search で利用可能です。

• L40S、A100 80GB、H100（利用状況はプロバイダーによって異なります）
• GPU 名で絞り込むには --gpu-name、必要なメモリを指定するには --min-vram を使用します

ストレージ

共有 NFS／Lustre はありません。すべてのデータは、script_runner の fsspec 統合を介して S3 経由でやり取りされます。ログインユーザーのホームディレクトリ（$HOME）配下にあるインスタンスローカルのディスクは、停止／起動後も保持されますが、削除／作成をまたいでは保持されません。

Brev 上の Docker

VM Mode インスタンスには Docker がプリインストールされています。TAO コンテナーイメージの場合：

# NGC auth (one-time per instance)
brev exec <instance> -- docker login nvcr.io -u '$oauthtoken' -p <NGC_KEY>

# Run a TAO training job
brev exec <instance> -- docker run --gpus all --rm \
  -v $HOME/data:/data \
  nvcr.io/nvidia/tao/tao-toolkit:6.26.3-pyt \
  visual_changenet train -e /data/spec.yaml

最初の brev exec の前にインスタンスの準備完了を待つ

新しく作成したインスタンスは、sshd、ホスト名の解決、ユーザーシェルの準備が整うずっと前に RUNNING を報告します。準備が整っていないインスタンスに対する最初の brev exec は、hostname not resolvable、Connection refused、または無応答のタイムアウトで失敗します。実際の処理を指示する前に、簡単な exec が成功するまで必ずポーリングしてください。

# Wait up to 5 minutes for shell readiness — covers the SSH bring-up window.
for i in $(seq 1 60); do
  brev exec <instance> -- true >/dev/null 2>&1 && break
  sleep 5
done
brev exec <instance> -- true >/dev/null 2>&1 || {
  echo "instance <instance> never became exec-ready"; exit 1;
}

コールドスタートのワークロードでの brev exec のタイムアウト

brev exec 自体にはデフォルトのタイムアウトはありませんが、それをラップするもの（SDK ハンドラー、CI ステップラッパー、timeout シェル組み込みコマンド）では、新しいインスタンスでの SSH の起動時間とコンテナーのプルの両方にかかる時間を見込む必要があります。新しいインスタンスでの最初の exec には 600 秒（10 分）以上を設定してください。以前のデフォルトである 60～120 秒ではリモートの起動が途中で打ち切られ、リモートコマンドがまだ進行中であるにもかかわらず、誤って exec failed が発生します。

混合プラットフォームのワークフロー

同じワークフロー内で Brev と Lepton を組み合わせられます。ステージごとのプラットフォーム割り当て：

{"skill": "vcn-gap-analysis", "action": "analyze", "platform": "brev"},
{"skill": "visual-changenet", "action": "train", "platform": "lepton"}

CPU ステージ（ギャップ分析、データのマージ）は Brev 上で低コストで実行できます。GPU ステージ（トレーニング）は Lepton H100 上で実行されます。

クリーンアップ

brev delete <instance>      # plain delete — no flags

CLI は --yes／-y を受け付けません。指定すると unknown flag: --yes というエラーになります。最近の CLI では brev delete <instance> はすでに非対話的なため、確認フラグは不要です。

エラーパターン

brev CLI が見つからない：https://docs.nvidia.com/brev/ からインストールしてください。

BREV_API_TOKEN を設定していても brev ls が認証 EOF を返す：ヘッドレスシェルには、対話型認証プロンプトへの入力に使える stdin がありません。最初に brev login --token "$BREV_API_TOKEN" を実行してから、再試行してください。1 回再試行しても失敗する場合は、トークン自体が古くなっています。新しいトークンを発行してください。

トークンの有効期限切れ：ハンドラーは brev login --token を使用して自動的に再認証します。解決しない場合は、手動で brev login を実行してください。

配置エラー（cloudCredId／workspaceGroupId が必要）により brev create が拒否される：複数の認証情報または複数のワークスペースがあるアカウントでは、--cloud-cred-id および／または --workspace-group-id を指定する必要があります。上記の「インスタンスの作成 — 配置情報」を参照してください。

作成直後に hostname not resolvable または Connection refused で brev exec が失敗する：インスタンスは sshd の起動前に RUNNING を報告します。実際のコマンドを実行する前に、「最初の brev exec の前にインスタンスの準備完了を待つ」にある準備完了待ちループを使用してください。

新しいインスタンスで SDK exec がタイムアウトする／exec failed が発生する：SDK の brev exec ラッパーが、リモートの起動完了前にタイムアウトしました。コールドスタートの実行では、タイムアウトを 600 秒以上に延ばしてください（「コールドスタートのワークロードでの brev exec のタイムアウト」を参照）。

brev delete --yes：unknown flag: --yes：CLI には確認フラグがありません。brev delete <instance> をそのまま使用してください。

インスタンスがプロビジョニング中のままになる：一部の GPU タイプは利用可能数が限られています。別の --gpu-name またはプロバイダーを試してください。

nvcr.io からの Docker のプルに失敗する：NGC_KEY が設定されていないか、有効期限が切れています。インスタンス上で docker login nvcr.io を実行してください。