evo2-nim

Evo 2 NIM

Evo 2 を DNA の生成と、ローカルでのレイヤー出力の抽出に使用します。補足ファイルは必要な場合にのみ読み込みます。

• references/api.md：正確なスキーマ、レイヤー名、Docker フラグ、ハードウェアに関する注意事項。
• references/science.md：ゲノムのユースケース、制限事項、解釈。
• references/parameters.md：生成／forward パラメーターの効果。
• references/validation.md：DNA、確率、タイミング、テンソルのチェック。
• references/examples.md：ホスト型／ローカルの簡潔なリクエストパターン。

手順

生成では、scripts/generate.py を使用してリクエストを実行し、レスポンスを検証して、その成果物を保存します。スクリプトのパスはこのスキルのディレクトリを基準に解決し、出力先ディレクトリにはユーザーのワークスペース内の場所を選んでください。ユーザーの配列と指定されたパラメーターを使用します。以下の例はスモークテストにすぎません。

1. 要求されたモードを選択します。ホスト型で生成する場合は、生成の例に直接進んでください。Docker のセットアップとローカルの forward パスは別のタスクです。
2. ユーザーが生成の実行を求めている場合は、クライアントを実行し、終了ステータスと結果を確認してください。スクリプトを書くだけでは、そのリクエストを完了したことにはなりません。
3. 成功した実行から、生成された DNA（長い配列の場合はそのファイル）、実際の elapsed_ms、サンプリングされた確率の要約、シード、成果物のパスを報告してください。結果が不明確な場合は、保存されたレスポンスまたはメトリクスを読み取ってください。

リクエストまたは検証に失敗した場合は、実際の失敗内容と診断ファイルがあれば報告してください。利用できない API レスポンスを、例の値で置き換えてはいけません。コードのみを求められた場合は、推論呼び出しを行わずにコマンドを提示してください。

モードの選択

NIM_API_MODE が設定されている場合は、その値を優先してください。有効な値は hosted と local です。設定されていない場合、EVO2_NIM_URL が明示的に指定されていれば local として扱います。それ以外の場合、要求されたモードが不明確であれば、次のように尋ねてください。

ホスト型の NVIDIA API とローカルの Docker Evo 2 NIM のどちらを使用しますか？

• ホスト型生成：https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate
• ローカルのベース URL：$EVO2_NIM_URL。設定されていない場合は http://localhost:8000
• ローカル生成：$EVO2_NIM_URL/biology/arc/evo2/generate
• ローカルの forward／レイヤー出力：$EVO2_NIM_URL/biology/arc/evo2/forward

EVO2_NIM_URL が設定されている場合は、ローカルのヘルスチェックと推論のルートを必ずそこから解決してください。localhost が機能するのは、呼び出し元と NIM が同じネットワーク名前空間を共有している場合に限られます。別のコンテナから呼び出す場合は、通常 http://evo2-nim:8000 のようなサービス URL が必要です。選択したエンドポイントが利用できない場合、モードを黙って切り替えてはいけません。失敗したエンドポイントを報告し、その設定を修正してください。

ホスト型のドキュメントで公開されているのは生成機能です。/forward はローカルの Docker 用に記載されているため、ホスト型の /forward エンドポイントを作り出してはいけません。ホスト型のリクエストでは Authorization: Bearer $NGC_API_KEY を使用します。サポートされているローカルの Docker 起動では、レジストリへのログイン、利用資格の確認、初回のモデルダウンロードに NGC_API_KEY（または preflight 経由の NVIDIA_API_KEY）を使用します。-e NGC_API_KEY でコンテナに渡してください。準備完了後のローカル推論リクエストでは、認証ヘッダーは不要です。ウォームキャッシュ時にキーなしで起動できるかどうかはイメージ／バージョンによって異なるため、可能だと想定してはいけません。

例

送信する前にプロンプトを正規化します。曖昧な塩基を意図的なモデリング上の選択として使用し、その旨を明確に報告する場合を除き、A/C/G/T を使用します。

ホステッド生成リクエストでは、ユーザーの入力を指定して同梱クライアントを実行します（以下のスクリプトパスはスキルディレクトリからの相対パスです）。

python scripts/generate.py \
  --mode hosted \
  --sequence ACTGACTGACTGACTG \
  --num-tokens 64 --seed 1 \
  --temperature 0.7 --top-k 3 --top-p 0.0 \
  --output-dir /path/to/workspace/evo2-output

すでに準備済みのローカル NIM では、--mode local を使用します。クライアントは EVO2_NIM_URL を解決し、Authorization ヘッダーを送信しません。リクエストが失敗しても、エンドポイントを切り替えることはありません。ユーザーがより長い生成を要求した場合は、読み取り時間を延長するために --timeout を設定します。失敗したリクエストが自動的に再送信されることはありません。

クライアントは、選択した出力ディレクトリに request.json、実際の response.json、generated.fasta、metrics.json を保存します。また、HTTP ステータスの確認や JSON の解析を行う前に、正確なレスポンス本文を response.raw に保存します。そのため、不正な JSON や有限値でない確率・時間が含まれていても、診断情報が残ります。 成功の概要を出力する前に、要求された生成塩基数、A/C/G/T のアルファベット、有限値であるサンプリング確率が [0, 1] の範囲内であること、計測時間が非負であることを検証します。既存のディレクトリは、空であっても再利用されません。存在しない出力ディレクトリを指定してください。クライアントはディレクトリをアトミックに作成するため、同時に実行しても互いの生成物を上書きできません。 FASTA には生成された塩基のみが含まれ、入力プロンプトが再度先頭に付加されることはありません。

