openfold3-nim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenFold3 NIM

Predict biomolecular structures with OpenFold3. It supports proteins, DNA, RNA, small-molecule ligands, and multi-entity assemblies. 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
```
: purpose, strengths, limitations, and model handoffs.
```
references/parameters.md
```
: molecule fields, MSAs, templates, samples, tuning.
```
references/validation.md
```
: artifact checks and scientific sanity checks.
```
references/examples.md
```
: compact hosted/local request patterns.

使用OpenFold3预测生物分子结构。它支持蛋白质、DNA、RNA、小分子配体以及多实体复合物。本

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/openfold3/predict

Local URL:

http://localhost:8000/biology/openfold/openfold3/predict

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

Mode difference: the local prediction path has no

/v1/

prefix. 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？

托管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

将其传入容器。本地推理请求在就绪检查通过后无需身份验证头。无密钥的预热缓存启动方式因镜像/版本而异，不应默认使用。

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. Local startup needs

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 before validation.

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

托管模式需在请求头中携带

NGC_API_KEY

。本地启动需

NGC_API_KEY

（或备用的

NVIDIA_API_KEY

）以及

LOCAL_NIM_CACHE

。可在验证前加载仓库根目录下的

.env

文件作为本地配置覆盖。

Local Docker

本地Docker部署

Use the official OpenFold3 NIM image and mount

LOCAL_NIM_CACHE

/opt/nim/.cache

. First startup downloads model artifacts and can take several minutes.

When writing local setup commands, copy the preflight below exactly. Do not replace it with a simple

: "${NGC_API_KEY:?Set NGC_API_KEY}"

check, do not drop

NVIDIA_API_KEY

, and do not invent a default

LOCAL_NIM_CACHE

; those lines are the repo's local NIM env contract. The default single-GPU launch should show the literal

--gpus "device=0"

; choose a different device only when the user asks.

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 openfold3 \
  --runtime=nvidia \
  --gpus "device=0" \
  --shm-size=16g \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/openfold/openfold3:latest

Readiness check:

bash

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

使用官方OpenFold3 NIM镜像，并将

LOCAL_NIM_CACHE

挂载到

/opt/nim/.cache

。首次启动会下载模型产物，可能需要数分钟时间。

编写本地搭建命令时，请完全复制以下预检代码。不要将其替换为简单的

: "${NGC_API_KEY:?Set NGC_API_KEY}"

检查，不要删除

NVIDIA_API_KEY

，也不要自行设置

LOCAL_NIM_CACHE

的默认值；这些代码是仓库本地NIM环境的约定。默认单GPU启动应显示字面量

--gpus "device=0"

；仅当用户要求时才选择其他设备。

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 openfold3 \
  --runtime=nvidia \
  --gpus "device=0" \
  --shm-size=16g \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/openfold/openfold3:latest

就绪检查：

bash

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

Request Pattern

请求模式

Use

requests.post(..., json=payload, timeout=300)

. For local Docker tasks, set

hosted = False

after the readiness check passes.

python

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

Payload gotchas:

Top level is
```
{"inputs": [...]}
```
and OpenFold3 accepts exactly one input.
```
molecules
```
can contain 1-32 objects with
```
type
```
:
```
protein
```
,
```
dna
```
,
```
rna
```
, or
```
ligand
```
.
Protein/RNA MSAs are optional but, when supplied,
```
alignment
```
must start with a FASTA header such as
```
>query\nSEQUENCE
```
.

Ligands use either

smiles

ccd_codes

, for example

{"type": "ligand", "id": "L", "ccd_codes": "ATP"}

DNA/RNA entities use

sequence

, for example

{"type": "dna", "id": "B", "sequence": "ATCGATCG"}

```
diffusion_samples
```
is 1-5.
```
output_format
```
is
```
pdb
```
or
```
cif
```
.

使用

requests.post(..., json=payload, timeout=300)

。对于本地Docker任务，在就绪检查通过后设置

hosted = False

。

python

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个对象，类型为
```
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
```
。

Save And Interpret Output

保存与解读输出

Save every returned structure as a scientific artifact. Main response path:

result["outputs"][0]["structures_with_scores"]

python

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

Higher

confidence_score

complex_plddt_score

ptm_score

, and

iptm_score

are generally better; lower

complex_pde_score

is generally better. Treat toy or very short sequences as API smoke tests, not meaningful structural biology. For why and when OpenFold3 is scientifically appropriate, read

references/science.md

将所有返回的结构保存为科学产物。主要响应路径为：

result["outputs"][0]["structures_with_scores"]

。

python

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

。

Common Limits

常见限制

Inputs per request: 1.
Molecules per input: 1-32.
Diffusion samples: 1-5.
TensorRT path supports shorter sequences; PyTorch path can support longer sequences, but long inputs need much more GPU memory.
Sequences over roughly 1800 residues require at least 80 GB GPU memory.
Local NIM is single-GPU only; choose the target device in the Docker flag.

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

Troubleshooting

故障排查

```
401
```
: missing, expired, or unauthorized NGC API key.
```
422
```
: invalid molecule type, invalid sequence characters, bad MSA shape, or
```
diffusion_samples
```
outside 1-5.
MSA errors: ensure the alignment starts with
```
>query\n
```
.
Local
```
404
```
: remove
```
/v1/
```
from the prediction URL.
Local startup stalls: first run may be downloading 10-15 GB of model weights into
```
LOCAL_NIM_CACHE
```
.
Memory errors: shorten the sequence, reduce samples, or use a larger GPU.

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