Task-Specific Profiles and Custom Databases | NVIDIA BioNeMo NIM Documentation

To choose a database, you can use task-specific profiles or custom databases.

Task-Specific Profiles

The MSA Search NIM includes task-specific profiles that download only the databases required for specific use cases. This reduces storage requirements and startup time.

Listing Available Profiles

To list available profiles:

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

Example output:

MODEL PROFILES
- Compatible with system:
    - 3087b7ea46d601200c1f90c9246a7aa344e487056286497515900b0924d7853a - databases:pdb70|nim_workspace_hash_v1:ab60c4867c3a8ea0613d73003dd9c7debf99925f57a00573de53f0990be8fcb6
    - 6875cb887326718705de1a4d1200b6043fcbdc0a10584dae64ec9dd724d7e047 - databases:all|nim_workspace_hash_v1:72d640b7ae022cda571cca6ef79d0731b11fd9d9e7f52ea53824ad4b31205e5f
    - 9146beba16db6be936e05104095b8fa6f9b0bd7c08356e5b5f50575cf0dd3e65 - databases:uniref30,pdb70,pdb|nim_workspace_hash_v1:67fe40488c771bb66d49916402f521e3b447ebd505a550c669c99e57f44f5b3f
    - 9a7645c82f54583fd741726cb1faf8de9d3a0e0849b50476590402394041a54e - databases:uniref30|nim_workspace_hash_v1:1cbe92b4f059c31d28389ca0cf1e97fa0b47c04b54d4de0eb3c4f9e392520181

Selecting a Profile

To select a specific profile, use the NIM_MODEL_PROFILE environment variable with the profile hash from list-model-profiles. The example below uses the PDB70-only profile (databases:pdb70, roughly ~100 MB on disk)—a small quick-start choice. Profiles that include Uniref30 (for example the databases:uniref30 hash) require on the order of ~500 GB. For more information, refer to Available Profiles.

export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"
docker run -it --rm \
  --runtime=nvidia \
  --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_PROFILE=3087b7ea46d601200c1f90c9246a7aa344e487056286497515900b0924d7853a \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

To verify the selected profile after the service starts:

curl localhost:8000/v1/metadata | jq

Available Profiles

Profile Tags	Databases	Best For	Storage
`databases:pdb70`	PDB70	Minimal profile with PDB sequences clustered at 70% identity. Useful for quick testing.	~100 MB
`databases:uniref30`	Uniref30	Paired MSA search for protein complexes. Uniref30 is the only database used for species-based sequence pairing.	~500 GB
`databases:uniref30,pdb70,pdb`	Uniref30, PDB70, PDB structures	Structural template search. Includes databases for profile building (Uniref30), template search (PDB70), and mmCIF structure files (PDB).	~700 GB
`databases:all`	Uniref30, ColabFold envdb, PDB70, PDB100, PDB structures	Full MSA search with all available databases. Provides maximum sensitivity and coverage.	~1.2 TB

Profile hashes may change between NIM releases. Always use list-model-profiles to get the current hashes for your version.

Custom Databases

You can use custom or manually downloaded MMSeqs2 databases with the MSA Search NIM by mounting them into the container and configuring the NIM_MODEL_NAME environment variable.

Custom databases completely replace the default databases. When you set NIM_MODEL_NAME, the NIM will only use databases found in that directory — it will not mix custom databases with the default model profile databases. If you need multiple databases, download them individually from NGC and mount them all under the same NIM_MODEL_NAME directory.

Prerequisites

Before proceeding, ensure the following prerequisites are met:

Your databases are in MMSeqs2 format, created using mmseqs createdb or compatible tools.
For GPU Server support (enabled by default), databases must be indexed with mmseqs createindex. Refer to Indexing Databases for GPU Server for instructions. Databases downloaded from NGC are already indexed and ready for GPU Server use.

Specifying Custom Databases

Mount your custom database directory into the Docker container and set the NIM_MODEL_NAME environment variable inside the container pointing to the mounted directory.

Example: Loading a Manually Downloaded Database

You can test this process by manually downloading one of the MSA Search databases and instructing NIM to load it as a custom database. This example uses PDB70, the smallest database, suitable for quick testing.

Set the required variables and paths:

DATABASE=pdb70_220313-m18v1
DATABASE_PATH="$PWD/msa-search_v$DATABASE/pdb70_220313"

Download the database and adjust permissions (the ngc CLI creates owner-only files that the container’s nvs user cannot read):

ngc registry model download-version nim/colabfold/msa-search:$DATABASE
chmod -R 755 "$DATABASE_PATH"

Run the NIM with the appropriate mount points and environment variables:

docker run -it --rm \
  --runtime=nvidia \
  --gpus all \
  -e NIM_MODEL_NAME=/databases \
  -v "$DATABASE_PATH":/databases/pdb70_220313:ro \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

Test the service with a simple query:

curl http://localhost:8000/biology/colabfold/msa-search/predict \
  -H "Content-Type: application/json" \
  -d '{"sequence": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH"}'

If your custom databases are not indexed for GPU Server, refer to Indexing Databases for GPU Server for instructions on how to create the required index.

To mount multiple databases, add additional -v flags for each database directory, all under the same NIM_MODEL_NAME: -v "$DB1_PATH":/databases/db1:ro -v "$DB2_PATH":/databases/db2:ro

Available Databases

The following databases can be downloaded individually from NGC:

Database	NGC Model Version	Description
uniref30_2302	`uniref30_2302-m18v1`	UniRef30 clustered sequences for profile building
colabfold_envdb_202108	`colabfold_envdb_202108-m18v1`	ColabFold environmental database
pdb70_220313	`pdb70_220313-m18v1`	PDB sequences clustered at 70% identity for template search
pdb100_230517	`pdb100_230517-m18v1`	PDB sequences clustered at 100% identity
pdb_20251028	`pdb_20251028_zip-m18v1`	mmCIF structure files for template search

Database Directory Structure

Custom databases should be organized with each database in its own subdirectory under NIM_MODEL_NAME. The NIM automatically discovers databases by scanning for MMSeqs2 database files. For example,

/databases/
├── pdb70_220313/
│   ├── pdb70_220313.dbtype
│   ├── pdb70_220313.idx
│   └── ...
└── other_database/
    └── ...

Database Discovery

The NIM automatically discovers databases at startup using glob patterns:

Sequence databases: The NIM scans for **/*.idx files (MMSeqs2 index files). Each .idx file found registers a searchable database. The database name is derived from the parent directory name (for example, pdb70_220313/pdb70_220313.idx registers as pdb70_220313).

PDB structure archive: For structural template search, the NIM looks for a **/pdb*.zip file containing mmCIF structure files. This archive is used to retrieve 3D structures for template hits.

The discovery patterns can be customized using environment variables:

NIM_MSA_DB_INDEX_PATTERN: Pattern for sequence database discovery (default: **/*.idx)
NIM_MSA_PDB_CIFS_ZIP: Pattern for PDB structure archive (default: **/pdb*.zip)

For additional configuration options and environment variables, refer to the Configuration Guide.