Skip to navigation

Configuration

View as Markdown

This section describes how to configure the MSA Search NIM container using environment variables, GPU selection, and volume mounting.

GPU Selection

By default, Docker uses all available GPUs on the system when started with the NVIDIA Container Runtime:

docker run --runtime=nvidia ...

To expose only specific GPUs to the container, use the --gpus flag:

docker run --gpus='"device=1"' ...

The device IDs are listed in the output of nvidia-smi -L. For more information on GPU selection, refer to the NVIDIA Container Toolkit documentation.

Environment Variables

The following environment variables can be passed to the NIM using the -e flag with docker run:

ENVRequired?DefaultNotes
NGC_API_KEYYesNoneYou must set this variable to the value of your personal NGC API key.
NIM_CACHE_PATHNo/opt/nim/.cacheLocation (in container) where the container caches model artifacts.
NIM_HTTP_API_PORTNo8000Port inside the container where the NIM service is published. When using the -p flag with docker run, ensure the right-hand side of the colon matches this value (for example, -p 8000:8000).
NIM_DISABLE_GPU_SERVERNoFalseControls the GPU Server for MMseqs2. The GPU Server is enabled by default for optimal performance with the included ColabFold databases. GPU Server requires MMseqs2 databases indexed for GPU use (for example with mmseqs createindex using parameters such as --split 1 and --index-subset 2 as described in Indexing Databases for GPU Server). Databases downloaded from NGC are already indexed correctly. Custom or third-party databases that are CPU-only, missing GPU index files, or built with incompatible index options may not work with GPU Server—set to True to run MMseqs2 on CPU instead.
NIM_GLOBAL_MAX_MSA_DEPTHNo500Sets the maximum number of MSA sequences returned, and is reflected as both the default and the maximum allowed value for the max_msa_sequences API parameter. Must be set globally for all requests when GPU Server is enabled (default in version 2.0.0).
NIM_MSA_API_MAX_DATABASESNo5Maximum number of databases that can be specified in a single API request.
NIM_MSA_API_MAX_ITERATIONSNo6Maximum value for the iterations API parameter.
NIM_MSA_API_MAX_CHAINSNo20Maximum number of chains (sequences) allowed in a paired MSA search request.
NIM_MSA_API_MAX_SEQUENCE_LENGTHNo4096Maximum length of an input protein sequence.
NIM_MSA_API_MAX_STRUCTURESNo1000Maximum value for the max_structures API parameter in template search requests.
NIM_MSA_API_SEQ_PATTERNNo^[ARNDCQEGHILKMFPSTWYVX]+$Regex pattern used to validate input protein sequences. Modify to accept non-standard amino acid characters.
NIM_MSA_API_DEFAULT_STRUCTURAL_TEMPLATE_DBSNopdb70_220313Comma-separated list of databases to search for structural templates by default.
NIM_MSA_COLABFOLD_DEFAULT_PROFILE_DBNouniref30_2302Database used as the profile (first) database in the cascaded ColabFold search pipeline. Must be one of the available databases.
NIM_MSA_EXPANDABLE_DBSNouniref30_2302,colabfold_envdb_202108Comma-separated list of databases that use the full cascaded expansion pipeline. Databases not in this list use a simpler non-expansion follow-up search.
NIM_MSA_DB_NAME_MAPPINGSNouniref30_2302:Uniref30_2302,pdb70_220313:PDB70_220313Comma-separated list of lowercase:DisplayName mappings for database names in API responses when using ["all"]. Used for backwards compatibility; will be removed in MSA 3.0 when all database names will resolve to lowercase.
NIM_MSA_DB_DISPLAY_NAMESNo(empty)Comma-separated list of db_name:Display Name overrides for human-readable database names returned by the /biology/colabfold/msa-search/config/msa-database-configs endpoint. Overrides the defaults in /opt/nim/msa/config.py. Example: my_custom_db:My Custom Database.
NIM_LOG_LEVELNoINFOSpecifies the level of logging detail. Available options: DEBUG, INFO, WARNING, ERROR.
NIM_MODEL_NAMENoNoneRoot directory inside the container under which databases are discovered (each database in its own subdirectory). The NIM scans for index files under this path (see NIM_MSA_DB_INDEX_PATTERN); pointing NIM_MODEL_NAME at a single database folder instead of the parent root can prevent discovery. Use with volume mounts to load external or custom MMseqs2 databases. Refer to Task-Specific Profiles and Custom Databases for details.
NIM_MODEL_PROFILENoNoneSelect a specific database profile by ID. Profiles allow reduced storage by loading only the databases needed for a particular task. Refer to Task-Specific Profiles and Custom Databases.
NIM_MSA_DB_INDEX_PATTERNNo**/*.idxGlob pattern for discovering sequence databases. The NIM scans for files matching this pattern under NIM_MODEL_NAME at startup. Database names are derived from the parent directory.
NIM_MSA_PDB_CIFS_ZIPNo**/pdb*.zipGlob pattern for discovering the PDB mmCIF structure archive. Used for retrieving 3D structures during structural template search.
NIM_GPUSERVER_STARTUP_TIMEOUT_SNo300Maximum time (seconds) to wait for a GPU server to become ready at startup.
NIM_GPUSERVER_STATUS_INTERVAL_SNo3Interval (seconds) between GPU server health-check status reports during startup.
NIM_TELEMETRY_MODENo0Controls telemetry collection. Set to 0 to disable telemetry (default), set to 1 to enable telemetry. Telemetry helps NVIDIA improve performance, compatibility, and reliability while maintaining strict privacy protections. For more information, refer to NVIDIA’s Privacy Policy and NIM Telemetry Settings.
NIM_TELEMETRY_ENABLE_LOGGINGNotrueEnables logging for telemetry operations when set to true. Only applicable when NIM_TELEMETRY_MODE=1.

