Inferencing with the NIM | NVIDIA BioNeMo NIM Documentation

This documentation provides a comprehensive guide for using the Boltz-2 NIM for protein structure prediction and related tasks.

Prerequisites

Before starting, ensure you have:

Docker installed and configured
NGC CLI installed
NGC registry access
NVIDIA GPU with appropriate drivers

Deployment

Pull the Boltz-2 NIM container:

docker pull nvcr.io/nim/mit/boltz2:1.5.0

Run the NIM container:

export LOCAL_NIM_CACHE=~/.cache/nim
export NGC_API_KEY=<Your NGC API Key>

docker run --rm --name boltz2 --runtime=nvidia \
    --shm-size=16G \
    -e NGC_API_KEY \
    -v $LOCAL_NIM_CACHE:/opt/nim/.cache \
    -p 8000:8000 \
    nvcr.io/nim/mit/boltz2:1.5.0

Note: The initial model download can take 2-10 hours on a 100+Mbps internet connection.

Verify the NIM is ready by checking the health endpoint:

curl -X 'GET' \
    'http://localhost:8000/v1/health/ready' \
    -H 'accept: application/json'

NIM API Reference

This documentation contains the API reference for the Boltz-2 NIM.

OpenAPI Specification

You can download the complete OpenAPI Specification for the Boltz-2 NIM here.

Example Notebooks

Below, we provide example notebooks that demonstrate how to use the Boltz-2 NIM API in various scenarios:

Protein-Ligand Covalent Complex Visualization with Mol*Star - Use Boltz-2 NIM to predict and visualize a protein-ligand covalent complex structure using Mol*Star viewer

Protein-Ligand Covalent Complex View
Download boltz2_nim_protein_ligand_covalent_complex_molstar_visualization.ipynb
DNA-Protein Complex Visualization with py3Dmol - Use Boltz-2 NIM to predict and visualize a DNA-Protein complex structure using py3Dmol viewer

DNA-Protein Complex View
Download boltz2_nim_DNA_Protein_Complex_example_py3Dmol.ipynb

These notebooks provide hands-on examples of:

Setting up the NIM environment
Making API calls to the NIM
Processing and visualizing the results
Working with different types of molecular structures
Using various visualization tools

Predict a Protein Structure

Endpoint path: /biology/mit/boltz2/predict

Request type: post

Input Parameters

polymers (list[Polymer]): Required. A list of polymers (DNA, RNA, or Protein). Minimum 1, maximum 12 polymers allowed. Each polymer contains:
- id (string): Optional. Unique identifier for the polymer chain. Can be either a single letter (A-Z) or a PDB-style ID (4 alphanumeric characters).
- molecule_type (string): Required. Type of molecule - “dna”, “rna”, or “protein”.
- sequence (string): Required. The sequence of the polymer. Must be 1-4,096 characters and contain only valid characters for the molecule type.
- cyclic (boolean): Optional (default: false). Whether the polymer forms a cyclic structure.
- msa (dictionary): Optional. Multiple Sequence Alignments for protein molecules only. This nested dictionary contains a mapping of database names to alignment formats and records (for example {"database_1" : {"A3M" : {"format" : "A3M", "alignment" : ">1\nMVNIDIAIAMAI", "rank" : 0}}}).
- modifications (list[Modification]): Optional. Chemical modifications to specific residues in the sequence. Each modification contains:
  - ccd (string): Required. Chemical Component Dictionary (CCD) ID of the modification (1-3 alphanumeric characters).
  - position (int): Required. The 1-based index of the residue to modify.
- structural_templates (list[StructuralTemplate]): Optional. Structural templates to guide the prediction. Each template contains:
  - structure (string): Required. The structural template content in the specified format.
  - format (string): Required. The format of the template structure. Supported formats: “cif” or “pdb”.
  - name (string): Optional. Identifier or name for the template (e.g., PDB ID).
ligands (list[Ligand]): Optional (default: empty list). A list of ligands. Maximum 20 ligands allowed. Each ligand contains:
- id (string): Optional. A chain ID for the ligand.
- ccd (string): Optional. Chemical Component Dictionary (CCD) code for the ligand (1-3 alphanumeric characters).
- smiles (string): Optional. SMILES string representation of the ligand. Either CCD or SMILES must be provided, but not both.
- predict_affinity (boolean): Optional (default: false). Enable affinity prediction for this ligand. When enabled, the model will predict binding affinity between the protein and this ligand. Note: Only one ligand per request can have predict_affinity=True.
constraints (list[Union[Pocket, Bond]]): Optional (default: empty list). Optional constraints for the prediction. Can be either:
- Bond Constraint: Specifies atomic bonds between molecules
  - constraint_type: “bond”
  - atoms (list[Atom]): List of atoms involved in the bond. Each atom contains:
    - id (string): Optional. Chain identifier for the atom.
    - residue_index (int): Required. Index of the residue containing the atom.
    - atom_name (string): Required. Name of the specific atom.
