Boltz2 NIM

Prédire des structures biomoléculaires et l'affinité de ligand optionnelle. Utilisez ce guide pour un premier passage en mode hébergé/local ; chargez les fichiers supplémentaires uniquement si nécessaire :

references/api.md : endpoints exacts, schémas, flags Docker, champs de réponse.
references/science.md : objectif, forces, limitations et transitions.
references/parameters.md : prédiction, sampling, MSA, template, tuning affinité.
references/validation.md : mmCIF, confiance, affinité et vérifications chimiques.
references/examples.md : patterns de payload compacts hébergés/locaux.

Instructions

Lisez les identifiants depuis l'environnement uniquement si nécessaire. Vérifiez la présence avec bool(os.getenv("NGC_API_KEY")); tenez les valeurs de clé et les en-têtes Authorization en dehors de la sortie terminal, des logs, des artefacts sauvegardés et de la réponse finale. Évitez les dumps d'environnement lors du diagnostic d'authentification. Si la clé hébergée est absente, signalez la variable manquante avant de soumettre une requête.

Choisir le mode

Posez la question uniquement si le contexte n'est pas clair :

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

Hébergé : https://health.api.nvidia.com/v1/biology/mit/boltz2/predict
Local : http://localhost:8000/biology/mit/boltz2/predict

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 droit et les téléchargements de modèles à la première exécution ; transmettez-la au conteneur avec -e NGC_API_KEY. Les requêtes d'inférence locales n'utilisent aucun en-tête d'authentification après la disponibilité. Le démarrage sans clé avec cache chaud varie selon l'image/version et ne doit pas être supposé.

Docker local

Pour les réponses de configuration locale, copiez la vérification préalable ci-dessous avant docker login, docker run, la disponibilité et la requête locale sans authentification. N'inventez pas une valeur par défaut de cache et ne supprimez pas le chargement .env ou le fallback 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

mkdir -p "${LOCAL_NIM_CACHE}"
chmod 755 "${LOCAL_NIM_CACHE}"

docker run --rm --name boltz2 --gpus all \
  --shm-size=16G \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/mit/boltz2:1.6.0

Disponibilité :

until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done

Le premier démarrage télécharge environ 30 GB de poids de modèle.

Exemples

Requête de prédiction

import os
import requests

HOSTED = True
url = (
    "https://health.api.nvidia.com/v1/biology/mit/boltz2/predict"
    if HOSTED else "http://localhost:8000/biology/mit/boltz2/predict"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
    api_key = os.getenv("NGC_API_KEY")
    if not api_key:
        raise SystemExit("NGC_API_KEY is required for the hosted API")
    headers["Authorization"] = f"Bearer {api_key}"

payload = {
    "polymers": [{
        "id": "A",
        "molecule_type": "protein",
        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT",
    }],
    "recycling_steps": 3,
    "sampling_steps": 50,
    "diffusion_samples": 1,
    "step_scale": 1.638,
    "output_format": "mmcif",
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

Essentiels du payload :

Polymère protéique : {"molecule_type": "protein", "sequence": "..."}.
Polymère ADN/ARN : ajoutez un autre polymère avec molecule_type "dna" ou "rna".
Ligand par SMILES : {"id": "L1", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}.
Ligand par CCD : {"id": "L1", "ccd": "ATP"}.
Affinité : définissez "predict_affinity": True sur exactement un ligand ; signalez affinity_pic50, affinity_pred_value et affinity_probability_binary.
MSA A3M préalculé va sous le polymère protéique. Le record A3M utilise alignment, format et rank ; n'utilisez pas un champ data obsolète.

protein_with_msa = {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
    "msa": {"msa_search": {"a3m": {
        "alignment": ">query\nMTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
        "format": "a3m",
        "rank": 0,
    }}},
}

Sauvegarder et rapporter la sortie

Sauvegardez chaque artefact .cif et lisez les champs confiance/affinité en utilisant l'extrait dans references/examples.md sous Save Structures And Affinity. Visualisez dans PyMOL, ChimeraX ou UCSF Chimera. Pour les vérifications de bon sens confiance/affinité, lisez references/validation.md.

Limites et dépannage

Polymères/requête : 12. Ligands/requête : 20. Longueur de chaîne : 4 096 résidus.
La prédiction d'affinité supporte un ligand par requête et ajoute du temps d'exécution.
422 : séquence invalide, CCD/SMILES invalide, MSA malformé ou plusieurs ligands affinité.
URL/authentification locale : le chemin local n'a pas d'en-tête d'authentification hébergé ; attendez /v1/health/ready.
Démarrage local : utilisez --gpus all, --shm-size=16G et le mount /opt/nim/.cache.

boltz2-nim