msa-search-nim

MSA-Search NIM

使用 GPU 加速的 MMSeqs2 生成蛋白质 MSA。请使用本指南了解首次托管或本地使用；仅在需要时加载补充文件：

• references/api.md：准确的端点、架构、Docker 标志和响应字段。
• references/science.md：MSA 用途、配对／模板、限制和交接。
• references/parameters.md：数据库、配对、深度和模板调优。
• references/validation.md：比对、模板和产物检查。
• references/examples.md：精简的托管／本地请求模式。

选择模式和端点

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

NVIDIA 托管 API 还是本地 Docker NIM？

• 托管标准 MSA：https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict
• 托管配对 MSA：https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict
• 本地标准 MSA：http://localhost:8000/biology/colabfold/msa-search/predict
• 本地配对 MSA：http://localhost:8000/biology/colabfold/msa-search/paired/predict
• 本地模板：http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict

本地推理路径不包含 /v1/。托管请求使用 Authorization: Bearer $NGC_API_KEY。受支持的本地 Docker 启动方式使用 NGC_API_KEY（或通过预检使用 NVIDIA_API_KEY）进行注册表登录、授权检查和首次模型下载；使用 -e NGC_API_KEY 将其传入容器。本地推理请求在就绪后无需身份验证标头。热缓存下免密钥启动的方式因镜像／版本而异，不应想当然地认为一定可用。 验证时，托管模板路径返回了 HTTP 404，因此除非托管文档／服务有所变更，否则请使用本地 Docker 进行模板搜索。

本地 Docker

本地部署默认方式 = 并行下载 + NIM_MODEL_NAME。 第一种方案适用于实际工作流。它使用支持范围并行的下载器（aria2c）下载数据库，然后启动 NIM 并使用这些文件——UniRef30 约需 14 分钟，而 NIM 内置下载器需 80 多分钟（实测，H100）。除非只想进行 databases:pdb70 烟雾测试，或确实希望由 NIM 管理自己的 blob 缓存，否则不要使用简单的 docker run（“备用方案”小节）。

本地设置需要 GPU。请根据所选配置确定 NVMe 卷大小（UniRef30 约 490 GB；完整数据集约 1.4 TB）。提供设置说明时，请包括环境预检、docker login、并行下载、NIM_MODEL_NAME 启动、就绪检查，以及随后无需身份验证的本地推理。不要臆造缓存默认值，也不要省略 NVIDIA_API_KEY 回退方案。

# --- env preflight (do not drop the NVIDIA_API_KEY fallback) ---
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
  export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${DB_DIR:=/data/fast-db}"          # where the parallel download lands

echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin

# --- 1) pick the DB version(s) you need (paired/complex work = uniref30 only) ---
DB_VERSION=uniref30_2302-m18v1
command -v aria2c >/dev/null || { echo "aria2c required; install it (e.g. apt-get install -y aria2) and re-run"; exit 1; }
mkdir -p "$DB_DIR"

# --- 2) parallel download from NGC (see "Parallel Download" section for the all-DB loop) ---
curl -fsS -H "Authorization: Bearer $NGC_API_KEY" \
  "https://api.ngc.nvidia.com/v2/org/nim/team/colabfold/models/msa-search/${DB_VERSION}/files" \
  -o /tmp/files.json
DB_DIR="$DB_DIR" python3 - <<'PY'
import json, os
d = json.load(open("/tmp/files.json")); dbdir = os.environ["DB_DIR"]; lines = []
for url, path in zip(d["urls"], d["filepath"]):
    lines += [url.strip(), f"  dir={dbdir}", f"  out={path}"]
open("/tmp/aria.in", "w").write("\n".join(lines) + "\n")
PY
aria2c -i /tmp/aria.in --max-concurrent-downloads=4 --max-connection-per-server=16 \
  --split=16 --min-split-size=1M --continue=true --file-allocation=none

# --- 3) launch the NIM against the downloaded files (skips the slow built-in download) ---
docker run -d --name msa-search --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_NAME=/databases \
  -v "${DB_DIR}:/databases" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

就绪检查：

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

如果 $DB_DIR 中已存在数据库，请跳过步骤 1–2——仅启动约需 20 秒即可完成热启动。多数据库（databases:all）循环及完整说明请参阅“任意数据库集的并行下载”。

