部署结论与适用范围

受体口袋条件下的环肽序列—结构联合生成基线

CP-Composer 先在受体结合口袋条件下，用潜空间扩散模型联合生成肽序列与三维构象；随后由 OpenMM 显式建立环化共价键并进行局部能量最小化。本机已完成官方 checkpoint 对应基线部署， 一键运行器当前聚焦并验证了 Condition 2：头尾成环。

GPU inference 已验证 OpenMM 成环已验证 PyMOL 加载已验证 官方模型源码未修改 当前一键入口仅支持头尾成环
生成模型
5.52 M
checkpoint 中共 5,521,661 个参数
反向扩散
100 步
序列潜变量与坐标潜变量同步去噪
潜表示
8 + 3D
每残基 8 维序列潜变量 + 1 个三维潜坐标
已验证终端键长
1.344 Å
1bjr demo 最小化后的首尾 C—N 距离
报告日期：2026-08-27 基线提交：6263670d7b04b383e6427e096ea3a878d48248f7 验证类型：单样本工程基线验证，不是性能基准测试
快速使用

一条命令生成头尾环肽

输入不是单独的一条肽序列，而是蛋白质–肽复合物 PDB。输入中的肽链提供生成长度和结合区域， 受体链提供口袋条件；模型重新生成肽的序列与坐标。

1. 基本命令

cd /home/luohaoxuan/work
bash run_cpcomposer.sh /absolute/path/input.pdb

2. 建议的多候选运行

CPC_SAMPLES=10 CPC_GUIDANCE=3 \
bash run_cpcomposer.sh /absolute/path/input.pdb

CPC_SAMPLES 控制随机起点数量。候选越多，越容易找到解码后首尾 N—C 距离较短的结构； CPC_GUIDANCE 默认是 3，盲目增大可能强化闭环倾向，也可能损害局部结构质量。

3. 明确指定链

CPC_RECEPTOR_CHAIN=E CPC_PEPTIDE_CHAIN=I \
bash run_cpcomposer.sh /absolute/path/input.pdb

未指定时，运行器默认把最短的标准蛋白链当作肽，把其余候选中最长链当作受体。 多亚基体系或链长度接近时，应显式指定。

4. 输出目录

cpcomposer_outputs/
└── 样本名_时间戳/
    ├── dataset/                 # 口袋裁剪与 mmap 数据
    ├── generated/
    │   ├── references/         # 参考复合物
    │   ├── candidates/         # 线性候选 PDB
    │   └── results.jsonl       # 序列、路径、pmetric
    ├── inference.yaml          # 本次运行参数
    └── cyclic/
        └── 样本名_head_tail.pdb # 最终闭环 PDB
输入规范

模型从输入 PDB 继承什么，不继承什么

输入必须满足

  • 至少两条包含 3 个以上标准氨基酸的蛋白链；
  • 肽链与受体存在至少一处小于 6 Å 的原子接触；
  • 关键主链原子 N、CA、C、O 基本完整；
  • 第一模型中链 ID 唯一且可被 Biopython 解析；
  • 当前 baseline 主要面向标准 20 种氨基酸。

生成时的继承关系

信息是否继承用途
受体完整结构保留提供固定结合口袋环境
输入肽长度保留决定生成节点数量
输入肽序列Condition 2 不作为答案提示数据集中会编码，但实际条件分支清零
输入肽坐标推理初始化时清除仅用于确定口袋和初始数据组织
肽链 ID保留用于保存、闭环和验证
本模型不是“输入任意氨基酸序列并直接折叠”，也不是自由生成任意长度环肽。当前一键流程需要一个已有的 受体–肽复合物框架，生成长度由输入肽链决定。
端到端流程

从复合物 PDB 到真正共价闭环

受体–肽 PDB 受体固定；肽提供长度与位置 口袋与张量 10 Å Cβ 口袋 X [N,14,3] · S [N] · mask 潜空间初始化 H：每残基 8 维 Z：每残基 1 × 3D 100 步反向扩散 AMEGNN + 口袋图 head–tail 3.8 Å 特殊边 全原子解码 20 AA argmax 主链 + 侧链坐标 几何候选筛选 解码后末端 N—C < 5 Å 多候选中取端点最近者 显式建立共价键 删除 H2/H3 与 OXT 添加末端 C—N topology bond OpenMM 最小化 CHARMM36 + 重原子约束 局部修复键长与碰撞 闭环 PDB
神经网络负责“可闭环的序列与构象”，OpenMM 负责把几何倾向变成真正的化学拓扑。
预处理与表示

