Transformers documentation

Evolla

Transformers

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Este modelo foi contribuído para o Hugging Face Transformers em 26/07/2025.

Evolla

Visão geral

The Evolla model was proposed in Decoding the Molecular Language of Proteins with Evolla by Zhou et al..

Evolla é um modelo generativo avançado de linguagem proteica com 80 bilhões de parâmetros, projetado para decodificar a linguagem molecular das proteínas. Ele integra informações de sequências, estruturas e consultas do usuário para gerar insights precisos e contextualmente matizados sobre a função proteica. Treinado em um conjunto de dados gerado por IA sem precedentes, composto por 546 milhões de pares de perguntas e respostas sobre proteínas e 150 bilhões de tokens de palavras, o Evolla avança significativamente a pesquisa em proteômica e genômica funcional, fornecendo insights de nível especialista e esclarecendo a lógica molecular codificada nas proteínas.

O resumo do artigo é o seguinte:

As proteínas, as intrincadas máquinas moleculares da natureza, são o resultado de bilhões de anos de evolução e desempenham papéis fundamentais na manutenção da vida. No entanto, decifrar sua linguagem molecular — ou seja, compreender como as sequências e estruturas de proteínas codificam e determinam as funções biológicas — continua sendo um desafio fundamental na biologia moderna. Aqui, apresentamos o Evolla, um modelo generativo de linguagem de proteínas de fronteira com 80 bilhões de parâmetros, projetado para decodificar a linguagem molecular das proteínas. Ao integrar informações de sequências, estruturas e consultas do usuário, o Evolla gera insights precisos e contextualmente matizados sobre a função das proteínas. Uma inovação-chave do Evolla reside em seu treinamento em um conjunto de dados gerado por IA sem precedentes: 546 milhões de pares de perguntas e respostas sobre proteínas e 150 bilhões de tokens de palavras, projetados para refletir a imensa complexidade e diversidade funcional das proteínas. Após o pré-treinamento, o Evolla integra a Otimização de Preferência Direta (DPO) para refinar o modelo com base em sinais de preferência e a Geração Aumentada por Recuperação (RAG) para a incorporação de conhecimento externo, melhorando a qualidade e a relevância das respostas. Para avaliar seu desempenho, propomos um novo framework, o Instructional Response Space (IRS), demonstrando que o Evolla fornece insights de nível especialista, avançando a pesquisa em proteômica e genômica funcional, ao mesmo tempo que lança luz sobre a lógica molecular codificada nas proteínas. A demonstração online está disponível em http://www.chat-protein.com/.

Exemplos:

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
)

Dicas:

Este modelo foi contribuído por Xibin Bayes Zhou.
O código original pode ser encontrado aqui.

EvollaConfig

classe 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 )

Parâmetros

