molmim-nim

MolMIM NIM

使用 MolMIM 生成、采样、嵌入和解码小分子。请使用本指南了解初步的托管/本地用法；仅在需要时加载补充文件：

• references/api.md：端点、架构、Docker 标志和响应字段。
• references/science.md：用例、优势、限制和交接。
• references/parameters.md：生成、采样和优化的影响。
• references/validation.md：SMILES/属性/产物检查。
• references/examples.md：精简的托管/本地请求模式。

选择模式

仅在上下文不明确时询问：

NVIDIA 托管 API 还是本地 Docker NIM？

完整的托管/本地端点列表，请参阅 references/api.md 中的 Endpoints。

模式差异：托管 API 参考文档列出了 /generate；本地容器则提供更广泛的潜空间工作流（/embedding、/hidden、/decode、/sampling、/generate）。不要臆造托管潜空间端点。

托管请求使用 Authorization: Bearer $NGC_API_KEY。本地推理在就绪后无需身份验证标头。

本地 Docker

优先使用 shell 环境变量；仅在仓库根目录存在 .env 时才加载。不要打印密钥。MolMIM 文档要求本地容器使用 NGC_CLI_API_KEY；本仓库接受 NGC_API_KEY 或 NVIDIA_API_KEY，并在启动时将其映射到 NGC_CLI_API_KEY。将 LOCAL_NIM_CACHE 挂载到 /home/nvs/.cache/nim。

准确的启动前检查（NGC_API_KEY/NVIDIA_API_KEY → NGC_CLI_API_KEY 映射、docker login，以及用于 nvcr.io/nim/nvidia/molmim:1.0.0 的 docker run），请原样复制 references/api.md 中 Local Docker 下的命令块。

就绪检查：

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

就绪后进行本地嵌入冒烟测试。本地推理无需 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)")

托管生成模式

使用托管 /generate 根据种子 SMILES 生成分子或进行优化。使用 algorithm: "CMA-ES" 进行引导式属性优化，使用 algorithm: "none" 在种子周围进行非引导式采样。

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()

生成注意事项：

• 字段名是 smi，不是 smiles。
• algorithm 的值为 "CMA-ES" 或 "none"。
• property_name 的值为 "QED" 或 "plogP"。
• num_molecules 的范围为 1-100。iterations 的范围为 1-1000。particles 的范围为 2-1000。
• 托管 API 参考文档中，min_similarity 的范围为 0-1；本地文档强调在受限优化中常用的值最高可达 0.7。
• scaled_radius 的范围为 0-2，主要与 algorithm: "none" 或本地 /sampling 搭配使用。

本地潜空间工作流

使用仅限本地的端点进行嵌入、隐藏状态操作和解码。这也是引导式优化示例包所使用的接口。对于本地潜空间工作流，请明确说明托管 API 参考文档列出了 /generate；/embedding、/hidden、/decode 和 /sampling 在当前文档中仅限本地使用。

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()

保存并验证输出

保存生成的 SMILES，并在后续使用前进行验证。

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)

如果可用，请使用 RDKit 检查是否可解析、是否唯一、简单的属性范围，以及种子相似度约束是否合理。生成的分子是候选分子，并非经过验证的命中分子；在确定优先级之前，应进行下游属性、对接、亲和力、毒性和合成可行性检查。

故障排除

• 在 /embedding、/hidden、/decode 或 /sampling 上收到托管 404：这些端点在文档中仅限本地使用。
• 401：托管请求缺少 NGC 密钥，或密钥未获授权。
• 托管响应解析：实时托管 /generate 可能会将 molecules 作为 {sample, score} 对象的 JSON 字符串返回，而本地端点可能会返回 generated；请同时解析这两种格式。
• 422：SMILES 无效、algorithm 不受支持、property_name 无效，或参数超出文档所述范围。
• 本地启动身份验证：设置 NGC_CLI_API_KEY，或设置 NGC_API_KEY/NVIDIA_API_KEY 并按上述说明进行映射。
• 本地启动时缓存未命中：将 LOCAL_NIM_CACHE 挂载到 /home/nvs/.cache/nim，而不是 /opt/nim/.cache。