molmim-nim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MolMIM NIM

Generate, sample, embed, and decode small molecules with MolMIM. 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
```
: generation, sampling, and optimization effects.
```
references/validation.md
```
: SMILES/property/artifact checks.
```
references/examples.md
```
: compact hosted/local request patterns.

使用MolMIM进行小分子的生成、采样、嵌入与解码。本

SKILL.md

文件适用于首次使用托管/本地部署场景；仅在需要时加载补充文件：

```
references/api.md
```
：端点、schema、Docker参数、响应字段。
```
references/science.md
```
：使用场景、优势、局限性及交接说明。
```
references/parameters.md
```
：生成、采样与优化的参数效果说明。
```
references/validation.md
```
：SMILES/属性/人工产物检查方法。
```
references/examples.md
```
：简洁的托管/本地请求示例。

Choose Mode

选择运行模式

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

See

references/api.md

under Endpoints for the full hosted/local endpoint list.

Mode difference: the hosted API reference exposes

/generate

; the local container exposes the broader latent-space workflow (

/embedding

/hidden

/decode

/sampling

/generate

). Do not invent hosted latent endpoints.

Hosted requests use

Authorization: Bearer $NGC_API_KEY

. Local inference uses no auth header after readiness.

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

使用NVIDIA托管API还是本地Docker NIM？

请查看

references/api.md

中的Endpoints章节，获取完整的托管/本地端点列表。

模式差异：托管API仅开放

/generate

端点；本地容器则支持更全面的潜空间工作流（

/embedding

、

/hidden

、

/decode

、

/sampling

、

/generate

）。请勿虚构托管端的潜空间相关端点。

托管请求需使用

Authorization: Bearer $NGC_API_KEY

。本地推理在就绪后无需认证头。

Local Docker

本地Docker部署

Use shell env first; source repo-root

.env

only if present. Do not print keys. MolMIM docs use

NGC_CLI_API_KEY

for the local container; this repo accepts

NGC_API_KEY

NVIDIA_API_KEY

and maps to

NGC_CLI_API_KEY

for startup. Mount

LOCAL_NIM_CACHE

/home/nvs/.cache/nim

For the exact startup preflight (the

NGC_API_KEY

NVIDIA_API_KEY

→

NGC_CLI_API_KEY

mapping,

docker login

, and the

docker run

for

nvcr.io/nim/nvidia/molmim:1.0.0

), copy the command block in

references/api.md

under Local Docker verbatim.

Readiness check:

bash

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

Local embedding smoke test after readiness. Local inference uses no

Authorization

header:

python

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

优先使用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章节下的命令块。

就绪检查：

bash

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

就绪后进行本地嵌入冒烟测试。本地推理无需

Authorization

头：

python

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

Hosted Generation Pattern

托管生成模式

Use hosted

/generate

for seed-SMILES generation or optimization. Use

algorithm: "CMA-ES"

for guided property optimization and

algorithm: "none"

for unguided sampling around the seed.

python

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

Generation gotchas:

Field name is
```
smi
```
, not
```
smiles
```
.
```
algorithm
```
is
```
"CMA-ES"
```
or
```
"none"
```
.
```
property_name
```
is
```
"QED"
```
or
```
"plogP"
```
.
```
num_molecules
```
is 1-100.
```
iterations
```
is 1-1000.
```
particles
```
is 2-1000.
```
min_similarity
```
is 0-1 in the hosted API reference; local docs emphasize common values up to 0.7 for constrained optimization.
```
scaled_radius
```
is 0-2 and is mainly used with
```
algorithm: "none"
```
or local
```
/sampling
```
.

使用托管

/generate

端点进行基于种子SMILES的生成或优化。使用

algorithm: "CMA-ES"

进行属性引导优化，使用

algorithm: "none"

进行基于种子的无引导采样。

python

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。
```
min_similarity
```
在托管API文档中范围为0-1；本地文档强调在约束优化中常用值不超过0.7。
```
scaled_radius
```
范围为0-2，主要用于
```
algorithm: "none"
```
或本地
```
/sampling
```
场景。

Local Latent Workflow

本地潜空间工作流

Use local-only endpoints for embedding, hidden-state manipulation, and decode. This is also the surface used by the guided optimization example package. For local latent workflows, state explicitly that the hosted API reference exposes

/generate

;

/embedding

/hidden

/decode

, and

/sampling

are local-only in the current docs.

python

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

使用本地专属端点进行嵌入、隐藏状态操作与解码。这也是引导优化示例包所使用的接口。对于本地潜空间工作流，需明确说明托管API仅开放

/generate

端点；当前文档中

/embedding

、

/hidden

、

/decode

和

/sampling

均为本地专属端点。

python

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

Save And Validate Output

保存并验证输出

Save generated SMILES and validate before using them downstream.

python

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)

Use RDKit when available to check parseability, uniqueness, simple property ranges, and whether seed similarity constraints are plausible. Generated molecules are candidates, not validated hits; use downstream property, docking, affinity, toxicity, and synthetic-feasibility checks before prioritization.

保存生成的SMILES并在下游使用前进行验证。

python

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检查SMILES的可解析性、唯一性、简单属性范围，以及种子相似性约束是否合理。生成的分子仅为候选，并非经过验证的有效产物；在优先选择前，需进行下游属性、对接、亲和力、毒性及合成可行性检查。

Troubleshooting

故障排除

Hosted
```
404
```
on
```
/embedding
```
,
```
/hidden
```
,
```
/decode
```
, or
```
/sampling
```
: those endpoints are local-only in the docs.
```
401
```
: missing or unauthorized NGC key for hosted requests.
Hosted response parsing: live hosted
```
/generate
```
may return
```
molecules
```
as a JSON string of
```
{sample, score}
```
objects, while local endpoints may return
```
generated
```
; parse both.
```
422
```
: invalid SMILES, unsupported
```
algorithm
```
, invalid
```
property_name
```
, or parameter outside documented ranges.
Local startup auth: set
```
NGC_CLI_API_KEY
```
, or set
```
NGC_API_KEY
```
/
```
NVIDIA_API_KEY
```
and map it as shown above.

Local startup cache misses: mount

LOCAL_NIM_CACHE

/home/nvs/.cache/nim

, not

/opt/nim/.cache

托管端调用
```
/embedding
```
、
```
/hidden
```
、
```
/decode
```
或
```
/sampling
```
返回
```
404
```
：这些端点在文档中仅支持本地部署。
```
401
```
：托管请求缺少NGC密钥或密钥未授权。
托管响应解析：实时托管
```
/generate
```
可能返回JSON字符串格式的
```
molecules
```
（包含
```
{sample, score}
```
对象），而本地端点可能返回
```
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
```
。