rfdiffusion-nim

RFDiffusion NIM

为从头设计蛋白质、基序支架和结合蛋白，生成蛋白质主链 PDB。 本指南适用于初步托管／本地使用；仅在需要时加载补充文件：

• references/api.md：精确的端点、架构、Docker 标志和响应字段。
• references/science.md：设计模式、优势、限制和后续衔接。
• references/parameters.md：contigs、热点、步数和种子。
• references/validation.md：PDB、contig 和产物的健全性检查。
• references/examples.md：精简的托管／本地请求模式。

选择模式

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

使用 NVIDIA 托管 API 还是本地 Docker NIM？

• 托管：https://health.api.nvidia.com/v1/biology/ipd/rfdiffusion/generate
• 本地：http://localhost:8000/biology/ipd/rfdiffusion/generate

本地推理路径不包含 /v1/。托管请求使用 Authorization: Bearer $NGC_API_KEY。受支持的本地 Docker 启动会使用 NGC_API_KEY（或通过预检使用 NVIDIA_API_KEY）进行注册表登录、授权检查和首次模型下载；使用 -e NGC_API_KEY 将其传入容器。本地推理请求在服务就绪后无需身份验证标头。不同映像／版本的预热缓存免密钥启动方式有所不同，不应假定其可用。

本地 Docker

回答本地设置问题时，请在 docker login、docker run、就绪检查和无身份验证的本地请求之前，原样复制以下预检代码。不要将其替换为简单的 : "${NGC_API_KEY:?Set NGC_API_KEY}" 检查，不要臆造缓存默认值，也不要删掉 NVIDIA_API_KEY 备用选项。默认设置为单 GPU device=0。

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 -it \
  --runtime=nvidia \
  --gpus "device=0" \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/ipd/rfdiffusion:2

就绪检查：

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

Contigs DSL

contigs 用于定义要保留和生成的内容。完整的模式语法（固定长度、范围、保留的链段、链间断点）请参阅 references/api.md 中的 Contigs Language Reference。

设计模式：

• 从头设计：contigs="80-120"；托管端的实时验证要求 input_pdb 或 input_pdb_asset 非空，因此内联请求应包含下方的虚拟 PDB。
• 基序支架：读取 target.pdb，传入 input_pdb，并使用类似 "A25-35/0 50-80" 的 contig。
• 结合蛋白设计：传入目标 input_pdb、包含目标和结合蛋白片段的 contig，以及 hotspot_res=["A50", "A51", ...]，采用 ChainResidue 字符串格式。

DUMMY_PDB = (
    "CRYST1    1.000    1.000    1.000  90.00  90.00  90.00 P 1           1\n"
    "ATOM      1  CA  ALA A   1       0.000   0.000   0.000  1.00  0.00           C\n"
    "END\n"
)

请求模式

import os
from pathlib import Path
import requests

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

payload = {
    "input_pdb": DUMMY_PDB,
    "contigs": "80-120",
    "diffusion_steps": 50,
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()
Path("designed_backbone.pdb").write_text(result["output_pdb"])

基序支架：

payload = {
    "input_pdb": Path("target.pdb").read_text(),
    "contigs": "A25-35/0 50-80",
    "diffusion_steps": 50,
}

结合蛋白设计：

payload = {
    "input_pdb": Path("target.pdb").read_text(),
    "contigs": "A1-100/0 50-100",
    "hotspot_res": ["A50", "A51", "A52", "A53", "A54"],
    "diffusion_steps": 50,
}

保存和解读输出

将 result["output_pdb"] 保存为 PDB 产物，并在存在 elapsed_ms 时报告其值。生成的主链并非最终蛋白质；应将其交给 ProteinMPNN 进行序列设计，然后使用 Boltz2 或 OpenFold3 验证序列／结构。如需检查 PDB 和 contig，请参阅 references/validation.md。

限制和故障排除

• diffusion_steps：1-50；50 表示最高质量，步数越少速度越快。
• 单 GPU；最低 GPU 显存约为 12 GB。
• hotspot_res 使用 "A50" 这类字符串，而非元组。
• 422 通常表示 contigs／hotspot_res 中的链 ID 与 input_pdb 不匹配、contig 格式错误，或托管端从头设计时未提供 input_pdb。
• 本地 URL 返回 404 通常是因为误加了 /v1/ 前缀。