proteinmpnn-nim

ProteinMPNN NIM

指定されたバックボーン PDB に対するタンパク質配列を設計します。初回のホスト型／ローカルでの使用にはこのガイドを参照し、補足ファイルは必要な場合にのみ読み込んでください。

• references/api.md：正確なエンドポイント、スキーマ、Docker フラグ、レスポンスフィールド。
• references/science.md：逆フォールディングの用途、制限、検証。
• references/parameters.md：設計制御、固定位置、サンプリング。
• references/validation.md：FASTA、スコア、構造のチェック。
• references/examples.md：ホスト型／ローカルの簡潔なリクエストパターン。

モードの選択

ユーザーが明示したモードを優先します。明示されていない場合は、設定済みのランタイムを使用します。NIM_API_MODE=local は、PROTEINMPNN_NIM_URL に設定されたローカルサービスを選択します。この URL のデフォルトは、同じホストまたはコンテナ内で実行されている NIM の場合、http://localhost:8000 です。環境変数でもユーザーのリクエストでもモードが明確にならない場合に限り、確認してください。

NVIDIA のホスト型 API とローカル Docker NIM のどちらを使用しますか？

• ホスト型：https://health.api.nvidia.com/v1/biology/ipd/proteinmpnn/predict
• ローカル：PROTEINMPNN_NIM_URL に /biology/ipd/proteinmpnn/predict を付加します（デフォルトのベース URL：http://localhost:8000）。

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

データの転送と認証

ホスト型リクエストを行う前に、PDB ファイル全体と設計パラメーターが、上記のエンドポイントにある NVIDIA のホスト型 API にアップロードされることをユーザーに伝えてください。ユーザーがその PDB のホスト型処理を明示的に依頼している場合、またはすでに転送を承認している場合は続行します。それ以外の場合は、送信前に確認を求めてください。機密性の高い構造については、ユーザーが承認した環境でのローカル NIM を推奨してください。設定済みのローカル URL が別のマシンを指している場合があります。設定済み、またはユーザーが選択した送信先のみを使用してください。ユーザーの許可なく、ローカル処理からホスト型処理に切り替えないでください。

クライアントは、環境変数から NIM_API_MODE、PROTEINMPNN_NIM_URL、およびホスト型モードの場合は NGC_API_KEY を読み取ります。キーは、HTTPS の Authorization ヘッダーでホスト型エンドポイントにのみ送信されます。ローカル推論ではキーを送信しません。認証情報をログや保存された成果物に含めないでください。出力ディレクトリには、request.json 内の入力 PDB 全体と、返された配列およびスコアが含まれます。そのため、入力の機密性に適した場所を使用してください。エンドポイントとデータの取り扱いについて詳しくは、references/api.md を参照してください。

ローカル Docker

ローカルでセットアップする場合は、環境変数のプリフライト、docker login、docker run、準備完了確認ループ、認証なしの localhost リクエストという一連の手順をすべて実行してください。localhost への Python リクエストだけで回答しないでください。正確なプリフライト（.env の読み込み、NGC_API_KEY／NVIDIA_API_KEY の処理、および nvcr.io/nim/ipd/proteinmpnn:latest を使った docker run）については、references/api.md の Docker Reference にあるコマンドブロックをそのままコピーしてください。この NIM のキャッシュマウント先は /home/nvs/.cache/nim であり、/opt/nim/.cache ではありません。PROTEINMPNN_NIM_URL が指定されている場合、サービスはすでに別の場所で管理されています。その URL を使用し、別の Docker コンテナを起動しないでください。

準備完了確認：

proteinmpnn_nim_url="${PROTEINMPNN_NIM_URL:-http://localhost:8000}"
until curl -sf "${proteinmpnn_nim_url%/}/v1/health/ready"; do sleep 5; done

手順

デザインの実行を依頼された場合は、scripts/design.py を実行し、その結果を確認してください。依頼スクリプトを書くだけでは、実行依頼を完了したことにはなりません。ユーザーがコードまたはセットアップ手順だけを求めている場合は、それらを提示し、推論リクエストは送信しないでください。