protein_encoder_config (dict, opcional) — Dicionário de opções de configuração usadas para inicializar SaProtConfig.
vocab_size (int, opcional, padrão 128256) — Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos input_ids.
hidden_size (int, opcional, padrão 4096) — Dimensão das representações ocultas.
intermediate_size (int, opcional, padrão 14336) — Dimensão das representações do MLP.
num_hidden_layers (int, opcional, padrão 32) — Número de camadas ocultas no decodificador do Transformer.
num_attention_heads (int, opcional, padrão 32) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
num_key_value_heads (int, opcional, padrão 8) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se num_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); se num_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de chave e valor deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão será num_attention_heads.
hidden_act (str, opcional, padrão silu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
max_position_embeddings (int, opcional, padrão 8192) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado.
rms_norm_eps (float, opcional, padrão 1e-05) — O epsilon usado pelas camadas de normalização rms.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.
attention_bias (bool, opcional, padrão False) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção.
attention_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
mlp_bias (bool, opcional, padrão False) — Se deve usar um viés nas camadas up_proj, down_proj e gate_proj das camadas MLP.
aligner_ffn_mult (int, opcional, padrão 4) — O multiplicador de FFN para a camada de alinhamento.
aligner_enable_bias (bool, opcional, padrão True) — Se deve usar viés na camada de alinhamento.
aligner_attention_probs_dropout_prob (float, opcional, padrão 0.1) — A taxa de dropout para as probabilidades de atenção na camada de alinhamento.
aligner_num_add_layers (int, opcional, padrão 8) — O número de camadas adicionais para a camada de alinhamento.
resampler_depth (int, opcional, padrão 6) — A profundidade da camada de resampler no modelo Llama.
resampler_dim_head (int, opcional, padrão 64) — A dimensão dos cabeçalhos na camada de resampler do modelo Llama.
resampler_heads (int, opcional, padrão 8) — O número de cabeças na camada de resampler no modelo Llama.
resampler_num_latents (int, opcional, padrão 64) — O número de latentes na camada de resampler no modelo Llama.
resampler_ff_mult (int, opcional, padrão 4) — O multiplicador do FFN para a camada de resampler.
initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
pad_token_id (int, opcional) — ID do token usado para preenchimento no vocabulário.
bos_token_id (int, opcional, padrão 128000) — ID do token usado para o início do fluxo no vocabulário.
eos_token_id (Union[int, list[int]], opcional, padrão 128009) — ID do token usado para o fim do fluxo no vocabulário.
use_cache (bool, opcional, padrão False) — Indica se o modelo deve ou não retornar as últimas chaves/valores de atenção (não utilizado por todos os modelos). Relevante apenas se config.is_decoder=True ou quando o modelo for um modelo generativo somente de decodificador.
tie_word_embeddings (bool, opcional, padrão False) — Se deve vincular as embeddings de pesos de acordo com o mapeamento tied_weights_keys do modelo.
is_decoder (bool, opcional, padrão False) — Indica se o modelo é usado como decodificador ou não. Se False, o modelo é usado como codificador.
add_cross_attention (bool, opcional, padrão False) — Se camadas de atenção cruzada devem ser adicionadas ao modelo.

Esta é a classe de configuração para armazenar a configuração de um EvollaModel. Ela é usada para instanciar um modelo Evolla de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do westlake-repl/Evolla-10B-hf

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> 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.config

EvollaModel

classe transformers.EvollaModel

< source >

( config: EvollaConfig )

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)

Parâmetros

input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.
Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

O que são IDs de entrada?
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
O que são máscaras de atenção?
position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo [0, config.n_positions - 1].
O que são IDs de posição?
past_key_values (~cache_utils.Cache, opcional) — Estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste no past_key_values retornado pelo modelo em uma etapa anterior da decodificação, quando use_cache=True ou config.use_cache=True.
Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum past_key_values for passado, DynamicCache será inicializado por padrão.

O modelo sairá no mesmo formato de cache que é fornecido como entrada.

Se past_key_values forem usados, espera-se que o usuário insira apenas os input_ids não processados (aqueles que não têm seus estados de chave e valor passados fornecidos a este modelo) com a forma (batch_size, unprocessed_length), em vez de todos os input_ids com a forma (batch_size, sequence_length).
inputs_embeds (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passar input_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de input_ids nos vetores associados do que a matriz de busca de incorporação interna do modelo.
use_cache (bool, opcional) — Se definido como True, os estados de chave-valor past_key_values são retornados e podem ser usados para acelerar a decodificação (veja past_key_values).
protein_input_ids (torch.LongTensor, opcional) — Os IDs de entrada para a sequência de proteína em tokens com consciência de estrutura. Deve ter a forma (batch_size, protein_seq_length) e o tipo torch.LongTensor.
protein_attention_mask (torch.Tensor, opcional) — A máscara de atenção para a sequência de proteína. Deve ter a forma (batch_size, protein_seq_length) e o tipo torch.Tensor.
structure_feats (torch.Tensor, opcional) — Os IDs de entrada para recursos baseados puramente em estrutura. Deve ter a forma (batch_size, structure_seq_length, structure_feat_dim) e o tipo torch.Tensor. Entrada fictícia por enquanto.
msa_feats (torch.Tensor, opcional) — Os IDs de entrada para recursos baseados puramente em MSA. Deve ter a forma (batch_size, msa_seq_length, msa_feat_dim) e o tipo torch.Tensor. Entrada fictícia por enquanto.
structure_batch_mask (torch.Tensor, opcional) — A máscara de lote para decidir quais sequências de proteína são puramente baseadas em estrutura. Deve ter a forma (batch_size) e o tipo torch.Tensor. Deve ser pareada com structure_feats. Entrada fictícia por enquanto.
msa_batch_mask (torch.Tensor, opcional) — A máscara de lote para decidir quais sequências de proteínas são puramente baseadas em MSA. Deve ter a forma (batch_size) e o tipo torch.Tensor. Deve ser pareada com msa_feats. Entrada fictícia por enquanto.

Retorna

BaseModelOutputWithPast ou tuple(torch.Tensor)

Um BaseModelOutputWithPast ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos dependendo da configuração (None) e das entradas.

O método forward do EvollaModel sobrescreve o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.

Se past_key_values for usado, apenas o último hidden-state das sequências, com forma (batch_size, 1, hidden_size), é retornado.
past_key_values (Cache, opcional, retornado quando use_cache=True é passado ou quando config.use_cache=True) — É uma instância de Cache. Para mais detalhes, consulte nosso guia de cache kv.

Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e, opcionalmente, se config.is_encoder_decoder=True, nos blocos de atenção cruzada) que podem ser usados (veja a entrada past_key_values) para acelerar a decodificação sequencial.
hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

