Transformers documentation
Evolla
Эта модель была добавлена в Hugging Face Transformers 26.07.2025.
Evolla
Обзор
The Evolla model was proposed in Decoding the Molecular Language of Proteins with Evolla by Zhou et al..
Evolla — это продвинутая генеративная модель с 80 миллиардами параметров, предназначенная для декодирования молекулярного языка белков. Она интегрирует информацию из последовательностей, структур белков и запросов пользователя, чтобы генерировать точные и контекстуально выверенные выводы о функции белков. Обученная на беспрецедентном датасете, сгенерированном с помощью ИИ, содержащем 546 миллионов пар «вопрос-ответ» по белкам и 150 миллиардов токенов, Evolla существенно продвигает исследования в области протеомики и функциональной геномики, предоставляя экспертные знания и проливая свет на молекулярную логику, закодированную в белках.
Аннотация из статьи следующая:
Белки — сложные молекулярные машины природы, продукт миллиардов лет эволюции, — играют фундаментальную роль в поддержании жизни. Однако расшифровка их молекулярного языка, то есть понимание того, как последовательности и структуры белков кодируют и определяют биологические функции, остаётся одной из ключевых задач современной биологии. В данной работе мы представляем Evolla — генеративную модель языка белков масштаба 80 миллиардов параметров, разработанную для расшифровки молекулярного языка белков. Интегрируя информацию о последовательностях, структурах белков и запросах пользователя, Evolla генерирует точные и контекстуально выверенные выводы о функциях белков. Ключевое новшество Evolla заключается в её обучении на беспрецедентном датасете, сгенерированном с помощью ИИ: 546 миллионов пар «вопрос–ответ» о белках и 150 миллиардов токенов, созданных для отражения огромной сложности и функционального разнообразия белков. После предварительного обучения в 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) — Это количество ключевых и value-голов, используемых для реализации Grouped Query Attention. Еслиnum_key_value_heads=num_attention_heads, модель использует Multi Head Attention (MHA); еслиnum_key_value_heads=1— Multi Query Attention (MQA); в остальных случаях применяется GQA. При конвертации мультиголовного чекпоинта в GQA-чекпоинт каждая групповая ключевая и value-голова должна конструироваться путем усреднения (meanpooling) всех исходных голов в этой группе. Дополнительные подробности — в этой статье. Если значение не указано, по умолчанию используетсяnum_attention_heads. - hidden_act (
str, необязательный, по умолчаниюsilu) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - max_position_embeddings (
int, необязательный, по умолчанию8192) — Максимальная длина последовательности, с которой может использоваться эта модель. - rms_norm_eps (
float, необязательный, по умолчанию1e-05) — Значение epsilon, используемое слоями нормализации rms. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], необязательный) — Словарь, содержащий параметры конфигурации для эмбеддингов RoPE. Словарь должен содержать значение дляrope_thetaи, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длиннымиmax_position_embeddings. - attention_bias (
bool, необязательный, по умолчаниюFalse) — Использовать ли смещение (bias) в слоях проекции query, key, value и output при само-внимании. - attention_dropout (
Union[float, int], необязательный, по умолчанию0.0) — Коэффициент dropout для вероятностей внимания. - mlp_bias (
bool, необязательный, по умолчаниюFalse) — Использовать ли смещение (bias) в слоях up_proj, down_proj и gate_proj внутри MLP-слоёв. - aligner_ffn_mult (
int, необязательный, по умолчанию 4) — Множитель FFN для слоя aligner. - aligner_enable_bias (
bool, необязательный, по умолчаниюTrue) — Использовать ли смещение (bias) в слое aligner. - aligner_attention_probs_dropout_prob (
float, необязательный, по умолчанию 0.1) — Коэффициент dropout для вероятностей внимания в слое aligner. - aligner_num_add_layers (
int, необязательный, по умолчанию 8) — Количество дополнительных слоев для слоя aligner. - resampler_depth (
int, необязательный, по умолчанию 6) — Глубина слоя ресемплера в модели Llama. - resampler_dim_head (
int, необязательный, по умолчанию 64) — Размерность голов в слое resampler в модели Llama. - resampler_heads (
int, необязательный, по умолчанию 8) — Количество головок в слое resampler в модели Llama. - resampler_num_latents (
int, необязательный, по умолчанию 64) — Количество латентов в слое resampler в модели Llama. - resampler_ff_mult (
int, необязательный, по умолчанию 4) — Множитель FFN для слоя resampler. - initializer_range (
float, необязательный, по умолчанию0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов. - pad_token_id (
int, необязательный) — Идентификатор токена, используемого для выравнивания в словаре. - bos_token_id (
int, необязательный, по умолчанию128000) — Идентификатор токена, используемого для обозначения начала потока в словаре. - eos_token_id (
Union[int, list[int]], необязательный, по умолчанию128009) — Идентификатор токена, используемого для обозначения конца потока в словаре. - 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), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью 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. Если
past_key_valuesне переданы, по умолчанию будет инициализирован DynamicCache.Модель будет выводить тот же формат кэша, который был передан на вход.
Если используются
past_key_values, ожидается, что пользователь передаст только необработанныеinput_ids(те, для которых в этой модели ещё не заданы состояния прошлых ключей и значений) формы(batch_size, unprocessed_length), а не всеinput_idsформы(batch_size, sequence_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, необязательный) — Входные идентификаторы для чисто структурных признаков. Должен иметь форму(batch_size, structure_seq_length, structure_feat_dim)и типtorch.Tensor. Пока что это фиктивный вход. - msa_feats (
torch.Tensor, необязательный) — Входные идентификаторы для чисто MSA-основанных признаков. Должен иметь форму(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. Должна иметь форму(batch_size)и типtorch.Tensor. Должна использоваться в паре сmsa_feats. На данный момент является фиктивным входом.
Возвращает
BaseModelOutputWithPast или tuple(torch.Tensor)
BaseModelOutputWithPast или кортеж
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (None) и входных данных.
Метод forward класса EvollaModel переопределяет специальный метод __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.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и, при необходимости, если
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(один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(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), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью 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формы(batch_size, sequence_length), необязательный) — Метки для вычисления потерь маскированного языкового моделирования. Индексы должны находиться в диапазоне[0, ..., config.vocab_size]или быть равны -100 (см. docstringinput_ids). Токены с индексами, установленными в-100, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне[0, ..., config.vocab_size]. - protein_input_ids (
torch.LongTensor, необязательный) — Входные идентификаторы для последовательности белка. Должны иметь форму(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 для последнихlogits_to_keepтокенов. Если указано0, logits вычисляются для всехinput_ids(особый случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типаtorch.Tensor, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (один размер для batch и длины последовательности).
Метод forward класса EvollaForProteinText2Text переопределяет специальный метод __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
класс 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': возвращает объектыtorch.TensorPyTorch.'np': возвращает объекты NumPynp.ndarray.
Возвращает
словарь со следующими ключами
protein_input_ids(torch.Tensorформы(batch_size, sequence_length)) — Вводные идентификаторы для последовательности белка.protein_attention_mask(torch.Tensorформы(batch_size, sequence_length)) — Маска внимания для последовательности белка.text_input_ids(torch.Tensorформы(batch_size, sequence_length)) — Вводные идентификаторы для текстовой последовательности.text_attention_mask(torch.Tensorформы(batch_size, sequence_length)) — Маска внимания для текстовой последовательности.