Msa Search Nim

MSA-Search NIM

Generate protein MSAs with GPU-accelerated MMSeqs2. Use this guide for first-pass hosted/local usage; load supplemental files only when needed:

• references/api.md: exact endpoints, schemas, Docker flags, response fields.
• references/science.md: MSA purpose, pairing/templates, limits, handoffs.
• references/parameters.md: database, pairing, depth, and template tuning.
• references/validation.md: alignment, template, and artifact checks.
• references/examples.md: compact hosted/local request patterns.

Choose Mode And Endpoint

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

• Hosted standard MSA: https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict
• Hosted paired MSA: https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict
• Local standard MSA: http://localhost:8000/biology/colabfold/msa-search/predict
• Local paired MSA: http://localhost:8000/biology/colabfold/msa-search/paired/predict
• Local templates: http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict

Local inference paths do not include /v1/. Hosted requests use Authorization: Bearer $NGC_API_KEY. Supported local Docker startup uses NGC_API_KEY (or NVIDIA_API_KEY via the preflight) for registry login, entitlement checks, and first-run model downloads; pass it into the container with -e NGC_API_KEY. Local inference requests use no auth header after readiness. Warm-cache key-free startup varies by image/version and should not be assumed. The hosted template path returned HTTP 404 in validation, so use local Docker for template search unless the hosted docs/service changes.

Local Docker

Default local deployment = parallel download + NIM_MODEL_NAME. The first recipe below is the one to use for real workflows. It downloads the database(s) with a range-parallel downloader (aria2c) and starts the NIM against those files — ~14 min for UniRef30 vs >80 min for the NIM's built-in downloader (measured, H100). Do not reach for the plain docker run (the "Fallback" subsection) unless you only want a databases:pdb70 smoke test or you deliberately want the NIM to manage its own blob cache.

Local setup requires a GPU. Size the NVMe volume to the profile you pick (UniRef30 ~490 GB; full set ~1.4 TB). For setup answers, include env preflight, docker login, the parallel download, NIM_MODEL_NAME launch, readiness, and then no-auth local inference. Do not invent a cache default or drop the NVIDIA_API_KEY fallback.

# --- env preflight (do not drop the NVIDIA_API_KEY fallback) ---
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}"          # where the parallel download lands

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

# --- 1) pick the DB version(s) you need (paired/complex work = uniref30 only) ---
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) parallel download from NGC (see "Parallel Download" section for the all-DB loop) ---
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) launch the NIM against the downloaded files (skips the slow built-in download) ---
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

Readiness:

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

If the DB is already present in $DB_DIR, skip steps 1-2 — the launch alone is a ~20 s warm start. See "Parallel Download For Any Database Set" for the multi-database (databases:all) loop and the full rationale.

Fallback: Let The NIM Download Its Own Databases (slower)

Use this only for a quick databases:pdb70 smoke test, or when you specifically want the NIM to manage its own blob cache. It uses the built-in downloader, which is slow on large profiles (UniRef30 stalled past 80 min in testing). Pin the smallest profile with NIM_MODEL_PROFILE (see "Faster Startup") so it does not fetch the full 1.4 TB.

: "${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

Faster Startup: Task-Specific Database Profiles

The full database download is ~1.4 TB and can take well over an hour on first launch. If you only need some databases, select a task-specific profile so the NIM downloads just those. This is the single biggest lever on local startup time.

List the profiles your image actually ships (hashes change between releases — never hardcode them):

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

Then pass the chosen hash with 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

Profiles available in this image (confirm hashes with list-model-profiles):

Verify the loaded profile after readiness:

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

Notes:

• The request-level databases parameter only selects among databases already downloaded; it does NOT change what is fetched at startup. Startup footprint is set by NIM_MODEL_PROFILE alone.
• Paired search needs UniRef30 only. colabfold_envdb_202108 has no taxonomy and cannot be used for pairing, so databases:uniref30 is the correct, smallest profile for complex/paired workflows — it skips the envdb, the largest part of the full set.
• For maximum monomer sensitivity (UniRef30 + envdb merged) you still need databases:all; there is no envdb-inclusive profile smaller than the full set.

Custom Or Individual Databases

To use a single manually downloaded database (or your own MMSeqs2 DB), download it from NGC and point the NIM at the mount with NIM_MODEL_NAME instead of a profile:

ngc registry model download-version nim/colabfold/msa-search:uniref30_2302-m18v1
# then mount the directory and set -e NIM_MODEL_NAME=/databases

NIM_MODEL_NAME replaces the profile databases entirely — the NIM uses only what is under that directory (discovered by scanning for **/*.idx). Mount multiple databases under one parent to combine them. NGC-downloaded databases are pre-indexed for GPU Server; custom databases must be indexed with mmseqs createindex first. Individually downloadable NGC model versions: uniref30_2302-m18v1, colabfold_envdb_202108-m18v1, pdb70_220313-m18v1, pdb100_230517-m18v1, pdb_20251028_zip-m18v1.