tao-run-on-brevSkill tao-run-on-brev

---

名称: tao-run-on-brev description: Brev 管理的 GPU 实例，支持 Docker。当需要在 Brev GPU 实例上运行 TAO 训练、评估或推理，管理 Brev 部署，或通过 Brev CLI 调度 TAO 作业时使用。触发短语包括“在 Brev 上运行”、“Brev GPU 实例”、“提交作业到 Brev”、“Brev CLI 部署”。 license: Apache-2.0 compatibility: 需要 brev CLI (https://github.com/brevdev/brev-cli) 和有效的 brev 登录。 metadata: author: NVIDIA 公司 version: “0.1.0” allowed-tools: 读取 Bash tags:

• gpu
• 计算
• 基于实例
• brev

---

Brev

独立安装？ 如果此会话不是由 TAO 技能库插件初始化的，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

NVIDIA Brev 提供跨多个云提供商的按需 GPU 实例。实例预装了 NVIDIA 驱动、CUDA、Docker 和 NVIDIA 容器工具包。

Brev 是基于实例的（不是基于作业的）。您创建实例，通过 brev exec 在实例上运行命令，并在完成后删除实例。TAO SDK 的 BrevHandler 将其封装到标准作业接口中。

预检

此技能需要 brev CLI 和有效登录。在继续之前检查：

# 1. 是否安装 brev CLI
command -v brev >/dev/null 2>&1 || {
  echo "缺少: 未安装 brev CLI。请安装:"
  echo "  https://docs.nvidia.com/brev/"
  exit 1
}

# 2. brev 命令参考可用。
brev --help >/dev/null || {
  echo "缺少: brev CLI 帮助不可用；请验证 brev 安装。"
  exit 1
}

# 3. brev 登录有效 — 在无人值守运行时始终先进行令牌登录。
#    即使设置了 BREV_API_TOKEN，直接运行 `brev ls` 会遇到交互式认证提示（读取: 标准输入 EOF），
#    因此请先刷新会话。
if [ -n "$BREV_API_TOKEN" ]; then
  brev login --token "$BREV_API_TOKEN" >/dev/null 2>&1 || {
    echo "缺少: brev 令牌登录失败。请验证 BREV_API_TOKEN。"
    exit 1
  }
fi
# 在强制重新登录后重试一次：缓存的凭据偶尔会失去同步，第一次 `brev ls` 会返回认证 EOF，
# 直到会话重建。
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 "缺少: 未登录到 brev。请运行:"
    echo "  brev login                                    # 交互式（打开浏览器）"
    echo "  # 或在启动前在 shell 中导出 BREV_API_TOKEN（然后执行 'brev login --token \$BREV_API_TOKEN'）"
    exit 1
  }
}

如果任何非 pip 步骤失败，代理会提示用户通过 Bash 授权修复，然后在继续之前重新运行预检。Brev 不需要 TAO SDK — brev exec <实例> "docker run …" 就足够了。仅当您想要作业句柄、通过 script_runner 的 S3 I/O 包装或状态持久化时才使用 SDK；nvidia-tao-sdk 在公共 PyPI 上；自动从固定的 Brev extra 安装缺失的 SDK 依赖：python -m pip install "nvidia-tao-sdk[brev]==7.1.0rc42" <!-- versions-key: wheels.tao_sdk_brev -->。当选择 SDK 路线时，请阅读 tao-skill-bank:tao-run-platform 以获取 BrevSDK 关键字参数参考、build_entrypoint 和 ActionWorkflow 模式。

身份验证

有两种选择：

1. 自动化（推荐）：从 Brev 控制台设置页面获取 API 令牌。将 BREV_API_TOKEN 设置为环境变量（例如，在 shell 中 export BREV_API_TOKEN=...）。处理器在首次使用时通过 brev login --token 自动进行身份验证。

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

S3 凭据（ACCESS_KEY、SECRET_KEY）需要单独用于数据传输。

无头 / 非交互式

在 CI shell、容器或没有控制 TTY 的代理会话中，始终在其他 brev 调用之前先运行 brev login --token "$BREV_API_TOKEN" — 即使令牌已导出。否则 CLI 会在标准输入上提示，并在 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. 除非用户已证明这些路径存在于目标 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>

发现值一次并在启动前在 shell 中导出它们：

brev ls --json | jq -r '.workspaces[0].workspaceGroupId'   # 默认组
brev orgs --json | jq -r '.[0].cloudCredentials[].id'      # 云凭据

使用 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。实例本地磁盘在 ~/，在停止/启动之间保留，但在删除/创建后不会保留。

Brev 上的 Docker

VM 模式实例预装了 Docker。

brev exec 语法 — 远程命令是一个带引号的字符串

