openfold2-nim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenFold2 NIM

Predict a single protein-chain structure from an amino-acid sequence, with optional A3M multiple sequence alignments and mmCIF templates. Use this

SKILL.md

for basic hosted/local NIM use; load supplemental files only when the task needs deeper context:

```
references/api.md
```
: exact endpoints, schemas, Docker flags, response fields.
```
references/science.md
```
: model scope, strengths, limitations, and handoffs.
```
references/parameters.md
```
: MSA, template, model-selection, and relax effects.
```
references/validation.md
```
: artifact and scientific sanity checks.
```
references/examples.md
```
: compact hosted/local payload patterns.

基于氨基酸序列预测单条蛋白质链结构，可选择使用A3M多序列比对和mmCIF模板。本

SKILL.md

适用于基础的托管/本地NIM使用场景；仅当任务需要更深入的上下文时，才加载补充文件：

```
references/api.md
```
：精确的端点、模式、Docker参数、响应字段。
```
references/science.md
```
：模型范围、优势、局限性及交接说明。
```
references/parameters.md
```
：多序列比对（MSA）、模板、模型选择及结构松弛的影响。
```
references/validation.md
```
：人工产物检查与科学合理性验证。
```
references/examples.md
```
：简洁的托管/本地请求负载示例。

Choose Mode

选择模式

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

Hosted URL:

https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template

Local URL:

http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template

Local readiness:
```
http://localhost:8000/v1/health/ready
```

Mode difference: hosted and local use the same prediction path except local does not include

/v1/

. Hosted requests use

Authorization: Bearer $NGC_API_KEY

; local inference requests use no auth header after readiness.

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

使用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

；本地推理请求在就绪检查通过后无需认证头。

Auth And Environment

认证与环境

Do not print API keys. Confirm they exist with shell tests, not echoes.

Hosted needs

NGC_API_KEY

in the request header. Supported local Docker startup uses

NGC_API_KEY

, or

NVIDIA_API_KEY

as a fallback, plus

LOCAL_NIM_CACHE

. A repo-root

.env

file may be sourced as a local override.

请勿打印API密钥。通过shell测试确认密钥存在，而非直接输出。

托管版需要在请求头中携带

NGC_API_KEY

。本地Docker启动支持使用

NGC_API_KEY

，或

NVIDIA_API_KEY

作为备选，同时需要

LOCAL_NIM_CACHE

。可通过仓库根目录的

.env

文件进行本地配置覆盖。

Local Docker

本地Docker部署

Use the official OpenFold2 NIM image and mount

LOCAL_NIM_CACHE

/opt/nim/.cache

. Current docs recommend at least 80 GB disk, 64 GB system RAM, 8 CPU cores, and one supported GPU; the container is roughly 55 GB and first startup downloads about 10 GB of model parameters.

For the exact startup preflight (

.env

sourcing,

NGC_API_KEY

NVIDIA_API_KEY

handling,

docker login

, and the

docker run

for

nvcr.io/nim/openfold/openfold2:latest

), copy the command block in

references/api.md

under Local Docker verbatim — do not drop

.env

NGC_API_KEY

LOCAL_NIM_CACHE

, or the no-auth local request.

Readiness check:

bash

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

使用官方OpenFold2 NIM镜像，并将

LOCAL_NIM_CACHE

挂载到

/opt/nim/.cache

。当前文档推荐至少80GB磁盘空间、64GB系统内存、8核CPU以及一块支持的GPU；容器大小约为55GB，首次启动时会下载约10GB的模型参数。

如需精确的启动预检步骤（包括

.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

或本地无认证请求的相关内容。

就绪检查命令：

bash

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

Request Pattern

请求模式

Use Python

requests

; curl escaping is fragile for A3M/mmCIF text. The

sequence

field is required.

input_id

alignments

selected_models

relax_prediction

use_templates

, and

explicit_templates

are optional.

python

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()

Payload gotchas:

