evo2-nim

Evo 2 NIM

使用 Evo 2 生成 DNA，并在本地提取层输出。仅在需要时加载补充文件：

• references/api.md：准确的架构、层名称、Docker 标志和硬件说明。
• references/science.md：基因组应用场景、局限性和解读方法。
• references/parameters.md：生成/前向参数的影响。
• references/validation.md：DNA、概率、耗时和张量检查。
• references/examples.md：简洁的托管/本地请求模式。

说明

生成时，使用 scripts/generate.py 执行请求、验证响应并保存其产物。相对于此技能目录解析脚本路径，并在用户的工作区中选择输出目录。使用用户提供的序列和请求参数；下方示例仅用于冒烟测试。

1. 选择请求的模式。对于托管生成，直接使用生成示例；Docker 设置和本地前向传递是单独的任务。
2. 用户要求运行生成时，执行客户端并检查其退出状态和结果。仅编写脚本并不算完成该请求。
3. 报告生成的 DNA（长序列则提供其文件）、实际的 elapsed_ms、采样概率摘要、种子，以及成功运行所产生的产物路径。若有任何结果不明确，请读取已保存的响应或指标。

如果请求或验证失败，请报告实际失败情况及任何诊断文件。不要用示例值代替不可用的 API 响应。对于仅要求代码的请求，提供命令，但不要执行推理调用。

选择模式

如果设置了 NIM_API_MODE，请遵循其值。接受的值为 hosted 和 local。 如果未设置，则将明确指定的 EVO2_NIM_URL 视为本地模式；否则，如果请求的模式不明确，请询问：

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
• 本地前向/层输出：$EVO2_NIM_URL/biology/arc/evo2/forward

如果存在 EVO2_NIM_URL，始终通过它解析本地健康检查和推理路由。只有调用方和 NIM 共用网络命名空间时，localhost 才可用；调用方位于独立容器中时，通常需要使用服务 URL，例如 http://evo2-nim:8000。所选端点不可用时，不要静默切换模式。请报告失败的端点并修正其配置。

托管文档介绍了生成接口。/forward 仅有本地 Docker 文档；不要臆造托管版的 /forward 端点。托管请求使用 Authorization: Bearer $NGC_API_KEY。受支持的本地 Docker 启动方式使用 NGC_API_KEY（或通过预检使用 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 要求计算能力达到 8.9 或更高。

• 默认 40B：2x H100 80 GB 或 1x H200 141 GB。2x H100 请使用 NIM_TEST_GPUS=0,1，单张 H200 请使用 NIM_TEST_GPUS=0。
• 7B 备用选项：设置 NIM_VARIANT=7b；支持的 GPU 包括 H100、H200、RTX 6000 Ada 和 L40S。
• 磁盘空间估算：40B 需要 110 GB，7B 需要 50 GB。

先使用 shell 环境变量；仅在存在时才加载仓库根目录的 .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 attention backend 而失败，请将其视为当前已验证矩阵之外的硬件，并改用有文档记录的 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 token 发送。
• 422：字段名错误，例如用 max_tokens 代替 num_tokens。
• 本地端点混淆：打印 NIM_API_MODE 和 EVO2_NIM_URL；不要用 localhost 替换已配置的服务 URL。
• 本地身份验证混淆：本地推理时不要发送 Authorization。
• 本地启动：首次运行会下载模型资源；推理前请轮询 $EVO2_NIM_URL/v1/health/ready。
• FP8 失败：请使用托管服务、在受支持的 FP8 GPU 上运行 7B，或使用有文档记录的 40B GPU。