从残基档案到模型张量

01解析链读取第一个 PDB model；过滤氢、水和常见溶剂，MSE 映射为 MET。
02检查接触必须存在至少一个受体–肽原子对距离小于 6 Å，否则样本不进入推理。
03裁剪口袋保留距肽 Cβ 小于 10 Å 的受体残基；缺 Cβ 时由 N、CA、C 构造虚拟 Cβ。
04建立张量每残基最多 14 个原子通道，生成区 mask=True，受体区 mask=False。
张量形状含义
X[N, 14, 3]N/CA/C/O 与侧链原子坐标；缺失或 padding 由 atom_mask 屏蔽
S[N]氨基酸或 LAT/PAD/MASK/UNK 特殊 token
mask[N]False=固定受体，True=待生成肽
position_ids[N]肽链顺序与受体原始位置索引
atom_mask[N, 14]标记每个原子通道是否真实存在
L[batch, 3, 3]受体 Cα 协方差的 Cholesky 因子，用于坐标白化和还原
X′ = L−1(X − μ)    ｜    X = LX′ + μ

白化把不同位置、朝向和空间尺度的口袋转换到较统一的坐标系；扩散结束后再恢复到输入 PDB 坐标系。

潜空间与扩散

为什么不直接生成 14 个原子的完整残基

冻结的全原子自编码器

预训练 AutoEncoder 使用 AMEGNN，将待生成肽压缩成两类潜变量： H 是每残基 8 维的序列/化学特征，Z 是每残基一个三维潜坐标。 推理时自编码器冻结，扩散模型只在这个低维空间中生成。

完整残基 (最多 14 × 3D) → H ∈ R8 + Z ∈ R1×3

这样可以降低维度、减少原子级噪声，并让序列与结构在同一个潜空间内联合更新。扩散完成后， 解码器再把 H、Z 还原为 20 种标准氨基酸及其主链、侧链原子。

推理初始化

  1. 把肽的 S 替换为 LAT token；
  2. 将肽的 8 维 H 清零，防止原序列泄漏；
  3. 将肽坐标清零，只启用一个潜坐标通道；
  4. 保留受体 H、X 作为固定上下文；
  5. 用标准高斯噪声替换肽的 H 和 Z。
受体像固定模具；肽只保留“有多少个位置”和“第几个位置”的空架子，再从随机噪声开始生成。

100 步反向扩散

pt−1 = 1/√αt · [pt − (1−αt)/√(1−ᾱt) · ε̂t] + σtz

其中 p 分别代表 H 和 Z。模型不是一步输出最终肽，而是在每个时间步预测当前潜变量中的噪声； t>1 时保留少量随机性，最后一步不再加新噪声。受体参与消息传递但通过 mask 保持固定。

t=100近似随机噪声 t≈75形成整体位置 t≈50协调口袋与肽内关系 t≈20潜变量逐渐收敛 t=0可解码潜表示 阶段描述是帮助理解的近似，不是代码中的硬分段
图网络原理

残基图、32 维 RBF 与 AMEGNN

节点

一个残基是一个图节点；最多 14 个原子作为节点内部坐标通道。

兼顾残基级计算效率与全原子几何信息。

边

同一样本内建立 N² 条有向边，分为同区域 context 和受体–肽 interaction。

边是通信线路，不代表化学键。

更新

边消息同时更新节点隐藏特征和相对方向上的坐标位移。

距离旋转不变，相对向量随整体旋转同步变化，保持 E(n) 等变。

为什么距离要转换成 32 维 RBF

分子相互作用随距离高度非线性：1 Å 可能是严重重叠，3–5 Å 可能是有效接触，远距离影响逐渐减弱。 单个距离数字要求 MLP 自己学习复杂曲线；32 个重叠 Gaussian 则像 32 个“软距离探测器”，分别对不同区间敏感。

φk(d) = exp[−c(d/rc − μk)²],   k = 1…32

示意：一个距离会同时激活附近多个 RBF 通道，因此 3.49 Å 与 3.51 Å 的编码平滑相近，不会像硬分箱那样突然跳变。 普通边使用 32 维、7 Å 缩放尺度；约束边使用 32 维、20 Å 缩放尺度。