EvollaForProteinText2Text

classe transformers.EvollaForProteinText2Text

< source >

( config: EvollaConfig )

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 )

Parâmetros

input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.
Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

O que são IDs de entrada?
attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
O que são máscaras de atenção?
inputs_embeds (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passar input_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de input_ids nos vetores associados do que a matriz de busca de incorporação interna do modelo.
labels (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Rótulos para o cálculo da perda de modelagem de linguagem mascarada. Os índices devem estar em [0, ..., config.vocab_size] ou ser -100 (veja a docstring de input_ids). Tokens com índices definidos como -100 são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em [0, ..., config.vocab_size].
protein_input_ids (torch.LongTensor, opcional) — Os IDs de entrada para a sequência de proteína. Deve ter a forma (batch_size, protein_seq_length) e o tipo torch.LongTensor.
protein_attention_mask (torch.Tensor, opcional) — A máscara de atenção para a sequência de proteína. Deve ter a forma (batch_size, protein_seq_length) e o tipo torch.Tensor.
use_cache (bool, opcional) — Se definido como True, os estados de chave-valor past_key_values são retornados e podem ser usados para acelerar a decodificação (veja past_key_values).
logits_to_keep (Union[int, torch.Tensor], opcional, padrão 0) — Se for um int, calcula os logits para os últimos logits_to_keep tokens. Se for 0, calcula os logits para todos os input_ids (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um torch.Tensor, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

O método forward de EvollaForProteinText2Text substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

Exemplo:

>>> 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

classe transformers.EvollaProcessor

< source >

( protein_tokenizertokenizer = Noneprotein_max_length = 1024text_max_length = 512**kwargs )

Parâmetros

protein_tokenizer (EsmTokenizer) — Uma instância de EsmTokenizer. O tokenizador de proteínas é uma entrada obrigatória.
tokenizer (tokenizer_class) — O tokenizer é uma entrada obrigatória.
protein_max_length (int, opcional, padrão 1024) — O comprimento máximo da sequência a ser gerada.
text_max_length (int, opcional, padrão 512) — O comprimento máximo do texto a ser gerado.

Constrói um EvollaProcessor que encapsula um tokenizador de proteínas e um tokenizador em um único processador.

EvollaProcessor oferece todas as funcionalidades de {protein_tokenizer_class} e tokenizer_class. Consulte ~{protein_tokenizer_class} e ~tokenizer_class para mais informações.

call

< source >

Parâmetros

proteins (Union[List[dict], dict]) — Uma lista de dicionários ou um único dicionário contendo as seguintes chaves:
- "aa_seq" (str) — A sequência de aminoácidos da proteína.
- "foldseek" (str) — A string foldseek da proteína.
messages_list (Union[List[List[dict]], List[dict]]) — Uma lista de listas de dicionários ou uma lista de dicionários contendo as seguintes chaves:
- "role" (str) — A função da mensagem.
- "content" (str) — O conteúdo da mensagem.
protein_max_length (int, opcional, padrão 1024) — O comprimento máximo da sequência a ser gerada.
text_max_length (int, opcional, padrão 512) — O comprimento máximo do texto.
return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
- 'pt': Retorna objetos torch.Tensor do PyTorch.
- 'np': Retorna objetos np.ndarray do NumPy.

Retorna

um dicionário com as seguintes chaves

protein_input_ids (torch.Tensor de forma (batch_size, sequence_length)) — Os IDs de entrada para a sequência de proteína.
protein_attention_mask (torch.Tensor de forma (batch_size, sequence_length)) — A máscara de atenção para a sequência de proteína.
text_input_ids (torch.Tensor de forma (batch_size, sequence_length)) — Os IDs de entrada para a sequência de texto.
text_attention_mask (torch.Tensor de forma (batch_size, sequence_length)) — A máscara de atenção para a sequência de texto.

Update on GitHub

←ernie4_5_vl_moe FastVLM→