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 执行 docker login nvcr.io，以验证镜像拉取（也可通过预检使用 NVIDIA_API_KEY）。将 -e NGC_API_KEY 传入容器，用于授权检查和首次运行时的模型下载。就绪后，本地推理请求无需身份验证标头，因此请使用 -p 127.0.0.1:8000:8000 将发布的端口绑定到回环地址。无密钥的热缓存启动方式因镜像版本而异，不应想当然地假设可用。

本地 Docker

使用 shell 环境中已提供或由机密管理器注入的凭据。不要加载凭据文件、打印密钥或启用 shell 跟踪。回答本地设置问题时，请按以下顺序提供步骤：环境预检、使用 --password-stdin 执行 docker login、docker run、就绪循环，然后发送无身份验证的 localhost 请求。不要臆测缓存默认值，也不要省略 NVIDIA_API_KEY 备用选项。

执行本地设置之前，请说明：注册表身份验证会将密钥发送到 NVIDIA 注册表 https://nvcr.io；首次运行时的模型下载会在 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 中 Local container startup 下的命令块。

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}]。

• 从头生成：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 Decoration 下的 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 中 Save Ranked Results 下的示例写入 .smi 文件。有关使用 RDKit 检查化学有效性、唯一性、PAINS/警示项及可视化的信息，请阅读 references/validation.md。

限制与故障排查

• 过滤后，分子数量少于请求数量属于预期情况。
• 无效的 SAFE 字符串会导致 status: "failed" 或验证错误。
• 仅在支架、基序或先导优化工作流中安装 safe-mol；从头生成的掩码无需转换。
• 本地启动会向 LOCAL_NIM_CACHE 下载约 20 GB 的内容。
• 容器问题：确认 nvidia-smi、NVIDIA Container Toolkit 和 --runtime=nvidia；使用 NIM_TEST_GPU 选择唯一可见的 GPU。