esm

ESM：进化尺度建模

概述

ESM 提供用于理解、生成和设计蛋白质的蛋白质语言模型。请将此技能用于当前的 EvolutionaryScale/Biohub 工作流：用于生成式设计的 ESM3、用于表征学习和嵌入的 ESMC、托管的 Forge/Biohub 推理，以及 ESMFold2 全原子结构预测。

核心功能

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

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

适用场景：

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

基本用法：

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

# Load local open weights after accepting the license on Hugging Face.
model: ESM3InferenceClient = ESM3.from_pretrained("esm3-open").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)

通过 Forge API 远程/云端使用：

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

# Same interface as local ESM3; token from ESM_API_KEY (see Authentication)
model = esm.sdk.client("esm3-medium-2024-08", token=os.environ["ESM_API_KEY"])

# Generate
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 sequence
protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP...")
protein_with_structure = model.generate(
    protein,
    GenerationConfig(track="structure", num_steps=protein.sequence.count("_"))
)

# 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 ESM C model
model = ESMC.from_pretrained("esmc_300m").to("cuda")

# Get embeddings
protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP...")
protein_tensor = model.encode(protein)
logits_output = model.logits(
    protein_tensor,
    LogitsConfig(sequence=True, return_embeddings=True),
)
embeddings = logits_output.embeddings

批处理：

# Encode multiple proteins
proteins = [
    ESMProtein(sequence="MPRTKEIND..."),
    ESMProtein(sequence="AGLIVHSPQ..."),
    ESMProtein(sequence="KTEFLNDGR...")
]