Volumes

The following container paths can be mounted to local directories for persistent storage.

Container PathRequiredNotesDocker Argument Example
/opt/nim/.cache (or NIM_CACHE_PATH if set)RecommendedDirectory where model artifacts and databases are cached. If not mounted, the container will re-download on each startup. Ensure the local directory has read-write-execute permissions (chmod 0777). Example: mkdir -p ~/.cache/nim && chmod 0777 ~/.cache/nim-v ~/.cache/nim:/opt/nim/.cache
Custom path (set using NIM_MODEL_NAME env variable)OptionalMount custom databases by setting NIM_MODEL_NAME to the root directory under which each database appears as its own subdirectory inside the container, then mount host paths under that root. Do not set NIM_MODEL_NAME to one database folder only—use a parent path and mount each DB under it. Refer to Task-Specific Profiles and Custom Databases for detailed examples.-e NIM_MODEL_NAME=/databases -v /host/path/to/db:/databases/mydb:ro

The MODEL_PATH environment variable is also supported for backward compatibility with the same behavior as NIM_MODEL_NAME.

MMseqs2 Pipeline Tuning Environment Variables

The MSA Search NIM exposes several environment variables that control internal MMseqs2 pipeline parameters. These are set at container startup and apply globally to all requests. The cascaded search pipeline (used by both colabfold and template search) follows these steps per database:

  1. Search — Iterative profile search to find initial hits
  2. Expand — Recover remote homologs similar to initial hits
  3. Align — Sensitive realignment of expanded candidates
  4. Filter — Quality filtering (for example, query coverage, and sequence identity)
  5. result2msa — Convert filtered results to A3M alignment

The variables below tune the align and filter steps, which directly affect per-database output depth and, consequently, the size of the merged colabfold alignment.

Align-Step Parameters

These control how many targets and alternative alignments are kept during the post-expansion realignment. Together, max_accept and alt_ali determine the upper bound U on the untrimmed per-database sequence count: U ≤ max_accept × (1 + alt_ali).

VariableDefaultDescription
NIM_MMSEQS_PROFILE_ALIGN_MAX_ACCEPT100Maximum number of accepted targets per query in the profile (first-database) align step. Corresponds to mmseqs align --max-accept.
NIM_MMSEQS_FOLLOWUP_ALIGN_MAX_ACCEPT100Same as above, but for follow-up (subsequent database) align steps.
NIM_MMSEQS_PROFILE_ALIGN_ALT_ALI10Maximum number of alternative non-overlapping alignments per accepted target in the profile align step. Corresponds to mmseqs align --alt-ali. Each accepted target can produce up to 1 + alt_ali alignment rows.
NIM_MMSEQS_FOLLOWUP_ALIGN_ALT_ALI10Same as above, but for follow-up align steps.
NIM_MMSEQS_PROFILE_ALIGN_EVALUE1e-5E-value threshold for the profile align step. Alignments above this e-value are discarded.
NIM_MMSEQS_FOLLOWUP_SEARCH_EVALUE1e-5E-value threshold for the follow-up search step.
NIM_MMSEQS_FOLLOWUP_ALIGN_EVALUE1e-5E-value threshold for the follow-up align step.

