Evolla

Service notice

Online service discontinued.

For safety reasons, we no longer provide the Evolla online service.

You can continue using Evolla by downloading the model weights and running it locally.

Download. Run locally.

Evolla is built into Hugging Face Transformers. Choose a Transformers checkpoint below and follow the Python example to get started.

View the Transformers quickstart

Using the original project? Get the original-format weights and follow the repository guide. The example below uses the -hf checkpoints.

Collaboration & bulk usage

If you would like to collaborate or use Evolla in bulk, please contact either of us:

Use Evolla with Transformers

Latest stable release checked on 21 October 2026.

Transformers 5.20.2

Use EvollaProcessor to prepare protein inputs and chat messages, then EvollaForProteinText2Text to generate an answer. The example uses westlake-repl/Evolla-10B-DPO-hf; you can also select westlake-repl/Evolla-10B-hf.

1. Prepare your environment

Use Python 3.10 or newer and install PyTorch 2.6 or newer for your hardware. Then install the reviewed Transformers release and Accelerate:

Terminal
python -m pip install "transformers==5.20.2" accelerate

This is a 10B model: allow sufficient GPU / system memory. The example loads bfloat16 weights and is intended for a GPU that supports BF16. The first run downloads the checkpoint from Hugging Face.

2. Prepare a protein input

Download the example input JSON from the official Transformers integration test, or create your own JSON with aa_seq, foldseek, and question.

Aligned inputs. aa_seq is the amino-acid sequence; foldseek is its residue-aligned Foldseek 3Di string. Both must have the same length. Use # for masked, low-confidence structure positions.

Input limits. This example sets protein_max_length=1024 and text_max_length=512. These are tokenizer limits, including any special tokens; longer inputs are truncated by the processor.

3. Run the Python example

Save evolla_example.py and protein.example.json in the same directory. The script validates the input, generates a response, and prints only the new answer tokens.

Terminal
python evolla_example.py protein.example.json
View the complete Python example
evolla_example.pyDownload .py
"""Local Evolla example for Transformers 5.20.2.

Usage: python evolla_example.py protein.json
Input JSON keys: aa_seq, foldseek, question.
Requires PyTorch, Accelerate, model weights, and sufficient memory.
The bfloat16 configuration below is intended for a compatible GPU.
API references: https://huggingface.co/docs/transformers/model_doc/evolla
"""

import json
import sys
from pathlib import Path


def load_input(path):
    data = json.loads(Path(path).read_text(encoding="utf-8"))
    if not isinstance(data, dict):
        raise ValueError("Input must be a JSON object.")
    for key in ("aa_seq", "foldseek", "question"):
        if not isinstance(data.get(key), str) or not data[key].strip():
            raise ValueError(f"Provide a non-empty string for {key}.")
    aa_seq = data["aa_seq"].strip().upper()
    foldseek = data["foldseek"].strip().lower()
    if len(aa_seq) != len(foldseek):
        raise ValueError("aa_seq and foldseek must have the same length.")
    if not set(aa_seq) <= set("ACDEFGHIKLMNPQRSTVWY"):
        raise ValueError("Use the 20 standard amino acids in aa_seq, without gaps or placeholders.")
    if not set(foldseek) <= set("acdefghiklmnpqrstvwy#"):
        raise ValueError("Replace foldseek with an aligned Foldseek 3Di string (or # for masked positions).")
    return {"aa_seq": aa_seq, "foldseek": foldseek}, data["question"].strip()


def main(path):
    protein, question = load_input(path)

    import torch
    from transformers import EvollaForProteinText2Text, EvollaProcessor

    model_id = "westlake-repl/Evolla-10B-DPO-hf"
    # A directory containing a downloaded -hf checkpoint also works here.
    processor = EvollaProcessor.from_pretrained(model_id)
    model = EvollaForProteinText2Text.from_pretrained(
        model_id, device_map="auto", dtype=torch.bfloat16
    ).eval()

    messages = [[
        {"role": "system", "content": "You are an AI expert that can answer any questions about protein."},
        {"role": "user", "content": question},
    ]]
    inputs = processor(
        proteins=[protein],
        messages_list=messages,
        protein_max_length=1024,
        text_max_length=512,
        return_tensors="pt",
    ).to(model.device)

    with torch.inference_mode():
        output_ids = model.generate(
            **inputs, max_new_tokens=256, do_sample=False, use_cache=False
        )
    answer_ids = output_ids[:, inputs["input_ids"].shape[1]:]
    print(processor.batch_decode(answer_ids, skip_special_tokens=True)[0])


if __name__ == "__main__":
    if len(sys.argv) != 2:
        raise SystemExit("Usage: python evolla_example.py protein.json")
    main(sys.argv[1])

To use downloaded files, replace model_id in both loading calls with your local checkpoint directory and add local_files_only=True to each from_pretrained call. Download the complete -hf repository, including the processor and tokenizer files.

Official documentation & source

The example follows the processor and model APIs in the reviewed release. The input fixture comes from its integration test.