boltz2-nim

Boltz2 NIM

预测生物分子结构，并可选择预测配体亲和力。使用本指南进行首次托管／本地使用；仅在需要时加载补充文件：

• references/api.md：准确的端点、架构、Docker 标志和响应字段。
• references/science.md：用途、优势、局限和后续处理。
• references/parameters.md：预测、采样、MSA、模板和亲和力调优。
• references/validation.md：mmCIF、置信度、亲和力和化学检查。
• references/examples.md：简洁的托管／本地请求负载示例。

说明

仅在需要时从环境中读取凭据。使用 bool(os.getenv("NGC_API_KEY")) 检查是否存在；不要将密钥值和 Authorization 标头输出到 终端、日志、保存的文件或最终回复中。诊断身份验证问题时，避免转储环境变量。如果缺少托管密钥，请在提交请求前报告缺少的变量。

选择模式

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

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 将其传入 容器。就绪后，本地推理请求不需要身份验证标头。预热缓存后无需密钥的启动方式因 镜像／版本而异，不应假定其可用。

本地 Docker

回答本地设置问题时，请在执行 docker login、 docker run、就绪检查和无身份验证的本地请求之前，复制以下预检内容。不要臆造缓存 默认值，也不要省略 .env 加载或 NVIDIA_API_KEY 回退逻辑。

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

就绪检查：

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

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

示例

预测请求

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:
    api_key = os.getenv("NGC_API_KEY")
    if not api_key:
        raise SystemExit("NGC_API_KEY is required for the hosted API")
    headers["Authorization"] = f"Bearer {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 字段。

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

保存并报告输出

保存每个 .cif 文件，并使用 references/examples.md 中 保存结构和亲和力部分的代码段读取置信度／亲和力字段。使用 PyMOL、ChimeraX 或 UCSF Chimera 进行可视化。如需检查置信度／亲和力是否合理，请参阅 references/validation.md。

限制和故障排除

• 每个请求最多包含 12 个聚合物和 20 个配体。链长最多为 4096 个残基。
• 亲和力预测每个请求仅支持一个配体，且会增加运行时间。
• 422：序列无效、CCD／SMILES 无效、MSA 格式错误，或包含多个亲和力配体。
• 本地 URL／身份验证：本地路径无需托管身份验证标头；请等待 /v1/health/ready。
• 本地启动：使用 --gpus all、--shm-size=16G 和 /opt/nim/.cache 挂载。