NVIDIA digital-biology-examples 完整教學：6 個生物 NIM × 1 個 Blueprint × 1 個 PyPI client 的端到端 cookbook

⚠️ 本文件為 NVIDIA/digital-biology-examples 的深度教學與資安審查報告。資安掃描章節（§6）含紅黃綠燈分級；商用部署前務必審視 §4 NIM 授權條款。

目錄

1. 專案定位
2. 安裝指南
3. 核心架構解析
4. Helper Scripts 與工具庫詳細用法
5. 應用場景：8 個 NIM × 1 個 Blueprint × 5 條 recipe
6. 資安掃描報告
7. FAQ
8. 進階技巧
9. 整合進其他工作流
10. 重點摘要 Checklist
11. 進一步閱讀

1. 專案定位

1.1 一句話

NVIDIA/digital-biology-examples 是 NVIDIA BioNeMo 平台官方的「生物 NIM 微服務 cookbook + Blueprint 端到端範例 + 單細胞 GPU 入門資源」整合倉，是把 BioNeMo Framework 訓練好的模型「包成 NIM 容器、暴露成 OpenAPI 服務、做成 Python client / Jupyter notebook、再串接成藥物發現工作流」的最終端使用者出口。

1.2 設計初衷與三條工作流

從 README 與 6 個子目錄歸納，本倉服務三條互不交疊的工作流：

1.3 在 NVIDIA AI 生態系的位置

flowchart TB
    A[NVIDIA Clara BioPharma 商用平台] --> B[NVIDIA BioNeMo Hub]
    B --> C[bionemo-framework
PyTorch 訓練 SDK]
    B --> D[digital-biology-examples
NIM + Blueprint cookbook]
    B --> E[NIM Catalog
build.nvidia.com/biology]

    C -.訓練好的 checkpoint 包成 NIM.-> E
    E -.NIM 容器 image.-> D
    D -.notebook 呼叫.-> E

    F[NVIDIA Parabricks
基因體 secondary 分析] -.同屬 Clara Genomics.-> A
    G[Nemotron LLM Hub] -.姐妹 Hub
LLM 領域.-> H[NVIDIA NeMo]
    I[Cosmos World Model] -.姐妹 Hub
機器人/世界模型.-> A

    style D fill:#ffcc99
    style B fill:#99ccff
    style C fill:#99ff99

核心區別：

• bionemo-framework 是「訓練 / 微調」工具（給研究員自己練 model）；
• digital-biology-examples 是「推論 / 應用」工具（給工程師呼叫已訓好的 NIM）；
• 兩者沒有直接互相 import，但概念上互補——framework 的 checkpoint 經 NVIDIA 工程團隊包裝後上架到 NGC，變成本倉 notebook 直接 docker run 起來的 NIM。

1.4 倉庫資料

• Stars：223 | Forks：60 | 建立：2023-04-18 | 最近活動：2026-05-10
• 主要語言：Jupyter Notebook / Python（部分 docker-compose / YAML）
• 頂層 License：N/A（README 標示 educational / demonstration only）
• 子目錄授權：boltz-2/ 為 MIT；molmim-* 為 NVIDIA Software License Agreement；其餘 notebook 通常繼承本倉的「無 license」狀態
• Releases：無（client 走 PyPI 發版，notebook 走 commit）
• 預設分支：main

1.5 與其他 NVIDIA AI hub 的對應（2026-06 視角）

2. 安裝指南

本倉沒有「整倉安裝」的概念；每個 NIM 子目錄與 client 套件需獨立安裝。以下分四種典型場景示範。

2.1 場景 A：只玩 Boltz-2（最快路徑）

 1# 1. 純 Python client，PyPI 直接裝
 2pip install boltz2-python-client
 3
 4# 或加 SageMaker 支援
 5pip install "boltz2-python-client[sagemaker]"
 6
 7# 2. 設環境變數（NVIDIA Hosted API）
 8export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxx"
 9
10# 3. 立即呼叫
11python -c "
12from boltz2_client import Boltz2SyncClient
13client = Boltz2SyncClient(base_url='https://health.api.nvidia.com', endpoint_type='nvidia_hosted')
14print(client.check_health())
15"

前置需求：Python 3.8+；NGC / build.nvidia.com 帳號取得 API Key。

2.2 場景 B：本機部署 GenMol NIM container

 1# 1. 取得 NGC API Key（https://ngc.nvidia.com/setup/api-key）
 2export NGC_API_KEY=<your_key>
 3
 4# 2. 登入 NGC docker registry
 5docker login --username '$oauthtoken' --password $NGC_API_KEY nvcr.io
 6
 7# 3. 準備本地快取目錄（避免每次重抽 model weights）
 8export LOCAL_NIM_CACHE=~/.cache/nim
 9mkdir -p $LOCAL_NIM_CACHE
10
11# 4. 啟動 GenMol NIM
12docker run --rm --name genmol --runtime=nvidia \
13  -e NGC_API_KEY \
14  -v $LOCAL_NIM_CACHE:/opt/nim/.cache \
15  --shm-size=2G \
16  --ulimit memlock=-1 \
17  --ulimit stack=67108864 \
18  -p 8000:8000 \
19  nvcr.io/nim/nvidia/genmol:1.0.0
20
21# 5. 驗證 NIM ready
22curl -X GET 'http://localhost:8000/v1/health/ready' -H 'accept: application/json'
23# {"status":"ready"}
24
25# 6. 跑配套 notebook
26cd digital-biology-examples/examples/nims/genmol
27python3 -m venv venv && source venv/bin/activate
28pip install -r requirements.txt
29pip install jupyterlab ipywidgets
30jupyter-lab

硬體需求（典型 NIM）：