AMEGNN 的一次消息传递

mij = MLP(hi, hj, rij, eij)
h′i = hi + MLP(hi, Σjmij)
x′i = xi + meanj[(xi−x̄j) · g(mij)]

序列潜变量 H 会影响坐标更新，当前坐标和距离又会影响 H 的更新，因此模型不是先选序列再摆结构， 而是在 100 个时间步中联合协调两者。

约束组合

官方四类条件与当前验证范围

Condition设计类型代码中的主要几何/残基条件本机状态
1Stapled peptide选择相隔 3 或 4 位的 K–D/E，代表距离约 4.5 Å源码存在，未纳入一键验证
2Head-to-tail首尾节点建立双向特殊边，目标代表距离 3.8 Å已完成端到端验证
3Disulfide选定 Cys 对并施加约 3.8 Å 的代表距离条件源码存在，需对应二硫键 relaxer
4Bicyclei、i+6、i+12 三个位点为 Cys，组合距离约 8 Å源码存在，需 bicycle linker 流程

Condition 2 的 guidance

每个时间步运行一次带首尾特殊边的预测 εcond，再运行一次不带特殊边的预测 εuncond。 本机设置 w=3：

ε̂ = (1+w)εcond − wεuncond = 4εcond − 3εuncond

这会放大首尾约束造成的去噪方向变化，但它仍是软条件；最终解码后的真正末端 N—C 距离需要筛选， 再交给 OpenMM 建立正常约 1.3–1.4 Å 的共价键。

文本 prompt 现状：数据集会用 SciBERT 计算 768 维文本 embedding，但 checkpoint 对应的实际 EpsilonNet 使用普通 AMEGNN，传入 prompt 的激活路径被注释。因此当前结果主要由口袋图、RBF 距离和显式几何边驱动， 不应把该 baseline 当作成熟的自由文本控制模型。
解码与化学闭环

从潜表示到可用 PDB 的两阶段边界

神经网络阶段

  1. 取最终肽潜变量 H [L,8] 与 Z [L,1,3]；
  2. 序列解码器输出 20 AA + UNK 的 logits；
  3. 屏蔽 UNK 后逐位 argmax，得到标准氨基酸序列；
  4. 根据残基类型确定原子清单；
  5. 全原子 AMEGNN 展开主链和侧链坐标；
  6. 写出“几何上适合闭环、拓扑仍线性”的候选 PDB。

OpenMM 阶段

  1. PDBFixer 补充缺失原子和氢；
  2. 删除第一个残基的 H2/H3；
  3. 删除最后一个残基的 OXT；
  4. 添加末端 C—N topology bond 与 CONECT；
  5. CHARMM36 + 自定义残基模板建系；
  6. 在重原子位置约束下局部能量最小化。
扩散模型本身不创建共价键。把生成候选直接称为“已成环结构”是不准确的；只有 OpenMM 识别到末端 topology bond， 且最小化后键长合理，才进入最终闭环输出。

pmetric 的正确解释

代码计算的是序列解码器对自身 argmax 类别的平均交叉熵，数值越小表示解码器越确信；它没有取指数， 不是严格 perplexity，更不是结合亲和力、自由能或实验活性评分。

验证样例

1bjr 官方 LNR 样本的端到端结果

受体 / 肽
279 / 10 aa
链 E / 链 I
模型实际节点
83
73 个口袋残基 + 10 个肽残基
OpenMM 前端点
4.438 Å
满足官方 Condition 2 的 <5 Å 筛选
OpenMM 后键长
1.344 Å
进入 1.1–1.6 Å 验证范围
项目结果解释
参考肽序列VAQGGAAGLA输入复合物中的原始链 I
生成肽序列AVVHKSYGLH10 位序列—结构联合生成结果
pmetric0.004066序列解码置信指标，不是亲和力
OpenMM 能量32,854,018.042 → −3,246.541 kcal/mol初始值包含严重拉伸的新建键；绝对值不可当结合自由能
最终 topology4,121 atoms / 4,165 bondsOpenMM 重新解析后的完整复合物
末端共价键已识别OpenMM topology 中存在第一个 N—最后一个 C bond
PyMOLPASS无界面模式成功加载最终 PDB
该结果证明本机 baseline 的“预处理 → GPU 生成 → 候选写出 → CPU OpenMM 成环 → 拓扑/键长/PyMOL 验证”链路可运行。 它是单样本工程验证，不代表模型整体成功率或药物发现性能。
部署环境

