openfold3-nim

OpenFold3 NIM

使用 OpenFold3 预测生物分子结构。它支持蛋白质、DNA、RNA、小分子配体和多实体组装体。使用本指南了解托管模式和本地 NIM 的基本用法；只有任务需要更深入的背景信息时，才加载补充文件：

• references/api.md：精确的端点、架构、Docker 标志和响应字段。
• references/science.md：用途、优势、局限性和模型交接。
• references/parameters.md：分子字段、MSA、模板、样本和调优。
• references/validation.md：产物检查和科学合理性检查。
• references/examples.md：精简的托管模式和本地请求示例。

选择模式

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

NVIDIA 托管 API 还是本地 Docker NIM？

• 托管 URL：https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict
• 本地 URL：http://localhost:8000/biology/openfold/openfold3/predict
• 本地就绪状态：http://localhost:8000/v1/health/ready

模式差异：本地预测路径没有 /v1/ 前缀。托管请求使用 Authorization: Bearer $NGC_API_KEY。支持的本地 Docker 启动方式使用 NGC_API_KEY（或通过预检使用 NVIDIA_API_KEY）进行注册表登录、授权检查和首次模型下载；将其传入容器时使用 -e NGC_API_KEY。就绪后，本地推理请求无需身份验证标头，因此应使用 -p 127.0.0.1:8000:8000 将主机端口绑定到环回地址。不同镜像版本的预热缓存免密钥启动方式有所不同，不应假定其可用。

身份验证和环境

使用环境中已提供或由密钥管理器注入的凭据。不要加载凭据文件、打印密钥或启用 shell 跟踪。使用 shell 测试确认密钥存在。

托管模式需要在请求标头中提供 NGC_API_KEY。本地启动需要 NGC_API_KEY，或将 NVIDIA_API_KEY 作为备用密钥，并设置 LOCAL_NIM_CACHE。

本地 Docker

使用官方 OpenFold3 NIM 镜像，并将 LOCAL_NIM_CACHE 挂载到 /opt/nim/.cache。执行设置前，说明注册表身份验证会将密钥发送到 NVIDIA 注册表 https://nvcr.io，且首次启动会向缓存中下载约 10–15 GB 的模型权重。仅在用户提出请求时才运行部署；如果用户需要设置指南，则提供命令但不要运行。

编写本地设置命令时，必须原样复制下面的预检内容。不要将其替换为简单的 : "${NGC_API_KEY:?Set NGC_API_KEY}" 检查，不要删去 NVIDIA_API_KEY，也不要为 LOCAL_NIM_CACHE 臆造默认值；这些行是仓库的本地 NIM 环境约定。默认的单 GPU 启动命令应显示字面量 --gpus "device=0"；只有用户提出要求时才选择其他设备。

set +x

if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
  NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
export NGC_API_KEY
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"

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

printf '%s\n' "$NGC_API_KEY" | \
  docker login nvcr.io --username '$oauthtoken' --password-stdin && \
docker run --rm --name openfold3 \
  --runtime=nvidia \
  --gpus "device=0" \
  --shm-size=16g \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 127.0.0.1:8000:8000 \
  nvcr.io/nim/openfold/openfold3:latest

就绪状态检查：

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

请求模式

使用 requests.post(..., json=payload, timeout=300)。对于本地 Docker 任务，在就绪状态检查通过后设置 hosted = False。

import os
import requests

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

seq = "MKTVRQERLKSIVR"
payload = {
    "inputs": [{
        "input_id": "prediction_1",
        "output_format": "pdb",
        "molecules": [{
            "type": "protein",
            "id": "A",
            "sequence": seq,
            "diffusion_samples": 1,
            "msa": {
                "main": {
                    "a3m": {
                        "alignment": f">query\n{seq}",
                        "format": "a3m"
                    }
                }
            }
        }]
    }]
}

response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

负载注意事项：

• 顶层结构为 {"inputs": [...]}，OpenFold3 仅接受一个输入。
• molecules 可包含 1–32 个对象，其 type 为 protein、dna、rna 或 ligand。
• 蛋白质/RNA 的 MSA 可选，但如果提供，alignment 必须以 FASTA 标题开头，例如 >query\nSEQUENCE。
• 配体使用 smiles 或 ccd_codes，例如 {"type": "ligand", "id": "L", "ccd_codes": "ATP"}。
• DNA/RNA 实体使用 sequence，例如 {"type": "dna", "id": "B", "sequence": "ATCGATCG"}。
• diffusion_samples 的范围为 1–5。output_format 为 pdb 或 cif。

保存并解读输出

将每个返回的结构保存为科学产物。主响应路径：result["outputs"][0]["structures_with_scores"]。

output = result["outputs"][0]
for i, sample in enumerate(output["structures_with_scores"], start=1):
    fmt = sample["format"]
    with open(f"openfold3_structure_{i}.{fmt}", "w", encoding="utf-8") as fh:
        fh.write(sample["structure"])
    print("confidence_score", sample.get("confidence_score"))
    print("complex_plddt_score", sample.get("complex_plddt_score"))
    print("ptm_score", sample.get("ptm_score"))
    print("iptm_score", sample.get("iptm_score"))
    print("complex_pde_score", sample.get("complex_pde_score"))

confidence_score、complex_plddt_score、ptm_score 和 iptm_score 越高通常越好；complex_pde_score 越低通常越好。将玩具序列或极短序列视为 API 冒烟测试，而非有意义的结构生物学结果。关于 OpenFold3 在科学上适用于哪些情况以及原因，请阅读 references/science.md。

常见限制

• 每个请求的输入数：1。
• 每个输入的分子数：1-32。
• 扩散采样数：1-5。
• TensorRT 路径支持较短的序列；PyTorch 路径可支持较长的序列，但较长的输入需要更多 GPU 内存。
• 超过约 1800 个残基的序列至少需要 80 GB GPU 内存。
• 本地 NIM 仅支持单 GPU；请在 Docker 标志中选择目标设备。

故障排查

• 401：NGC API 密钥缺失、已过期或未获授权。
• 422：分子类型无效、序列字符无效、MSA 形状错误，或 diffusion_samples 不在 1-5 范围内。
• MSA 错误：确保比对以 >query\n 开头。
• 本地 404：从预测 URL 中移除 /v1/。
• 本地启动停滞：首次运行可能正在将 10-15 GB 的模型权重下载到 LOCAL_NIM_CACHE。
• 内存错误：缩短序列、减少采样数，或使用更大的 GPU。