embeddings_list = [
    model.logits(
        model.encode(p),
        LogitsConfig(sequence=True, return_embeddings=True),
    ).embeddings
    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. 使用 Forge API 进行批处理

使用 Forge 的异步方法，高效处理多个蛋白质。

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

client = esm.sdk.client("esm3-medium-2024-08", token=os.environ["ESM_API_KEY"])

# Async batch processing
async def batch_generate(proteins_list):
    tasks = [
        client.async_generate(protein, GenerationConfig(track="sequence"))
        for protein in proteins_list
    ]
    return await asyncio.gather(*tasks)

# Execute
proteins = [ESMProtein(sequence=f"MPRT{'_' * 50}KEND") for _ in range(10)]
results = asyncio.run(batch_generate(proteins))

有关详细的 Forge API 文档、身份验证、速率限制和批处理模式，请参阅 references/forge-api.md。

模型选择指南

ESM3 模型（生成式）：

• esm3-open（1.4B）——开放权重，接受 Hugging Face 许可协议后可本地使用
• esm3-medium-2024-08（7B）——质量与速度的最佳平衡（仅限 Forge）
• esm3-large-2024-03（98B）——质量最高，速度较慢（仅限 Forge）

ESM C 模型（嵌入）：

• esmc_300m / esmc-300m-2024-12（30 层）——轻量、推理速度快（开放权重，可本地使用）
• esmc_600m / esmc-600m-2024-12（36 层）——性能均衡（开放权重，可本地使用）
• esmc-6b-2024-12（80 层）——质量最高（Forge API；本地 6B 权重需要 Forge 或 SageMaker）

本地 ESMC.from_pretrained() 示例使用带下划线的别名（esmc_300m、esmc_600m）。托管 API 客户端使用带日期的模型 ID，例如 esmc-600m-2024-12。

选择标准：

• 本地开发/测试： 使用 esm3-open 或 esmc_300m
• 生产级质量： 通过 Forge 使用 esm3-medium-2024-08
• 最高准确度： 通过 Forge 使用 esm3-large-2024-03 或 esmc-6b-2024-12
• 高吞吐量： 使用 Forge 或 Biohub API，并设置明确的异步并发限制
• 成本优化： 使用较小的模型并实施缓存策略

安装

从 PyPI 安装（EvolutionaryScale 在 PyPI 上发布的 esm）。当前 PyPI 版本：3.2.3（2025 年 10 月 14 日）。需要 Python >=3.12,<3.13。

基本安装：

uv pip install "esm==3.2.3"

安装 Flash Attention（推荐用于提升 NVIDIA GPU 上的推理速度）：

uv pip install "esm==3.2.3"
uv pip install flash-attn --no-build-isolation

Forge 客户端随 esm 软件包一同提供——使用 Forge 进行 ESM3 或 ESMC 推理无需额外安装。

身份验证

访问 Forge API 需要 API 密钥。切勿在脚本中硬编码令牌，也不要将其提交到版本控制中。

1. 检查环境中是否已设置 ESM_API_KEY。
2. 如果没有，仅检查本地 .env 中的 ESM_API_KEY（不要加载无关的机密信息）。
3. 如果仍未设置，请为 Biohub API 在 Biohub developer console 中创建密钥；如果要访问旧版 Forge 托管的 ESM3/ESMC，则在 Forge 中创建密钥。

import os

token = os.environ["ESM_API_KEY"]  # raises KeyError if unset

如果省略 token，esm.sdk.client() 会自动读取 ESM_API_KEY。请将端点 URL 固定为可信主机，例如 https://forge.evolutionaryscale.ai 或 https://biohub.ai；不要使用来自不可信用户输入的 API 主机地址。

Biohub 平台： EvolutionaryScale 和 Forge 现在通过 biohub.ai 提供当前托管模型。SDK 类名中可能仍会包含“Forge”。有关 ESMFold2 和 Biohub 专属配置，请参阅 references/biohub-platform.md。

常见工作流

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

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

参考资料

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

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

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

最佳实践

对于生成任务：

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

对于嵌入任务：

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

对于生产部署：

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

资源与文档

• GitHub 仓库： https://github.com/Biohub/esm（当前的 ESMC/ESMFold2/Biohub 文档；ESM3 文档仍通过仓库中的链接提供）
• Forge 平台： https://forge.evolutionaryscale.ai
• Biohub 平台： https://biohub.ai
• 科学论文： Hayes 等，Science（2025）- https://www.science.org/doi/10.1126/science.ads0018
• 博客文章：
  • ESM3 发布：https://www.evolutionaryscale.ai/blog/esm3-release
  • ESM C 发布：https://www.evolutionaryscale.ai/blog/esm-cambrian
• 社区： Slack 社区：https://bit.ly/3FKwcWd
• 模型权重： Hugging Face 上的 EvolutionaryScale 和 Biohub 组织

负责任地使用

ESM 旨在用于蛋白质工程、药物发现和科学研究等有益领域。设计新型蛋白质时，请遵循负责任生物设计框架（https://responsiblebiodesign.ai/）和 Biohub 可接受使用政策（https://biohub.org/acceptable-use-policy/）。在实验验证之前，请考虑蛋白质设计的生物安全和伦理影响。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组/注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一条染色体、几千个细胞）上运行流水线。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果发生这种情况	请执行此操作
输入之间的基因组版本或标识符不匹配	停止并先进行统一（liftover、ID 映射），然后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。切勿臆造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所作的假设。

完整性规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直言说明。
• 不要作出超出统计结果支持范围的生物学意义解读；报告多重检验校正。
• 此处与特定版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 涉及费用、占用共享 GPU 或云配额、处理个人或患者数据，或无法撤销的操作时，请先征求同意。

相关技能

• sentence-transformers：使用 Python sentence-transformers（SBERT）库在本地生成句子、文本和图像嵌入，使用预训练的 Hugging Fac…
• adaptyv：介绍如何使用 Adaptyv Bio Foundry API 和 Python SDK 进行蛋白质实验设计、提交和结果检索。
• tamarind：通过其 REST API 或 MCP 服务，在 Tamarind Bio 平台上访问一系列开源分子设计和结构生物学工具。