备用方案：让 NIM 自行下载数据库（较慢）

仅在进行快速的 databases:pdb70 烟雾测试，或明确希望由 NIM 管理自己的 blob 缓存时使用。此方案使用内置下载器，对于大型配置速度很慢（测试中，UniRef30 下载超过 80 分钟仍未完成）。使用 NIM_MODEL_PROFILE 固定为最小配置（参见“更快启动”），避免下载完整的 1.4 TB。

: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
mkdir -p "${LOCAL_NIM_CACHE}"; chmod 755 "${LOCAL_NIM_CACHE}"
docker run --rm --name msa-search \
  --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_PROFILE=<hash-from-list-model-profiles> \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

加快启动：任务专用数据库配置

完整数据库下载量约为 1.4 TB，首次启动可能需要一个多小时。如果你只需要部分数据库，请选择任务专用配置，让 NIM 只下载这些数据库。这是大幅缩短本地启动时间的最有效方法。

列出镜像实际包含的配置（不同版本的哈希会变化，切勿硬编码）：

docker run --rm --entrypoint list-model-profiles nvcr.io/nim/colabfold/msa-search:2

然后通过 NIM_MODEL_PROFILE 传入所选哈希：

docker run --rm --name msa-search \
  --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_PROFILE=<hash-from-list-model-profiles> \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

此镜像中可用的配置（请使用 list-model-profiles 确认哈希）：

配置标签	数据库	适用场景	存储空间
databases:pdb70	PDB70	快速测试 / 冒烟测试	~100 MB
databases:uniref30	UniRef30	复合物的配对 MSA 搜索——UniRef30 是唯一用于基于物种配对的数据库	~500 GB
databases:uniref30,pdb70,pdb	UniRef30 + PDB70 + PDB 结构	结构模板搜索	~700 GB
databases:all（默认）	UniRef30 + ColabFold envdb + PDB70 + PDB100 + PDB 结构	最高灵敏度，包含所有数据库	~1.2 TB

就绪后，验证已加载的配置：

curl -s localhost:8000/v1/metadata | jq

注意：

• 请求级别的 databases 参数仅用于从已下载的数据库中选择；它不会改变启动时下载的内容。启动占用空间仅由 NIM_MODEL_PROFILE 决定。
• 配对搜索只需要 UniRef30。colabfold_envdb_202108 没有分类信息，无法用于配对，因此对于复合物 / 配对工作流，databases:uniref30 是正确且占用空间最小的配置——它会跳过 envdb，也就是完整数据库集合中占用空间最大的部分。
• 若要获得最高的单体灵敏度（合并 UniRef30 + envdb），仍需使用 databases:all；没有包含 envdb 且比完整集合更小的配置。

自定义数据库或单个数据库

若要使用单个手动下载的数据库（或你自己的 MMSeqs2 数据库），请从 NGC 下载，并使用 NIM_MODEL_NAME 指定挂载路径，而不是使用配置：

ngc registry model download-version nim/colabfold/msa-search:uniref30_2302-m18v1
# then mount the directory and set -e NIM_MODEL_NAME=/databases

