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 で、初回起動時には 1 時間以上かかることがあります。一部のデータベースだけが必要な場合は、タスク固有のプロファイルを選択すると、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 DB）を使用するには、NGC からダウンロードし、プロファイルではなく NIM_MODEL_NAME を使ってマウント先を NIM に指定します。

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 を検索して検出します）。複数のデータベースを組み合わせるには、1 つの親ディレクトリ内にマウントしてください。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 セットも対象です。 タスク固有のプロファイルはダウンロードする内容を絞り込み、この並列ダウンローダーはダウンロードにかかる時間を短縮します。必要なデータベースが1つでもすべてでも、この方法を使用してください。特に効果が大きいのは databases:uniref30 プロファイルです。約490 GBあり、その大部分を2つの非常に大きなファイル（約241 GBのGPUインデックスと約134 GBのシーケンスDB）が占めています。

NIM に組み込まれているダウンローダーは、ファイル間で並列化します（max_parallel_files=10）が、各ファイルはおよそ1つの接続でダウンロードします。NGC CDN は1つの接続を約20～25 MB/sに制限するため、2つの巨大ファイルのどちらかをダウンロードしている間、並列スロットの大部分がアイドル状態になり、スループットはその単一接続の速度まで低下します。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 と同等）の場合は、各DBバージョンについて手順1を繰り返し、1つの親ディレクトリの下にある兄弟ディレクトリにそれぞれダウンロードします。その後、NIM_MODEL_NAME にその親ディレクトリを指定します。NIM は **/*.idx をスキャンしてすべてのDBを検出します。

# 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は通常1日以内に期限切れになります。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 を読み取ります。リクエストは最大2回までで、各リクエストの接続タイムアウトは10秒、読み取りタイムアウトは300秒、試行間隔は5秒です。終了コードが0以外の場合は、サービス障害を報告して停止してください。繰り返し再起動したり、タスクの時間予算を超えてタイムアウトを延長したり、応答がない場合に合成アラインメントで代替したりしないでください。

実行中のローカル 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 には、少なくとも2つの配列が必要です。
• ローカル URL で404が発生する場合は、誤って/v1/プレフィックスを付けていることがよくあります。
• ローカルでの初回実行は、データベースがLOCAL_NIM_CACHEに格納されるまで数時間かかる場合があります。
• ホスト型サービスで HTTP 502/503/504 が発生したり、読み取りタイムアウトが繰り返し発生したりする場合は、ホスト型サービスへのリクエストが完了していません。規定回数の再試行後にサービスの稼働状況を確認してください。クライアントのタイムアウトを長くしても、サーバーが生成した HTTP 504 は解決できません。
• health.api.nvidia.comのポーリング URL を作り出さないでください。公開されている標準の MSA の例では同期 POST を使用しています。保留中の応答を結果として扱うには、サービス固有の完了確認方法が文書化されている必要があります。