• GPU：A100 / H100（80GB VRAM 推薦）；GenMol / MolMIM 可在 L40S 上跑
• RAM：≥ 32GB
• 磁碟：≥ 100GB（model weights + cache）
• CUDA：12.x

2.3 場景 C：跑 MolMIM Optimization API（Docker Compose 多服務）

molmim-opt-api/ 提供完整 docker-compose 範本（MolMIM NIM + 自訂 FastAPI inference server + Jupyter notebook 三 service 串接）：

 1cd examples/nims/molmim/molmim-opt-api
 2
 3# 1. 設定 NGC 認證
 4export NGC_API_KEY=<your_key>
 5docker login --username '$oauthtoken' --password $NGC_API_KEY nvcr.io
 6
 7# 2. 啟動 compose stack
 8docker compose up -d
 9
10# 3. 服務埠
11# MolMIM NIM:   localhost:8000/docs
12# Inference API: localhost:8080/docs
13# Jupyter:      localhost:8888
14
15# 4. 開 notebook 走 end-to-end
16jupyter notebook molmim-opt-api-runner.ipynb

2.4 場景 D：AWS Marketplace 雲端部署

1# 1. 已在 AWS Marketplace 訂閱 Boltz2 NIM v1.6.0 / MSA-Search NIM v2.1.0
2# 2. 透過 SageMaker 部署 endpoint（會啟動 ml.g5.12xlarge / ml.p4d.24xlarge）
3
4# 跑配套 notebook（會用 boto3 + boltz2_client[sagemaker] 操作）
5cd examples/nims/boltz-2
6jupyter notebook examples/notebooks/  # 含 SageMaker endpoint deploy 範例
7
8# 3. 用完務必 delete endpoint
9aws sagemaker delete-endpoint --endpoint-name <your_endpoint>

⚠️ 計費警告：ml.g5.12xlarge ≈ $5.7/hr；ml.p4d.24xlarge ≈ $32.8/hr。一個忘記關的 endpoint 一週可燒掉 $5000+。

2.5 安裝流程總覽

flowchart TD
    Start[拿到 NGC API Key] --> Choose{選擇場景}
    Choose -->|A: 只試 Boltz-2| PyPI[pip install boltz2-python-client]
    Choose -->|B: 本機 NIM| Docker[docker login + docker run
nvcr.io/nim/nvidia/...]
    Choose -->|C: 多服務串接| Compose[docker compose up -d]
    Choose -->|D: 雲端 prod| AWS[AWS Marketplace
SageMaker endpoint]

    PyPI --> Verify1[client.check_health]
    Docker --> Verify2[curl /v1/health/ready]
    Compose --> Verify3[3 個 service 都 ready]
    AWS --> Verify4[describe-endpoint InService]

    Verify1 & Verify2 & Verify3 & Verify4 --> Run[執行 notebook / 寫自己的 client code]

    style Docker fill:#ffcc99
    style AWS fill:#ff9999

3. 核心架構解析

3.1 倉庫整體分類圖

本倉的「資產」分四類：NIM client / Blueprint 工作流 / 單細胞資源 / 文檔。下圖呈現倉庫結構與依賴：

flowchart LR
    subgraph NIMs["examples/nims/ — 8 個獨立 NIM"]
        N1[alphafold2
1 notebook]
        N2[openfold2
2 notebook + PDB]
        N3[boltz-2
完整 Python package
v0.5.2 on PyPI]
        N4[diffdock
1 notebook + ligand/protein]
        N5[genmol
3 notebook + py 工具庫]
        N6[molmim
1 notebook + client + opt-api]
        N7[msa-search
4 notebook + JSON sample]
    end

    subgraph BP["examples/blueprints/"]
        B1[generative-virtual-screening
端到端 ipynb]
    end

    subgraph RES["examples/resources/"]
        R1[GPU-singlecell-resources
RAPIDS + scverse 教學]
    end

    B1 -.串接.-> N6
    B1 -.串接.-> N1
    B1 -.串接.-> N4
    N3 -.可用 MSA.-> N7
    N1 -.可用 MSA.-> N7
    N2 -.可用 MSA.-> N7
    R1 -.進入點.-> Brev[Brev.dev
NVIDIA Single Cell Blueprint]

    style N3 fill:#99ff99
    style B1 fill:#ffcc99

3.2 Digital Biology 工作流的「umbrella 視角」

NVIDIA 把「digital biology」分成 4 大象限。本倉覆蓋前 3 個，第 4 個只給入口（指向 Parabricks / cuCIM）：

flowchart TB
    DB[Digital Biology Workflows
NVIDIA umbrella]

    DB --> DD[1. Drug Discovery
小分子 / 蛋白藥]
    DB --> PE[2. Protein Engineering
結構設計 / 親和力]
    DB --> SCG[3. Single-Cell Genomics
scRNA / 細胞圖譜]
    DB --> GEN[4. Genomics Secondary
變異檢測 / 序列比對]

    DD --> DD1[MolMIM
guided gen]
    DD --> DD2[GenMol
fragment-based gen]
    DD --> DD3[DiffDock
blind docking]
    DD --> DD4[Boltz-2
protein-ligand + affinity]

    PE --> PE1[AlphaFold2 NIM]
    PE --> PE2[OpenFold2 NIM]
    PE --> PE3[MSA-Search NIM
MMseqs2 GPU]
    PE --> PE4[Boltz-2
covalent / DNA-protein]

    SCG --> SCG1[RAPIDS-singlecell
AnnData-first API]
    SCG --> SCG2[bionemo-scdl
scDL 訓練 loader]

    GEN -.本倉不直接覆蓋.-> GEN1[NVIDIA Parabricks
變異檢測 / STAR / BWA]

    style DD fill:#ffcc99
    style PE fill:#99ccff
    style SCG fill:#99ff99
    style GEN fill:#eeeeee

