genmol-nim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GenMol NIM

Generate drug-like molecules with GenMol. Use this

SKILL.md

for first-pass hosted/local usage; load supplemental files only when needed:

```
references/api.md
```
: endpoints, schema, Docker flags, response fields.
```
references/science.md
```
: use cases, strengths, limits, and handoffs.
```
references/parameters.md
```
: SAFE patterns and tuning effects.
```
references/validation.md
```
: chemical and artifact checks.
```
references/examples.md
```
: compact request patterns.

使用GenMol生成类药分子。请使用此

SKILL.md

进行首次托管/本地使用；仅在需要时加载补充文件：

```
references/api.md
```
：端点、模式、Docker参数、响应字段。
```
references/science.md
```
：用例、优势、局限性及交接说明。
```
references/parameters.md
```
：SAFE模式及调优效果。
```
references/validation.md
```
：化学有效性及人工产物检查。
```
references/examples.md
```
：简洁请求模式。

Choose Mode

选择模式

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

Hosted:

https://health.api.nvidia.com/v1/biology/nvidia/genmol/generate

Local:
```
http://localhost:8000/generate
```

Hosted requests use

Authorization: Bearer $NGC_API_KEY

. Supported local Docker startup uses

NGC_API_KEY

(or

NVIDIA_API_KEY

via the preflight) for registry login, entitlement checks, and first-run model downloads; pass it into the container with

-e NGC_API_KEY

. Local inference requests use no auth header after readiness. Warm-cache key-free startup varies by image/version and should not be assumed.

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

使用托管式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

）进行注册表登录、权限验证及首次运行模型下载；需通过

-e NGC_API_KEY

将其传入容器。本地推理请求在就绪后无需认证头。无缓存密钥的预热启动因镜像/版本而异，请勿默认假设其可用。

Local Docker

本地Docker部署

Use shell env first; source repo-root

.env

only if present. Do not print keys. For local setup answers, include this sequence: env preflight,

docker login

docker run

, readiness loop, then a no-auth localhost request. Do not invent a cache default or drop the

NVIDIA_API_KEY

fallback.

For the exact startup preflight (

.env

sourcing,

NVIDIA_API_KEY

fallback,

--shm-size=2G

, both

--ulimit

flags,

docker login

, and the

docker run

for

nvcr.io/nim/nvidia/genmol:1.0.1

), copy the command block in

references/api.md

under Docker run reference verbatim.

GenMol is single-GPU;

NIM_TEST_GPU

defaults to

. Wait for readiness:

bash

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

优先使用Shell环境变量；仅当存在仓库根目录的

.env

文件时才加载它。请勿打印密钥。对于本地设置相关问题，请包含以下步骤：环境预检、

docker login

、

docker run

、就绪循环，然后发起无认证的本地主机请求。请勿自行设置缓存默认值，也不要省略

NVIDIA_API_KEY

备选方案。

如需获取确切的启动预检流程（包括

.env

文件加载、

NVIDIA_API_KEY

备选、

--shm-size=2G

、两个

--ulimit

参数、

docker login

以及针对

nvcr.io/nim/nvidia/genmol:1.0.1

的

docker run

命令），请直接复制

references/api.md

中Docker run reference下的命令块内容。

GenMol为单GPU运行；

NIM_TEST_GPU

默认值为

。等待服务就绪：

bash

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

SAFE Input

SAFE输入

The API field is named

smiles

, but GenMol expects SAFE notation. Masked positions use

[*{min-max}]

De novo:
```
safe_input = "[*{20-30}]"
```

Scaffold decoration:

safe_input = scaffold_to_safe("C1CC(=O)NC1", 10, 15)

Motif extension:

safe_input = f"[*{{5-10}}].{motif_safe}.[*{{5-10}}]"

Lead optimization: encode the hit, then replace a fragment with
```
.[*{5-12}]
```

Use

safe-mol

for conditioned generation. Simple ring scaffolds may raise

SAFEFragmentationError

; fall back to the original SMILES plus a SAFE mask.

See the

scaffold_to_safe

helper in

references/examples.md

under Scaffold Decoration.

Wider masks increase diversity; tight masks keep analog size more predictable.

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

辅助函数。

掩码范围越宽，多样性越高；掩码范围越窄，类似物大小越可预测。

Request Pattern

请求模式

python

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.0",    # string, not float
    "noise": "1.0",          # 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()

Gotchas:

```
temperature
```
and
```
noise
```
are strings.
```
num_molecules
```
is 1-1000; invalid/duplicate molecules may be filtered, so request extra when the user needs a minimum count.
```
scoring
```
is
```
"QED"
```
for drug-likeness or
```
"LogP"
```
for lipophilicity.
Set
```
unique=True
```
for deduplicated analog lists.

python

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.0",    # string, not float
    "noise": "1.0",          # 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
```
可获取去重的类似物列表。

Save And Report Output

保存并报告输出

Sort molecules by score, print the top ranks, and write a

.smi

file as shown in

references/examples.md

under Save Ranked Results. For chemical validity, uniqueness, PAINS/alerts, and visualization with RDKit, read

references/validation.md

按分数对分子排序，打印排名靠前的结果，并按照

references/examples.md

中Save Ranked Results下的示例写入

.smi

文件。如需了解化学有效性、唯一性、PAINS警示及使用RDKit进行可视化，请阅读

references/validation.md

。

Limits And Troubleshooting

局限性与故障排除

Fewer molecules than requested is expected after filtering.
Invalid SAFE strings cause
```
status: "failed"
```
or validation errors.
Install
```
safe-mol
```
only for scaffold, motif, or lead-optimization workflows; de novo masks work without conversion.
Local startup downloads about 20 GB into
```
LOCAL_NIM_CACHE
```
.
Container issues: confirm
```
nvidia-smi
```
, NVIDIA Container Toolkit, and
```
--runtime=nvidia
```
; use
```
NIM_TEST_GPU
```
to choose the single visible GPU.

过滤后得到的分子数量可能少于请求数量，这属于正常情况。
无效的SAFE字符串会导致
```
status: "failed"
```
或验证错误。
仅在进行骨架、基序或先导化合物优化工作流时才需要安装
```
safe-mol
```
；从头生成掩码无需转换即可使用。
本地启动时会下载约20GB数据到
```
LOCAL_NIM_CACHE
```
目录。
容器问题：请确认
```
nvidia-smi
```
、NVIDIA Container Toolkit及
```
--runtime=nvidia
```
已正确配置；使用
```
NIM_TEST_GPU
```
选择单个可见GPU。