With defaults, each database can produce up to 100 × (1 + 10) = 1,100 sequences before trimming. Per-database API results are trimmed to max_msa_sequences (N, default 500), but the merged colabfold entry concatenates untrimmed results from all D databases, yielding up to D × 1,100 sequences.

Filter-Step Parameters

These control quality filtering applied after the align step. Separate variables are provided for the profile (first-database) and follow-up (subsequent database) filter steps.

VariableDefaultDescription
NIM_MMSEQS_PROFILE_FILTER_QID0Minimum sequence identity with query (0–1) in the profile filter step. Set to 0 to disable.
NIM_MMSEQS_PROFILE_FILTER_QSC0.0Minimum score per aligned residue with query sequence (mmseqs filterresult --qsc, range −50 to 100) in the profile filter step.
NIM_MMSEQS_PROFILE_FILTER_DIFF0Diversity filter: keep at least this many sequences in each MSA block of length 50 (--diff) in the profile filter step. Set to 0 to disable diversity filtering.
NIM_MMSEQS_PROFILE_FILTER_MAX_SEQ_ID1.0Maximum pairwise sequence identity (0–1) for redundancy reduction in the profile filter step. Set to 1.0 to disable.
NIM_MMSEQS_PROFILE_FILTER_MIN_ENABLE100Only apply filtering when the MSA has more than this many sequences in the profile filter step. Set to 0 to always filter.
NIM_MMSEQS_FOLLOWUP_FILTER_QID0Minimum sequence identity with query (0–1) in the follow-up filter step. Set to 0 to disable.
NIM_MMSEQS_FOLLOWUP_FILTER_QSC0.0Minimum score per aligned residue with query sequence (range −50 to 100) in the follow-up filter step.
NIM_MMSEQS_FOLLOWUP_FILTER_DIFF0Diversity filter: keep at least this many sequences in each MSA block of length 50 in the follow-up filter step. Set to 0 to disable diversity filtering.
NIM_MMSEQS_FOLLOWUP_FILTER_MAX_SEQ_ID1.0Maximum pairwise sequence identity (0–1) for redundancy reduction in the follow-up filter step. Set to 1.0 to disable.
NIM_MMSEQS_FOLLOWUP_FILTER_MIN_ENABLE100Only apply filtering when the MSA has more than this many sequences in the follow-up filter step. Set to 0 to always filter.

Expand-Step Parameters

VariableDefaultDescription
NIM_MMSEQS_FOLLOWUP_EXPAND_EVALUEinfE-value threshold for the follow-up expansion step. inf means all expanded hits are kept.

Search Iteration Parameters

VariableDefaultDescription
NIM_MMSEQS_PROFILE_SEARCH_ITERATIONS3Number of profile-search iterations in the profile (first-database) search.
NIM_MMSEQS_FOLLOWUP_SEARCH_ITERATIONS3Number of profile-search iterations in follow-up searches.
NIM_MMSEQS_PAIRED_SEARCH_ITERATIONS3Number of profile-search iterations in paired (multimer) search.
NIM_MMSEQS_FOLLOWUP_NONEXP_SEARCH_ITERATIONS3Number of profile-search iterations for follow-up databases that are not in NIM_MSA_EXPANDABLE_DBS (for example, non-expandable databases).

Other Pipeline Parameters

VariableDefaultDescription
NIM_MMSEQS_NUM_THREADS12Default number of threads for MMseqs2 commands.
NIM_MMSEQS_TEMPLATE_SENSITIVITY7.5Sensitivity parameter for template search. Higher values are more sensitive but slower.
NIM_MMSEQS_TEMPLATE_EVALUE0.1E-value threshold for template search hits.
NIM_MMSEQS_TEMPLATE_CONVERTALIS_FORMATquery,target,fident,...Output format for convertalis (template search hits). Refer to the MMseqs2 documentation for column options.
NIM_MMSEQS_PAIRED_ALIGN_MAX_ACCEPT1000000Maximum accepted targets in paired search alignment. Set very high by default to maximize pairing candidates.
NIM_MMSEQS_PAIRED_ALIGN_EVALUE0.001E-value threshold for paired search alignment.
NIM_MMSEQS_PAIRED_EXPAND_MAX_SEQ_ID0.95Maximum sequence identity threshold during paired search expansion.

These environment variables are global: they apply to all requests served by the NIM instance. To change them, restart the container with the desired values. A future release may expose some of these as per-request API parameters.