Brev

NVIDIA Brev fournit des instances GPU à la demande sur plusieurs fournisseurs cloud. Les instances sont préconfigurées avec les drivers NVIDIA, CUDA, Docker et NVIDIA Container Toolkit.

Brev est basé sur les instances (et non sur les jobs comme Lepton). Vous créez une instance, exécutez des commandes dessus via brev exec, et la supprimez quand vous avez terminé. Le BrevHandler du TAO SDK encapsule cela dans l'interface job standard.

Vérifications préalables

Cette compétence nécessite le CLI brev, sa compétence agent associée (brev-cli), et une connexion active. Vérifiez avant de continuer :

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

# 2. compétence agent brev-cli installée — fournit la référence des commandes du CLI brev à l'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. connexion brev active — effectuez toujours une connexion par token en premier lors d'une exécution sans interface.
#    Un simple `brev ls` affichera une invite d'authentification interactive (c.-à-d. EOF sur stdin)
#    même quand BREV_API_TOKEN est défini, alors rafraîchissez la session d'abord.
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
# Réessayez une fois après une re-connexion forcée : les identifiants en cache se désynchronisent parfois et le
# premier `brev ls` retourne un EOF d'authentification jusqu'à ce que la session soit reconstruite.
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
  }
}

Si une étape échoue, l'agent demande à l'utilisateur d'autoriser le correctif via Bash, puis réexécute les vérifications préalables avant de continuer. Le TAO SDK n'est pas obligatoire pour Brev — brev exec docker run … suffit. N'utilisez le SDK que si vous voulez des handles Job, un wrapping d'E/S S3 via script_runner, ou une persistance d'état ; nvidia-tao-sdk est sur le PyPI public, installez l'extra Brev épinglée depuis versions.yaml : pip install "$("${TAO_SKILL_BANK_PATH:?}/scripts/resolve_versions_key.py" wheels.tao_sdk_brev)". Quand vous utilisez la route SDK, lisez tao-skill-bank:tao-run-platform pour la référence des kwargs BrevSDK, build_entrypoint, et les motifs ActionWorkflow.

Authentification

Deux options :

1. Automatisée (recommandée) : Obtenez un token API depuis la page des paramètres de la console Brev. Définissez BREV_API_TOKEN comme variable d'environnement (par exemple, dans ~/.config/tao/.env). Le handler s'authentifie automatiquement via brev login --token à la première utilisation — même UX que Lepton.

2. Manuelle : Exécutez brev login (ouvre le navigateur). Les tokens expirent toutes les heures — le handler les rafraîchit automatiquement.

Les identifiants S3 (ACCESS_KEY, SECRET_KEY) sont nécessaires séparément pour le transfert de données.

Sans interface / non-interactif

Dans un shell CI, un conteneur, ou une session agent sans TTY contrôlant, exécutez toujours brev login --token "$BREV_API_TOKEN" avant tout autre appel brev — même quand le token est exporté. Sinon le CLI demande sur stdin et retourne une erreur d'authentification EOF sur des commandes comme brev ls, brev create, ou brev exec. Réexécutez la connexion par token si un appel retourne une authentification-EOF ; un seul rafraîchissement suffit généralement.

Vérifications préalables au lancement

Avant de générer des scripts ou de soumettre des jobs :

1. Vérifiez que BREV_API_TOKEN est défini.
2. Vérifiez que le CLI brev est installé et peut lister les instances, par exemple brev ls --json. Si nécessaire, authentifiez-vous avec brev login --token.
3. Pour les datasets/résultats s3://, vérifiez que ACCESS_KEY et SECRET_KEY sont définis et que les chemins exacts sont lisibles avec aws s3 ls.
4. N'acceptez pas d'entrées /path locales pour Brev sauf si l'utilisateur a prouvé que ces chemins existent sur l'instance Brev cible ou y sont montés.
5. Vérifiez les identifiants spécifiques au modèle comme HF_TOKEN avant le lancement.

Cycle de vie des instances

L'agent contrôle le cycle de vie des instances :

