boltz2-nim

Boltz2 NIM

生体分子の構造と、オプションでリガンド親和性を予測します。このガイドでは、まずホスト型／ローカル型での利用方法を説明します。必要な場合にのみ補足ファイルを読み込んでください。

• references/api.md：正確なエンドポイント、スキーマ、Docker フラグ、レスポンスフィールド。
• references/science.md：目的、強み、制限事項、引き継ぎ方法。
• references/parameters.md：予測、サンプリング、MSA、テンプレート、親和性の調整。
• references/validation.md：mmCIF、信頼度、親和性、化学的チェック。
• references/examples.md：ホスト型／ローカル型の簡潔なペイロード例。

手順

必要な場合にのみ、環境変数から認証情報を読み取ってください。bool(os.getenv("NGC_API_KEY")) で有無を確認してください。キーの値や Authorization ヘッダーを、ターミナル出力、ログ、保存済みアーティファクト、最終回答に含めないでください。認証の問題を診断する際は、環境変数の一括出力を避けてください。ホスト型のキーが設定されていない場合は、リクエストを送信する前に、変数が未設定であることを報告してください。

モードの選択

状況が不明確な場合にのみ、次のように質問してください。

NVIDIA API のホスト型ですか、それともローカルの Docker NIM ですか？

• ホスト型：https://health.api.nvidia.com/v1/biology/mit/boltz2/predict
• ローカル：http://localhost:8000/biology/mit/boltz2/predict

ホスト型のリクエストでは Authorization: Bearer $NGC_API_KEY を使用します。サポート対象のローカル Docker 起動では、レジストリへのログイン、利用資格の確認、初回のモデルダウンロードに NGC_API_KEY（またはプリフライトで使用する NVIDIA_API_KEY）を使用します。-e NGC_API_KEY でコンテナに渡してください。準備完了後のローカル推論リクエストでは、認証ヘッダーは不要です。ウォームキャッシュを使ったキー不要の起動方法は、イメージやバージョンによって異なるため、前提としないでください。

ローカル Docker

ローカルセットアップについて回答する場合は、docker login、docker run、準備状況の確認、認証なしのローカルリクエストより前に、以下のプリフライトをそのまま記載してください。キャッシュのデフォルトを作り上げたり、.env の読み込みや NVIDIA_API_KEY へのフォールバックを省略したりしないでください。

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 boltz2 --gpus all \
  --shm-size=16G \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/mit/boltz2:1.6.0

準備状況：

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

初回起動時には、約 30 GB のモデル重みがダウンロードされます。

例

予測リクエスト

import os
import requests

HOSTED = True
url = (
    "https://health.api.nvidia.com/v1/biology/mit/boltz2/predict"
    if HOSTED else "http://localhost:8000/biology/mit/boltz2/predict"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
    api_key = os.getenv("NGC_API_KEY")
    if not api_key:
        raise SystemExit("NGC_API_KEY is required for the hosted API")
    headers["Authorization"] = f"Bearer {api_key}"

payload = {
    "polymers": [{
        "id": "A",
        "molecule_type": "protein",
        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT",
    }],
    "recycling_steps": 3,
    "sampling_steps": 50,
    "diffusion_samples": 1,
    "step_scale": 1.638,
    "output_format": "mmcif",
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

ペイロードの要点：

• タンパク質ポリマー：{"molecule_type": "protein", "sequence": "..."}。
• DNA／RNA ポリマー：molecule_type を "dna" または "rna" にしたポリマーを追加します。
• SMILES によるリガンド：{"id": "L1", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}。
• CCD によるリガンド：{"id": "L1", "ccd": "ATP"}。
• 親和性：リガンドをちょうど 1 つ選び、"predict_affinity": True を設定します。affinity_pic50、affinity_pred_value、affinity_probability_binary を報告してください。
• 事前計算済みの A3M MSA は、タンパク質ポリマーの下に指定します。A3M レコードでは alignment、format、rank を使用し、古い data フィールドは使用しないでください。

protein_with_msa = {
    "id": "A",
    "molecule_type": "protein",
    "sequence": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
    "msa": {"msa_search": {"a3m": {
        "alignment": ">query\nMTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT",
        "format": "a3m",
        "rank": 0,
    }}},
}

出力の保存と報告

すべての .cif アーティファクトを保存し、references/examples.md の Save Structures And Affinity にあるスニペットを使って、信頼度／親和性フィールドを読み取ってください。PyMOL、ChimeraX、または UCSF Chimera で可視化してください。信頼度／親和性の妥当性チェックについては、references/validation.md を参照してください。

制限事項とトラブルシューティング

• ポリマー／リクエスト数：12。リガンド／リクエスト数：20。鎖長：4096 残基。
• 親和性予測では、1 リクエストにつき 1 つのリガンドのみサポートされ、実行時間が長くなります。
• 422：無効な配列、無効な CCD／SMILES、不正な形式の MSA、または複数の親和性リガンド。
• ローカル URL／認証：ローカルパスにはホスト型の認証ヘッダーは不要です。/v1/health/ready が準備完了になるまで待ってください。
• ローカル起動：--gpus all、--shm-size=16G、および /opt/nim/.cache のマウントを使用してください。