tao-run-on-brev

Brev

NVIDIA Brev 在多个云服务提供商处提供按需 GPU 实例。实例预装了 NVIDIA 驱动、CUDA、Docker 和 NVIDIA Container Toolkit。

Brev 基于实例（不像 Lepton 那样基于作业）。你可以创建实例，通过 brev exec 在实例上运行命令，并在完成后删除实例。TAO SDK 的 BrevHandler 会将此流程封装为标准作业接口。

前置检查

此技能需要 brev CLI、配套的 Agent 技能（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
  }
}

如果任何步骤失败，Agent 会提示用户通过 Bash 授权修复，然后重新运行前置检查，再继续操作。Brev 无需 TAO SDK——brev exec docker run … 已足够。只有在需要 Job 句柄、通过 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，请阅读 tao-skill-bank:tao-run-platform，了解 BrevSDK 关键字参数参考、build_entrypoint 和 ActionWorkflow 模式。

身份验证

有两种方式：

1. 自动（推荐）：从 Brev 控制台设置页面获取 API 令牌。将 BREV_API_TOKEN 设置为环境变量（例如，写入 ~/.config/tao/.env）。处理程序会在首次使用时通过 brev login --token 自动进行身份验证，体验与 Lepton 相同。

2. 手动：运行 brev login（会打开浏览器）。令牌每小时过期一次，处理程序会自动刷新。

数据传输还需要单独提供 S3 凭据（ACCESS_KEY、SECRET_KEY）。

无头／非交互模式

在没有控制 TTY 的 CI shell、容器或 Agent 会话中，务必在任何其他 brev 调用之前 运行 brev login --token "$BREV_API_TOKEN"， 即使令牌已导出。否则 CLI 会从 stdin 提示输入，并在 brev ls、brev create 或 brev exec 等命令中返回 EOF 身份验证错误。如果调用返回身份验证 EOF，请重新运行令牌登录；通常刷新一次 就足够了。

启动前检查

生成脚本或提交作业前：

1. 确认已设置 BREV_API_TOKEN。
2. 确认已安装 brev CLI，且能够列出实例，例如 brev ls --json。如有需要，请使用 brev login --token 进行身份验证。
3. 对于 s3:// 数据集／结果，确认已设置 ACCESS_KEY 和 SECRET_KEY， 并且可以使用 aws s3 ls 读取确切路径。
4. 除非用户已证明本地 /path 输入在目标 Brev 实例上存在或已挂载到该实例， 否则不要将其用于 Brev。
5. 在启动前确认模型专用凭据（例如 HF_TOKEN）已设置。

实例生命周期

Agent 控制实例生命周期：

• 复用：在 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 基于实例——一个作业在一个实例上运行，实例之间无法协调。

支持在单个实例上使用多 GPU（实例最多配备 8 张 H100／A100／L40S）。gpu_count 对应实例上的 GPU 数量；torchrun --nproc-per-node=N 或 PyTorch DDP 均可在实例内运行。

GPU 类型

可通过 brev search 查找：

• L40S、A100 80GB、H100（可用性因提供商而异）
• 使用 --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 前等待实例就绪

新创建的实例很早就会报告状态为 RUNNING，此时 sshd、主机名解析和用户 shell 尚未就绪。对尚未稳定的实例首次执行 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 shell 内置命令）都必须为 SSH 启动窗口和新实例上的容器拉取留出时间。对新实例上的首次 exec，请使用 ≥ 600 s（10 分钟）；此前 60–120 s 的默认值会截断远程启动过程，并显示误导性的 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 仍返回 auth EOF：无头 shell 没有 stdin，无法响应交互式身份验证提示。请先运行 brev login --token "$BREV_API_TOKEN"，然后重试。如果重试一次后仍然失败，说明令牌本身已过期——请重新生成令牌。

令牌已过期：处理程序会通过 brev login --token 自动刷新。如果问题持续存在，请手动运行 brev login。

brev create 因放置错误（需要 cloudCredId / workspaceGroupId）而被拒绝：使用多个凭据或多个工作区的账户必须传入 --cloud-cred-id 和/或 --workspace-group-id。请参阅上文的创建实例 — 放置信息。

创建实例后立即执行 brev exec，却出现 hostname not resolvable 或 Connection refused：实例会在 sshd 启动前就报告状态为 RUNNING。执行实际命令前，请使用首次执行 brev exec 前等待实例就绪中的就绪等待循环。

新实例上的 SDK exec 超时 / exec failed：SDK 的 brev exec 封装器在远程启动完成前就超时了。冷启动运行时，请将超时时间提高到 ≥ 600 s（参见冷启动工作负载的 brev exec 超时）。

brev delete --yes：unknown flag: --yes：CLI 没有确认标志。请直接使用 brev delete <instance>。

实例卡在配置中状态：某些 GPU 类型的可用量有限。请尝试其他 --gpu-name 或提供商。

从 nvcr.io 拉取 Docker 镜像失败：未设置 NGC_KEY 或令牌已过期。请在实例上运行 docker login nvcr.io。