alterlab-esm

ESM：进化尺度建模

概述

ESM 提供先进的蛋白质语言模型，用于理解、生成和设计蛋白质。esm 包中包含三个系列：

• ESMC — 当前的表征模型（300M / 600M 开放权重，可通过托管平台使用 6B），用于生成嵌入、logits 和下游机器学习特征。
• ESMFold2 — 基于 ESMC-6B 构建的结构预测模型，通过 esmfold2_client 托管。
• ESM3 — 面向序列 / 结构 / 功能轨道的生成式多模态模型。

命名和托管方式已变更——复制旧代码前请先阅读

EvolutionaryScale 现以 Biohub 之名运营。实际变化如下：

• 托管 API 已从 forge.evolutionaryscale.ai 迁移至 https://biohub.ai；esm.sdk 中的每个客户端都默认使用该 URL，并从 ESM_API_KEY 读取令牌。为保持向后兼容，这些类仍命名为 *ForgeInferenceClient。
• 模型权重存放在 Hugging Face 的 biohub 组织下（biohub/ESMC-6B、biohub/esm3-sm-open-v1、biohub/ESMFold2）。
• ESMC 和 ESMFold2 也可通过 Hugging Face Transformers v5.16+ 使用，其依赖栈与 esm 包的优化推理路径不同。

何时使用此技能

当用户需要蛋白质嵌入或 logits、ESM 模型生成的蛋白质结构、逆折叠或生成式序列设计时，使用此技能。

不适用场景

场景	改用
使用 AlphaFold2/ColabFold 折叠蛋白质或复合物	alterlab-alphafold
与配体共同折叠，或预测结合亲和力	alterlab-boltz
抗体–抗原或混合多实体复合物	alterlab-chai
为固定骨架设计序列（ProteinMPNN 系列）	alterlab-proteinmpnn、alterlab-ligandmpnn
生成用于设计的从头骨架	alterlab-rfdiffusion

核心能力

1. 使用 ESM3 生成蛋白质序列

使用多模态生成建模，生成具有所需属性的新型蛋白质序列。

适用场景：

• 设计具有特定功能属性的蛋白质
• 补全部分蛋白质序列
• 生成现有蛋白质的变体
• 创建具有所需结构特征的蛋白质

基本用法：

from esm.models.esm3 import ESM3
from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig

# Load model locally
model: ESM3InferenceClient = ESM3.from_pretrained("esm3-sm-open-v1").to("cuda")

# Create protein prompt
protein = ESMProtein(sequence="MPRT___KEND")  # '_' represents masked positions

# Generate completion
protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
print(protein.sequence)

通过 Biohub Platform 远程 / 云端使用：

import esm
from esm.sdk.api import ESMProtein, GenerationConfig

# url defaults to https://biohub.ai and token to os.environ["ESM_API_KEY"]
model = esm.sdk.client("esm3-medium-2024-08")

protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))

有关详细的 ESM3 模型规格、高级生成配置和多模态提示示例，请参阅 references/esm3-api.md。

2. 结构预测与逆折叠

使用 ESM3 的结构轨道，根据序列预测结构，或进行逆折叠（根据结构设计序列）。

结构预测：

from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig

# Predict structure from a complete sequence
protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP")
protein_with_structure = model.generate(
    protein,
    # num_steps controls how many structure tokens are decoded per step;
    # use the sequence length (not a "_" count — the sequence is complete here)
    GenerationConfig(track="structure", num_steps=len(protein.sequence))
)

# Access predicted structure
coordinates = protein_with_structure.coordinates  # 3D coordinates
pdb_string = protein_with_structure.to_pdb()

逆折叠（根据结构生成序列）：

# Design sequence for a target structure
protein_with_structure = ESMProtein.from_pdb("target_structure.pdb")
protein_with_structure.sequence = None  # Remove sequence

# Generate sequence that folds to this structure
designed_protein = model.generate(
    protein_with_structure,
    GenerationConfig(track="sequence", num_steps=50, temperature=0.7)
)

3. 使用 ESM C 生成蛋白质嵌入

生成高质量嵌入，用于功能预测、分类或相似性分析等下游任务。

适用场景：

• 提取用于机器学习的蛋白质表征
• 计算序列相似度
• 为蛋白质分类提取特征
• 将迁移学习用于蛋白质相关任务

基本用法：

from esm.models.esmc import ESMC
from esm.sdk.api import ESMProtein, LogitsConfig

