Evo 2 NIM

Utilisez Evo 2 pour la génération d'ADN et, localement, l'extraction de sorties de couches. Chargez les fichiers supplémentaires uniquement si nécessaire :

references/api.md : schémas exacts, noms de couches, flags Docker, notes matérielles.
references/science.md : cas d'usage génomiques, limites et interprétation.
references/parameters.md : effets des paramètres de génération/forward.
references/validation.md : contrôles d'ADN, probabilité, timing et tenseurs.
references/examples.md : motifs de requêtes hébergées/locales compacts.

Instructions

Pour la génération, utilisez scripts/generate.py pour exécuter la requête, valider la réponse et enregistrer ses artefacts. Résolvez le chemin du script relativement au répertoire de cette skill et choisissez un répertoire de sortie dans l'espace de travail de l'utilisateur. Utilisez la séquence de l'utilisateur et les paramètres demandés ; l'exemple ci-dessous n'est qu'un test de fumée.

Sélectionnez le mode demandé. Pour la génération hébergée, allez directement à l'exemple de génération ; la configuration Docker et les passes forward locales sont des tâches séparées.
Lorsque l'utilisateur demande d'exécuter la génération, exécutez le client et inspectez son code de sortie et son résultat. Écrire un script seul ne complète pas cette requête.
Rapportez l'ADN généré (ou son fichier pour les longues séquences), elapsed_ms réels, résumé des probabilités échantillonnées, seed et chemins des artefacts de l'exécution réussie. Lisez la réponse enregistrée ou les métriques si un résultat n'est pas clair.

Si la requête ou la validation échoue, rapportez l'échec réel et tous les fichiers de diagnostic. Ne remplacez pas une réponse API indisponible par des valeurs d'exemple. Pour une requête code uniquement, fournissez la commande sans effectuer d'appel d'inférence.

Choisir le mode

Respectez NIM_API_MODE lorsqu'il est défini. Les valeurs acceptées sont hosted et local. S'il n'est pas défini, traitez un EVO2_NIM_URL explicite comme local ; sinon demandez lorsque le mode demandé n'est pas clair :

API NVIDIA hébergée ou Evo 2 NIM Docker local ?

Génération hébergée : https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate
URL de base locale : $EVO2_NIM_URL, avec secours à http://localhost:8000
Génération locale : $EVO2_NIM_URL/biology/arc/evo2/generate
Sorties forward/couches locales : $EVO2_NIM_URL/biology/arc/evo2/forward

Résolvez toujours les routes de santé et d'inférence locales à partir de EVO2_NIM_URL lorsqu'elle est présente. localhost fonctionne uniquement lorsque l'appelant et le NIM partagent un espace de noms réseau ; un appelant dans un conteneur séparé a généralement besoin d'une URL de service telle que http://evo2-nim:8000. Ne changez pas silencieusement de mode lorsque le point de terminaison sélectionné est indisponible. Rapportez le point de terminaison ayant échoué et corrigez sa configuration.

La documentation hébergée expose la génération. /forward est documenté pour Docker local ; n'inventez pas un point de terminaison /forward hébergé. Les requêtes hébergées utilisent Authorization: Bearer $NGC_API_KEY. Le démarrage Docker local supporté utilise NGC_API_KEY (ou NVIDIA_API_KEY via la vérification préalable) pour la connexion au registre, les vérifications de droits et les téléchargements de modèles au premier lancement ; passez-le au conteneur avec -e NGC_API_KEY. Les requêtes d'inférence locales n'utilisent pas d'en-tête d'authentification après la disponibilité. Le démarrage sans clé à cache chaud varie selon l'image/version et ne doit pas être supposé.

Exemples

Normalisez les prompts avant d'envoyer. Utilisez A/C/G/T sauf si les bases ambiguës sont un choix de modélisation délibéré et clairement rapporté.

Pour une requête de génération hébergée, exécutez le client fourni avec les entrées de l'utilisateur (le chemin du script ci-dessous est relatif au répertoire de la skill) :

python scripts/generate.py \
  --mode hosted \
  --sequence ACTGACTGACTGACTG \
  --num-tokens 64 --seed 1 \
  --temperature 0.7 --top-k 3 --top-p 0.0 \
  --output-dir /path/to/workspace/evo2-output

Pour un NIM local déjà prêt, utilisez --mode local ; le client résout EVO2_NIM_URL et n'envoie pas d'en-tête Authorization. Il ne change jamais de point de terminaison après une requête ayant échoué. Définissez --timeout pour une lecture plus longue si l'utilisateur demande une génération plus grande ; les requêtes ayant échoué ne sont pas automatiquement renvoyées.

Le client enregistre request.json, la réponse réelle response.json, generated.fasta et metrics.json dans le répertoire de sortie choisi. Il enregistre également le corps de la réponse exact dans response.raw avant de vérifier le statut HTTP ou d'analyser JSON, afin que les diagnostics survivent à du JSON malformé et à des valeurs non finies de probabilité/timing. Il valide le nombre demandé de bases générées, l'alphabet A/C/G/T, les probabilités échantillonnées finies dans [0, 1] et les timings non négatifs avant d'imprimer un résumé réussi. Les répertoires existants ne sont jamais réutilisés, même s'ils sont vides. Choisissez un répertoire de sortie qui n'existe pas ; le client le crée de manière atomique pour que les exécutions concurrentes ne puissent pas écraser les artefacts les uns des autres. Le FASTA contient uniquement les bases générées, pas le prompt d'entrée prepended à nouveau.

