MSA-Search NIM

Générez des MSA protéiques avec MMSeqs2 accéléré par GPU. Utilisez ce guide pour une utilisation hébergée/locale en première passe ; 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 MSA, appairage/templates, limites, handoffs.
• references/parameters.md : tuning de base de données, appairage, profondeur et templates.
• references/validation.md : vérifications d'alignement, template et artefacts.
• references/examples.md : motifs de requêtes compacts hébergés/locaux.

Choisir le mode et l'endpoint

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

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

• MSA standard hébergé : https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict
• MSA appairé hébergé : https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict
• MSA standard local : http://localhost:8000/biology/colabfold/msa-search/predict
• MSA appairé local : http://localhost:8000/biology/colabfold/msa-search/paired/predict
• Templates local : http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict

Les chemins d'inférence locaux n'incluent pas /v1/. 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 le preflight) pour la connexion au registre, les vérifications de droit 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 disponibilité. Le démarrage sans clé avec cache chaud varie selon l'image/version et ne doit pas être supposé. Le chemin template hébergé a retourné HTTP 404 en validation, utilisez donc Docker local pour la recherche de templates à moins que la documentation/service hébergé ne change.

Docker local

Déploiement local par défaut = téléchargement parallèle + NIM_MODEL_NAME. La première recette ci-dessous est celle à utiliser pour les flux de travail réels. Elle télécharge la(les) base(s) de données avec un téléchargeur parallèle par plage (aria2c) et démarre le NIM par rapport à ces fichiers — ~14 min pour UniRef30 vs >80 min pour le téléchargeur intégré du NIM (mesuré, H100). Ne choisissez pas le simple docker run (la section « Fallback ») à moins que vous ne vouliez juste un test de fumée databases:pdb70 ou que vous vouliez délibérément que le NIM gère son propre cache blob.

La configuration locale nécessite un GPU. Dimensionnez le volume NVMe au profil que vous choisissez (UniRef30 ~490 GB ; ensemble complet ~1,4 TB). Pour les réponses de configuration, incluez le preflight env, docker login, le téléchargement parallèle, le lancement NIM_MODEL_NAME, la disponibilité, puis l'inférence locale sans authentification. N'inventez pas une valeur par défaut de cache et ne supprimez pas le fallback NVIDIA_API_KEY.

# --- env preflight (ne supprimez pas 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}"
: "${DB_DIR:=/data/fast-db}"          # où le téléchargement parallèle aboutit

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

# --- 1) choisir la(les) version(s) de DB que vous avez besoin (appairage/complexe = uniref30 uniquement) ---
DB_VERSION=uniref30_2302-m18v1
command -v aria2c >/dev/null || { echo "aria2c required; install it (e.g. apt-get install -y aria2) and re-run"; exit 1; }
mkdir -p "$DB_DIR"

# --- 2) téléchargement parallèle depuis NGC (voir la section « Parallel Download » pour la boucle all-DB) ---
curl -fsS -H "Authorization: Bearer $NGC_API_KEY" \
  "https://api.ngc.nvidia.com/v2/org/nim/team/colabfold/models/msa-search/${DB_VERSION}/files" \
  -o /tmp/files.json
DB_DIR="$DB_DIR" python3 - <<'PY'
import json, os
d = json.load(open("/tmp/files.json")); dbdir = os.environ["DB_DIR"]; lines = []
for url, path in zip(d["urls"], d["filepath"]):
    lines += [url.strip(), f"  dir={dbdir}", f"  out={path}"]
open("/tmp/aria.in", "w").write("\n".join(lines) + "\n")
PY
aria2c -i /tmp/aria.in --max-concurrent-downloads=4 --max-connection-per-server=16 \
  --split=16 --min-split-size=1M --continue=true --file-allocation=none

# --- 3) lancer le NIM par rapport aux fichiers téléchargés (ignore le téléchargement intégré lent) ---
docker run -d --name msa-search --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_NAME=/databases \
  -v "${DB_DIR}:/databases" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

Disponibilité :

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

Si la DB est déjà présente dans $DB_DIR, ignorez les étapes 1-2 — le lancement seul est un démarrage chaud ~20 s. Voir « Parallel Download For Any Database Set » pour la boucle multi-base (databases:all) et la justification complète.

Fallback : Laisser le NIM télécharger ses propres bases de données (plus lent)