• Réutilisation : Passez instance_id dans backend_details pour exécuter plusieurs jobs sur la même instance. Efficace pour les workflows multi-étapes.
• Éphémère : Omettez instance_id — le handler crée une nouvelle instance par job. Propre mais plus lent (démarrage de l'instance ~2-5 min).

Créer une instance — informations de placement

Pour les comptes ayant plus d'une credential cloud ou groupe workspace, un simple brev create rejette l'appel avec une erreur de placement. Passez les identifiants spécifiques au compte explicitement :

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

Découvrez les valeurs une fois et stockez-les dans ~/.config/tao/.env :

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

Quand vous utilisez le SDK, passez-les via backend_details :

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

Multi-GPU et multi-nœud

Le multi-nœud n'est pas supporté sur Brev. Brev est basé sur les instances — un job s'exécute sur une instance, sans coordination inter-instances.

Le multi-GPU sur une seule instance est supporté (instances disponibles avec jusqu'à 8× H100 / A100 / L40S). gpu_count correspond au nombre de GPUs sur l'instance ; torchrun --nproc-per-node=N ou PyTorch DDP fonctionnent au sein de l'instance.

Types de GPU

Disponibles via brev search :

• L40S, A100 80GB, H100 (la disponibilité varie selon le fournisseur)
• Utilisez --gpu-name pour filtrer, --min-vram pour les besoins en mémoire

Stockage

Pas de NFS/Lustre partagé. Toutes les données passent par S3 via l'intégration fsspec du script_runner. Le disque local de l'instance sous le répertoire home de l'utilisateur de connexion ($HOME) persiste à travers un arrêt/démarrage mais pas à travers une suppression/création.

Docker sur Brev

Les instances en Mode VM ont Docker pré-installé. Pour les images de conteneur TAO :

# Authentification NGC (une fois par instance)
brev exec <instance> -- docker login nvcr.io -u '$oauthtoken' -p <NGC_KEY>

# Exécutez un job d'entraînement TAO
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

Attendez que l'instance soit prête avant le premier brev exec

Une instance nouvellement créée signale RUNNING bien avant que sshd, la résolution de nom d'hôte, et le shell utilisateur ne soient prêts. Le premier brev exec sur une instance non stabilisée échoue avec hostname not resolvable, Connection refused, ou un délai d'attente silencieux. Interrogez toujours jusqu'à ce qu'un exec trivial réussisse avant d'émettre un vrai travail :

# Attendez jusqu'à 5 minutes pour que le shell soit prêt — couvre la fenêtre de démarrage SSH.
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;
}

Délai d'attente brev exec pour les charges de travail de démarrage à froid

brev exec n'hérite d'aucun délai d'attente par défaut, mais tout ce qui l'enveloppe (le handler SDK, les wrappers d'étapes CI, les builtins timeout du shell) doit laisser du temps à la fois pour la fenêtre de démarrage SSH et la traction du conteneur sur une instance fraîche. Utilisez ≥ 600 s (10 min) pour le premier exec sur une nouvelle instance ; le défaut de 60–120 s précédent tronque le démarrage distant et apparaît comme un exec failed faux même si la commande distante progresse encore.

Workflows multi-plateformes

Brev peut être mélangé avec Lepton dans le même workflow. Attribution de plateforme par étape :

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

Les étapes CPU (gap analysis, data merge) s'exécutent peu cher sur Brev. Les étapes GPU (entraînement) s'exécutent sur les H100s Lepton.

Nettoyage

brev delete <instance>      # suppression simple — pas de flags

Le CLI n'accepte pas --yes / -y ; le passer échoue avec unknown flag: --yes. brev delete <instance> est déjà non-interactif sur les CLIs récents, donc aucun flag de confirmation n'est nécessaire.

Motifs d'erreur

CLI brev introuvable : Installez depuis https://docs.nvidia.com/brev/.

brev ls retourne auth EOF même avec BREV_API_TOKEN défini : Le shell sans interface n'a pas de stdin pour l'invite d'authentification interactive. Exécutez brev login --token "$BREV_API_TOKEN" d'abord, puis réessayez. Si l'échec persiste à travers un seul nouveau essai, le token lui-même est périmé — générez-en un nouveau.

Token expiré : Le handler auto-rafraîchit via brev login --token. Si c'est persistant, exécutez brev login manuellement.

brev create rejeté avec erreur de placement (cloudCredId / workspaceGroupId requis) : Les comptes multi-credentials ou multi-workspace doivent passer --cloud-cred-id et/ou --workspace-group-id. Voir Créer une instance — informations de placement ci-dessus.

brev exec échoue avec hostname not resolvable ou Connection refused juste après create : L'instance signale RUNNING avant que sshd soit opérationnel. Utilisez la boucle d'attente de disponibilité dans Attendez que l'instance soit prête avant le premier brev exec avant d'émettre la vraie commande.

Timeout exec SDK / exec failed sur une instance fraîche : Le wrapper brev exec du SDK a expiré avant la fin du démarrage distant. Augmentez le timeout à ≥ 600 s pour les exécutions de démarrage à froid (voir Délai d'attente brev exec pour les charges de travail de démarrage à froid).

brev delete --yes : unknown flag: --yes : Le CLI n'a pas de flag de confirmation. Utilisez un simple brev delete <instance>.

Instance bloquée en provisioning : Certains types de GPU ont une disponibilité limitée. Essayez un --gpu-name ou un fournisseur différent.

La traction Docker échoue sur nvcr.io : NGC_KEY non défini ou expiré. Exécutez docker login nvcr.io sur l'instance.