MolMIM NIM

Générez, échantillonnez, intégrez et décodez des petites molécules avec MolMIM. Utilisez ce guide pour une première utilisation en mode hébergé/local ; chargez les fichiers supplémentaires uniquement si nécessaire :

references/api.md : endpoints, schéma, drapeaux Docker, champs de réponse.
references/science.md : cas d'usage, points forts, limites et transitions.
references/parameters.md : effets de la génération, l'échantillonnage et l'optimisation.
references/validation.md : vérifications SMILES/propriété/artefact.
references/examples.md : modèles de requêtes compacts hébergé/local.

Choisir le mode

Posez la question uniquement si le contexte est peu clair :

API NVIDIA hébergée ou NIM Docker local ?

Consultez references/api.md sous Endpoints pour la liste complète des endpoints hébergés/locaux.

Différence de mode : la référence API hébergée expose /generate ; le conteneur local expose le workflow d'espace latent plus large (/embedding, /hidden, /decode, /sampling, /generate). N'inventez pas d'endpoints latents hébergés.

Les requêtes hébergées utilisent Authorization: Bearer $NGC_API_KEY. L'inférence locale n'utilise aucun en-tête d'authentification après la vérification de disponibilité.

Docker local

Utilisez d'abord les variables d'environnement du shell ; sourcez le .env de la racine du repo uniquement s'il existe. N'affichez pas les clés. La documentation MolMIM utilise NGC_CLI_API_KEY pour le conteneur local ; ce repo accepte NGC_API_KEY ou NVIDIA_API_KEY et les mappe à NGC_CLI_API_KEY au démarrage. Montez LOCAL_NIM_CACHE à /home/nvs/.cache/nim.

Pour la vérification de démarrage exacte (la correspondance NGC_API_KEY/NVIDIA_API_KEY → NGC_CLI_API_KEY, docker login, et le docker run pour nvcr.io/nim/nvidia/molmim:1.0.0), copiez le bloc de commande dans references/api.md sous Local Docker textuellement.

Vérification de disponibilité :

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

Test de fumée d'embedding local après vérification de disponibilité. L'inférence locale n'utilise pas d'en-tête Authorization :

import requests

seed = "CN1C=NC2=C1C(=O)N(C(=O)N2C)C"
response = requests.post(
    "http://localhost:8000/embedding",
    headers={"Content-Type": "application/json"},
    json={"sequences": [seed]},
    timeout=60,
)
response.raise_for_status()
embedding_data = response.json()
embeddings = embedding_data["embeddings"]
print(f"received {len(embeddings)} embedding vector(s)")

Modèle de génération hébergé

Utilisez /generate hébergé pour la génération de seed-SMILES ou l'optimisation. Utilisez algorithm: "CMA-ES" pour l'optimisation de propriété guidée et algorithm: "none" pour l'échantillonnage non guidé autour du seed.

import os
import requests

hosted = True
url = (
    "https://health.api.nvidia.com/v1/biology/nvidia/molmim/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 = {
    "smi": "CN1C=NC2=C1C(=O)N(C(=O)N2C)C",
    "algorithm": "CMA-ES",
    "num_molecules": 10,
    "property_name": "QED",
    "minimize": False,
    "min_similarity": 0.4,
    "particles": 8,
    "iterations": 3,
}

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

Pièges de génération :

Le nom du champ est smi, pas smiles.
algorithm est "CMA-ES" ou "none".
property_name est "QED" ou "plogP".
num_molecules est 1-100. iterations est 1-1000. particles est 2-1000.
min_similarity est 0-1 dans la référence API hébergée ; la documentation locale insiste sur les valeurs courantes jusqu'à 0,7 pour l'optimisation contrainte.
scaled_radius est 0-2 et est principalement utilisé avec algorithm: "none" ou /sampling local.

Workflow latent local

Utilisez les endpoints locaux uniquement pour l'embedding, la manipulation d'état caché et le décodage. C'est aussi la surface utilisée par le package d'exemple d'optimisation guidée. Pour les workflows latents locaux, déclarez explicitement que la référence API hébergée expose /generate ; /embedding, /hidden, /decode et /sampling sont locaux uniquement dans la documentation actuelle.

seed = "CC(Cc1ccc(cc1)C(C(=O)O)C)C"
base = "http://localhost:8000"
headers = {"Content-Type": "application/json"}

embedding = requests.post(
    f"{base}/embedding",
    headers=headers,
    json={"sequences": [seed]},
    timeout=60,
)
embedding.raise_for_status()
embedding_data = embedding.json()
embeddings = embedding_data["embeddings"]
print(f"received {len(embeddings)} embedding vector(s)")

hidden = requests.post(
    f"{base}/hidden",
    headers=headers,
    json={"sequences": [seed]},
    timeout=60,
)
hidden.raise_for_status()
hidden_data = hidden.json()
hiddens = hidden_data["hiddens"]
mask = hidden_data["mask"]

decoded = requests.post(
    f"{base}/decode",
    headers=headers,
    json={"hiddens": hiddens, "mask": mask},
    timeout=60,
)
decoded.raise_for_status()

sampled = requests.post(
    f"{base}/sampling",
    headers=headers,
    json={"sequences": [seed], "num_molecules": 10, "scaled_radius": 0.7},
    timeout=60,
)
sampled.raise_for_status()

Enregistrer et valider la sortie

Enregistrez les SMILES générés et validez-les avant de les utiliser en aval.

from pathlib import Path
import json

def molmim_smiles(result):
    values = []
    if isinstance(result.get("generated"), list):
        for item in result["generated"]:
            if isinstance(item, str):
                values.append(item)
            elif isinstance(item, list):
                values.extend(x for x in item if isinstance(x, str))
    molecules = result.get("molecules")
    if isinstance(molecules, str):
        molecules = json.loads(molecules)
    if isinstance(molecules, list):
        for item in molecules:
            if isinstance(item, dict) and isinstance(item.get("sample"), str):
                values.append(item["sample"])
    return values

generated = molmim_smiles(result)
if not generated:
    raise RuntimeError(f"MolMIM returned no generated molecules: {result}")

Path("molmim_response.json").write_text(json.dumps(result, indent=2))
Path("molmim_generated.smi").write_text("\n".join(generated) + "\n")
for i, smiles in enumerate(generated, start=1):
    print(i, smiles)

Utilisez RDKit si disponible pour vérifier l'analysabilité, l'unicité, les plages de propriétés simples et si les contraintes de similarité au seed sont plausibles. Les molécules générées sont des candidats, non des hits validés ; utilisez des vérifications en aval de propriété, docking, affinité, toxicité et faisabilité synthétique avant la priorisation.

Dépannage

Hosted 404 sur /embedding, /hidden, /decode ou /sampling : ces endpoints sont locaux uniquement dans la documentation.
401 : clé NGC manquante ou non autorisée pour les requêtes hébergées.
Analyse des réponses hébergées : le /generate hébergé en direct peut retourner molecules comme une chaîne JSON d'objets {sample, score}, tandis que les endpoints locaux peuvent retourner generated ; analysez les deux.
422 : SMILES invalide, algorithm non supporté, property_name invalide, ou paramètre en dehors des plages documentées.
Auth de démarrage local : définissez NGC_CLI_API_KEY, ou définissez NGC_API_KEY/NVIDIA_API_KEY et mappez-le comme indiqué ci-dessus.
Erreurs de cache de démarrage local : montez LOCAL_NIM_CACHE à /home/nvs/.cache/nim, pas /opt/nim/.cache.

molmim-nim