经过兼容性调整的实际运行栈

组件本机版本部署说明
操作系统Ubuntu 24.04.4 LTS / Linux 7.0.0-28x86_64
GPUNVIDIA GeForce RTX 4070 Laptop GPU，8 GB驱动 595.84
Python3.9.25conda 环境名 CPComposer
PyTorch2.0.1 + CUDA 11.8 buildtorch.cuda.is_available() = True
PyG 关键扩展torch-scatter 2.1.1+pt20cu118与 PyTorch/CUDA ABI 匹配
OpenMM8.1.1神经网络用 GPU；本机 relaxer 使用 CPU 平台
RDKit2023.09.6环境中可用
SciBERTallenai/scibert_scivocab_uncased 本地资产运行层重定向作者机器硬编码路径
官方 README 与 env.yaml 对 CUDA/PyTorch 组合存在不一致描述；本部署没有机械复制环境，而是选择与当前驱动、 GPU 和 torch-scatter ABI 相匹配的 PyTorch 2.0.1 + cu118 组合，并完成实际 GPU 推理验证。
故障排查

常见问题与处理原则

现象常见原因建议处理
提示至少需要两条蛋白链只有一条可识别标准蛋白链，或链太短确认输入是受体–肽复合物；显式指定链 ID
预处理后无候选肽与受体没有小于 6 Å 的原子接触检查肽是否位于结合口袋，避免把两条远离的链直接拼在一个 PDB
GPU 不可用或 torch-scatter 导入失败PyTorch、CUDA build 与扩展 ABI 不匹配在 CPComposer 环境中检查 torch 2.0.1/cu118 与 pt20cu118 扩展
生成端点距离 ≥5 Å单次随机样本未满足软约束提高 CPC_SAMPLES；不要只靠增大 guidance
OpenMM 无法识别闭环末端 N/C 缺失、非标准残基或链 ID 选错检查输入 PDB 主链完整性和 CPC_PEPTIDE_CHAIN
能量初值极高新建 bond 在最小化前仍被拉长结合最终能量、拓扑和键长判断；不要把初值当结合能
PyMOL 加载失败PDB 格式、原子记录或路径异常先检查最终文件是否存在，再查看 PyMOL 无界面输出
科学边界与可追溯性

哪些结论可以说，哪些不能说

本报告支持的结论

  • 官方 checkpoint 能在本机 GPU 上完成推理；
  • Condition 2 能生成几何上接近闭环的候选；
  • OpenMM 能建立并识别末端共价键；
  • 最终 PDB 键长合理且能被 PyMOL 解析；
  • 模型的数据流、张量和约束路径已由源码核查。

不能从单次 demo 推出的结论

  • 不能证明生成肽具有高结合亲和力；
  • 不能证明动力学稳定、可合成或有细胞活性；
  • 不能用 pmetric 或 OpenMM 最小化能量替代自由能计算；
  • 不能据此宣称四类约束均已完成端到端部署；
  • 不能把 SciBERT embedding 存在等同于文本控制已经生效。

源码与权重指纹

项目记录
上游项目jdp22 / CP-Composer_final；ICML 2025，Zero-Shot Cyclic Peptide Design with Composable Geometric Conditions
本机基线目录/home/luohaoxuan/work/CP-Composer_baseline
基线 commit6263670d7b04b383e6427e096ea3a878d48248f7
checkpointepoch37_step85234.ckpt
checkpoint SHA-256eed3bcef300036967bbaec7bf9bb0c94f06b21bf3f4e5c5c571181280e2b7133
一键运行器/home/luohaoxuan/work/run_cpcomposer.sh
运行封装/home/luohaoxuan/work/cpcomposer_runtime/run_cpcomposer.py
验证输出cpcomposer_outputs/1bjr_20260820_174844/cyclic/1bjr_head_tail.pdb

选择该历史 commit 是为了与 checkpoint、PromptDataset、generate.py 和 sample() 的发布接口保持一致。运行封装只在内存中处理 SciBERT 路径、CONDITION 类型和本机 OpenMM 平台兼容性，未改动模型源码与权重。