服务公告
线上服务已停止
出于安全考虑,我们已停止提供 Evolla 线上服务。
如需继续使用,您可以自行下载模型权重,在本地部署和使用。
03 / Transformers 快速入门
通过 Transformers 使用 Evolla
使用 EvollaProcessor 处理蛋白输入与对话,再通过 EvollaForProteinText2Text 生成回答。示例使用 westlake-repl/Evolla-10B-DPO-hf,也可改用 westlake-repl/Evolla-10B-hf。
1. 准备运行环境
使用 Python 3.10 或更新版本,并按硬件环境安装 PyTorch 2.6 或更新版本。然后安装本页核查的 Transformers 版本及 Accelerate:
python -m pip install "transformers==5.20.2" accelerate
这是一个 10B 参数模型,需要足够的显存或系统内存。示例以 bfloat16 加载权重,适用于支持 BF16 的 GPU。首次运行会从 Hugging Face 下载模型文件。
2. 准备蛋白输入
下载来自 Transformers 官方集成测试的示例输入 JSON,或者自行准备包含 aa_seq、foldseek 和 question 的 JSON 文件。
输入需要对齐。aa_seq 为氨基酸序列,foldseek 为逐残基对应的 Foldseek 3Di 结构序列,两者必须等长。低置信度、需要掩码的结构位置使用 #。
注意输入长度。示例设定 protein_max_length=1024、text_max_length=512;这些是包含特殊 token 在内的分词长度上限,超长输入会被处理器截断。
3. 运行 Python 示例
将 evolla_example.py 和 protein.example.json 保存到同一目录。脚本会验证输入、生成回答,并只输出新增的回答文本。
python evolla_example.py protein.example.json
查看完整 Python 示例
"""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])
使用已下载的本地文件时,将两处加载调用中的 model_id 改为本地模型目录,并分别为 from_pretrained 添加 local_files_only=True。请完整下载 -hf 仓库,包含处理器和分词器文件。
官方文档与源码
示例依据所核查版本的处理器和模型接口整理;输入数据来自该版本的官方集成测试。