3.3 NIM 微服務的標準互動模式

無論哪個 NIM，都遵循「OpenAPI HTTP service + Python client」雙層模式。下圖以 GenMol 為例：

sequenceDiagram
    participant User as 使用者 / Notebook
    participant Client as Python Client
(genmol.py)
    participant NIM as GenMol NIM
(localhost:8000)
    participant Cache as LOCAL_NIM_CACHE
(~/.cache/nim)
    participant NGC as NGC Registry
(nvcr.io)

    Note over NGC,Cache: 一次性初始化
    User->>NGC: docker login + docker pull
    NGC->>Cache: 下載 model weights
    User->>NIM: docker run (container 起來)
    NIM->>Cache: 載入權重
    NIM-->>User: /v1/health/ready: {"status":"ready"}

    Note over User,NIM: 推論呼叫
    User->>Client: oracle.generate(fragment, n_samples=100)
    Client->>NIM: POST /generate {"smiles":"...","mask":"..."}
    NIM-->>Client: {"generated":[...100 SMILES...]}
    Client-->>User: list[SMILES] + scores

    Note over User: 後處理
    User->>User: filter + dock + visualize

3.4 Generative Virtual Screening Blueprint 的端到端 pipeline

本倉最重要的 Blueprint——示範 3 個 NIM 如何串接成完整 hit-finding 工作流：

flowchart LR
    T[標靶 protein 序列 + binding site] --> Step1
    Step1[MolMIM
guided generation
~5000 candidate SMILES] --> Step2
    Step2[AlphaFold2
結構折疊
產生標靶 3D 結構] --> Step3
    Step3[DiffDock
blind docking
每個 candidate 對標靶 docking]
    Step3 --> Score[scoring + ranking
top-K hits]

    subgraph Optional["可選：以 Boltz-2 加 affinity 評分"]
        Score -.串接.-> Aff[Boltz-2
predict pIC50 for top-K]
    end

    Aff --> Final[排名 hits 進入 wet-lab validation]
    Score -.直接走.-> Final

    style Step1 fill:#ffcc99
    style Step2 fill:#99ccff
    style Step3 fill:#99ff99
    style Aff fill:#ff9999

3.5 三類運算節點 / 服務的拓樸

實際部署時，會分成「client 機」「NIM server」「雲端 API」三類節點：

3.6 設計品味觀察

✅ 好品味：

• Client / Server 嚴格分離，本機 / 雲端用同一份 client code（只換 base_url）。
• Boltz-2 v0.5+ 引入 MultiEndpointClient 處理高吞吐 virtual screening 場景，自帶 health check、retry、load balancing。
• 大型 notebook（如 cma_custom_oracles.ipynb、MolMIMOracleControlledGeneration.ipynb）會用 oracle.py / optimizer.py 等獨立 .py 模組封裝核心邏輯，notebook 只展示呼叫，不寫實作。

⚠️ 可改善：

• 頂層 LICENSE 缺失導致整倉商用屬性不清，需子目錄逐個審。
• examples/framework/ 是空目錄（只有 .gitignore），未來 placeholder。
• 部分 notebook 仍硬寫 placeholder（如 http://your-msa-nim:8000），需使用者手動替換才能跑。

4. Helper Scripts 與工具庫詳細用法

本倉的「腳本資產」集中在三個 Python package：boltz2_client/、genmol/、molmim/。逐個展示。

4.1 boltz2-python-client（最完整的 client）

4.1.1 套件結構

 1boltz-2/boltz2_client/
 2├── __init__.py            # 公開 API（Boltz2Client / Boltz2SyncClient / MultiEndpointClient）
 3├── __main__.py            # 支援 python -m boltz2_client
 4├── client.py              # 1700+ 行，所有 async / sync / SageMaker 邏輯
 5├── cli/                   # rich + click CLI（boltz2 命令）
 6│   ├── __init__.py
 7│   ├── info.py
 8│   ├── msa.py
 9│   └── ...
10├── models.py              # pydantic schema（Request / Response）
11├── msa_search.py          # 整合 MSA-Search NIM
12├── multi_endpoint_client.py  # 多端點 load balancing
13├── a3m_to_csv_converter.py   # A3M → multimer paired CSV
14├── virtual_screening.py   # high-level screening API
15├── utils.py
16└── exceptions.py

4.1.2 三種使用方式

(a) Async API：

 1import asyncio
 2from boltz2_client import Boltz2Client
 3
 4async def main():
 5    client = Boltz2Client(base_url="http://localhost:8000")
 6    # 純蛋白折疊
 7    result = await client.predict_protein_structure(
 8        sequence="MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG"
 9    )
10    print(f"Confidence: {result.confidence_scores[0]:.3f}")
11    # 寫 PDB
12    with open("out.pdb", "w") as f:
13        f.write(result.structures[0])
14
15asyncio.run(main())

(b) Sync API（給不熟 asyncio 的使用者）：

 1from boltz2_client import Boltz2SyncClient
 2
 3client = Boltz2SyncClient(
 4    base_url="https://health.api.nvidia.com",
 5    endpoint_type="nvidia_hosted",  # 走 NVIDIA hosted endpoint
 6)
 7result = client.predict_protein_ligand_complex(
 8    protein_sequence="MKTVRQ...",
 9    ligand_smiles="CC(=O)Oc1ccccc1C(=O)O",  # aspirin
10    predict_affinity=True,
11)
12print(f"pIC50: {result.affinity_pred}")

(c) CLI：

 1# 本機 NIM
 2boltz2 --base-url http://localhost:8000 protein "MKTVRQERLK..."
 3
 4# 多端點負載平衡
 5boltz2 --multi-endpoint \
 6       --base-url "http://localhost:8000,http://localhost:8001,http://localhost:8002,http://localhost:8003" \
 7       screen target.fasta compounds.csv
 8
 9# NVIDIA hosted
