OpenFold3 NIM

Prédisez des structures biomolécules avec OpenFold3. Il supporte les protéines, l'ADN, l'ARN, les petites molécules ligandes et les assemblages multi-entités. Utilisez ce guide pour l'utilisation basique du NIM hébergé et local ; chargez les fichiers supplémentaires uniquement quand la tâche nécessite un contexte plus approfondi :

references/api.md : endpoints exacts, schémas, drapeaux Docker, champs de réponse.
references/science.md : objectif, forces, limitations et transferts de modèle.
references/parameters.md : champs de molécules, MSAs, templates, samples, réglage.
references/validation.md : vérifications d'artefacts et contrôles de cohérence scientifique.
references/examples.md : motifs de requête compacts pour hébergé et local.

Choisir le mode

Posez la question uniquement si le contexte est flou :

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

URL hébergée : https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict
URL locale : http://localhost:8000/biology/openfold/openfold3/predict
Disponibilité locale : http://localhost:8000/v1/health/ready

Différence de mode : le chemin de prédiction local n'a pas de préfixe /v1/. Les requêtes hébergées utilisent Authorization: Bearer $NGC_API_KEY. Le démarrage local Docker supporté utilise NGC_API_KEY (ou NVIDIA_API_KEY via la vérification préalable) pour l'authentification au registre, les vérifications de droits et les téléchargements de modèles à la première exécution ; 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 vérification de disponibilité, donc liez le port hôte à loopback avec -p 127.0.0.1:8000:8000. Le démarrage sans clé avec cache chaud varie selon la version de l'image et ne doit pas être supposé.

Authentification et environnement

Utilisez les identifiants déjà fournis dans l'environnement ou injectés par un gestionnaire de secrets. Ne chargez pas de fichiers d'identifiants, n'imprimez pas de clés et n'activez pas le traçage shell. Confirmez l'existence des clés avec des tests shell.

L'hébergé nécessite NGC_API_KEY dans l'en-tête de requête. Le démarrage local nécessite NGC_API_KEY, ou NVIDIA_API_KEY comme secours, plus LOCAL_NIM_CACHE.

Docker local

Utilisez l'image OpenFold3 NIM officielle et montez LOCAL_NIM_CACHE à /opt/nim/.cache. Avant d'exécuter la configuration, expliquez que l'authentification au registre envoie la clé au registre NVIDIA à https://nvcr.io et le premier démarrage télécharge environ 10–15 Go de poids de modèle dans le cache. Exécutez le déploiement uniquement quand cela est demandé ; pour un guide de configuration, fournissez les commandes sans les exécuter.

Quand vous écrivez des commandes de configuration locale, copiez exactement le préambule ci-dessous. Ne le remplacez pas par une simple vérification : "${NGC_API_KEY:?Set NGC_API_KEY}", ne supprimez pas NVIDIA_API_KEY et n'inventez pas une LOCAL_NIM_CACHE par défaut ; ces lignes sont le contrat d'environnement NIM local du dépôt. Le lancement monogpu par défaut doit afficher le littéral --gpus "device=0" ; choisissez un appareil différent uniquement quand l'utilisateur le demande.

set +x

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

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

printf '%s\n' "$NGC_API_KEY" | \
  docker login nvcr.io --username '$oauthtoken' --password-stdin && \
docker run --rm --name openfold3 \
  --runtime=nvidia \
  --gpus "device=0" \
  --shm-size=16g \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 127.0.0.1:8000:8000 \
  nvcr.io/nim/openfold/openfold3:latest

Vérification de disponibilité :

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

Motif de requête

Utilisez requests.post(..., json=payload, timeout=300). Pour les tâches Docker locales, définissez hosted = False après que la vérification de disponibilité réussisse.

import os
import requests

hosted = True
url = (
    "https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict"
    if hosted
    else "http://localhost:8000/biology/openfold/openfold3/predict"
)
headers = {"Content-Type": "application/json"}
if hosted:
    headers["Authorization"] = f"Bearer {os.getenv('NGC_API_KEY')}"

seq = "MKTVRQERLKSIVR"
payload = {
    "inputs": [{
        "input_id": "prediction_1",
        "output_format": "pdb",
        "molecules": [{
            "type": "protein",
            "id": "A",
            "sequence": seq,
            "diffusion_samples": 1,
            "msa": {
                "main": {
                    "a3m": {
                        "alignment": f">query\n{seq}",
                        "format": "a3m"
                    }
                }
            }
        }]
    }]
}

response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

Pièges de payload :

Le niveau supérieur est {"inputs": [...]} et OpenFold3 accepte exactement une entrée.
molecules peut contenir 1-32 objets avec type : protein, dna, rna, ou ligand.
Les MSAs de protéine/ARN sont optionnels mais, quand fournis, alignment doit commencer avec un en-tête FASTA tel que >query\nSEQUENCE.
Les ligands utilisent soit smiles soit ccd_codes, par exemple {"type": "ligand", "id": "L", "ccd_codes": "ATP"}.
Les entités ADN/ARN utilisent sequence, par exemple {"type": "dna", "id": "B", "sequence": "ATCGATCG"}.
diffusion_samples est 1-5. output_format est pdb ou cif.

Enregistrer et interpréter la sortie

Enregistrez chaque structure retournée en tant qu'artefact scientifique. Chemin de réponse principal : result["outputs"][0]["structures_with_scores"].

output = result["outputs"][0]
for i, sample in enumerate(output["structures_with_scores"], start=1):
    fmt = sample["format"]
    with open(f"openfold3_structure_{i}.{fmt}", "w", encoding="utf-8") as fh:
        fh.write(sample["structure"])
    print("confidence_score", sample.get("confidence_score"))
    print("complex_plddt_score", sample.get("complex_plddt_score"))
    print("ptm_score", sample.get("ptm_score"))
    print("iptm_score", sample.get("iptm_score"))
    print("complex_pde_score", sample.get("complex_pde_score"))

Les confidence_score, complex_plddt_score, ptm_score et iptm_score plus élevés sont généralement meilleurs ; les complex_pde_score plus bas sont généralement meilleurs. Traitez les séquences jouets ou très courtes comme des tests de fumée d'API, non comme de la biologie structurale significative. Pour savoir pourquoi et quand OpenFold3 est scientifiquement approprié, consultez references/science.md.

Limites courantes

Entrées par requête : 1.
Molécules par entrée : 1-32.
Samples de diffusion : 1-5.
Le chemin TensorRT supporte les séquences plus courtes ; le chemin PyTorch peut supporter les séquences plus longues, mais les entrées longues ont besoin de beaucoup plus de mémoire GPU.
Les séquences de plus de environ 1 800 résidus nécessitent au moins 80 Go de mémoire GPU.
NIM local est monogpu uniquement ; choisissez l'appareil cible dans le drapeau Docker.

Dépannage

401 : clé NGC API manquante, expirée ou non autorisée.
422 : type de molécule invalide, caractères de séquence invalides, mauvaise forme de MSA, ou diffusion_samples en dehors de 1-5.
Erreurs MSA : assurez-vous que l'alignement commence par >query\n.
404 local : supprimez /v1/ de l'URL de prédiction.
Démarrage local qui stagne : la première exécution peut télécharger 10-15 Go de poids de modèle dans LOCAL_NIM_CACHE.
Erreurs de mémoire : raccourcissez la séquence, réduisez les samples, ou utilisez un GPU plus grand.

openfold3-nim