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.
03 / Transformers quickstart
Use Evolla with Transformers
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:
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.
python evolla_example.py protein.example.json
View the complete Python example
"""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.