alterlab-esm

ESM：Evolutionary Scale Modeling

概要

ESM は、タンパク質の理解、生成、設計を支援する最先端のタンパク質言語モデルを提供します。3 つのファミリーが同じ esm パッケージに含まれています。

• ESMC — 現行の表現モデル（オープンウェイトは 300M／600M、ホステッドプラットフォームでは 6B）。埋め込み、ロジット、下流の ML 機能に使用します。
• ESMFold2 — ESMC-6B を基盤とする構造予測。esmfold2_client 経由でホストされています。
• ESM3 — 配列／構造／機能の各トラックを扱う生成マルチモーダルモデル。

名称とホスティングが変更されました — 古いコードをコピーする前にお読みください

EvolutionaryScale は現在、Biohub として運営されています。実際の変更点は次のとおりです。

• ホステッド API の URL は 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 パッケージの最適化された推論パスとは異なる依存関係スタックです。

このスキルを使用する場面

ユーザーがタンパク質の埋め込みやロジット、ESM モデルによるタンパク質構造、インバースフォールディング、または生成的な配列設計を求めている場合に、このスキルを使用します。

対象外

シナリオ	代わりに使用
AlphaFold2／ColabFold でタンパク質または複合体をフォールディングする	alterlab-alphafold
リガンドとの共フォールディング、または結合親和性を予測する	alterlab-boltz
抗体–抗原複合体、または複数の異なるエンティティを含む複合体	alterlab-chai
固定されたバックボーンに対する配列を設計する（ProteinMPNN ファミリー）	alterlab-proteinmpnn、alterlab-ligandmpnn
設計の土台となるバックボーンを de novo で生成する	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. Chain-of-Thought 生成

ESM3 の Chain-of-Thought 生成手法を使用して、タンパク質の設計を段階的に改良します。

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
• 構造予測： ESM3 の構造トラックではなく、esmfold2_client()
• 高スループット： ホスト型クライアントと 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 et al., Science — https://www.science.org/doi/10.1126/science.ads0018
• チュートリアル： https://github.com/Biohub/esm/tree/main/cookbook/tutorials
• モデルの重み： Hugging Faceのbiohub組織

責任ある利用

ESMは、タンパク質工学、創薬、科学研究における有益な用途を目的に設計されています。Biohubは利用規定を公開し、リリース前にバイオセーフティ／バイオセキュリティのリスク評価を実施しています。新規タンパク質を設計する際は、その規定とResponsible Biodesign Framework（https://responsiblebiodesign.ai/）に従ってください。設計した配列は発注した時点で計算上の領域を離れるため、実験による検証の前に、バイオセーフティとデュアルユースへの影響を十分に検討してください。

AlterLab Academic Skillsスイートの一部です。