openfold2-nim

OpenFold2 NIM

アミノ酸配列から単一タンパク質鎖の構造を予測します。オプションでA3M多重配列アラインメントとmmCIFテンプレートを指定できます。基本的なホスト版／ローカル版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/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キーを表示しないでください。キーの存在確認には、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以上、システムRAM 64 GB、CPUコア8個、サポート対象のGPU 1基以上を推奨しています。コンテナのサイズは約55 GBで、初回起動時には約10 GBのモデルパラメーターがダウンロードされます。

正確な起動前チェック（.envの読み込み、NGC_API_KEY／NVIDIA_API_KEYの処理、docker login、およびnvcr.io/nim/openfold/openfold2:latestのdocker run）については、references/api.mdのローカル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を選択します。スモークテストでは1つまたは2つのモデルを選択し、本番環境でより高い精度を得るには5つすべてを使用してください。

出力の保存と解釈

応答には、選択したモデルごとに予測結果が1つずつ含まれ、信頼度の高い順に並んでいます。 返された構造形式のテキストフィールドをすべて保存し、完全な 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 にパラメーターがダウンロードされます。