蛋白质模型平台 · API 调用说明

鉴权

所有 /api/* 请求都必须带 API Token，放在 Authorization 头里：

Authorization: Bearer <API_TOKEN>

Token 由平台管理员分配，请勿写入前端代码或公开仓库。缺失或错误会返回 401。

快速开始

四步完成一次预测：提交 → 轮询 → 列产物 → 下载。

BASE=https://ai4s.cypherpharma.cloud/api
TOKEN=<API_TOKEN>

# 1) 健康检查
curl -s $BASE/health -H "Authorization: Bearer $TOKEN"

# 2) 提交作业
curl -s -X POST $BASE/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "boltz",
    "input_text": "name: demo\nchains:\n  - id: A\n    type: protein\n    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG\n    copies: 1\nmsa: none\nseeds: [42]\nsamples: 1\nrecycles: 3\n",
    "params": {"samples": 1}
  }'
# → {"job_id":"f534c9a1...","status":"queued",...}

# 3) 轮询状态（queued → running → done）
curl -s $BASE/jobs/<JOB_ID> -H "Authorization: Bearer $TOKEN"

# 4) 列产物并下载
curl -s $BASE/jobs/<JOB_ID>/files -H "Authorization: Bearer $TOKEN"
curl -s -G $BASE/jobs/<JOB_ID>/file \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'path=results.json' -o results.json

接口一览

输入格式

预测类 5 个模型（boltz / protenix / chai1 / colabfold / openfold3）统一使用 YAML spec，通过 input_text 内联提交：

name: demo                 # 作业名，影响产物文件名
chains:
  - id: A
    type: protein          # protein | dna | rna
    sequence: MQIFVKTLT... # 单字母序列
    copies: 1
  - id: B
    type: protein
    sequence: GSHMK...
ligands:
  - id: L
    type: ligand
    smiles: "CC(=O)O"      # 或者 ccd: ATP
    copies: 1
msa: none                  # none | server | cached | /path/to/x.a3m
seeds: [42]
samples: 1
recycles: 3

7 个模型

boltz

{"model":"boltz","input_text":"name: ubq\nchains:\n  - id: A\n    type: protein\n    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG\n    copies: 1\nmsa: none\nseeds: [42]\nsamples: 1\nrecycles: 3\n"}

protenix

{"model":"protenix","input_text":"name: ubq\nchains:\n  - id: A\n    type: protein\n    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG\n    copies: 1\nmsa: none\nseeds: [42]\nsamples: 1\nrecycles: 10\n"}

chai1

{"model":"chai1","input_text":"name: ubq\nchains:\n  - id: A\n    type: protein\n    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG\n    copies: 1\nmsa: none\nseeds: [42]\nsamples: 1\nrecycles: 3\n"}

colabfold

{"model":"colabfold","input_text":"name: ubq\nchains:\n  - id: A\n    type: protein\n    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG\n    copies: 1\nmsa: none\nseeds: [42]\nsamples: 1\nrecycles: 3\n"}

openfold3

{"model":"openfold3","input_text":"name: ubq\nchains:\n  - id: A\n    type: protein\n    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG\n    copies: 1\nmsa: none\nseeds: [42]\nsamples: 1\nrecycles: 3\n"}

rfantibody

三阶段抗体设计。耗时数十分钟起，target_pdb 必须是服务器上已存在的路径（无上传接口）。

{"model":"rfantibody","input_text":"{\"target_pdb\":\"/home/xiaodong/models/targets/flu_HA.pdb\",\"num_designs\":2,\"design_loops\":\"H1:7,H2:6,H3:5-13\",\"hotspots\":\"B146,B170,B177\",\"diffuser_t\":15,\"num_seqs\":1,\"num_recycles\":3}"}

bindcraft2

内置靶点：dynorphin_a、hIL2R、hIL7RA、hPD1、hPDL1、mPDL1。

{"model":"bindcraft2","input_text":"{\"modality\":\"binder\",\"target\":\"hPDL1\",\"campaign_name\":\"pdl1_round1\",\"number_of_final_designs\":1,\"max_trajectories\":2,\"binder_lengths\":[60,80],\"validation_recycles\":3}"}

params 参数

提交时 params 是可选的，会覆盖 spec 里的同名字段：

提交后返回的 tokens 是折算残基数，est_vram_mb 是预估峰值显存；超过单卡 22000 MB 会直接 422。

结果产物

预测类作业的 result_dir 结构固定：

<job_id>/
├── _spec.yaml       实际执行的 spec
├── results.json     结构化分数与结构文件路径
├── report.html      人工查看用的汇总页
└── work/<cache_key>/  后端原生输出（.cif / .pdb / .npz）

results.json 里每个采样一项：

{"results":[
  {"id":"boltz_s42_m0","seed":42,"sample":0,
   "path":".../predictions/demo/demo_model_0.cif",
   "plddt":92.08,"ptm":0.910,"iptm":0.0,"ranking":0.919}
]}

设计类产物不同：RFantibody 输出 1_rfdiffusion.qv / 2_proteinmpnn.qv / 3_rf2.qv；BindCraft2 输出 3_Ranked/、summary.csv、campaign_metadata.json。

错误码

Python 示例

import time, requests

BASE = "https://ai4s.cypherpharma.cloud/api"
HEAD = {"Authorization": "Bearer <API_TOKEN>"}

spec = """name: demo
chains:
  - id: A
    type: protein
    sequence: MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTHRLVLRLRGG
msa: none
seeds: [42]
samples: 1
recycles: 3
"""

job = requests.post(BASE + "/jobs", headers=HEAD,
                    json={"model": "boltz", "input_text": spec}).json()
jid = job["job_id"]

while True:
    info = requests.get(f"{BASE}/jobs/{jid}", headers=HEAD).json()
    if info["status"] in ("done", "failed", "cancelled"):
        break
    time.sleep(5)

if info["status"] == "done":
    files = requests.get(f"{BASE}/jobs/{jid}/files", headers=HEAD).json()["files"]
    for f in files:
        if f["path"].endswith(".cif"):
            data = requests.get(f"{BASE}/jobs/{jid}/file", headers=HEAD,
                                params={"path": f["path"]}).content
            open("model.cif", "wb").write(data)

并发与约束

• 2 张 RTX 3090，每卡最多 2 个进程 → 最多 4 个预测作业并行，其余排队。
• 设计类固定预留 12 GB 显存，建议一次只跑一个。
• 预测类 tokens 上限：boltz/protenix/openfold3 1500，chai1 500，colabfold 2000。
• 作业结果保留在服务器磁盘上，请及时下载；磁盘余量有限。
• 网页版与 API 共用同一队列，作业按 priority 与提交时间排序。