10boltz2 --base-url https://health.api.nvidia.com \
11       --endpoint-type nvidia_hosted \
12       --api-key $NVIDIA_API_KEY \
13       protein "MKTVRQERLK..."

4.1.3 13 個 example scripts 一覽

 1examples/
 2├── 01_basic_protein_folding.py            # 最基本：序列 → 結構
 3├── 02_protein_structure_prediction_with_msa.py
 4├── 03_protein_ligand_complex.py           # 蛋白 + 小分子
 5├── 04_covalent_bonding.py                 # 共價結合（新功能）
 6├── 05_dna_protein_complex.py              # DNA-蛋白複合體
 7├── 06_yaml_configurations.py              # YAML 設定檔模式
 8├── 07_advanced_parameters.py              # 採樣 / temperature / num_recycle
 9├── 08_affinity_prediction_simple.py       # pIC50 預測
10├── 09_virtual_screening.py                # 高層次 VS API
11├── 10_msa_search_integration.py
12├── 11_msa_search_large_protein.py
13├── 12_msa_affinity_prediction.py
14├── 13_a3m_to_multimer_csv.py
15├── barnase_barstar_with_msa.py            # 經典 protein-protein 案例
16├── cdk4_msa_affinity_example.py           # CDK4 kinase + inhibitor
17├── comprehensive_multi_endpoint_demo.py
18├── msa_search_simple_demo.py
19└── multi_endpoint_screening.py

4.1.4 測試套件

 1tests/
 2├── test_basic.py                          # 基本 sanity
 3├── test_a3m_to_csv_converter.py
 4├── test_cli_multi_endpoint.py
 5├── test_comprehensive_stress.py           # stress test
 6├── test_examples_syntax.py                # 防止 example script 壞掉
 7├── test_integration_scenarios.py
 8├── test_live_endpoints.py                 # 真實打 NIM
 9├── test_msa_search.py
10├── test_multi_endpoint_functionality.py
11└── test_multi_endpoint_reliability.py     # MultiEndpoint v0.5.2 重點

跑全套：

1cd examples/nims/boltz-2
2pip install -e ".[dev]"
3pytest tests/ -v

4.2 genmol/（fragment-based generation 工具庫）

4.2.1 套件結構

 1genmol/
 2├── 1.basics.ipynb         # SAFE 表示法基礎
 3├── 2.linker-design.ipynb  # 兩個 fragment 中間自動找 linker
 4├── 3.hit-generation.ipynb # 完整 hit-finding 場景
 5├── genmol.py              # GenMolClient（封裝 NIM API call）
 6├── library.py             # 化合物庫管理 + filter
 7├── optimizer.py           # CMA-ES / genetic algorithm 包裝
 8├── oracle.py              # 自訂 scoring function（pIC50 / QED / SA）
 9├── utils.py               # SMILES 操作、視覺化
10├── fda_drugs.csv          # FDA approved drugs（demo 用 library）
11└── requirements.txt

4.2.2 典型用法（Linker Design）

 1from genmol import GenMolClient
 2from oracle import QEDOracle
 3
 4client = GenMolClient(base_url="http://localhost:8000")
 5
 6# Linker design：給兩個 fragment，找中間 linker
 7result = client.generate(
 8    fragments=["[*]C1=CC=CC=C1", "[*]N1CCOCC1"],   # 苯環 + 嗎啉
 9    schema="linker",
10    n_samples=200,
11    max_length=10,
12)
13
14# 用 QED oracle 過濾
15oracle = QEDOracle(threshold=0.5)
16filtered = [m for m in result.molecules if oracle.score(m) > 0.5]
17print(f"通過 QED filter: {len(filtered)}/{len(result.molecules)}")

4.2.3 5 種 generation schema

4.3 molmim-client/ 與 molmim-opt-api/（guided generation）

4.3.1 兩個子目錄的關係

• molmim-client/：純 Python client，呼叫 MolMIM NIM 的 encoder / decoder / sampling endpoints，是「底層庫」。
• molmim-opt-api/：在 client 之上多疊一層 FastAPI server（自訂 oracle 排序），是「完整服務範本」，可獨立部署。

4.3.2 molmim-opt-api 的多服務拓樸

flowchart LR
    Notebook[Jupyter notebook
localhost:8888] -->|HTTP| OptAPI[FastAPI
localhost:8080
main.py]
    OptAPI -->|HTTP| MolMIM[MolMIM NIM
localhost:8000
nvcr.io/nim/nvidia/molmim:1.0.0]
    OptAPI -->|呼叫.encode / .decode / .sample / .generate| MolMIM
    User[使用者] --> Notebook

    style MolMIM fill:#ffcc99
    style OptAPI fill:#99ccff

4.3.3 4 個 endpoint

molmim-opt-api/inference_client.py 包裝了 MolMIM NIM 的 4 個基本功能：

4.4 安裝流程的「依賴注意事項」