- Pocket Constraint: Defines binding site interactions
  - constraint_type: “pocket”
  - binder (string): Required. The ID of the binding molecule.
  - contacts (list[Contact]): Required. List of contacts defining the pocket. Each contact contains:
    - id (string): Optional. Chain identifier for the contact.
    - residue_index (int): Required. Index of the residue in the binding site.
recycling_steps (int): Optional (default: 3). The number of recycling steps to use for prediction. Range: 1-10.
sampling_steps (int): Optional (default: 50). The number of sampling steps to use for prediction. Range: 10-1,000.
diffusion_samples (int): Optional (default: 1). The number of diffusion samples to use for prediction. Range: 1-25.
step_scale (float): Optional (default: 1.638). The step size is related to the temperature at which the diffusion process samples the distribution. Lower values increase diversity among samples (recommended between 1 and 2). Range: 0.5-5.0.
without_potentials (boolean): Optional (default: false). Returns the results without potentials.
output_format (string): Optional (default: “mmcif”). The output format of the returned structure. Currently only “mmcif” is supported.
concatenate_msas (boolean): Optional (default: false). Concatenate Multiple Sequence Alignments for a polymer into one alignment.
sampling_steps_affinity (int): Optional (default: 200). The number of sampling steps to use for affinity prediction. Range: 10-1,000. Higher values may improve accuracy but increase runtime. Reduce for faster results.
diffusion_samples_affinity (int): Optional (default: 5). The number of diffusion samples to use for affinity prediction. Range: 1-10. Higher values may improve reliability but increase runtime. Reduce to 1 for faster results.
affinity_mw_correction (boolean): Optional (default: false). Enable molecular weight correction for affinity prediction, especially useful for metal-containing ligands.
write_full_pae (boolean): Optional (default: false). Enable full PAE (Predicted Aligned Error) Matrix output in the prediction results. When set to true, returns the complete PAE matrix for detailed error analysis.

Outputs

structures (list[Structure]): The predicted protein structures. Each structure contains:
- structure (string): The contents of a single structural prediction in the specified format.
- format (string): The format of the structure record (currently “mmcif”).
- name (string): Optional name for the structure.
- source (string): Optional source file for the structure.
confidence_scores (list[float]): Confidence scores for each predicted structure.
affinities (dictionary): Returned when predict_affinity is true for a ligand. Map from ligand ID to affinity results; each value may contain affinity_pic50, affinity_pred_value (log IC50), and affinity_probability_binary (binding probability 0–1).
metrics (dictionary): Runtime metrics for the request, useful for debugging and measuring performance.

Examples

Basic Protein Structure Prediction

Curl

Python

#!/bin/bash
# Create JSON payload for protein structure prediction
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"
    }
],
"recycling_steps": 3,
"sampling_steps": 50,
"diffusion_samples": 1,
"step_scale": 1.638,
"output_format": "mmcif"
}'
# Make request
echo "Making request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict

Protein-Ligand Complex Prediction

Curl

Python

#!/bin/bash
# Create JSON payload for protein-ligand complex prediction
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"
    }
],
"ligands": [
    {
    "id": "B1",
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"
    }
],
"recycling_steps": 3,
"sampling_steps": 50,
"output_format": "mmcif"
}'
# Make request
echo "Making request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict

Comprehensive Example with All Features

Curl

Python

#!/bin/bash
# Comprehensive example with all possible fields
JSON='{
"polymers": [
    {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN",
    "cyclic": false,
    "modifications": [
        {
        "ccd": "SEP",
        "position": 15
        }
    ]
    }
],
"ligands": [
    {
    "id": "L1",
    "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"
    }
],
"constraints": [
    {
    "constraint_type": "pocket",
    "binder": "L1",
    "contacts": [
        {
        "id": "A",
        "residue_index": 25
        }
    ]
    }
],
"recycling_steps": 3,
"sampling_steps": 50,
"diffusion_samples": 1,
"step_scale": 1.638,
"without_potentials": false,
"output_format": "mmcif",
"concatenate_msas": false
}'
echo "Making comprehensive prediction request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/mit/boltz2/predict | jq '.'

Check Readiness

Endpoint path: /v1/health/ready

Input parameters

None.

Outputs

The output of the endpoint is a JSON response with a value that indicates the readiness of the microservice. When the NIM is ready, it returns the response 200.

Example

Curl

Python

#!/bin/bash
URL=${NIM_URL:-"http://localhost:8000/v1/health/ready"}
curl -s -w "\nStatus code: %{http_code}\n" -H "Content-Type: application/json" $URL