Folding a protein
Fold a sequence into a structure file, with the weights pinned to a revision so every worker loads the same ones.
Introduction
A protein sequence goes in and a predicted structure comes out as PDB, on the same GPUs the models API runs on.
ESMFold is MIT licensed and its weights are ungated, so you deploy it with no token.
The app
"""Folding a protein: a sequence in, a predicted structure out.
ESMFold predicts a structure from a single sequence, with no multiple sequence
alignment and so no call out to an alignment server. The whole app is one model
and one forward pass.
"""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
from runware_serverless import serve
MODEL = "facebook/esmfold_v1"
REVISION = "75a3841ee059df2bf4d56688166c8fb459ddd97a"
"""Pinned, deliberately.
A moving reference is how you end up with weights the installed version cannot
load: the checkpoint drifts, the code does not, and the worker dies at startup
with a constructor it cannot satisfy. A revision costs nothing and removes that."""
CACHE = "/weights"
"""Mount a volume here. The model is about 2.6GB, which is a download worth doing
once rather than on every cold start."""
WARMUP = "MKTAYIAKQRQISFVKSHFSRQ"
"""Folded once in ``load`` so the weights arrive before any request does."""
MAX_RESIDUES = 400
"""Attention over the sequence grows with the square of its length. The schema
publishes the ceiling, and this app enforces it: the platform checks the types it
published but not a value constraint."""
CHUNK = 64
"""Trades speed for peak memory inside the folding trunk. Lower it if a long
sequence runs out of room."""
class Request(BaseModel):
model_config = ConfigDict(extra="forbid")
sequence: str = Field(
min_length=10,
max_length=MAX_RESIDUES,
pattern=r"^[ACDEFGHIKLMNPQRSTVWY]+$",
description="One protein chain, as standard single-letter amino acids.",
)
class Folded(BaseModel):
structure: str = Field(description="The predicted structure as PDB text.")
format: str
residues: int
confidence: dict[str, float] = Field(
description="Mean pLDDT for the structure, from 0 to 100. Above 70 is confident."
)
@serve
class ProteinFolding:
requirements = [
"torch==2.14.1",
"transformers==5.21.0",
"accelerate==1.15.0",
]
def load(self) -> None:
if hasattr(self, "model"):
return
# Here and not at the top of the file. The build imports this file with the
# platform's own dependencies, not yours, so nothing in requirements exists
# until a worker runs. A `with imports():` block at the top of the file does
# the same, and is what to use when a name has to be visible outside a method.
import torch
from transformers import AutoTokenizer, EsmForProteinFolding
self.torch = torch
self.tokenizer = AutoTokenizer.from_pretrained(
MODEL, revision=REVISION, cache_dir=CACHE
)
self.model = EsmForProteinFolding.from_pretrained(
MODEL, revision=REVISION, cache_dir=CACHE
)
self.model = self.model.cuda().eval()
self.model.trunk.set_chunk_size(CHUNK)
print(f"warming up: folding {len(WARMUP)} residues", flush=True)
self._fold(WARMUP)
print("warmup complete", flush=True)
def predict(self, request: Request) -> Folded:
structure, confidence = self._fold(request.sequence)
return Folded(
structure=structure,
format="pdb",
residues=len(request.sequence),
confidence=confidence,
)
def _fold(self, sequence: str) -> tuple[str, dict[str, float]]:
tokens = self.tokenizer(
[sequence], return_tensors="pt", add_special_tokens=False
)["input_ids"].cuda()
with self.torch.no_grad():
output = self.model(tokens)
# Measured: this model returns pLDDT on a 0 to 1 scale, while the
# literature and every structure viewer use 0 to 100. Scaled once here,
# and guarded so a version that already returns 0 to 100 is left alone.
plddt = float(output["plddt"].mean())
return self.model.output_to_pdb(output)[0], {
"mean_plddt": round(plddt * 100 if plddt <= 1.0 else plddt, 2)
}Deploying the app
runware serverless deploy --from https://runware.ai/docs/serverless/examples/protein-folding.ziprunware serverless deploy model.py \
--id protein-folding \
--gpu-type rtx-pro-6000 \
--volume /weightsThe weights are about 2.6GB and the first fold is what pulls them, so load does one on a short peptide. The volume keeps them off the checkpoint and out of the next cold start.
load prints what it is folding and when it is done. A worker that dies quietly during startup leaves a task pending with no error, and the logs are the only place a reason can appear.
Work outside the models API
The models API covers image, video, audio and text. A workload outside those four is what this path is for: you bring the weights, the platform brings the hardware.
Nothing in this file is unusual: a protein folding model is loaded, called and returned from exactly like an image model.
Pinning the weights
from_pretrained takes revision, and without it you are asking for whatever main holds today.
EsmForProteinFolding.from_pretrained(MODEL, revision=REVISION, cache_dir=CACHE)A moving reference is how you end up with weights the installed version cannot load. The failure does not arrive as a bad answer: it arrives as a worker that exits during startup, leaving a task pending with no error anywhere except the logs.
Choosing the transformers port
fair-esm[esmfold], the original package, pulls in OpenFold and wants nvcc to build kernels. A code worker has no toolchain at all, so that route cannot run here.
The transformers port dropped the OpenFold dependency, which is what lets this run as a code app rather than a container. When a scientific package offers both, check what the install builds before you choose.
No alignment server
ESMFold predicts from a single sequence. Folding tools that want a multiple sequence alignment reach out to an alignment server, and an app that calls a third party on every request depends on that third party staying up.
Sequence length limits
Attention over the sequence grows with the square of its length, so max_length is published and documents the limit.
It does not enforce it. The platform checks the types it published but not a value constraint, so an oversized sequence reaches the worker and is refused there, after something has already woken up. Enforcing it is the app's job.
Calling the app
Use invoke-async and poll. A fold is tens of seconds, not milliseconds.
import { createClient } from '@runware/sdk'
const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
const task = await client.invoke({
appId: 'protein-folding',
endpointPath: 'predict',
payload: {
request: {
sequence: 'MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE'
}
}
})import asyncio
import os
from runware import Runware
async def main():
client = Runware(api_key=os.environ["RUNWARE_API_KEY"])
try:
task = await client.invoke(
"protein-folding",
"predict",
{
"request": {
"sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
}
},
)
finally:
await client.close()
asyncio.run(main())curl https://api.serverless.runware.ai/v1/apps/protein-folding/invoke-async/predict \
-H "Authorization: Bearer $RUNWARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"payload": {
"request": {
"sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
}
}
}'cat <<'EOF' | runware serverless apps invoke protein-folding predict -f -
{
"request": {
"sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
}
}
EOF{
"taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"payload": {
"request": {
"sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
}
}
}The structure comes back as PDB text at output.predictions[0].structure. Save it to a .pdb file and any molecular viewer will open it.
confidence.mean_plddt runs from 0 to 100 and is the model's own estimate of how much to trust what it drew. Above 70 is confident, below 50 is close to a guess, so a caller can tell the two apart without reading coordinates.
What the run cost
| Call | Time |
| First call, empty volume: weights plus a warmup fold | 4m36s |
| A restart, weights already on the volume | 3m3s |
| A warm worker, 154 residues | 1.2s |
| A warm worker, 22 residues | 1.3s |
A restart still takes minutes. The volume saves the download, not the load: 2.6GB still has to reach the GPU and the warmup fold still runs. Keep --min-workers 1 if a cold caller cannot wait.
Length barely moves the warm number at these sizes, so the fold is mostly fixed cost until the sequence gets long enough for the quadratic term to show.