NIM_MODEL_NAME 会完全替代配置中的数据库——NIM 只会使用该目录下的内容（通过扫描 **/*.idx 进行发现）。将多个数据库挂载到同一个父目录下即可组合使用。通过 NGC 下载的数据库已针对 GPU Server 建立索引；自定义数据库必须先使用 mmseqs createindex 建立索引。可单独下载的 NGC 模型版本：uniref30_2302-m18v1、colabfold_envdb_202108-m18v1、pdb70_220313-m18v1、pdb100_230517-m18v1、pdb_20251028_zip-m18v1。

推荐：针对任何数据库集合进行并行下载（快速部署）

这是下载数据库的推荐方式，适用于任何配置文件， 包括完整的 databases:all 集合。 针对特定任务的配置文件缩减了你 下载的内容；这个并行下载器缩短了下载所需的时间。无论你 需要一个数据库还是全部数据库，都可以使用。对于 databases:uniref30 配置文件，效果最明显；该配置文件约为 490 GB， 其中主要是两个超大文件（约 241 GB 的 GPU 索引和约 134 GB 的序列数据库）。

NIM 内置下载器会在文件之间并行下载（max_parallel_files=10），但每个文件大致只通过一个连接下载。NGC CDN 会将单个连接限速至约 20–25 MB/s，因此，下载器获取两个超大文件之一时，大多数并行 槽位都会空闲，吞吐量会降至单连接速率。在 H100 节点上的实测中， 内置下载方式超过 80 分钟仍未达到 /health/ready。

分段并行下载器会将每个文件拆分为多个字节范围段（NGC CDN 声明支持 accept-ranges: bytes），因此单个 241 GB 文件可同时通过 16 个连接下载——速率约为单连接的 15 倍。在同一节点上，aria2c 用约 13.5 分钟下载了完整的约 490 GB 数据。

工作流（使用 aria2 下载一次，然后通过 NIM_MODEL_NAME 指向这些文件并启动 NIM）：

# 1) Get presigned file URLs for the individual database model version from NGC.
#    (Requires NGC_API_KEY. The response arrays `urls` and `filepath` are positionally paired.)
curl -s -H "Authorization: Bearer $NGC_API_KEY" \
  'https://api.ngc.nvidia.com/v2/org/nim/team/colabfold/models/msa-search/uniref30_2302-m18v1/files' \
  -o files.json

# 2) Build an aria2 input file (URL + target filename per entry) and download in parallel.
python3 - <<'PY'
import json
d = json.load(open("files.json"))
lines = []
for url, path in zip(d["urls"], d["filepath"]):
    lines += [url.strip(), "  dir=/data/fast-db", f"  out={path}"]
open("aria.in", "w").write("\n".join(lines) + "\n")
PY
aria2c -i aria.in \
  --max-concurrent-downloads=4 --max-connection-per-server=16 --split=16 \
  --min-split-size=1M --continue=true --file-allocation=none

# 3) Start the NIM against the downloaded directory. NIM_MODEL_NAME makes the NIM discover
#    databases by scanning for **/*.idx, bypassing the profile/blob cache entirely.
docker run -d --name msa-search --runtime=nvidia --gpus all \
  -e NGC_API_KEY \
  -e NIM_MODEL_NAME=/databases \
  -v /data/fast-db:/databases \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:2

