evo2-nim

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Evo 2 NIM

Evo 2 NIM

Use Evo 2 for DNA generation and, locally, layer-output extraction. Use this
SKILL.md
for basic hosted/local use; load supplemental files only when needed:
  • references/api.md
    : exact schemas, layer names, Docker flags, hardware notes.
  • references/science.md
    : genomic use cases, limits, and interpretation.
  • references/parameters.md
    : generation/forward parameter effects.
  • references/validation.md
    : DNA, probability, timing, and tensor checks.
  • references/examples.md
    : compact hosted/local request patterns.
使用Evo 2进行DNA生成,在本地部署场景下还可提取层输出。本
SKILL.md
适用于基础的云端/本地使用场景;仅在需要时加载补充文件:
  • references/api.md
    :精确的模式、层名称、Docker参数、硬件说明。
  • references/science.md
    :基因组学用例、限制条件及解读说明。
  • references/parameters.md
    :生成/前向传播参数的影响。
  • references/validation.md
    :DNA、概率、时序及张量检查。
  • references/examples.md
    :简洁的云端/本地请求示例。

Choose Mode

选择模式

Ask only when context is unclear:
Hosted NVIDIA API or local Docker Evo 2 NIM?
  • Hosted generation:
    https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate
  • Local generation:
    http://localhost:8000/biology/arc/evo2/generate
  • Local forward/layer outputs:
    http://localhost:8000/biology/arc/evo2/forward
The hosted docs expose generation.
/forward
is documented for local Docker; do not invent a hosted
/forward
endpoint. Hosted requests use
Authorization: Bearer $NGC_API_KEY
. Supported local Docker startup uses
NGC_API_KEY
(or
NVIDIA_API_KEY
via the preflight) for registry login, entitlement checks, and first-run model downloads; pass it into the container with
-e NGC_API_KEY
. Local inference requests use no auth header after readiness. Warm-cache key-free startup varies by image/version and should not be assumed.
仅在上下文不明确时询问:
使用NVIDIA云端API还是本地Docker部署的Evo 2 NIM?
  • 云端托管生成:
    https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate
  • 本地生成:
    http://localhost:8000/biology/arc/evo2/generate
  • 本地前向传播/层输出:
    http://localhost:8000/biology/arc/evo2/forward
云端文档仅开放生成功能。
/forward
接口仅针对本地Docker部署提供文档;请勿虚构云端的
/forward
端点。云端请求需使用
Authorization: Bearer $NGC_API_KEY
。本地Docker启动需使用
NGC_API_KEY
(或通过预检流程使用
NVIDIA_API_KEY
)进行镜像仓库登录、权限验证及首次运行时的模型下载;需通过
-e NGC_API_KEY
将其传入容器。本地推理请求在服务就绪后无需认证头。无密钥的预热缓存启动方式因镜像/版本而异,请勿默认该方式可用。

Local Docker Requirements

本地Docker部署要求

Evo 2 local deployment requires FP8-capable GPUs. Do not present A100 as compatible; A100 can pull the image but fails warmup because FP8 requires compute capability 8.9 or higher.
  • Default 40B: 2x H100 80 GB or 1x H200 141 GB. Use
    NIM_TEST_GPUS=0,1
    for 2x H100, or
    NIM_TEST_GPUS=0
    for one H200.
  • 7B fallback: set
    NIM_VARIANT=7b
    ; supported GPUs include H100, H200, RTX 6000 Ada, and L40S.
  • Approximate disk: 110 GB for 40B, 50 GB for 7B.
Use shell env first; source repo-root
.env
only if present. Do not invent a cache default or drop the
NVIDIA_API_KEY
fallback.
bash
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
Evo 2本地部署需要支持FP8的GPU。请勿将A100列为兼容设备;A100可拉取镜像,但因FP8要求计算能力8.9或更高,会在预热阶段失败。
  • 默认40B模型:需要2张H100 80 GB或1张H200 141 GB GPU。使用
    NIM_TEST_GPUS=0,1
    适配2张H100,或
    NIM_TEST_GPUS=0
    适配单张H200。
  • 7B fallback模型:设置
    NIM_VARIANT=7b
    ;支持的GPU包括H100、H200、RTX 6000 Ada及L40S。
  • 磁盘空间需求:40B模型约110 GB,7B模型约50 GB。
优先使用Shell环境变量;仅当存在仓库根目录的
.env
文件时才加载该文件。请勿虚构缓存默认值或忽略
NVIDIA_API_KEY
的 fallback 机制。
bash
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.

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

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

Readiness:

```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 10; done
If RTX PRO 6000 Blackwell Workstation fails with no Transformer Engine attention backend, treat it as outside the current validated matrix and rerun on a documented GPU/runtime.
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

就绪检查:

```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 10; done
如果RTX PRO 6000 Blackwell工作站因缺少Transformer Engine注意力后端而运行失败,将其视为超出当前验证矩阵范围,需在已验证的GPU/运行时环境中重新运行。

DNA Generation

DNA生成

Normalize prompts before sending. Use A/C/G/T unless ambiguous bases are a deliberate modeling choice and clearly reported.
python
import json
import os
from pathlib import Path
import requests

HOSTED = True

