boltz2-nim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Boltz2 NIM

Predict biomolecular structures and optional ligand affinity. Use this

SKILL.md

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
```
: purpose, strengths, limitations, and handoffs.
```
references/parameters.md
```
: prediction, sampling, MSA, template, affinity tuning.
```
references/validation.md
```
: mmCIF, confidence, affinity, and chemistry checks.
```
references/examples.md
```
: compact hosted/local payload patterns.

预测生物分子结构及可选的配体亲和力。首次使用托管/本地版本时可参考此

SKILL.md

；仅在需要时加载补充文件：

```
references/api.md
```
: 详细端点、数据结构、Docker参数、响应字段说明。
```
references/science.md
```
: 工具用途、优势、局限性及交接说明。
```
references/parameters.md
```
: 预测、采样、MSA、模板、亲和力调参说明。
```
references/validation.md
```
: mmCIF格式、置信度、亲和力及化学性质校验说明。
```
references/examples.md
```
: 托管/本地版本的简洁请求示例。

Choose Mode

选择运行模式

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

Hosted:

https://health.api.nvidia.com/v1/biology/mit/boltz2/predict

Local:

http://localhost:8000/biology/mit/boltz2/predict

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.

仅当上下文不明确时询问：

使用NVIDIA托管API还是本地Docker NIM？

托管版：

https://health.api.nvidia.com/v1/biology/mit/boltz2/predict

本地版：

http://localhost:8000/biology/mit/boltz2/predict

托管版请求需使用

Authorization: Bearer $NGC_API_KEY

认证。本地Docker启动时，需使用

NGC_API_KEY

（或通过预检查使用

NVIDIA_API_KEY

）进行镜像仓库登录、权限校验及首次运行时的模型下载；通过

-e NGC_API_KEY

将其传入容器。本地推理服务就绪后，请求无需携带认证头。免密钥的热缓存启动方式因镜像/版本而异，请勿默认依赖此方式。

Local Docker

本地Docker部署

For local setup answers, copy the preflight below before

docker login

docker run

, readiness, and the no-auth local request. Do not invent a cache default or drop the

.env

load or

NVIDIA_API_KEY

fallback.

bash

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}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"

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

mkdir -p "${LOCAL_NIM_CACHE}"
chmod 755 "${LOCAL_NIM_CACHE}"

docker run --rm --name boltz2 --gpus all \
  --shm-size=16G \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/mit/boltz2:1.6.0

Readiness:

bash

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

First startup downloads about 30 GB of model weights.

如需本地部署指导，请在执行

docker login

、

docker run

、就绪检查及无认证本地请求前，复制以下预检查脚本。请勿自行设置缓存默认值，也不要省略

.env

文件加载或

NVIDIA_API_KEY

fallback逻辑。

bash

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}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"

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

mkdir -p "${LOCAL_NIM_CACHE}"
chmod 755 "${LOCAL_NIM_CACHE}"

docker run --rm --name boltz2 --gpus all \
  --shm-size=16G \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/mit/boltz2:1.6.0

就绪检查：

bash

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

首次启动时将下载约30GB的模型权重。

Request Pattern

请求示例

python

import os
import requests

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

payload = {
    "polymers": [{
        "id": "A",
        "molecule_type": "protein",
        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT",
    }],
    "recycling_steps": 3,
    "sampling_steps": 50,
    "diffusion_samples": 1,
    "step_scale": 1.638,
    "output_format": "mmcif",
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

Payload essentials:

Protein polymer:

{"molecule_type": "protein", "sequence": "..."}

DNA/RNA polymer: add another polymer with
```
molecule_type
```
```
"dna"
```
or
```
"rna"
```
.

Ligand by SMILES:

{"id": "L1", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}

Ligand by CCD:
```
{"id": "L1", "ccd": "ATP"}
```
.

Affinity: set

"predict_affinity": True

on exactly one ligand; report

affinity_pic50

affinity_pred_value

, and

affinity_probability_binary

Precomputed A3M MSA goes under the protein polymer. The A3M record uses
```
alignment
```
,
```
format
```
, and
```
rank
```
; do not use a stale
```
data
```
field.

python

protein_with_msa = {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
    "msa": {"msa_search": {"a3m": {
        "alignment": ">query\nMTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
        "format": "a3m",
        "rank": 0,
    }}},
}

python

import os
import requests

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

payload = {
    "polymers": [{
        "id": "A",
        "molecule_type": "protein",
        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT",
    }],
    "recycling_steps": 3,
    "sampling_steps": 50,
    "diffusion_samples": 1,
    "step_scale": 1.638,
    "output_format": "mmcif",
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

请求体要点：

蛋白质聚合物：

{"molecule_type": "protein", "sequence": "..."}

。

DNA/RNA聚合物：添加另一个
```
molecule_type
```
为
```
"dna"
```
或
```
"rna"
```
的聚合物。

通过SMILES指定配体：

{"id": "L1", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}

。

通过CCD指定配体：
```
{"id": "L1", "ccd": "ATP"}
```
。

亲和力预测：仅对一个配体设置

"predict_affinity": True

；结果将返回

affinity_pic50

、

affinity_pred_value

及

affinity_probability_binary

字段。

预计算的A3M MSA需添加到蛋白质聚合物中。A3M记录需使用
```
alignment
```
、
```
format
```
和
```
rank
```
字段；请勿使用过时的
```
data
```
字段。

python

protein_with_msa = {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
    "msa": {"msa_search": {"a3m": {
        "alignment": ">query\nMTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
        "format": "a3m",
        "rank": 0,
    }}},
}

Save And Report Output

保存并报告结果

Save every

.cif

artifact and read the confidence/affinity fields using the snippet in

references/examples.md

under Save Structures And Affinity. Visualize in PyMOL, ChimeraX, or UCSF Chimera. For confidence/affinity sanity checks, read

references/validation.md

保存所有

.cif

结果文件，并使用

references/examples.md

中Save Structures And Affinity部分的代码片段读取置信度/亲和力字段。可使用PyMOL、ChimeraX或UCSF Chimera进行可视化。如需对置信度/亲和力进行合理性校验，请参考

references/validation.md

。

Limits And Troubleshooting

限制与故障排查

Polymers/request: 12. Ligands/request: 20. Chain length: 4096 residues.
Affinity prediction supports one ligand per request and adds runtime.
```
422
```
: invalid sequence, invalid CCD/SMILES, malformed MSA, or multiple affinity ligands.
Local URL/auth: local path has no hosted auth header; wait on
```
/v1/health/ready
```
.
Local startup: use
```
--gpus all
```
,
```
--shm-size=16G
```
, and the
```
/opt/nim/.cache
```
mount.

每个请求最多支持12个聚合物、20个配体。链长上限为4096个残基。
亲和力预测每个请求仅支持一个配体，且会增加运行时间。
错误码
```
422
```
：序列无效、CCD/SMILES无效、MSA格式错误，或指定了多个亲和力预测配体。
本地URL/认证：本地请求无需携带托管版的认证头；需等待
```
/v1/health/ready
```
接口返回就绪状态。
本地启动：需使用
```
--gpus all
```
、
```
--shm-size=16G
```
参数，并挂载
```
/opt/nim/.cache
```
目录。