genmol-nim

GenMol NIM

GenMol で医薬品らしい分子を生成します。このガイドでは、ホステッド環境とローカル環境での基本的な使い方を説明します。補足ファイルは必要な場合のみ参照してください。

• references/api.md：エンドポイント、スキーマ、Docker フラグ、レスポンスフィールド。
• references/science.md：ユースケース、強み、制限事項、引き継ぎ方法。
• references/parameters.md：SAFE パターンと調整による効果。
• references/validation.md：化学的検証と生成物のチェック。
• references/examples.md：簡潔なリクエストパターン。

モードの選択

状況が不明確な場合にのみ確認してください。

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

• ホステッド：https://health.api.nvidia.com/v1/biology/nvidia/genmol/generate
• ローカル：http://localhost:8000/generate

ホステッドリクエストでは、Authorization: Bearer $NGC_API_KEY を使用します。ローカル Docker では、NGC_API_KEY を使って（または事前チェックで NVIDIA_API_KEY を使って）イメージを取得するために docker login nvcr.io で認証します。エンタイトルメントの確認と初回のモデルダウンロードのため、コンテナに -e NGC_API_KEY を渡してください。準備完了後のローカル推論リクエストでは認証ヘッダーは不要です。そのため、公開ポートは -p 127.0.0.1:8000:8000 を使ってループバックにバインドしてください。ウォームキャッシュ時にキーなしで起動できるかどうかはイメージのバージョンによって異なるため、前提にしないでください。

ローカル Docker

シェル環境ですでに提供されている、またはシークレットマネージャーから注入された認証情報を使用してください。認証情報ファイルを読み込んだり、キーを表示したり、シェルトレースを有効にしたりしないでください。ローカルセットアップの回答には、次の順序を含めてください：環境変数の事前チェック、--password-stdin を使った docker login、docker run、準備完了確認のループ、認証なしのローカルホストへのリクエスト。キャッシュのデフォルト値を推測したり、NVIDIA_API_KEY のフォールバックを省略したりしないでください。

ローカルセットアップを実行する前に、レジストリ認証によってキーが https://nvcr.io の NVIDIA レジストリに送信され、初回のモデルダウンロードで LOCAL_NIM_CACHE に約 20 GB が使用されることを説明してください。 デプロイの実行はユーザーが依頼した場合に限ります。セットアップガイドの場合は、コマンドを実行せずに提示してください。

正確な起動前チェック（環境変数の確認、NVIDIA_API_KEY のフォールバック、--shm-size=2G、両方の --ulimit フラグ、docker login、および nvcr.io/nim/nvidia/genmol:1.0.1 用の docker run）については、references/api.md の ローカルコンテナの起動 にあるコマンドブロックをそのままコピーしてください。

GenMol は単一 GPU を使用し、NIM_TEST_GPU のデフォルト値は 0 です。準備完了を待ちます。

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

SAFE 入力

API フィールド名は smiles ですが、GenMol が想定するのは SAFE 表記です。マスク位置には [*{min-max}] を使用します。

• De novo：safe_input = "[*{20-30}]"
• スキャフォールドの修飾：safe_input = scaffold_to_safe("C1CC(=O)NC1", 10, 15)
• モチーフの拡張：safe_input = f"[*{{5-10}}].{motif_safe}.[*{{5-10}}]"
• リード最適化：ヒット化合物をエンコードし、フラグメントを .[*{5-12}] に置き換えます

条件付き生成には safe-mol を使用してください。単純な環状スキャフォールドでは SAFEFragmentationError が発生する場合があります。その場合は、元の SMILES と SAFE マスクを使用してください。

references/examples.md の スキャフォールドの修飾 にある scaffold_to_safe ヘルパーを参照してください。

マスクの範囲を広げると多様性が増し、狭くすると類似体のサイズを予測しやすくなります。

リクエストパターン

import os
import requests

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

payload = {
    "smiles": "[*{20-30}]",  # SAFE notation
    "num_molecules": 30,
    "temperature": "1",      # string, not float
    "noise": "1",            # string, not float
    "step_size": 1,
    "scoring": "QED",        # or "LogP"
    "unique": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=180)
response.raise_for_status()
result = response.json()

注意点：

• temperature と noise は文字列です。
• num_molecules の範囲は 1～1000 です。無効な分子や重複分子は除外される場合があるため、ユーザーが最低数を必要としている場合は余分にリクエストしてください。
• scoring は、医薬品らしさの評価には "QED"、親油性の評価には "LogP" を指定します。
• 重複を除いた類似体リストを得るには、unique=True を設定してください。

出力の保存と報告

分子をスコア順に並べ、上位の順位を表示し、references/examples.md の 順位付き結果の保存 にある方法で .smi ファイルに書き込みます。化学的妥当性、一意性、PAINS／アラート、RDKit による可視化については、references/validation.md を参照してください。

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

• フィルタリング後に、要求した数より分子が少なくなるのは想定どおりです。
• 無効な SAFE 文字列では、status: "failed" または検証エラーが発生します。
• 骨格、モチーフ、リード最適化のワークフローでのみ safe-mol をインストールしてください。 de novo マスクは変換なしで動作します。
• ローカルでの起動時に、約 20 GB が LOCAL_NIM_CACHE にダウンロードされます。
• コンテナーの問題が発生した場合は、nvidia-smi、NVIDIA Container Toolkit、--runtime=nvidia を確認してください。表示する GPU を 1 つ選ぶには、NIM_TEST_GPU を使用します。