クライアントは sampled_probs を要求し、件数・最小値・最大値・平均値を要約します。全値は保存されたレスポンスに含まれます。確率配列が存在しない、または形式が不正な場合は検証エラーとなり、信頼度の値を捏造してよいことにはなりません。 必要な場合に限り、カスタムリクエストで enable_logits を要求してください。logits によってレスポンスが大きくなることがあります。カスタムペイロードについては references/api.md を参照してください。 random_seed は開発時の再現性をサポートするものであり、生物学的な確実性を保証するものではありません。

ローカル Docker の要件

Evo 2 のローカルデプロイには、FP8 対応 GPU が必要です。A100 を互換性があるものとして提示しないでください。A100 ではイメージを取得できますが、FP8 には compute capability 8.9 以上が必要なため、ウォームアップに失敗します。

• デフォルトの 40B：2x H100 80 GB または 1x H200 141 GB。2x H100 では NIM_TEST_GPUS=0,1、H200 1 基では NIM_TEST_GPUS=0 を使用します。
• 7B のフォールバック：NIM_VARIANT=7b を設定します。対応 GPU には H100、H200、RTX 6000 Ada、L40S があります。
• ディスク容量の目安：40B では 110 GB、7B では 50 GB。

まずシェル環境変数を使用し、リポジトリルートの .env は存在する場合に限り読み込みます。キャッシュのデフォルト値を作り上げたり、NVIDIA_API_KEY のフォールバックを削除したりしないでください。

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}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"

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

# 40B default: 0,1 for 2x H100; set 0 for a single H200.
export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0,1}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 700 "${LOCAL_NIM_CACHE}"   # owner-only; if the NIM runs as a different UID, add -u "$(id -u)" to docker run

# For 7B: export NIM_VARIANT=7b; export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0}"
docker run --rm -it --name evo2-nim \
  --runtime=nvidia \
  --gpus "\"device=${NIM_TEST_GPUS}\"" \
  -e NGC_API_KEY \
  -e NIM_VARIANT \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/arc/evo2:2

準備状態：

evo2_nim_url="${EVO2_NIM_URL:-http://localhost:8000}"
until curl -sf "${evo2_nim_url%/}/v1/health/ready"; do sleep 10; done

RTX PRO 6000 Blackwell Workstation で Transformer Engine のアテンションバックエンドがないというエラーが発生した場合は、現在の検証済み構成の対象外として扱い、文書化された GPU／ランタイムで再実行してください。

ローカルのフォワードパス

フォワードパスは、base64 エンコードされた NPZ テンソルを返します。

import base64
import io
import os
import numpy as np
import requests

mode = os.getenv("NIM_API_MODE", "local")
if mode != "local":
    raise RuntimeError("Evo 2 /forward is available only in local mode")
nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000").rstrip("/")
sequence = "ACTGACTGACTG"  # Replace with the user's DNA sequence.
sequence = "".join(sequence.upper().split())
if not sequence or set(sequence) - set("ACGT"):
    raise ValueError("Expected nonempty A/C/G/T DNA")
payload = {
    "sequence": sequence,
    "output_layers": ["output_layer", "decoder.layers.3.self_attention"],
}
response = requests.post(
    f"{nim_url}/biology/arc/evo2/forward",
    headers={"Content-Type": "application/json"},
    json=payload,
    timeout=300,
)
response.raise_for_status()
npz_bytes = base64.b64decode(response.json()["data"])
with open("evo2_forward_outputs.npz", "wb") as handle:
    handle.write(npz_bytes)
arrays = np.load(io.BytesIO(npz_bytes), allow_pickle=False)
for name in arrays.files:
    arr = arrays[name]
    print(name, arr.shape, arr.dtype, bool(np.isfinite(arr).all()), float(arr.mean()))

検証と報告

リクエスト／レスポンスの JSON、生成された FASTA、ならびに配列長、GC 含有率、曖昧な塩基の割合、ホモポリマー長、サンプリング確率のチェック、経過時間を含む metrics JSON を保存します。スキーマまたはアルファベットが無効な場合は致命的なエラーとして扱い、極端な GC 含有率、低複雑度、重複、モチーフの欠落は警告として扱います。詳しいチェックについては references/validation.md を参照してください。

主なフィールド：sequence、num_tokens、temperature、top_k（0-6）、top_p（0-1）、random_seed、enable_sampled_probs、enable_elapsed_ms_per_token、および任意の enable_logits。

トラブルシューティング

• 401/403：ホステッドキーが未設定または期限切れ、あるいは Bearer トークンとして送信されていません。
• 422：max_tokens を num_tokens の代わりに指定するなど、フィールド名が間違っています。
• ローカルエンドポイントの混同：NIM_API_MODE と EVO2_NIM_URL を出力してください。設定済みのサービス URL を localhost に置き換えないでください。
• ローカル認証の混同：ローカル推論には Authorization を送信しないでください。
• ローカル起動：初回実行時にモデルアセットがダウンロードされます。推論の前に $EVO2_NIM_URL/v1/health/ready をポーリングしてください。
• FP8 エラー：ホステッド版、対応する FP8 GPU 上の 7B、または文書化された 40B 対応 GPU を使用してください。