Transformers documentation
Evolla
このモデルは2025年7月26日にHugging Face Transformersに貢献されました。
Evolla
概要
The Evolla model was proposed in Decoding the Molecular Language of Proteins with Evolla by Zhou et al..
Evollaは、タンパク質の分子言語を解読するために設計された、高度な800億パラメータのタンパク質言語生成モデルです。タンパク質の配列、構造、およびユーザーのクエリからの情報を統合し、タンパク質の機能に関する正確で文脈に即した洞察を生成します。5億4,600万組のタンパク質に関する質問と回答のペア、および1,500億ワードトークンからなる前例のないAI生成データセットで学習されたEvollaは、プロテオミクスおよび機能ゲノミクスにおける研究を大幅に推進し、専門家レベルの洞察を提供するとともに、タンパク質にコード化された分子論理を明らかにします。
論文の抄録は以下の通りです。
タンパク質は、自然が作り出した複雑な分子機械であり、何十億年もの進化の産物として、生命の維持に不可欠な役割を果たしています。しかし、タンパク質の分子言語を解読する、すなわちタンパク質の配列と構造がどのように生物学的機能をエンコードし決定しているかを理解することは、現代生物学における依然として核心的な課題です。本稿では、タンパク質の分子言語を解読するために設計された、800億パラメータ規模のフロンティアタンパク質言語生成モデル Evolla を紹介します。Evolla は、タンパク質の配列、構造、およびユーザーのクエリからの情報を統合することで、タンパク質の機能に関する正確で文脈に即した洞察を生成します。Evolla の重要な革新点は、前例のない AI 生成データセットを用いて学習されていることにあります。このデータセットは、タンパク質の莫大な複雑さと機能的多様性を反映するように設計された、5億4,600万組のタンパク質に関する質問応対ペアと1,500億ワードトークンで構成されています。事前学習の後、Evolla は Direct Preference Optimization (DPO) を統合して好意シグナルに基づいてモデルを洗練させ、外部知識の取り込みには Retrieval-Augmented Generation (RAG) を用いることで、応答の品質と関連性を向上させています。その性能を評価するために、私たちは新しいフレームワークである Instructional Response Space (IRS) を提案し、Evolla が専門家レベルの洞察を提供することを示しました。これにより、プロテオミクスや機能ゲノミクスにおける研究が推進されるとともに、タンパク質にエンコードされた分子論理に光が当てられます。オンラインデモは http://www.chat-protein.com/ で利用可能です。
例:
processor = EvollaProcessor.from_pretrained("westlake-repl/Evolla-10B-DPO-hf")
model = EvollaForProteinText2Text.from_pretrained("westlake-repl/Evolla-10B-DPO-hf", device_map="auto")
# aa_seq should have same length as foldseek
protein_inputs = [
{
"aa_seq": "MATGGRRG...",
"foldseek": "###lqpfd...", # hashtag means the low-confidence foldseek tokens
},
{
"aa_seq": "MLPGLALL...",
"foldseek": "dfwwkwad...",
}
]
message_list = [
[
{
"role": "system",
"content": "You are an AI expert that can answer any questions about protein.",
},
{"role": "user", "content": "What is the function of this protein?"},
],
[
{
"role": "system",
"content": "You are an AI expert that can answer any questions about protein.",
},
{"role": "user", "content": "What is the function of this protein?"},
]
]
input_dict = processor(
protein_inputs, messages_list, return_tensors="pt", text_max_length=512, protein_max_length=1024
)
with torch.no_grad():
generated_ids = hf_model.generate(**input_dict)
generated_texts = processor.batch_decode(
generated_ids, skip_special_tokens=True
)ヒント:
- このモデルは、Xibin Bayes Zhou によって提供されました。
- 元のコードはこちらで確認できます。
EvollaConfig
クラス transformers.EvollaConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneprotein_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevocab_size: int = 128256hidden_size: int = 4096intermediate_size: int = 14336num_hidden_layers: int = 32num_attention_heads: int = 32num_key_value_heads: int | None = 8hidden_act: str = 'silu'max_position_embeddings: int = 8192rms_norm_eps: float = 1e-05rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int | None = 0.0mlp_bias: bool = Falsealigner_ffn_mult: int | None = 4aligner_enable_bias: bool | None = Truealigner_attention_probs_dropout_prob: float | None = 0.1aligner_num_add_layers: int | None = 8resampler_depth: int | None = 6resampler_dim_head: int | None = 64resampler_heads: int | None = 8resampler_num_latents: int | None = 64resampler_ff_mult: int | None = 4initializer_range: float = 0.02pad_token_id: int | None = Nonebos_token_id: int | None = 128000eos_token_id: int | list[int] | None = 128009use_cache: bool = Falsetie_word_embeddings: bool = Falseis_decoder: bool | None = Falseadd_cross_attention: bool | None = False )
パラメータ
- protein_encoder_config (
dict、任意) —SaProtConfigを初期化するために使用される設定オプションの辞書。 - vocab_size (
int、任意、デフォルトは128256) — モデルの語彙サイズです。input_idsで表現できるトークンの種類数を定義します。 - hidden_size (
int、任意、デフォルトは4096) — 隠れ表現の次元数。 - intermediate_size (
int、任意、デフォルトは14336) — MLP 表現の次元数。 - num_hidden_layers (
int、任意、デフォルトは32) — Transformer デコーダーの隠れ層の数。 - num_attention_heads (
int、任意、デフォルトは32) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。 - num_key_value_heads (
int、任意、デフォルトは8) — Grouped Query Attention の実装に使用する key_value ヘッドの数を指定します。num_key_value_heads=num_attention_headsの場合、モデルは Multi Head Attention (MHA) を使用し、num_key_value_heads=1の場合は Multi Query Attention (MQA) を使用し、それ以外の場合は GQA が使用されます。 マルチヘッドのチェックポイントを GQA のチェックポイントに変換する際は、各グループの key ヘッドと value ヘッドを、そのグループ内の元のすべてのヘッドの平均プーリングによって構築する必要があります。詳細については、この論文を参照してください。指定しない場合、デフォルトでnum_attention_headsが使用されます。 - hidden_act (
str、任意、デフォルトはsilu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、"relu"、"silu"など。 - max_position_embeddings (
int、任意、デフォルトは8192) — このモデルが使用される可能性のある最大シーケンス長です。 - rms_norm_eps (
float、任意、デフォルト値は1e-05) — RMS正規化レイヤーで使用するepsilonです。 - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], 省略可) — RoPE 埋め込みの設定パラメータを含む辞書です。この辞書にはrope_thetaの値が含まれており、より長いmax_position_embeddingsで RoPE を使用する場合にスケーリングに使用されるパラメータが任意で含まれます。 - attention_bias (
bool、任意、デフォルトはFalse) — 自己注意機構において、クエリ、キー、バリュー、出力の投影層にバイアスを使用するかどうかを指定します。 - attention_dropout (
Union[float, int]、任意、デフォルトは0.0) — アテンション確率のドロップアウト率です。 - mlp_bias (
bool、任意、デフォルトはFalse) — MLP層のup_proj、down_proj、gate_proj層でバイアスを使用するかどうかを指定します。 - aligner_ffn_mult (
int、任意、デフォルト値は 4) — アライナー層の FFN 倍率です。 - aligner_enable_bias (
bool、任意、デフォルトはTrue) — aligner レイヤーでバイアスを使用するかどうか。 - aligner_attention_probs_dropout_prob (
float、任意、デフォルト値は 0.1)— aligner レイヤーにおけるアテンション確率の dropout 率です。 - aligner_num_add_layers (
int、任意、デフォルト値は 8)— aligner レイヤーに追加するレイヤーの数。 - resampler_depth (
int、任意、デフォルトは 6)— Llama モデルにおける resampler レイヤーの深さです。 - resampler_dim_head (
int、任意、デフォルト値は 64)— Llama モデルの resampler レイヤーにおけるヘッドの次元数です。 - resampler_heads (
int、任意、デフォルトは 8) — Llama モデルの resampler レイヤーにおけるヘッド数です。 - resampler_num_latents (
int、省略可、デフォルトは 64)— Llama モデルの resampler レイヤーにおける latents の数。 - resampler_ff_mult (
int、任意、デフォルト値は 4)— resampler レイヤーの FFN 倍率です。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - pad_token_id (
int, 任意) — 語彙内でパディングに使用されるトークン ID。 - bos_token_id (
int、任意、デフォルトは128000) — 語彙におけるストリーム開始に使用されるトークン ID。 - eos_token_id (
Union[int, list[int]]、任意、デフォルトは128009) — 語彙におけるストリーム終了に使用されるトークン ID。 - use_cache (
bool、任意、デフォルトはFalse) — モデルが最後のキー/バリューの注意を返すかどうか（すべてのモデルで利用されるわけではありません）。config.is_decoder=Trueの場合、またはモデルがデコーダー専用の生成モデルである場合にのみ関連します。 - tie_word_embeddings (
bool、任意、デフォルトはFalse) — モデルのtied_weights_keysマッピングに従って重み埋め込みを共有するかどうかを指定します。 - is_decoder (
bool、任意、デフォルトはFalse) — モデルがデコーダーとして使用されるかどうかを示します。Falseの場合、モデルはエンコーダーとして使用されます。 - add_cross_attention (
bool、任意、デフォルトはFalse) — モデルにクロスアテンション層を追加するかどうか。
これは EvollaModel の設定を保存するための設定クラスです。指定された引数に基づいて Evolla モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、westlake-repl/Evolla-10B-hf と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import EvollaModel, EvollaConfig
>>> # Initializing a Evolla evolla-10b style configuration
>>> configuration = EvollaConfig()
>>> # Initializing a model from the evolla-10b style configuration
>>> model = EvollaModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configEvollaModel
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Noneprotein_input_ids: typing.Optional[torch.LongTensor] = Noneprotein_attention_mask: typing.Optional[torch.Tensor] = Nonestructure_feats: typing.Optional[torch.Tensor] = Nonemsa_feats: typing.Optional[torch.Tensor] = Nonestructure_batch_mask: typing.Optional[torch.Tensor] = Nonemsa_batch_mask: typing.Optional[torch.Tensor] = None**kwargs ) → BaseModelOutputWithPast or tuple(torch.Tensor)
パラメータ
- input_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- attention_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- position_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、任意) — 各入力シーケンスのトークンが位置埋め込み内で占める位置のインデックス。範囲[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, 省略可) — 逐次デコードを高速化するために使用できる、事前計算された隠れ状態(自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー)。通常、これはデコードの以前の段階でモデルが返したpast_key_valuesであり、use_cache=Trueまたはconfig.use_cache=True.入力として許可されるのは Cache インスタンスのみです。kv cache ガイドを参照してください。
past_key_valuesが渡されない場合、デフォルトで DynamicCache が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。
past_key_valuesを使用する場合、すべてのinput_ids（形状(batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理のinput_ids（形状(batch_size, unprocessed_length)）のみを入力することになります。 - inputs_embeds (
torch.Tensor、形状(batch_size, sequence_length, hidden_size)、任意) —input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - use_cache (
bool、任意) —Trueに設定すると、past_key_valuesのキーバリュー状態が返され、デコーディングの高速化に利用できます（past_key_valuesを参照）。 - protein_input_ids (
torch.LongTensor, 任意) — 構造認識トークンによるタンパク質配列の入力 ID です。形状は(batch_size, protein_seq_length)、型はtorch.LongTensorである必要があります。 - protein_attention_mask (
torch.Tensor, 任意) — タンパク質シーケンス用のアテンションマスクです。形状は(batch_size, protein_seq_length)、型はtorch.Tensorである必要があります。 - structure_feats (
torch.Tensor, 任意) — 純粋に構造ベースの特徴量用の入力 ID です。形状は(batch_size, structure_seq_length, structure_feat_dim)、型はtorch.Tensorである必要があります。現在はダミー入力です。 - msa_feats (
torch.Tensor, 任意) — 純粋に MSA ベースの機能のための入力 ID です。形状は(batch_size, msa_seq_length, msa_feat_dim)、型はtorch.Tensorである必要があります。現在はダミー入力です。 - structure_batch_mask (
torch.Tensor, 任意) — タンパク質配列が純粋に構造ベースであるかを決定するためのバッチマスクです。形状は(batch_size)、型はtorch.Tensorである必要があります。structure_featsとペアで使用する必要があります。現時点ではダミー入力です。 - msa_batch_mask (
torch.Tensor、任意) — 純粋に MSA ベースのプロtein シーケンスを判定するためのバッチマスクです。形状は(batch_size)、型はtorch.Tensorである必要があります。msa_featsと対で使用する必要があります。現時点ではダミー入力です。
戻り値
BaseModelOutputWithPast または tuple(torch.Tensor)
None や入力に応じて、さまざまな要素で構成される BaseModelOutputWithPast または torch.Tensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）。
EvollaModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
last_hidden_state (
torch.Tensor、形状(batch_size, sequence_length, hidden_size)) — モデルの最終層の出力における隠れ状態のシーケンス。past_key_valuesが使用されている場合、出力されるのは、形状(batch_size, 1, hidden_size)のシーケンスの最後の隠れ状態のみです。past_key_values (
Cache、任意、use_cache=Trueが渡された場合またはconfig.use_cache=Trueの場合に返されます) — Cache のインスタンスです。詳細については、kv cache ガイドを参照してください。自己アテンションブロック（および
config.is_encoder_decoder=Trueの場合、クロスカレンションブロック）の事前計算済みヒドゥンステート（キーとバリュー）を保持します。これらは逐次デコーディングを高速化するために使用できます（past_key_values入力参照）。hidden_states (
tuple(torch.Tensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます) —torch.Tensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.Tensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます) —torch.Tensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。アテンションのsoftmax後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。
EvollaForProteinText2Text
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneprotein_input_ids: typing.Optional[torch.LongTensor] = Noneprotein_attention_mask: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs )
パラメータ
- input_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスはAutoTokenizerを使用して取得できます。詳細については、PreTrainedTokenizer.encode()およびPreTrainedTokenizer.call()を参照してください。
- attention_mask (
torch.Tensorの形状(batch_size, sequence_length), 、任意) — パディングトークンのインデックスに対するアテンションを回避するためのマスク。[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
- inputs_embeds (
torch.Tensor、形状(batch_size, sequence_length, hidden_size)、任意) —input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - labels (
torch.LongTensor、shape(batch_size, sequence_length)、任意) — マスク言語モデリング損失を計算するためのラベルです。インデックスは[0, ..., config.vocab_size]の範囲内であるか、-100 である必要があります（input_idsの docstring を参照）。インデックスが-100に設定されたトークンは無視（マスク）され、損失は[0, ..., config.vocab_size]の範囲内のラベルを持つトークンに対してのみ計算されます。 - protein_input_ids (
torch.LongTensor、任意) — タンパク質配列の入力 ID です。形状は(batch_size, protein_seq_length)、型はtorch.LongTensorである必要があります。 - protein_attention_mask (
torch.Tensor, 任意) — タンパク質シーケンス用のアテンションマスクです。形状は(batch_size, protein_seq_length)、型はtorch.Tensorである必要があります。 - use_cache (
bool、任意) —Trueに設定すると、past_key_valuesのキーバリュー状態が返され、デコーディングの高速化に利用できます（past_key_valuesを参照）。 - logits_to_keep (
Union[int, torch.Tensor]、省略可、デフォルトは0) —intの場合、最後のlogits_to_keepトークンについて logits を計算します。0の場合、すべてのinput_idsについて logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。torch.Tensorの場合、シーケンス長次元で保持するインデックスに対応する 1 次元テンソルである必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめた形式）を使用する場合に有用です。
EvollaForProteinText2Text の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
例:
>>> from transformers import EvollaProcessor, EvollaForProteinText2Text
>>> model = EvollaForProteinText2Text.from_pretrained("westlake/Evolla-10B-hf")
>>> processor = EvollaProcessor.from_pretrained("westlake/Evolla-10B-hf")
>>> protein_information = {
"aa_seq": "your amino acid sequence",
"foldseek": "your foldseek sequence",
}
>>> question = "What is the function of this protein?"
>>> message = [
{"role": "system", "content": "You are an AI expert that can answer any questions about protein."},
{"role": "user", "content": question},
]
>>> inputs = processor(proteins=[protein_information], messages_list=[message], return_tensors="pt", padding="longest")
>>> outputs = model.generate(**inputs)
>>> print(processor.batch_decode(outputs, skip_special_tokens=True))EvollaProcessor
class transformers.EvollaProcessor
< source >( protein_tokenizertokenizer = Noneprotein_max_length = 1024text_max_length = 512**kwargs )
パラメータ
- protein_tokenizer (
EsmTokenizer) — EsmTokenizer のインスタンスです。タンパク質のトークナイザーは必須の入力です。 - tokenizer (
tokenizer_class) — トークナイザーは必須の入力です。 - protein_max_length (
int、任意、デフォルトは 1024) — 生成されるシーケンスの最大長です。 - text_max_length (
int、任意、デフォルト値は 512) — 生成対象のテキストの最大長です。
タンパク質トークナイザーとトークナイザーを単一のプロセッサーにラップするEvollaProcessorを構築します。
EvollaProcessor は、{protein_tokenizer_class} と tokenizer_class のすべての機能を提供します。詳細については、~{protein_tokenizer_class} および ~tokenizer_class を参照してください。
__call__
< source >( proteins: list[dict] | dict | None = Nonemessages_list: list[list[dict]] | list[dict] | None = Noneprotein_max_length: int | None = Nonetext_max_length: int | None = None**kwargs ) → a dict with following keys
パラメータ
- proteins (
Union[List[dict], dict]) — 以下のキーを含む辞書のリスト、または単一の辞書:"aa_seq"(str) — タンパク質のアミノ酸配列。"foldseek"(str) — 蛋白质的foldseek文字列。
- messages_list (
Union[List[List[dict]], List[dict]]) — 以下のキーを含む辞書のリストのリスト、または辞書のリスト:"role"(str) — メッセージの役割。"content"(str) — メッセージの内容。
- protein_max_length (
int、任意、デフォルトは 1024) — 生成されるシーケンスの最大長です。 - text_max_length (
int、任意、デフォルトは 512) — テキストの最大長です。 - return_tensors (
strまたは TensorType, 省略可) — 設定すると、特定のフレームワークのテンソルを返します。使用可能な値は以下の通りです:'pt': PyTorchのtorch.Tensorオブジェクトを返します。'np': NumPyのnp.ndarrayオブジェクトを返します。
戻り値
以下のキーを持つ dict
protein_input_ids(torch.Tensor、shape(batch_size, sequence_length)) — 蛋白质シーケンスの入力IDです。protein_attention_mask(torch.Tensor、shape(batch_size, sequence_length)) — プロテインシーケンス用のアテンションマスクです。text_input_ids(torch.Tensor、shape(batch_size, sequence_length)) — テキストシーケンスの入力 ID。text_attention_mask(torch.Tensor、shape(batch_size, sequence_length)) — テキストシーケンス用のアテンションマスクです。