对于所有数据库（相当于 databases:all），对每个数据库版本分别重复步骤 1，并将它们下载到同一父目录下的并列目录中，然后将 NIM_MODEL_NAME 指向该父目录——NIM 会通过扫描 **/*.idx 来发现每个数据库：

# fetch each DB's file list into /data/all-db/<db>/ ... then one aria2c per list, e.g.:
for V in uniref30_2302-m18v1 colabfold_envdb_202108-m18v1 pdb70_220313-m18v1 \
         pdb100_230517-m18v1 pdb_20251028_zip-m18v1; do
  curl -s -H "Authorization: Bearer $NGC_API_KEY" \
    "https://api.ngc.nvidia.com/v2/org/nim/team/colabfold/models/msa-search/$V/files" \
    -o "files_$V.json"
  # build an aria2 input from files_$V.json (dir=/data/all-db) and run aria2c on it
done
# then launch once against the parent:
#   docker run -d ... -e NIM_MODEL_NAME=/databases -v /data/all-db:/databases ...

所有数据库的 CDN 单连接限速都相同，因此并行下载能按比例加速完整集合——下载的数据越多，节省的绝对时间就越多。

注意：

• 预签名 URL 会过期（通常在一天内）——获取 files.json 后，请尽快生成 aria2 输入文件并开始下载。
• 保持下载目录的内部布局不变（例如 uniref30_2302/…）；filepath 值中已包含目录结构。NIM 需要 .idx 文件及其配套文件，以及小型 .UNIREF30_READY / *.tar.gz.unpacked 标记文件。
• 瓶颈在于 CDN 的单连接限速，而非本地磁盘或 CPU——快速 NVMe 卷的写入速度远高于网络传输速度。提高 --split / --max-connection-per-server 只能在节点的总出口带宽上限内发挥作用。
• 最重要的是：下载一次配置文件，然后持久化缓存卷（或此 fast-db 目录），并将其挂载到后续节点上，即可在约 20 秒内完成热启动，无需重新下载。

标准 MSA 请求

数据库名称和响应键必须使用大小写完全匹配的形式。

对于托管的标准搜索，请从此技能目录运行捆绑的客户端。 它会提交真实请求、验证两个数据库的结果，并保存原始 JSON 和 A3M 文件。每次运行都选择一个新的输出目录：

python scripts/hosted_search.py \
  --sequence SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR \
  --output-dir msa-output

客户端会从环境中读取 NGC_API_KEY 或 NVIDIA_API_KEY。它最多发送两次请求，每次的连接超时为 10 秒， 读取超时为 300 秒，两次尝试之间间隔五秒。如果退出码非零，请报告 服务故障并停止。不要反复重启、将超时时间延长至任务预算之外，或用合成比对结果替代缺失的响应。

底层请求格式如下，也可用于运行中的本地 NIM：

import os
import requests

HOSTED = True
url = (
    "https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict"
    if HOSTED else "http://localhost:8000/biology/colabfold/msa-search/predict"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
    headers["Authorization"] = f"Bearer {os.getenv('NGC_API_KEY')}"

payload = {
    "sequence": "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR",
    "databases": ["Uniref30_2302", "colabfold_envdb_202108"],
    "e_value": 0.0001,
    "output_alignment_formats": ["a3m"],
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()

配对 MSA 请求

对于蛋白质复合物，请使用配对搜索；载荷字段为复数形式 sequences，输出为 alignments_by_chain。

url = (
    "https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict"
    if HOSTED else "http://localhost:8000/biology/colabfold/msa-search/paired/predict"
)
payload = {
    "sequences": [chain_a_sequence, chain_b_sequence],
    "e_value": 0.0001,
    "output_alignment_formats": ["a3m"],
}

本地模板搜索

使用本地 Docker 搜索结构模板。除非 NIM_GLOBAL_MAX_MSA_DEPTH 已更改，否则将 max_msa_sequences=500。

url = "http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict"
headers = {"Content-Type": "application/json"}
payload = {
    "sequence": "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVA",
    "structural_template_databases": ["pdb70_220313"],
    "max_structures": 20,
    "max_msa_sequences": 500,
}

保存输出

# Standard MSA: result["alignments"][database][format]["alignment"]
for db_name, formats in result.get("alignments", {}).items():
    for fmt_name, data in formats.items():
        with open(f"msa_{db_name}.{fmt_name}", "w", encoding="utf-8") as handle:
            handle.write(data["alignment"])

# Paired MSA: one alignment set per chain
for chain_id, chain_data in result.get("alignments_by_chain", {}).items():
    for db_name, formats in chain_data.items():
        for fmt_name, data in formats.items():
            with open(f"msa_chain_{chain_id}_{db_name}.{fmt_name}", "w", encoding="utf-8") as handle:
                handle.write(data["alignment"])

# Template search: save mmCIF structures and M8 hit tables
for name, cif in result.get("structures", {}).items():
    open(f"template_{name}.cif", "w", encoding="utf-8").write(cif)
for name, hit_table in result.get("search_hits", {}).items():
    open(f"template_hits_{name}.m8", "w", encoding="utf-8").write(hit_table)

A3M 输出可用于 OpenFold3、AlphaFold2 或 RoseTTAFold。有关比对深度、 模板和序列合理性检查，请阅读 references/validation.md。

限制与故障排查

• 序列长度：1-4096 个氨基酸；从 v2.3.0 起支持 X。
• max_msa_sequences：1-500；本地 GPU 服务的默认值必须与 NIM_GLOBAL_MAX_MSA_DEPTH 一致。
• 配对 MSA 至少需要两个序列。
• 本地 URL 返回 404 通常意味着意外添加了 /v1/ 前缀。
• 首次在本地运行时，数据库填充到 LOCAL_NIM_CACHE 可能需要数小时。
• 托管服务出现 HTTP 502/503/504 或反复读取超时，表明托管请求未能完成。有限次重试后，请检查服务是否可用；延长客户端超时时间无法解决服务器生成的 HTTP 504。
• 不要为 health.api.nvidia.com 臆造轮询 URL。已发布的标准 MSA 示例使用同步 POST；待处理的响应必须有文档说明的特定服务完成机制，才能作为结果。