Utilisez ceci uniquement pour un test de fumée rapide databases:pdb70, ou quand vous voulez spécifiquement que le NIM gère son propre cache blob. Il utilise le téléchargeur intégré, qui est lent sur les grands profils (UniRef30 s'est bloqué au-delà de 80 min en test). Épinglez le plus petit profil avec NIM_MODEL_PROFILE (voir « Faster Startup ») pour qu'il ne récupère pas les 1,4 TB complets.

: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
mkdir -p "${LOCAL_NIM_CACHE}"; chmod 755 "${LOCAL_NIM_CACHE}"
docker run --rm --name msa-search \
  --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_PROFILE=<hash-from-list-model-profiles> \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

Démarrage plus rapide : profils de bases de données spécifiques à la tâche

Le téléchargement complet de la base de données est ~1,4 TB et peut prendre bien plus d'une heure au premier lancement. Si vous ne besoin que de certaines bases de données, sélectionnez un profil spécifique à la tâche pour que le NIM ne télécharge que ceux-ci. C'est le levier unique le plus important sur le temps de démarrage local.

Listez les profils que votre image expédie réellement (les hashes changent entre les versions — ne les codez jamais en dur) :

docker run --rm --entrypoint list-model-profiles nvcr.io/nim/colabfold/msa-search:2

Ensuite, passez le hash choisi avec NIM_MODEL_PROFILE :

docker run --rm --name msa-search \
  --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_PROFILE=<hash-from-list-model-profiles> \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

Profils disponibles dans cette image (confirmez les hashes avec list-model-profiles) :

Vérifiez le profil chargé après la disponibilité :

curl -s localhost:8000/v1/metadata | jq

Notes :

• Le paramètre databases au niveau de la requête sélectionne uniquement parmi les bases de données déjà téléchargées ; il ne change PAS ce qui est récupéré au démarrage. L'empreinte de démarrage est définie par NIM_MODEL_PROFILE seul.
• La recherche appairée a besoin d'UniRef30 uniquement. colabfold_envdb_202108 n'a pas de taxonomie et ne peut pas être utilisé pour l'appairage, donc databases:uniref30 est le profil correct et le plus petit pour les flux de travail complexe/appairé — il ignore l'envdb, la plus grande partie de l'ensemble complet.
• Pour la sensibilité monomère maximale (UniRef30 + envdb fusionnés), vous avez toujours besoin de databases:all ; il n'y a pas de profil incluant envdb plus petit que l'ensemble complet.

Bases de données personnalisées ou individuelles

Pour utiliser une base de données téléchargée manuellement unique (ou votre propre DB MMSeqs2), téléchargez-la depuis NGC et pointez le NIM vers le mount avec NIM_MODEL_NAME au lieu d'un profil :

ngc registry model download-version nim/colabfold/msa-search:uniref30_2302-m18v1
# puis montez le répertoire et définissez -e NIM_MODEL_NAME=/databases

NIM_MODEL_NAME remplace entièrement les bases de données du profil — le NIM n'utilise que ce qui est dans ce répertoire (découvert en analysant **/*.idx). Montez plusieurs bases de données sous un parent pour les combiner. Les bases de données téléchargées depuis NGC sont pré-indexées pour GPU Server ; les bases de données personnalisées doivent d'abord être indexées avec mmseqs createindex. Versions de modèle NGC téléchargeables individuellement : uniref30_2302-m18v1, colabfold_envdb_202108-m18v1, pdb70_220313-m18v1, pdb100_230517-m18v1, pdb_20251028_zip-m18v1.

Recommandé : téléchargement parallèle pour un ensemble de bases de données quelconques (déploiement rapide)

Ceci est la façon recommandée de télécharger les bases de données du tout — pour n'importe quel profil, y compris l'ensemble complet databases:all. Les profils spécifiques à la tâche réduisent ce que vous téléchargez ; ce téléchargeur parallèle réduit combien de temps ce téléchargement prend. Utilisez-le, que vous ayez besoin d'une base de données ou de toutes. Le gain est le plus important pour le profil databases:uniref30, qui est ~490 GB dominé par deux fichiers très volumineux (un index GPU ~241 GB et une DB de séquences ~134 GB).

Le téléchargeur intégré du NIM parallélise entre les fichiers (max_parallel_files=10) mais tire chaque fichier sur environ une connexion. Le CDN NGC accélère une connexion unique à ~20–25 MB/s, donc pendant que le téléchargeur récupère l'un des deux fichiers géants, la plupart de ses emplacements parallèles sont inactifs et le débit s'effondre à ce débit à flux unique. Mesuré sur un nœud H100, le chemin intégré n'a pas atteint /health/ready en plus de 80 minutes.

Un téléchargeur parallèle par plage divise chaque fichier en nombreux segments de plage d'octets (le CDN NGC annonce accept-ranges: bytes), donc un fichier unique de 241 GB est tiré sur 16 connexions à la fois — ~15× le débit à flux unique. Même nœud, aria2c a récupéré les ~490 GB complets en ~13,5 minutes.

Flux de travail (téléchargez une fois avec aria2, puis démarrez le NIM par rapport aux fichiers via NIM_MODEL_NAME) :

# 1) Obtenez les URL de fichiers signés pour la version de modèle de base de données individuelle depuis NGC.
#    (Nécessite NGC_API_KEY. Les tableaux de réponse `urls` et `filepath` sont appairés positionnellement.)
curl -s -H "Authorization: Bearer $NGC_API_KEY" \
  'https://api.ngc.nvidia.com/v2/org/nim/team/colabfold/models/msa-search/uniref30_2302-m18v1/files' \
  -o files.json

# 2) Construisez un fichier d'entrée aria2 (URL + nom de fichier cible par entrée) et téléchargez en parallèle.
python3 - <<'PY'
import json
d = json.load(open("files.json"))
lines = []
for url, path in zip(d["urls"], d["filepath"]):
    lines += [url.strip(), "  dir=/data/fast-db", f"  out={path}"]
open("aria.in", "w").write("\n".join(lines) + "\n")
PY
aria2c -i aria.in \
  --max-concurrent-downloads=4 --max-connection-per-server=16 --split=16 \
  --min-split-size=1M --continue=true --file-allocation=none

# 3) Démarrez le NIM par rapport au répertoire téléchargé. NIM_MODEL_NAME permet au NIM de découvrir
#    les bases de données en analysant **/*.idx, en contournant entièrement le profil/cache blob.
docker run -d --name msa-search --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_NAME=/databases \
  -v /data/fast-db:/databases \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

Pour toutes les bases de données (équivalent à databases:all), répétez l'étape 1 pour chaque version DB individuelle et téléchargez-les dans des répertoires frères sous un parent, puis pointez NIM_MODEL_NAME vers ce parent — le NIM découvre chaque DB en analysant **/*.idx :

# récupérez la liste de fichiers de chaque DB dans /data/all-db/<db>/ ... puis un aria2c par liste, ex. :
for V in uniref30_2302-m18v1 colabfold_envdb_202108-m18v1 pdb70_220313-m18v1 \
         pdb100_230517-m18v1 pdb_20251028_zip-m18v1; do
  curl -s -H "Authorization: Bearer $NGC_API_KEY" \
    "https://api.ngc.nvidia.com/v2/org/nim/team/colabfold/models/msa-search/$V/files" \
    -o "files_$V.json"
  # construisez une entrée aria2 à partir de files_$V.json (dir=/data/all-db) et exécutez aria2c dessus
done
# puis lancez une fois par rapport au parent :
#   docker run -d ... -e NIM_MODEL_NAME=/databases -v /data/all-db:/databases ...

Le CDN par connexion est le même pour chaque base de données, donc le téléchargement parallèle aide l'ensemble complet proportionnellement — plus vous téléchargez, plus il économise de temps absolu.

Notes :

• Les URL signés expirent (généralement en un jour) — construisez l'entrée aria2 et démarrez le téléchargement rapidement après la récupération de files.json.
• Conservez la disposition interne du répertoire téléchargé intacte (ex. uniref30_2302/…) ; les valeurs filepath l'encodent déjà. Le NIM a besoin du fichier .idx plus ses fichiers compagnons et les petits marqueurs .UNIREF30_READY / *.tar.gz.unpacked.
• Le goulot d'étranglement est le plafond par connexion du CDN, pas le disque local ou le CPU — un volume NVMe rapide écrit beaucoup plus vite que le réseau ne livre. Augmenter --split / --max-connection-per-server ne aide que jusqu'au plafond d'egress agrégé du nœud.
• Mieux encore : téléchargez le profil une fois, puis conservez le volume de cache (ou ce répertoire fast-db) et montez-le sur les nœuds futurs pour un démarrage chaud ~20 s sans re-téléchargement.

Requête MSA standard

Utilisez les noms de bases de données et clés de réponse exactes, sensibles à la casse.

Pour une recherche standard hébergée, exécutez le client fourni à partir du répertoire de cette skill. Il soumet la vraie requête, valide les deux résultats de base de données et enregistre les fichiers JSON bruts et A3M. Choisissez un nouveau répertoire de sortie pour chaque exécution :

python scripts/hosted_search.py \
  --sequence SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR \
  --output-dir msa-output

Le client lit NGC_API_KEY ou NVIDIA_API_KEY depuis l'environnement. Il permet au maximum deux requêtes, chacune avec un délai d'expiration de connexion de 10 secondes et un délai d'expiration de lecture de 300 secondes, avec cinq secondes entre les tentatives. S'il sort avec un code non nul, signalez l'échec du service et arrêtez-vous. Ne le redémarrez pas à plusieurs reprises, n'étendez pas les délais d'expiration au-delà du budget de tâche, ou ne remplacez pas la réponse manquante par des alignements synthétiques.

Le format de requête sous-jacent, également utilisable avec un NIM local en cours d'exécution, est :

import os
import requests

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

payload = {
    "sequence": "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR",
    "databases": ["Uniref30_2302", "colabfold_envdb_202108"],
    "e_value": 0.0001,
    "output_alignment_formats": ["a3m"],
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

Requête MSA appairée

Utilisez la recherche appairée pour les complexes protéiques ; le champ de payload est sequences au pluriel, et la sortie est alignments_by_chain.

url = (
    "https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict"
    if HOSTED else "http://localhost:8000/biology/colabfold/msa-search/paired/predict"
)
payload = {
    "sequences": [chain_a_sequence, chain_b_sequence],
    "e_value": 0.0001,
    "output_alignment_formats": ["a3m"],
}

Recherche de templates locale

Utilisez Docker local pour les templates structurels. Définissez max_msa_sequences=500 sauf si NIM_GLOBAL_MAX_MSA_DEPTH a été modifié.

url = "http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict"
headers = {"Content-Type": "application/json"}
payload = {
    "sequence": "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVA",
    "structural_template_databases": ["pdb70_220313"],
    "max_structures": 20,
    "max_msa_sequences": 500,
}

Enregistrer les sorties

# MSA standard : result["alignments"][database][format]["alignment"]
for db_name, formats in result.get("alignments", {}).items():
    for fmt_name, data in formats.items():
        with open(f"msa_{db_name}.{fmt_name}", "w", encoding="utf-8") as handle:
            handle.write(data["alignment"])

# MSA appairé : un ensemble d'alignements par chaîne
for chain_id, chain_data in result.get("alignments_by_chain", {}).items():
    for db_name, formats in chain_data.items():
        for fmt_name, data in formats.items():
            with open(f"msa_chain_{chain_id}_{db_name}.{fmt_name}", "w", encoding="utf-8") as handle:
                handle.write(data["alignment"])

# Recherche de templates : enregistrez les structures mmCIF et les tableaux de hits M8
for name, cif in result.get("structures", {}).items():
    open(f"template_{name}.cif", "w", encoding="utf-8").write(cif)
for name, hit_table in result.get("search_hits", {}).items():
    open(f"template_hits_{name}.m8", "w", encoding="utf-8").write(hit_table)

La sortie A3M peut alimenter OpenFold3, AlphaFold2, ou RoseTTAFold. Pour les vérifications de profondeur d'alignement, de template et de cohérence de séquence, lisez references/validation.md.

Limites et dépannage

• Longueur de séquence : 1-4096 acides aminés ; X fonctionne depuis v2.3.0.
• max_msa_sequences : 1-500 ; la valeur par défaut du serveur GPU local doit correspondre à NIM_GLOBAL_MAX_MSA_DEPTH.
• MSA appairé nécessite au moins deux séquences.
• Une URL 404 locale signifie généralement un préfixe /v1/ accidentel.
• La première exécution locale peut prendre des heures pendant que les bases de données remplissent LOCAL_NIM_CACHE.
• Les HTTP 502/503/504 hébergés ou les délais d'expiration de lecture répétés indiquent que la requête hébergée n'a pas été complétée. Vérifiez la disponibilité du service après la tentative limitée ; un délai d'expiration client plus long ne peut pas corriger une HTTP 504 générée par le serveur.
• N'inventez pas une URL de polling pour health.api.nvidia.com. L'exemple MSA standard publié utilise POST synchrone ; une réponse en attente a besoin d'un mécanisme de fin spécifique au service documenté avant de pouvoir compter comme un résultat.