openfold2-nim

OpenFold2 NIM

根据氨基酸序列预测单条蛋白质链的结构，可选提供 A3M 多序列比对和 mmCIF 模板。此指南介绍托管版／本地 NIM 的基本用法；仅在任务需要更深入的背景信息时加载补充文件：

• references/api.md：准确的端点、架构、Docker 标志和响应字段。
• references/science.md：模型范围、优势、局限性和交接方式。
• references/parameters.md：MSA、模板、模型选择和 relax 的影响。
• references/validation.md：产物和科学合理性检查。
• references/examples.md：简洁的托管版／本地请求示例。

选择模式

仅在上下文不清楚时询问：

NVIDIA 托管 API 还是本地 Docker NIM？

• 托管版 URL：https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template
• 本地 URL：http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template
• 本地就绪状态：http://localhost:8000/v1/health/ready

模式差异：托管版和本地版使用相同的预测路径，但本地版不包含 /v1/。托管版请求使用 Authorization: Bearer $NGC_API_KEY；就绪检查通过后，本地推理请求无需身份验证标头。

身份验证和环境

不要打印 API 密钥。使用 shell 测试确认密钥存在，不要使用 echo。

托管版需要在请求标头中提供 NGC_API_KEY。受支持的本地 Docker 启动方式使用 NGC_API_KEY，或将 NVIDIA_API_KEY 用作后备密钥，并需要 LOCAL_NIM_CACHE。仓库根目录中的 .env 文件可以作为本地覆盖配置加载。

本地 Docker

使用官方 OpenFold2 NIM 镜像，并将 LOCAL_NIM_CACHE 挂载到 /opt/nim/.cache。当前文档建议至少配备 80 GB 磁盘空间、64 GB 系统 RAM、8 个 CPU 核心和一块受支持的 GPU；容器大小约为 55 GB，首次启动时会下载约 10 GB 的模型参数。

如需查看准确的启动前检查（加载 .env、处理 NGC_API_KEY/NVIDIA_API_KEY、docker login，以及运行 nvcr.io/nim/openfold/openfold2:latest 的 docker run 命令），请原样复制 references/api.md 中 Local Docker 部分的命令块——不要省略 .env、NGC_API_KEY、LOCAL_NIM_CACHE 或无需身份验证的本地请求。

就绪检查：

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

请求模式

使用 Python requests；对 A3M/mmCIF 文本进行 curl 转义很容易出错。sequence 字段为必填项。input_id、alignments、selected_models、relax_prediction、use_templates 和 explicit_templates 均为可选项。

import os
import requests

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

seq = "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT"
payload = {
    "sequence": seq,
    "input_id": "kras_fragment",
    "selected_models": [1],
    "relax_prediction": False,
    "alignments": {
        "uniref90": {
            "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()

请求载荷注意事项：

• OpenFold2 仅支持单体。对于蛋白质－配体、蛋白质－DNA/RNA 或多链复合物，请改用 OpenFold3 或 Boltz2。
• sequence 必须使用有效的氨基酸 IUPAC 符号。
• 托管版 API 文档列出的序列长度为 1-1000；本地文档指出，当前 NIM 在受支持的硬件上支持最多 2048 个残基的序列。
• A3M 比对应按数据库名称放在 alignments 下，然后使用包含 alignment 和 format 的 a3m。如果用户需要创建或深化 MSA，请交接给 msa-search-nim／MSA Search，并将其 A3M 输出映射到此处的 alignments 结构。
• 从 OpenFold2 2.0.0 开始，使用包含 mmCIF 内容的 explicit_templates；不要编写新的 HHR 模板示例。
• selected_models 用于选择 AlphaFold2/OpenFold 参数集 1-5。冒烟测试选择一个或两个模型；生产运行若要获得更强结果，则使用全部五个模型。

保存和解读输出

响应会为每个选定模型返回一个预测结果，并按置信度排序。 保存所有返回的类结构文本字段以及完整的 JSON 响应，以便审计字段形状差异。生产环境中的答案应明确写入 .pdb 或 .cif 文件，保留响应 JSON，并输出服务返回的任何置信度／排名字段。

from pathlib import Path
import json

Path("openfold2_response.json").write_text(json.dumps(result, indent=2))

def save_strings(obj, prefix="openfold2"):
    i = 0
    if isinstance(obj, dict):
        for key, value in obj.items():
            if isinstance(value, str) and ("ATOM" in value or value.lstrip().startswith("data_")):
                i += 1
                ext = "cif" if value.lstrip().startswith("data_") else "pdb"
                Path(f"{prefix}_{key}_{i}.{ext}").write_text(value)
            elif isinstance(value, (dict, list)):
                i += save_strings(value, f"{prefix}_{key}")
    elif isinstance(obj, list):
        for idx, value in enumerate(obj, start=1):
            if isinstance(value, (dict, list)):
                i += save_strings(value, f"{prefix}_{idx}")
    return i

saved = save_strings(result)
print(f"saved {saved} structure artifact(s)")

对于生产环境中的单体运行：

• 除非用户要求进行冒烟测试，否则使用 selected_models: [1, 2, 3, 4, 5]。
• 如果需要进行松弛处理，在 Python 负载中使用 relax_prediction: True； JSON 示例中可以写作 true。
• 说明序列长度注意事项：托管 API 文档列出的范围为 1-1000 个残基，而本地支持矩阵文档列出在受支持硬件上最多支持 2048 个残基。
• 如果任务处理的是复合物而非单体，请改用 OpenFold3 或 Boltz2。

将极短的示例序列和单序列 MSA 视为 API 冒烟测试，而非质量证据。有关科学解读和验证，请阅读 references/science.md 和 references/validation.md。

故障排除

• 401：缺少、已过期或未经授权的 NGC API 密钥。
• 422：氨基酸字符无效、序列过长、A3M 格式错误、selected_models 无效，或 mmCIF 模板对象格式错误。
• 本地出现 404：从预测 URL 中移除 /v1/。
• 结构较弱：使用 MSA Search 生成更深层的 A3M 比对，并在适当时添加具有生物学相关性的 mmCIF 模板。
• 本地启动停滞：首次运行会将参数下载到 LOCAL_NIM_CACHE。