OpenFold2 is monomer-only. For protein-ligand, protein-DNA/RNA, or multi-chain complexes, use OpenFold3 or Boltz2 instead.
```
sequence
```
must use valid amino-acid IUPAC symbols.
Hosted API docs list sequence length 1-1000; local docs say current NIM supports sequences up to 2048 residues on supported hardware.
A3M alignments go under
```
alignments
```
by database name, then
```
a3m
```
with
```
alignment
```
and
```
format
```
. When the user needs to create or deepen an MSA, hand off to
```
msa-search-nim
```
/ MSA Search and map its A3M output into this
```
alignments
```
shape.
Starting with OpenFold2 2.0.0, use
```
explicit_templates
```
with mmCIF content; do not write new HHR-template examples.
```
selected_models
```
chooses AlphaFold2/OpenFold parameter sets 1-5. Select one or two models for smoke tests; use all five for stronger production runs.

建议使用Python

requests

库；curl对A3M/mmCIF文本的转义处理较为脆弱。

sequence

字段为必填项。

input_id

、

alignments

、

selected_models

、

relax_prediction

、

use_templates

和

explicit_templates

为可选字段。

python

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版本开始，需使用
```
explicit_templates
```
字段传入mmCIF内容；请勿编写新的HHR模板示例。
```
selected_models
```
用于选择AlphaFold2/OpenFold参数集（1-5）。冒烟测试可选择1或2个模型；生产环境运行建议使用全部5个模型。

Save And Interpret Output

保存与解读输出

The response includes one prediction per selected model, ordered by confidence. Save every returned structure-like text field and the full JSON response so field-shape differences are auditable. Production answers should explicitly write

.pdb

.cif

artifacts, preserve the response JSON, and print any confidence/ranking fields the service returns.

python

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)")

For production monomer runs:

Use
```
selected_models: [1, 2, 3, 4, 5]
```
unless the user requests a smoke test.
Use
```
relax_prediction: True
```
in Python payloads when relaxation is desired; JSON examples may show
```
true
```
.
State the sequence length caveat: hosted API docs list 1-1000 residues, while local support-matrix docs list up to 2048 residues on supported hardware.
If the task is a complex rather than a monomer, redirect to OpenFold3 or Boltz2.

Treat tiny toy sequences and single-sequence MSAs as API smoke tests, not quality evidence. For scientific interpretation and validation, read

references/science.md

and

references/validation.md

响应结果包含每个选中模型的预测结果，按置信度排序。保存所有返回的类结构文本字段以及完整的JSON响应，以便审计字段结构的差异。生产环境中应明确生成

.pdb

或

.cif

文件，保留响应JSON，并输出服务返回的所有置信度/排名字段。

python

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。

将小型测试序列和单序列MSAs视为API冒烟测试，而非质量验证依据。如需科学解读与验证，请阅读

references/science.md

和

references/validation.md

。

Troubleshooting

故障排查

```
401
```
: missing, expired, or unauthorized NGC API key.
```
422
```
: invalid amino-acid characters, sequence too long, malformed A3M, bad
```
selected_models
```
, or malformed mmCIF template object.
Local
```
404
```
: remove
```
/v1/
```
from the prediction URL.
Weak structures: use MSA Search to generate deeper A3M alignments and add biologically relevant mmCIF templates when appropriate.
Local startup stalls: first run downloads parameters into
```
LOCAL_NIM_CACHE
```
.

```
401
```
：NGC API密钥缺失、过期或未授权。
```
422
```
：氨基酸字符无效、序列过长、A3M格式错误、
```
selected_models
```
参数错误或mmCIF模板对象格式不正确。
本地
```
404
```
：移除预测URL中的
```
/v1/
```
。
结构预测质量不佳：使用MSA Search生成更全面的A3M比对，并在合适时添加生物学相关的mmCIF模板。
本地启动停滞：首次运行时会将模型参数下载到
```
LOCAL_NIM_CACHE
```
中。