# Load ESMC locally (local from_pretrained names use UNDERSCORES; default is esmc_600m)
model = ESMC.from_pretrained("esmc_300m").to("cuda")

# Encode, then request embeddings via the logits() API
protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP")
protein_tensor = model.encode(protein)
out = model.logits(protein_tensor, LogitsConfig(sequence=True, return_embeddings=True))

embeddings = out.embeddings   # (1, L+2, hidden_dim), incl. BOS/EOS tokens
logits = out.logits.sequence  # per-position amino-acid logits

不要调用 model.forward(...) 来获取嵌入——forward 返回的是原始模型输出，而非可用的表征张量。请使用 model.logits(..., LogitsConfig(return_embeddings=True)).embeddings。

批处理：

# Encode multiple proteins and pull mean-pooled embeddings
proteins = [
    ESMProtein(sequence="MPRTKEIND"),
    ESMProtein(sequence="AGLIVHSPQ"),
    ESMProtein(sequence="KTEFLNDGR"),
]
cfg = LogitsConfig(sequence=True, return_embeddings=True)
embeddings_list = [
    model.logits(model.encode(p), cfg).embeddings.mean(dim=1) for p in proteins
]

有关 ESM C 模型详情、效率比较和高级嵌入策略，请参阅 references/esm-c-api.md。

4. 功能条件控制与注释

使用 ESM3 的功能轨道生成带有特定功能注释的蛋白质，或根据序列预测功能。

功能条件生成：

from esm.sdk.api import ESMProtein, FunctionAnnotation, GenerationConfig

# Create protein with desired function
protein = ESMProtein(
    sequence="_" * 200,  # Generate 200 residue protein
    function_annotations=[
        FunctionAnnotation(label="fluorescent_protein", start=50, end=150)
    ]
)

# Generate sequence with specified function
functional_protein = model.generate(
    protein,
    GenerationConfig(track="sequence", num_steps=200)
)

5. 思维链生成

使用 ESM3 的思维链生成方法，迭代优化蛋白质设计。

from esm.sdk.api import GenerationConfig

# Multi-step refinement
protein = ESMProtein(sequence="MPRT" + "_" * 100 + "KEND")

# Step 1: Generate initial structure
config = GenerationConfig(track="structure", num_steps=50)
protein = model.generate(protein, config)

# Step 2: Refine sequence based on structure
config = GenerationConfig(track="sequence", num_steps=50, temperature=0.5)
protein = model.generate(protein, config)

# Step 3: Predict function
config = GenerationConfig(track="function", num_steps=20)
protein = model.generate(protein, config)

6. 使用托管平台进行批处理

客户端提供异步 API 和并行执行器，可处理重试并显示进度条：

import asyncio
import esm
from esm.sdk import parallel_executor
from esm.sdk.api import ESMProtein, GenerationConfig

client = esm.sdk.client("esm3-medium-2024-08")   # token from ESM_API_KEY
proteins = [ESMProtein(sequence=f"MPRT{'_' * 50}KEND") for _ in range(10)]
cfg = GenerationConfig(track="sequence", num_steps=8)

# Option A: async fan-out
async def run():
    return await asyncio.gather(*(client.async_generate(p, cfg) for p in proteins))

results = asyncio.run(run())

# Option B: managed executor (retries + progress)
with parallel_executor() as executor:
    results = executor.execute_batch(client.generate, protein=proteins, config=cfg)

此外，还提供 client.batch_generate(...) / async_batch_generate(...)，以及用于其他轨道的 async_fold / async_inverse_fold / async_logits。

平台文档、身份验证、速率限制和批处理模式请参阅 references/forge-api.md。

模型选择指南

ESM3 模型（生成式）：

• esm3-sm-open-v1（1.4B，别名为 esm3_sm_open_v1 / esm3-open）——开放权重，可在本地运行
• esm3-medium-2024-08（7B）——质量和速度均衡（仅托管）
• esm3-large-2024-03（98B）——质量最高，速度较慢（仅托管）

ESMC 模型（表示）：

• esmc_300m——轻量、快速；开放权重，可在本地运行
• esmc_600m——均衡；开放权重，可在本地运行，也是 from_pretrained 的默认值
• esmc_6b / 托管版 esmc-6b-2024-12——表示质量最高

ESMFold2（结构）： esmfold2-fast-2026-05（esmfold2_client 的默认值）、 esmfold2-2026-05、esmfold2-2026-05-cutoff-2025。