CLI 签名是 brev exec [实例...] <命令>：每个除了最后一个之外的位置参数都被视为实例名称，而 -- 只终止标志解析 — 它不会将后面的单词组合成单个命令。因此，多令牌形式 brev exec <实例> -- docker run --gpus all … <!-- lint-ok: brev-exec-form --> 使 CLI 将 docker、run、… 视为实例名称，并以 could not look up instance "docker" / illegal option -- -（退出码 255）失败 — 这个错误看起来像是 SSH/实例故障，但实际上是语法故障。单令牌探测（brev exec <实例> -- true）<!-- lint-ok: brev-exec-form --> “成功”只是因为孤立的令牌被解析为命令；绝不将其视为执行健康的证明。始终将整个远程命令作为一个带引号的字符串传递：

brev exec <实例> "docker --version"

NGC 认证 + 运行 TAO 容器

# NGC 认证（每个实例一次性）。密钥通过标准输入传输 — 切勿放入 argv，
# 否则它会出现在实例进程表、brev 转发的 SSH 命令字符串和会话记录中。
printf '%s' "$NGC_KEY" | brev exec <实例> "docker login nvcr.io -u '\$oauthtoken' --password-stdin"

# 在不读取凭据文件的情况下验证登录：清单检查仅在登录有效且密钥的组织具有该图像的权限时才成功。
TAO_PYT_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.1.0-pyt  # versions-key: images.tao_toolkit.pyt
brev exec <实例> "docker manifest inspect $TAO_PYT_IMAGE >/dev/null && echo AUTH_OK || echo AUTH_FAIL"

# 运行 TAO 训练作业 — 整个 docker run 是一个带引号的字符串。
brev exec <实例> "docker run --gpus all --rm -v ~/data:/data $TAO_PYT_IMAGE visual_changenet train -e /data/spec.yaml"

在第一次 brev exec 之前等待实例就绪

一个新创建的实例在 sshd、主机名解析和用户 shell 准备好之前很久就报告 RUNNING。对未稳定实例的第一次 brev exec 会失败并显示 hostname not resolvable、Connection refused 或静默超时。在发出实际工作之前，始终轮询直到平凡的 exec 成功。探测必须是一个多词带引号的命令：它既证明 SSH 就绪，也证明每个真实命令都依赖的单字符串 exec 形式（单纯的 true 探测即使在所有多令牌命令都会失败时也能通过）：

# 等待最多 5 分钟让 shell 就绪 — 覆盖 SSH 启动窗口。
for i in $(seq 1 60); do
  [ "$(brev exec <实例> "echo ok" 2>/dev/null)" = "ok" ] && break
  sleep 5
done
[ "$(brev exec <实例> "echo ok" 2>/dev/null)" = "ok" ] || {
  echo "实例 <实例> 从未准备好 exec"; exit 1;
}

冷启动工作负载的 brev exec 超时

brev exec 没有默认超时，但任何包装它的东西（SDK 处理器、CI 步骤包装器、timeout shell 内置命令）都必须留出时间，既包括 SSH 启动窗口，也包括新实例上的容器拉取。对于新实例上的首次 exec，使用 ≥ 600 秒（10 分钟）；之前的 60–120 秒默认值会截断远程启动，并表现为虚假的 exec failed，即使远程命令仍在进行中。

清理

brev delete <实例>      # 简单删除 — 没有标志

CLI 不接受 --yes / -y；传递它会报错 unknown flag: --yes。brev delete <实例> 在最近的 CLI 上已经是非交互式的，因此不需要确认标志。

错误模式

找不到 brev CLI：从 https://docs.nvidia.com/brev/ 安装。

即使设置了 BREV_API_TOKEN，brev ls 返回认证 EOF：无头 shell 没有用于交互式认证提示的标准输入。先运行 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 之前实例就绪 中的就绪等待循环。

could not look up instance "<word>" / ssh: illegal option -- - / 多词 brev exec 上退出码 255：远程命令作为单独的令牌传递（brev exec <实例> -- docker run …）。<!-- lint-ok: brev-exec-form --> CLI 将每个除了最后一个之外的位置参数解析为实例名称，因此 docker、run、… 被查找为实例，并且散落的 --flags 泄漏到 ssh。将整个远程命令作为一个带引号的字符串传递：brev exec <实例> "docker run …"。请参阅上面的 brev exec 语法。

SDK exec 超时 / 新实例上的 exec failed：SDK 的 brev exec 包装器在远程启动完成前超时。对于冷启动运行，将超时提高到 ≥ 600 秒（请参阅 冷启动工作负载的 brev exec 超时）。

brev delete --yes: unknown flag: --yes：CLI 没有确认标志。使用简单的 brev delete <实例>。

实例卡在置备中：某些 GPU 类型可用性有限。尝试不同的 --gpu-name 或提供商。

Docker 拉取 / docker manifest inspect 在 nvcr.io 上失败：有两种不同的原因 — 通过登录状态区分它们：

• 实例上之前没有 Login Succeeded：未认证 — NGC_KEY 未设置、已过期或登录从未运行。使用 NGC 认证 + 运行 TAO 容器 中的标准输入登录，并使用有效的密钥重新运行。
• 登录成功但拉取/检查仍返回 Access Denied / unauthorized：密钥可以认证，但其 NGC 组织无权访问图像的 org（例如预发布暂存 org）。请求组织访问或选择密钥可以读取的 org 中的镜像 — 重新运行登录没有帮助。