OpenFold2 NIM

Prédire une structure de chaîne protéique unique à partir d'une séquence d'acides aminés, avec des alignements de séquences multiples A3M facultatifs et des templates mmCIF. Utilisez ce guide pour l'utilisation basique de NIM hébergé/local ; chargez les fichiers supplémentaires uniquement quand la tâche a besoin d'un contexte plus profond :

references/api.md : endpoints exacts, schémas, drapeaux Docker, champs de réponse.
references/science.md : portée du modèle, forces, limitations, et transferts.
references/parameters.md : effets MSA, template, sélection de modèle, et relax.
references/validation.md : vérifications d'artefacts et de validité scientifique.
references/examples.md : motifs de payload hébergés/locaux compacts.

Choisir le mode

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

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

URL hébergée : https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template
URL locale : http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template
Vérification locale : http://localhost:8000/v1/health/ready

Différence de mode : l'API hébergée et locale utilisent le même chemin de prédiction sauf que le local n'inclut pas /v1/. Les requêtes hébergées utilisent Authorization: Bearer $NGC_API_KEY ; les requêtes d'inférence locales n'utilisent pas d'en-tête d'authentification après vérification de disponibilité.

Auth et environnement

Ne pas afficher les clés API. Confirmez leur existence avec des tests shell, pas des echo.

L'hébergement a besoin de NGC_API_KEY dans l'en-tête de requête. Le démarrage Docker local supporté utilise NGC_API_KEY, ou NVIDIA_API_KEY comme fallback, plus LOCAL_NIM_CACHE. Un fichier .env à la racine du repo peut être sourcé comme override local.

Docker local

Utilisez l'image officielle OpenFold2 NIM et montez LOCAL_NIM_CACHE à /opt/nim/.cache. La documentation actuelle recommande au moins 80 GB de disque, 64 GB de RAM système, 8 cœurs CPU, et un GPU supporté ; le conteneur fait environ 55 GB et le premier démarrage télécharge environ 10 GB de paramètres de modèle.

Pour la vérification de démarrage exacte (sourçage .env, gestion NGC_API_KEY/NVIDIA_API_KEY, docker login, et le docker run pour nvcr.io/nim/openfold/openfold2:latest), copiez le bloc de commande dans references/api.md sous Local Docker textuellement — ne supprimez pas .env, NGC_API_KEY, LOCAL_NIM_CACHE, ou la requête locale sans authentification.

Vérification de disponibilité :

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

Motif de requête

Utilisez Python requests ; l'échappement curl est fragile pour le texte A3M/mmCIF. Le champ sequence est requis. input_id, alignments, selected_models, relax_prediction, use_templates, et explicit_templates sont optionnels.

import os
import requests

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

seq = "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT"
payload = {
    "sequence": seq,
    "input_id": "kras_fragment",
    "selected_models": [1],
    "relax_prediction": False,
    "alignments": {
        "uniref90": {
            "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 du payload :

OpenFold2 est monomère uniquement. Pour protéine-ligand, protéine-ADN/ARN, ou complexes multi-chaînes, utilisez OpenFold3 ou Boltz2 à la place.
sequence doit utiliser des symboles IUPAC d'acides aminés valides.
Les docs de l'API hébergée listent une longueur de séquence 1-1000 ; les docs locales disent que le NIM actuel supporte les séquences jusqu'à 2048 résidus sur le matériel supporté.
Les alignements A3M vont sous alignments par nom de base de données, puis a3m avec alignment et format. Quand l'utilisateur a besoin de créer ou d'approfondir une MSA, transférez à msa-search-nim / MSA Search et mappez sa sortie A3M dans cette forme alignments.
À partir d'OpenFold2 2.0.0, utilisez explicit_templates avec du contenu mmCIF ; n'écrivez pas de nouveaux exemples de templates HHR.
selected_models choisit les ensembles de paramètres AlphaFold2/OpenFold 1-5. Sélectionnez un ou deux modèles pour les tests de vérification ; utilisez les cinq pour des exécutions de production plus robustes.

Sauvegarder et interpréter la sortie

La réponse inclut une prédiction par modèle sélectionné, ordonnée par confiance. Sauvegardez chaque champ texte de structure retourné et la réponse JSON complète afin que les différences de forme de champ soient vérifiables. Les réponses de production doivent explicitement écrire les artefacts .pdb ou .cif, préserver la réponse JSON, et afficher tous les champs de confiance/classement que le service retourne.

from pathlib import Path
import json

Path("openfold2_response.json").write_text(json.dumps(result, indent=2))

def save_strings(obj, prefix="openfold2"):
    i = 0
    if isinstance(obj, dict):
        for key, value in obj.items():
            if isinstance(value, str) and ("ATOM" in value or value.lstrip().startswith("data_")):
                i += 1
                ext = "cif" if value.lstrip().startswith("data_") else "pdb"
                Path(f"{prefix}_{key}_{i}.{ext}").write_text(value)
            elif isinstance(value, (dict, list)):
                i += save_strings(value, f"{prefix}_{key}")
    elif isinstance(obj, list):
        for idx, value in enumerate(obj, start=1):
            if isinstance(value, (dict, list)):
                i += save_strings(value, f"{prefix}_{idx}")
    return i

saved = save_strings(result)
print(f"saved {saved} structure artifact(s)")

Pour les exécutions monomères de production :

Utilisez selected_models: [1, 2, 3, 4, 5] sauf si l'utilisateur demande un test de vérification.
Utilisez relax_prediction: True dans les payloads Python quand la relaxation est désirée ; les exemples JSON peuvent montrer true.
Énoncez la mise en garde sur la longueur de séquence : les docs de l'API hébergée listent 1-1000 résidus, tandis que les docs de la matrice de support locale listent jusqu'à 2048 résidus sur le matériel supporté.
Si la tâche est un complexe plutôt qu'un monomère, redirigez vers OpenFold3 ou Boltz2.

Traitez les minuscules séquences jouets et les MSA monoséquence comme des tests de vérification d'API, pas comme des preuves de qualité. Pour l'interprétation scientifique et la validation, lisez references/science.md et references/validation.md.

Dépannage

401 : clé API NGC manquante, expirée, ou non autorisée.
422 : caractères d'acides aminés invalides, séquence trop longue, A3M mal formée, selected_models mauvais, ou objet template mmCIF mal formé.
Local 404 : supprimez /v1/ de l'URL de prédiction.
Structures faibles : utilisez MSA Search pour générer des alignements A3M plus profonds et ajoutez les templates mmCIF biologiquement pertinents le cas échéant.
Le démarrage local s'arrête : la première exécution télécharge les paramètres dans LOCAL_NIM_CACHE.

openfold2-nim