flowchart TD
    Box[使用者準備跑 notebook] --> Q1{有 GPU 嗎}
    Q1 -->|沒有| Cloud[只能走 NVIDIA Hosted / SageMaker / Brev.dev]
    Q1 -->|有，CUDA 12| Q2{NGC API Key}
    Q2 -->|沒有| Get[https://ngc.nvidia.com/setup/api-key]
    Q2 -->|有| Q3{要哪個 NIM}
    Q3 -->|Boltz-2 / GenMol / MolMIM| Local[本機 docker run]
    Q3 -->|AlphaFold2 / OpenFold2| Heavy[需要 80GB VRAM
建議用 Hosted API]
    Q3 -->|MSA-Search| Med[24GB VRAM 即可]
    Local --> Mount[務必 mount LOCAL_NIM_CACHE
避免重抽 weights]
    Heavy --> Mount
    Med --> Mount

    style Cloud fill:#99ccff
    style Heavy fill:#ff9999

5. 應用場景：8 個 NIM × 1 個 Blueprint × 5 條 recipe

5.1 NIM 對應表

5.2 Recipe 1：用 Boltz-2 算一個藥物-蛋白親和力

情境：想知道 aspirin 對 COX-2 的預測 pIC50。

 1from boltz2_client import Boltz2SyncClient
 2
 3client = Boltz2SyncClient(
 4    base_url="https://health.api.nvidia.com",
 5    endpoint_type="nvidia_hosted",
 6)
 7
 8cox2_sequence = "MLARALLLCAVLALSHTANP..." # 完整 COX-2 序列略
 9aspirin_smiles = "CC(=O)Oc1ccccc1C(=O)O"
10
11result = client.predict_protein_ligand_complex(
12    protein_sequence=cox2_sequence,
13    ligand_smiles=aspirin_smiles,
14    predict_affinity=True,
15    num_recycle=3,
16)
17
18print(f"Predicted pIC50: {result.affinity_pred:.2f}")
19print(f"Confidence: {result.confidence_scores[0]:.3f}")
20
21# 存 PDB
22with open("cox2_aspirin.pdb", "w") as f:
23    f.write(result.structures[0])

典型輸出：pIC50 ≈ 4.8（aspirin 對 COX-2 的實驗值約 4.3–4.7，模型表現合理）。

5.3 Recipe 2：用 MolMIM 做 guided generation（找 high QED 化合物）

 1from guided_molecule_gen.inference_client import InferenceClient
 2import numpy as np
 3
 4client = InferenceClient(nim_host="localhost:8000")
 5
 6# 1. 編碼 seed molecule（譬如已知 hit）
 7seed_smiles = ["CC1=C(C(=NO1)c1ccccc1Cl)C(=O)Nc1ccc(F)cc1"]
 8hidden = client.encode(seed_smiles)  # shape: (1, 512)
 9
10# 2. 在 latent space 加 gaussian noise 採樣
11n_samples = 1000
12noise = np.random.normal(0, 0.5, size=(n_samples, 512))
13sampled_hidden = hidden + noise
14
15# 3. 解碼
16generated = client.decode(sampled_hidden.tolist())
17
18# 4. 用 oracle（這裡用 RDKit QED）排序
19from rdkit import Chem
20from rdkit.Chem.QED import qed
21
22scored = [(s, qed(Chem.MolFromSmiles(s))) for s in generated if Chem.MolFromSmiles(s)]
23scored.sort(key=lambda x: -x[1])
24print("Top 10 by QED:")
25for s, q in scored[:10]:
26    print(f"  {q:.3f}  {s}")

5.4 Recipe 3：用 GenMol 做 linker design

情境：已有 fragment A（苯環）+ fragment B（嗎啉），找最佳 linker。

 1import requests
 2
 3# 假設 GenMol NIM 在 localhost:8000
 4payload = {
 5    "smiles": "[*]c1ccccc1.[*]N1CCOCC1",   # SAFE 雙片段格式
 6    "schema": "linker",
 7    "n_samples": 500,
 8    "max_length": 8,
 9    "temperature": 1.0,
10}
11
12resp = requests.post("http://localhost:8000/generate", json=payload)
13result = resp.json()
14print(f"Generated {len(result['molecules'])} linker candidates")
15for mol in result["molecules"][:5]:
16    print(f"  {mol['smiles']}  (logP={mol.get('logp'):.2f})")

5.5 Recipe 4：跑 Generative Virtual Screening Blueprint（端到端）

情境：拿到一個 target 序列，跑完整 hit-finding pipeline。

 1# 來自 examples/blueprints/generative-virtual-screening/generative-virtual-screening.ipynb
 2# 簡化骨架
 3
 4# Step 1: MolMIM 生成 5000 candidates
 5from molmim_client import MolMIMClient
 6mm = MolMIMClient(base_url="http://localhost:8000")
 7candidates = mm.generate_around(
 8    seed_smiles="<known_hit>",
 9    n_samples=5000,
10    diversity=0.3,
11)
12
13# Step 2: AlphaFold2 折疊標靶
14from alphafold2_client import AF2Client
15af2 = AF2Client(base_url="http://localhost:8001")
16target_pdb = af2.predict(sequence=target_seq)
17
18# Step 3: DiffDock 對每個 candidate 做 blind docking
19from diffdock_client import DiffDockClient
20dd = DiffDockClient(base_url="http://localhost:8002")
21results = []
22for smi in candidates:
23    poses = dd.dock(protein_pdb=target_pdb, ligand_smiles=smi, num_poses=10)
24    results.append((smi, poses[0].confidence))
25
26# Step 4: 排序取 top-K
27results.sort(key=lambda x: -x[1])
28top_k = results[:50]
29print(f"Top 50 hits 進入下一輪 Boltz-2 affinity scoring")

5.6 Recipe 5：MSA-Search → Boltz-2 多步整合

 1from boltz2_client import Boltz2SyncClient
 2from boltz2_client.msa_search import MSASearchClient
 3
 4# 1. 拿 MSA
 5msa_client = MSASearchClient(endpoint="http://localhost:8001")
 6a3m = msa_client.search_a3m(
 7    sequence="MKTVRQ...",
 8    databases=["uniref30"],
 9)
10
11# 2. 餵 Boltz-2 帶 MSA 做更準的折疊
12b2 = Boltz2SyncClient(base_url="http://localhost:8000")
13result = b2.predict_protein_structure(
14    sequence="MKTVRQ...",
15    msa=a3m,                  # 帶 MSA 通常 confidence 提升 0.05–0.15
16    num_recycle=3,
17)
18print(f"With MSA confidence: {result.confidence_scores[0]:.3f}")

5.7 應用場景對照表

6. 資安掃描報告

6.1 自動化掃描結果（grep + 手動 review）

執行：

1grep -rn -E "eval\(|exec\(|os\.system|subprocess|shell=True|http://|requests\.|pickle\.|secret|token|password|api_key|API_KEY|NVIDIA_API_KEY|getenv" \
2  examples/ --include="*.py" --include="*.md" 2>/dev/null

掃描結果分類見下表。

6.2 紅黃綠燈分級

🔴 高風險（無）

未發現任何「會立即造成資安事件」的問題：

• 沒有硬編碼 secrets / API keys
• 沒有 eval() / exec() 動態執行使用者輸入
• 沒有 pickle.load() 不可信來源
• 沒有 shell injection（subprocess shell=True + 使用者輸入串接）

🟡 中風險

🟢 低風險 / 良好實踐

6.3 商用部署檢查清單

部署到 production / 對外服務前必須：

• 確認子目錄 LICENSE 允許商用（boltz-2 OK，其他需逐查）
• NIM container 走 HTTPS（透過 nginx / Caddy reverse proxy）
• API Key 走 secrets manager（AWS Secrets Manager / HashiCorp Vault）
• 為 requests.post() 加 timeout（PR 上游 / 自行 fork patch）
• AWS Marketplace endpoint 必須 auto-shutdown CloudWatch alarm（避免 $5000/週 燒帳）
• 容器 image 定期 scan（trivy / grype）追上游 CVE
• Log redaction：避免 SMILES / 標靶序列洩漏到一般 application log

6.4 一句話結論

🟢 整體資安姿勢良好（沒發現高風險）；🟡 主要風險是「部署層的設定」（HTTPS、timeout、secret 管理）而非 client 程式碼本身。商用前的重點是「逐子目錄審 LICENSE + 雲端 endpoint 計費守則」。

7. FAQ

Q1. 我沒有 GPU，能跑這些 notebook 嗎？ 能。所有 NIM 都有 NVIDIA Hosted endpoint（https://health.api.nvidia.com），用 API Key + client 就能呼叫。Notebook 在 CPU 機器 / Colab 上即可開。

Q2. NIM container 是付費的嗎？ NIM container image 從 nvcr.io 抓需 NGC 帳號（免費）。但商用部署需 NVIDIA AI Enterprise License；NVIDIA Hosted endpoint 走 NV credits（按 token 計）。research / 試水溫多半在免費額度內。

Q3. Boltz-2 vs AlphaFold2 vs OpenFold2 該用哪個？

• AlphaFold2：經典、論文圈接受度最高、純蛋白
• OpenFold2：AF2 的 PyTorch 重新實作，速度 / 顯存更友善
• Boltz-2：最新最強，支援蛋白-配體 / 共價 / DNA-protein / affinity prediction，是 2025-2026 BioNeMo 主推

Q4. GenMol vs MolMIM 該用哪個？

• GenMol：fragment-based、SAFE 表示法、適合 linker / scaffold / motif extension
• MolMIM：latent space guided generation、適合「我已知 hit、找相似但更好」場景

Q5. 為什麼 examples/framework/ 是空的？ 是 placeholder，未來可能加入 bionemo-framework 整合範例。目前 framework 範例請看 NVIDIA-BioNeMo/bionemo-framework。

Q6. AWS Marketplace 部署最低成本？ boltz2 NIM v1.6 在 ml.g5.12xlarge（4× A10G，96GB VRAM）上跑得起；按小時計費 ~$5.7/hr。比本機 H100（自買 $30k）划算許多，但必須自動關。

Q7. 商用研究時，模型輸出的 IP 屬於誰？ NVIDIA NIM 的輸出（結構、分子、affinity）通常屬使用者；但 NIM container 與底層權重不屬於使用者。涉及專利、發表、商業化前請審 NVIDIA AI Enterprise EULA。

Q8. 我能拿 GenMol 生成的分子直接申請專利嗎？ 理論上可以（生成結果屬使用者）；但需自行做 prior art 檢索、需確認 SMILES 真實可合成（synthetic accessibility）。本倉提供 oracle.py 含 SA 評估示範。

Q9. NIM 與 NIM Blueprints 差別？

• NIM：單一 model 微服務（atomic unit）
• NIM Blueprint：多個 NIM 串接的「完整參考解決方案」（如 generative virtual screening）

Q10. 與 BioNeMo Framework 倉的關係？ 本倉「用」現成 NIM；framework 倉「訓」自己模型。兩者沒有 import 依賴。

Q11. 我能 fork 並魔改 boltz2-python-client 嗎？ boltz-2 子目錄是 MIT，可自由 fork / 商用 / 修改 / 重新發佈。其他子目錄需個別審 LICENSE。

Q12. 為什麼 boltz-2 v0.5+ 加了 MultiEndpoint？ 針對高吞吐 virtual screening 場景（一天跑 10 萬個 docking）；單一 NIM 太慢，要橫向 scale。v0.5.2 修了 reliability bug：之前 endpoint 一次 transient failure 會永久標記不健康，現在每次 success 重設。

Q13. 跟 Parabricks 怎麼搭？ Parabricks 處理基因體 secondary analysis（fastq → bam → vcf），本倉處理蛋白 / 分子 / 結構。完整 omics pipeline：Parabricks 做 variant calling → 找 disease variant → 找到對應 protein → 用 BioNeMo NIM 做結構 / 配體生成 / docking。

8. 進階技巧

8.1 多端點 high-throughput virtual screening

 1from boltz2_client import MultiEndpointClient
 2
 3client = MultiEndpointClient(
 4    endpoints=[
 5        "http://gpu-01:8000",
 6        "http://gpu-02:8000",
 7        "http://gpu-03:8000",
 8        "http://gpu-04:8000",
 9    ],
10    strategy="least_loaded",   # round_robin / random / least_loaded
11)
12
13# 跑 10k 化合物 screening
14import csv
15results = []
16with open("library.csv") as f:
17    for row in csv.DictReader(f):
18        r = client.predict_protein_ligand_complex(
19            protein_sequence=target_seq,
20            ligand_smiles=row["smiles"],
21            predict_affinity=True,
22        )
23        results.append((row["id"], r.affinity_pred))
24
25# 自動分散到 4 個 endpoint，自動處理 endpoint failure

8.2 YAML config 模式（避免 notebook 寫死參數）

 1# config.yaml
 2sequence: MKTVRQ...
 3ligand_smiles: CC(=O)Oc1ccccc1C(=O)O
 4num_recycle: 5
 5num_samples: 25
 6diffusion_samples: 1
 7predict_affinity: true
 8templates:
 9  - pdb_id: 1HRC
10    chain: A

1result = client.predict_from_yaml_file("config.yaml")

8.3 A3M → multimer paired CSV

對 multimer prediction（hetero-dimer / -trimer），Boltz-2 需要 paired MSA。用內建 converter：

1python -m boltz2_client.a3m_to_csv_converter \
2    --input chain_A.a3m chain_B.a3m \
3    --output paired.csv \
4    --pair-mode taxonomy   # 用 species 配對

8.4 templates-guided prediction

1result = client.predict_protein_structure(
2    sequence="MKTVRQ...",
3    templates=[
4        {"pdb_id": "1HRC", "chain": "A"},
5        {"pdb_id": "2WTT", "chain": "B"},
6    ],
7    num_recycle=5,
8)
9# 用 template 通常能讓 confidence 大幅提升（尤其 low-MSA 情況）

8.5 用 PAE matrix 評估 domain interaction

 1import matplotlib.pyplot as plt
 2import numpy as np
 3
 4result = client.predict_protein_structure(sequence=multidomain_seq)
 5pae = np.array(result.pae_matrix)  # (L, L)
 6
 7plt.imshow(pae, cmap="viridis_r", vmin=0, vmax=30)
 8plt.colorbar(label="PAE (Å)")
 9plt.title("Predicted Aligned Error")
10plt.savefig("pae.png")
11# 低 PAE 區塊 = 模型對 domain 間相對位置很有把握

8.6 用 GenMol + oracle 做 iterative optimization

 1from genmol import GenMolClient
 2from oracle import MultiObjectiveOracle
 3
 4client = GenMolClient()
 5oracle = MultiObjectiveOracle({
 6    "qed": (0.5, 1.0, 1.0),       # threshold, target, weight
 7    "sa": (0.0, 3.0, 0.8),
 8    "logp": (1.0, 4.0, 0.6),
 9})
10
11seeds = ["CC1=C(C(=NO1)c1ccccc1Cl)C(=O)Nc1ccc(F)cc1"]
12for iter_n in range(10):
13    candidates = client.generate(fragments=seeds, schema="motif_extension", n_samples=200)
14    scored = [(s, oracle.score(s)) for s in candidates]
15    scored.sort(key=lambda x: -x[1])
16    seeds = [s for s, _ in scored[:20]]   # 取 top-20 當下輪 seed
17    print(f"Iter {iter_n}: best score = {scored[0][1]:.3f}")

8.7 NVIDIA Hosted endpoint 的 streaming / async

 1import asyncio
 2from boltz2_client import Boltz2Client
 3
 4async def batch_predict(sequences):
 5    client = Boltz2Client(base_url="https://health.api.nvidia.com", endpoint_type="nvidia_hosted")
 6    tasks = [client.predict_protein_structure(sequence=s) for s in sequences]
 7    results = await asyncio.gather(*tasks, return_exceptions=True)
 8    return results
 9
10# 100 個蛋白同時送出
11results = asyncio.run(batch_predict(my_100_seqs))

8.8 Local NIM cache 共用（多人共享 weights）

1# /opt/nim-cache 設為 NFS / shared volume
2docker run --rm --runtime=nvidia \
3  -e NGC_API_KEY \
4  -v /opt/nim-cache:/opt/nim/.cache \
5  -p 8000:8000 \
6  nvcr.io/nim/nvidia/boltz2:1.6.0
7# 同實驗室多台機器共用 weights，省 download 時間 & 磁碟

9. 整合進其他工作流

9.1 與 AI-knowledge_template 工作流的整合

本倉的「8 個 NIM + 1 Blueprint」可以這樣餵進 AI-knowledge_template 的 19 個 Layer：

9.2 與 bionemo-framework / BioNeMo Hub 的協作關係

flowchart LR
    subgraph Train["訓練 / 微調（research lab）"]
        FW[bionemo-framework
PyTorch SDK]
        FW --> CKPT[自家 checkpoint]
    end

    subgraph Deploy["NVIDIA 工程團隊"]
        CKPT -.官方收編.-> Pack[包成 NIM container]
        Pack --> NGC2[nvcr.io/nim/nvidia/...]
    end

    subgraph Use["應用 / 評估（drug discovery team）"]
        EX[digital-biology-examples
本倉]
        EX -.docker pull.-> NGC2
        EX --> BP[Blueprint pipeline]
        BP --> Hits[hits 進入 wet lab]
    end

    Hub[BioNeMo Hub
index repo] -.指向.-> FW
    Hub -.指向.-> EX
    Hub -.指向.-> NGC2

    style FW fill:#99ccff
    style EX fill:#ffcc99
    style Pack fill:#99ff99

9.3 整合 Parabricks（完整 omics → drug discovery）

flowchart LR
    Fastq[患者 fastq] --> PA[Parabricks
GPU secondary analysis]
    PA --> VCF[somatic variants VCF]
    VCF --> Pick[篩 disease-causing variants]
    Pick --> Target[找出對應 protein target]
    Target --> AF[AlphaFold2 / OpenFold2 NIM
預測突變後結構]
    AF --> Dock[DiffDock / Boltz-2
已知 inhibitor docking]
    Dock --> Decide{變異會抗藥嗎}
    Decide -->|是| GenMol[GenMol / MolMIM
生成新 inhibitor]
    Decide -->|否| Reuse[沿用既有 inhibitor]
    GenMol --> Blueprint[Generative Virtual Screening Blueprint]
    Blueprint --> Hits[wet-lab 驗證]

    style PA fill:#99ff99
    style Blueprint fill:#ffcc99

9.4 與 LangChain / LlamaIndex 整合做「對話式 drug discovery agent」

 1from langchain.tools import Tool
 2from boltz2_client import Boltz2SyncClient
 3
 4b2 = Boltz2SyncClient(base_url="http://localhost:8000")
 5
 6def predict_affinity(input_str: str) -> str:
 7    """Input: 'protein_seq|smiles'  Output: pIC50"""
 8    seq, smi = input_str.split("|")
 9    r = b2.predict_protein_ligand_complex(seq, smi, predict_affinity=True)
10    return f"pIC50 = {r.affinity_pred:.2f}"
11
12tool = Tool(name="boltz2_affinity", func=predict_affinity, description="...")
13# 餵給 ReAct agent，讓 LLM 自動呼叫

9.5 對應姐妹 hub 的兩種「developer asset hub」模式

兩者共享同一個「hub-framework-application」三層架構，是 NVIDIA AI 生態系的標準配置。

10. 重點摘要 Checklist

• 本倉是 NVIDIA BioNeMo 平台的「NIM + Blueprint 終端使用者出口」
• 8 個生物 NIM：AlphaFold2 / OpenFold2 / Boltz-2 / DiffDock / GenMol / MolMIM / MSA-Search
• 1 個 Blueprint：Generative Virtual Screening（MolMIM → AlphaFold2 → DiffDock 三 NIM 串接）
• 最完整子套件：boltz2-python-client v0.5.2 已上 PyPI，MIT 授權，含 async / sync / multi-endpoint / SageMaker / VS
• 本倉不訓練模型——訓練見 bionemo-framework
• 本倉不直接做基因體 secondary analysis——見 NVIDIA Parabricks
• 頂層 LICENSE 缺失；boltz-2 子目錄為 MIT；其他子目錄各自有 NVIDIA Software License；商用前必須逐目錄審
• 資安整體 🟢，無高風險；🟡 主要在「部署層」（HTTPS、timeout、secret 管理）
• AWS Marketplace 部署是雙面刃：省掉自買 H100、但忘記關 endpoint 一週燒 $5000+
• 整合姐妹 hub：Nemotron（LLM）/ Cosmos（世界模型）/ Parabricks（基因體）/ MONAI（醫療影像）

一句話總結

「拿著 NGC API Key 走進 BioNeMo 世界的第一個門——進門看是 8 個 NIM、出門看是 1 條完整 hit-finding pipeline。」

11. 進一步閱讀

官方資源

• BioNeMo 平台主頁：https://www.nvidia.com/en-us/clara/biopharma/
• BioNeMo NIM 索引：https://build.nvidia.com/explore/biology
• NIM Blueprints：https://build.nvidia.com/nim/blueprints
• NGC Setup：https://ngc.nvidia.com/setup
• BioNeMo 開發者論壇：https://forums.developer.nvidia.com/c/healthcare/bionemo/643

程式碼倉 / 套件

• 本倉：https://github.com/NVIDIA/digital-biology-examples
• Boltz-2 PyPI：https://pypi.org/project/boltz2-python-client/
• BioNeMo Framework：https://github.com/NVIDIA-BioNeMo/bionemo-framework
• BioNeMo Hub（兄弟 hub repo）：https://github.com/NVIDIA/BioNeMo
• 單細胞 Blueprint：https://github.com/NVIDIA-AI-Blueprints/single-cell-analysis-blueprint

關鍵論文

• OpenFold2：Ahdritz et al., Nat. Methods 2024, 21, 1514–1524
• MMseqs2 GPU（MSA-Search 底層）：Kallenborn et al., bioRxiv 2024.11.13.623350
• SAFE 表示法（GenMol）：arXiv:2310.10773

配套文件（本倉相關）

• gh-save 版：inbox/2026-06-02-github-NVIDIA-digital-biology-examples.md
• 姐妹 hub：inbox/2026-06-02-github-NVIDIA-BioNeMo.md、inbox/2026-06-02-github-NVIDIA-NeMo-Nemotron.md
• BioNeMo Framework：inbox/2026-06-02-github-NVIDIA-BioNeMo-bionemo-framework.md（並行處理中）
• Nemotron 完整教學（可參照 hub 教學寫法）：inbox/2026-06-02-tutorial-Nemotron.md
• 其他 NVIDIA AI hub 索引：inbox/2026-06-02-github-nvidia-cosmos.md、inbox/2026-06-02-github-NVIDIA-Isaac-GR00T.md

NVIDIA AI 知識系列其它入口

• NVlabs：研究發表為主（如 cuOpt、Stylegan-T）
• NVIDIA-AI-Blueprints：reference architectures
• NVIDIA-AI-IOT：邊緣 / Jetson 場景
• NVIDIA-Merlin：推薦系統

本文件由 AI-knowledge_template gh-tutorial-qd workflow 自動生成（2026-06-02）。對應 quarkdown 編譯產物：projects/digital-biology-examples/quarkdown-out/02-tutorial/index.html。