def clean_dna(value: str) -> str:
    seq = "".join(value.upper().split())
    invalid = sorted(set(seq) - set("ACGT"))
    if invalid:
        raise ValueError(f"Unexpected DNA characters: {''.join(invalid)}")
    return seq

prompt = clean_dna("ACTGACTGACTGACTG")
nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000")
url = (
    "https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate"
    if HOSTED else f"{nim_url}/biology/arc/evo2/generate"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
    api_key = os.getenv("NGC_API_KEY")
    headers["Authorization"] = f"Bearer {api_key}"

payload = {
    "sequence": prompt,
    "num_tokens": 64,
    "temperature": 0.7,
    "top_k": 3,
    "top_p": 0.0,
    "random_seed": 1,
    "enable_sampled_probs": True,
    "enable_elapsed_ms_per_token": True,
}
response = requests.post(url, headers=headers, json=payload, timeout=180)
response.raise_for_status()
result = response.json()
seq = result["sequence"]
if sorted(set(seq.upper()) - set("ACGT")):
    raise ValueError("Generated sequence contains unexpected non-ACGT bases")

Path("evo2_generation.json").write_text(json.dumps(result, indent=2) + "\n")
Path("evo2_generated.fa").write_text(f">evo2_generated\n{seq}\n")
print(f"Generated {len(seq)} bases in {result.get('elapsed_ms')} ms")
Only request
enable_logits
when needed; logits can make responses large.
random_seed
supports development reproducibility, not biological certainty.
发送请求前需标准化提示词。除非明确报告并将模糊碱基作为建模的刻意选择,否则仅使用A/C/G/T碱基。
python
import json
import os
from pathlib import Path
import requests

HOSTED = True

def clean_dna(value: str) -> str:
    seq = "".join(value.upper().split())
    invalid = sorted(set(seq) - set("ACGT"))
    if invalid:
        raise ValueError(f"Unexpected DNA characters: {''.join(invalid)}")
    return seq

prompt = clean_dna("ACTGACTGACTGACTG")
nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000")
url = (
    "https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate"
    if HOSTED else f"{nim_url}/biology/arc/evo2/generate"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
    api_key = os.getenv("NGC_API_KEY")
    headers["Authorization"] = f"Bearer {api_key}"

payload = {
    "sequence": prompt,
    "num_tokens": 64,
    "temperature": 0.7,
    "top_k": 3,
    "top_p": 0.0,
    "random_seed": 1,
    "enable_sampled_probs": True,
    "enable_elapsed_ms_per_token": True,
}
response = requests.post(url, headers=headers, json=payload, timeout=180)
response.raise_for_status()
result = response.json()
seq = result["sequence"]
if sorted(set(seq.upper()) - set("ACGT")):
    raise ValueError("Generated sequence contains unexpected non-ACGT bases")

Path("evo2_generation.json").write_text(json.dumps(result, indent=2) + "\n")
Path("evo2_generated.fa").write_text(f">evo2_generated\n{seq}\n")
print(f"Generated {len(seq)} bases in {result.get('elapsed_ms')} ms")
仅在需要时请求
enable_logits
;logits会大幅增加响应体积。
random_seed
用于保障开发阶段的可复现性,而非生物层面的确定性。

Local Forward Pass

本地前向传播

Forward returns base64-encoded NPZ tensors.
python
import base64
import io
import os
import numpy as np
import requests

nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000")
payload = {
    "sequence": clean_dna("ACTGACTGACTG"),
    "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()))
前向传播返回base64编码的NPZ张量。
python
import base64
import io
import os
import numpy as np
import requests

nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000")
payload = {
    "sequence": clean_dna("ACTGACTGACTG"),
    "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()))

Validate And Report

验证与报告

Save request/response JSON, generated FASTA, and a metrics JSON with sequence length, GC fraction, ambiguous-base fraction, homopolymer length, sampled-prob checks, and elapsed timing. Treat invalid schema or alphabet as hard failures; treat extreme GC, low complexity, duplicates, and missing motifs as warnings. For deeper checks, read
references/validation.md
.
Key fields:
sequence
,
num_tokens
,
temperature
,
top_k
(0-6),
top_p
(0-1),
random_seed
,
enable_sampled_probs
,
enable_elapsed_ms_per_token
, and optional
enable_logits
.
保存请求/响应JSON、生成的FASTA文件,以及包含序列长度、GC含量、模糊碱基占比、均聚物长度、采样概率检查和耗时统计的指标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

Troubleshooting

故障排查

  • 401/403
    : hosted key missing/expired or not sent as Bearer token.
  • 422
    : wrong field names such as
    max_tokens
    instead of
    num_tokens
    .
  • Local auth confusion: do not send
    Authorization
    to localhost.
  • Local startup: first run downloads model assets; wait on
    /v1/health/ready
    .
  • FP8 failure: use hosted, 7B on a supported FP8 GPU, or documented 40B GPUs.
  • 401/403
    :云端密钥缺失/过期,或未以Bearer token形式发送。
  • 422
    :字段名称错误,例如使用
    max_tokens
    而非
    num_tokens
  • 本地认证混淆:请勿向localhost发送
    Authorization
    头。
  • 本地启动:首次运行会下载模型资源;需等待
    /v1/health/ready
    接口返回就绪状态。
  • FP8失败:使用云端服务、在支持FP8的GPU上运行7B模型,或使用已验证的40B模型兼容GPU。