命名注意事项：本地 from_pretrained(...) 使用下划线（esmc_300m、 esmc_600m、esmc_6b）。托管客户端字符串使用连字符和日期 （esmc-600m-2024-12、esm3-medium-2024-08、esmfold2-fast-2026-05）。

选择标准：

• **本地开发/测试：**使用 esmc_300m 生成嵌入，使用 esm3-sm-open-v1 进行生成
• **生产环境质量：**通过 Biohub Platform 使用 esm3-medium-2024-08 或 esmc-6b-2024-12
• **结构预测：**使用 esmfold2_client()，而非 ESM3 结构轨道
• **高吞吐量：**使用托管客户端以及 esm.sdk.parallel_executor / 批处理客户端
• **成本优化：**使用较小的模型，缓存嵌入

安装

基本安装（固定次版本号——SDK 仍会随发布版本变化）：

uv pip install "esm>=3.4,<3.5"     # 3.4.1.post1 as of 2026-09; needs Python >= 3.12

安装 Flash Attention（可选，可加快 GPU 推理）：

uv pip install flash-attn --no-build-isolation

托管客户端（esm.sdk.client、esmc_client、esmfold2_client）已包含在 esm 包中，无需额外安装。在 Biohub 开发者控制台 （https://biohub.ai/developer-console/api-keys）中创建 API 令牌，并将其导出为 ESM_API_KEY。本地 权重从 Hugging Face 获取，因此请使用具有读取权限的令牌运行一次 huggingface_hub.login()。

通过 Biohub Platform 使用 ESMC：

from esm.sdk import esmc_client
from esm.sdk.api import ESMProtein, LogitsConfig

model = esmc_client(model="esmc-600m-2024-12")       # url/token default as above
out = model.logits(model.encode(ESMProtein(sequence="MPRTKEINDAGLIVHSP")),
                   LogitsConfig(sequence=True, return_embeddings=True))
print(out.logits, out.embeddings)

常见工作流

详细示例和完整工作流请参阅 references/workflows.md，其中包括：

• 使用思维链设计新型 GFP
• 蛋白质变体生成与筛选
• 基于结构的序列优化
• 功能预测流水线
• 基于嵌入的聚类与分析

参考资料

此技能包含全面的参考文档：

• references/esm3-api.md - ESM3 模型架构、API 参考、生成参数和多模态提示
• references/esm-c-api.md - ESM C 模型详情、嵌入策略和性能优化
• references/forge-api.md - Forge 平台文档、身份验证、批处理和部署
• references/workflows.md - 完整示例和常见工作流模式

这些参考资料包含详细的 API 规范、参数说明和高级用法模式。请根据具体任务按需加载。

最佳实践

对于生成任务：

• 原型开发时从较小的模型开始（esm3-sm-open-v1）
• 使用温度参数控制多样性（0.0 = 确定性，1.0 = 多样）
• 对于复杂设计，使用思维链进行迭代优化
• 使用结构预测或湿实验验证生成的序列

对于嵌入任务：

• 尽可能批量处理序列以提高效率
• 缓存嵌入结果，以便重复分析时使用
• 计算相似度时对嵌入进行归一化
• 根据下游任务的要求选择合适的模型大小

对于生产部署：

• 使用托管的 Biohub Platform，以获得可扩展性并使用最大规模的模型
• 为 API 调用实现错误处理和重试逻辑
• 监控令牌用量并实施速率限制
• 考虑使用 AWS SageMaker 部署专用基础设施

资源和文档

• GitHub 仓库： https://github.com/Biohub/esm（ESM3 文档位于 _assets/ESM3_README.md）
• Biohub Platform： https://biohub.ai — API 密钥位于 https://biohub.ai/developer-console/api-keys
• ESM Atlas： https://biohub.ai/esm/protein/atlas
• ESM3 论文： Hayes 等人，Science — https://www.science.org/doi/10.1126/science.ads0018
• 教程： https://github.com/Biohub/esm/tree/main/cookbook/tutorials
• 模型权重： Hugging Face biohub 组织

负责任地使用

ESM 旨在用于蛋白质工程、药物发现和科学研究等有益应用。Biohub 发布了《可接受使用政策》，并在发布前开展了生物安全风险评估——设计新型蛋白质时，请遵循该政策以及《负责任的生物设计框架》（https://responsiblebiodesign.ai/）。在进行实验验证前，请充分考虑生物安全和双重用途的影响，因为设计的序列一经订购，就不再局限于计算领域。

属于 AlterLab Academic Skills 套件的一部分。