sampled_probs est demandé par le client et résumé avec count/min/max/mean ; les valeurs complètes restent dans la réponse enregistrée. Un tableau de probabilités manquant ou malformé est un échec de validation, pas une permission d'inventer des valeurs de confiance. Demandez enable_logits uniquement dans une requête personnalisée lorsque c'est nécessaire ; les logits peuvent rendre les réponses volumineuses. Voir references/api.md pour les payloads personnalisés. random_seed prend en charge la reproductibilité du développement, non la certitude biologique.

Exigences Docker local

Le déploiement local d'Evo 2 nécessite des GPUs capables de FP8. Ne présentez pas A100 comme compatible ; A100 peut extraire l'image mais échoue au warmup car FP8 nécessite une capacité de calcul de 8,9 ou supérieure.

40B par défaut : 2x H100 80 GB ou 1x H200 141 GB. Utilisez NIM_TEST_GPUS=0,1 pour 2x H100, ou NIM_TEST_GPUS=0 pour un H200.
Secours 7B : définissez NIM_VARIANT=7b ; les GPUs supportés incluent H100, H200, RTX 6000 Ada et L40S.
Disque approximatif : 110 GB pour 40B, 50 GB pour 7B.

Utilisez d'abord l'env shell ; sourcez .env à la racine du repo uniquement s'il est présent. N'inventez pas une valeur par défaut de cache ou ne supprimez pas le secours NVIDIA_API_KEY.

set -a
[ -f .env ] && . ./.env
set +a

if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
  export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"

echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin

# 40B par défaut : 0,1 pour 2x H100 ; définissez 0 pour un seul H200.
export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0,1}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 700 "${LOCAL_NIM_CACHE}"   # owner-only; si le NIM s'exécute avec un UID différent, ajoutez -u "$(id -u)" à docker run

# Pour 7B : export NIM_VARIANT=7b; export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0}"
docker run --rm -it --name evo2-nim \
  --runtime=nvidia \
  --gpus "\"device=${NIM_TEST_GPUS}\"" \
  -e NGC_API_KEY \
  -e NIM_VARIANT \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/arc/evo2:2

Disponibilité :

evo2_nim_url="${EVO2_NIM_URL:-http://localhost:8000}"
until curl -sf "${evo2_nim_url%/}/v1/health/ready"; do sleep 10; done

Si RTX PRO 6000 Blackwell Workstation échoue sans backend d'attention Transformer Engine, traitez-le comme en dehors de la matrice validée actuelle et relancez sur un GPU/runtime documenté.

Pass Forward local

Forward retourne des tenseurs NPZ codés en base64.

import base64
import io
import os
import numpy as np
import requests

mode = os.getenv("NIM_API_MODE", "local")
if mode != "local":
    raise RuntimeError("Evo 2 /forward is available only in local mode")
nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000").rstrip("/")
sequence = "ACTGACTGACTG"  # Replace with the user's DNA sequence.
sequence = "".join(sequence.upper().split())
if not sequence or set(sequence) - set("ACGT"):
    raise ValueError("Expected nonempty A/C/G/T DNA")
payload = {
    "sequence": sequence,
    "output_layers": ["output_layer", "decoder.layers.3.self_attention"],
}
response = requests.post(
    f"{nim_url}/biology/arc/evo2/forward",
    headers={"Content-Type": "application/json"},
    json=payload,
    timeout=300,
)
response.raise_for_status()
npz_bytes = base64.b64decode(response.json()["data"])
with open("evo2_forward_outputs.npz", "wb") as handle:
    handle.write(npz_bytes)
arrays = np.load(io.BytesIO(npz_bytes), allow_pickle=False)
for name in arrays.files:
    arr = arrays[name]
    print(name, arr.shape, arr.dtype, bool(np.isfinite(arr).all()), float(arr.mean()))

Valider et rapporter

Enregistrez les JSON de requête/réponse, le FASTA généré et un JSON de métriques avec longueur de séquence, fraction GC, fraction de bases ambiguës, longueur d'homopolymère, vérifications de probabilités échantillonnées et timing écoulé. Traitez un schéma invalide ou un alphabet comme des échecs durs ; traitez un GC extrême, une faible complexité, des doublons et des motifs manquants comme des avertissements. Pour des vérifications plus profondes, lisez references/validation.md.

Champs clés : sequence, num_tokens, temperature, top_k (0-6), top_p (0-1), random_seed, enable_sampled_probs, enable_elapsed_ms_per_token et enable_logits optionnel.

Dépannage

401/403 : clé hébergée manquante/expirée ou non envoyée en tant que token Bearer.
422 : noms de champs incorrects tels que max_tokens au lieu de num_tokens.
Confusion de point de terminaison local : imprimez NIM_API_MODE et EVO2_NIM_URL ; ne remplacez pas une URL de service configurée par localhost.
Confusion d'authentification locale : n'envoyez pas Authorization à l'inférence locale.
Démarrage local : la première exécution télécharge les ressources du modèle ; interrogez $EVO2_NIM_URL/v1/health/ready avant l'inférence.
Échec FP8 : utilisez le mode hébergé, 7B sur un GPU FP8 supporté ou des GPUs 40B documentés.