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（または preflight を介した NVIDIA_API_KEY）を使用します。-e NGC_API_KEY でコンテナに渡してください。準備状態の確認後、ローカルの推論リクエストでは認証ヘッダーを使用しないため、ホストポートはループバックにバインドし、-p 127.0.0.1:8000:8000 を指定してください。キャッシュが温まった後のキー不要な起動方法はイメージのバージョンによって異なるため、前提にしないでください。

認証と環境

環境内で既に提供されている、またはシークレットマネージャーから注入された認証情報を使用してください。認証情報ファイルを読み込んだり、キーを表示したり、シェルトレースを有効にしたりしないでください。シェルテストでキーの有無を確認してください。

ホスト型では、リクエストヘッダーに 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 のモデル重みがキャッシュにダウンロードされることを説明してください。デプロイは依頼された場合にのみ実行してください。セットアップガイドを求められた場合は、コマンドを提示するだけで、実行しないでください。

ローカルのセットアップコマンドを記述するときは、以下の preflight をそのままコピーしてください。単純な : "${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 が受け付ける入力は 1 つだけです。
• molecules には、type が protein、dna、rna、ligand のいずれかであるオブジェクトを 1～32 個指定できます。
• タンパク質／RNA の MSA は省略できますが、指定する場合、alignment は >query\nSEQUENCE のような FASTA ヘッダーで始まる必要があります。
• リガンドでは smiles または ccd_codes のいずれかを使用します。例：{"type": "ligand", "id": "L", "ccd_codes": "ATP"}。
• DNA／RNA エンティティでは、たとえば {"type": "dna", "id": "B", "sequence": "ATCGATCG"} のように sequence を使用します。
• 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。
• 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 を使用してください。