1. ユーザーが指定した PDB パスと配列数を使用してください。クライアントは PDB 全体を input_pdb に読み込みます。提供されたバックボーンを置き換えたり、切り詰めたりしないでください。
2. --mode hosted または --mode local を選択し、送信前に上記の データ転送と認証 に従ってください。ホステッドモードでは、PDB をドキュメントに記載された NVIDIA エンドポイントにアップロードし、環境に NGC_API_KEY が必要です。キーが設定されているかどうかだけを確認し、キーを表示したり、環境変数をダンプしたり、認証ヘッダーを保存したりしないでください。ローカル推論では認証ヘッダーは送信されません。
3. リクエストごとに新しい --output-dir を選択してください。クライアントは送信前に出力先を確保し、診断用に未加工のレスポンスを保持し、完了を報告する前に設計配列数とスコアの対応関係を検証します。
4. summary.json を読み、以下に示す実際の結果を報告してください。リクエストまたは検証が失敗した場合は、失敗と診断用パスを報告してください。サンプル配列で代用したり、同じリクエストを繰り返し再送信したりしないでください。

例

このスキルのディレクトリから実行するか、scripts/design.py に絶対パスを指定してください。ユーザーの入力パスと、新しい出力ディレクトリに置き換えてください。

python scripts/design.py --mode hosted \
  --pdb /path/to/backbone.pdb --num-sequences 10 \
  --temperature 0.1 --output-dir /path/to/new-design-run

実行中のローカル NIM には --mode local を使用してください。クライアントは PROTEINMPNN_NIM_URL を使用します。チェーン A のみを設計する場合、システインを除外する場合、または可溶性モデルをリクエストする場合は、それぞれ --chains A、--omit-aas C、--soluble を追加してください。--seed は random_seed を設定し、--ca-only は CA のみのモデルを選択します。ヘルパーはリクエストごとに温度を 1 つ使用します。温度を変えて試す場合は、出力ディレクトリを分けて実行してください。高度な JSONL 制御やカスタムバッチリクエストについては、references/api.md と references/examples.md のレスポンス後の例を参照してください。

出力の保存と報告

クライアントは、指定された出力ディレクトリに request.json、response.raw、response.json、designed_sequences.fa、summary.json を書き込みます。FASTA には、ネイティブ／WT エントリーがある場合、それを含む、返された mfasta 全体が保持されます。サマリーには設計配列のみが含まれ、それぞれに実際のスコアが対応付けられます。また、スコアが JSON 配列と FASTA ヘッダーのどちらから取得されたかも記録されます。成果物を保存して検証した後、サマリーは画面にも表示されます。

最終回答では、次の内容を報告してください。

• ネイティブ／WT 参照配列を除いた、設計済み配列の数。
• 各設計の ID、実際に返されたスコア、および配列。長い配列の場合は、プレビューであることを明記し、完全な FASTA へのリンクを示してください。
• 保存した FASTA とサマリーのパス、および出所を確認できる未加工レスポンスのパス。
• 実際に依頼され、実行された場合を除き、フォールドバック検証は行っていないこと。また、これらは逆フォールディングの候補配列であること。

スコアを、配列がフォールドする、または結合する証拠として扱わないでください。Boltz2 または OpenFold3 による追加検証は、次のステップとして任意で実施できます。FASTA とスコアの整合性を確認するには、references/validation.md を参照してください。

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

• 必要な GPU VRAM の最小容量：約 3 GB。
• sampling_temp は、値が 1 つだけの場合でもリストである必要があります。
• mfasta が空の場合：input_pdb にデータが含まれていること、および num_seq_per_target >= 1 であることを確認してください。
• PDB の解析エラー：有効な PDB ATOM レコードを使用してください。
• ローカル URL の 404 は、誤って /v1/ プレフィックスを付けたことが原因である場合がほとんどです。
• キャッシュのマウントエラー：コンテナ内では /home/nvs/.cache/nim を使用してください。