UFold（multimolecule/ufold）在昇腾 NPU 上的服务化推理

1. 简介

• 模型来源: multimolecule/ufold（gitcode 镜像: hf_mirrors/multimolecule/ufold）
• 模型任务: RNA 二级结构预测 —— 由单条 RNA 序列预测碱基配对接触图（base-pair contact map），输出序列中每个 (i, j) 位置的配对概率（含 Watson-Crick/wobble 与非经典配对、伪结 pseudoknot）
• 参数量: 8.64M（8,640,000）
• 模型架构: UfoldModel —— 逐碱基 one-hot 特征（A/C/G/U，N 为无效掩码）做外积拼接得到 16 个配对通道，再叠加 1 个手工构造的经典/wobble 配对先验通道，构成 L×L×17 的图像式表示，经 5 级下采样/上采样的 U-Net（channel_sizes=[32,64,128,256,512]）回归出对称的接触分数矩阵，对每个 (i,j) 输出配对 logit
• 适配状态: SUCCESS
• 适配时间: 2026-08-19

UFold（Fu et al., Nucleic Acids Research 2021）由 MultiMolecule 团队复现并发布。 与 1D 逐位置打分模型（如 OpenSpliceAI / DeltaSplice）不同，UFold 直接对配对空间 建模：将序列编码为图像式 L×L×17 表示后经 U-Net 回归，logits 为 raw 分数（非概率， 勿直接当概率用），torch.sigmoid(logits) 得到配对概率矩阵 contact_map (1, L, L)； 施加阈值（config.threshold = 0.5）+ UFold 约束后处理（拉格朗日乘子迭代 + L1 收缩） 后得到 0/1 配对图，可还原为 dot-bracket 结构串（支持 () [] {} <> 四级括号标注伪结）。

2. 验证环境

注：multimolecule 0.2.1 需要 transformers>=5.0，会与 vllm 0.18（要求 transformers<5） 冲突；UFold 为二维卷积判别模型（非 LLM），不走 vLLM，直接使用 multimolecule + torch_npu 在昇腾 NPU 上推理，故无影响。

3. 昇腾 NPU 适配要点

1. 非 vLLM 路径：UFold 为 2D 卷积判别模型（U-Net），vLLM-Ascend 无法加载；正确路径为 multimolecule.UfoldModel + torch_npu + FastAPI（同 SPOT-RNA / OpenSpliceAI / DeltaSplice 等生物模型部署模式）。
2. 输入/输出约定：RnaTokenizer（词表 A/C/G/U/N，DNA 的 T 自动转 U，N 在 one-hot 置零）， add_special_tokens=False；模型内部将序列 padding 到 min_size=80 且为 size_multiple=16 的倍数（U-Net 四次下采样需要，_pad_inputs_embeds 自动处理）； 输出 contact_map 为 sigmoid 后的配对概率矩阵，model.postprocess() 施加 UFold 约束后处理 + 阈值得到 0/1 配对图。
3. logits 非概率：UFold 的 logits 是 raw 分数（UfoldEncoder.forward 末尾 transpose(-1,-2) * logits 得到的平方分数），不是概率；配对概率一律取 outputs.contact_map（即 sigmoid(logits)）。
4. 长度限制：模型全卷积无固定窗口，但计算量随 L 二次增长（L×L×17 图像表示 + U-Net），默认最大长度 600 nt（--max-length 可调至 1000），超长拒绝。
5. 演示序列：使用模型卡 widget 内置真实 RNA（tRNA 76 nt / microRNA 21 / HIV-1 TAR）， 其中 microRNA 21 与 HIV-1 TAR 预测结构与参考结构完全一致。

4. 服务化推理

4.1 启动服务

python3 inference.py --serve \
    --model-path /opt/atomgit/models/ufold \
    --port 8000 --device npu:0

4.2 HTTP 端点

4.3 调用示例

# 二级结构预测
curl -X POST http://127.0.0.1:8000/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"sequence": "UAGCUUAUCAGACUGAUGUUGA", "top_k": 8}'

# 结构变异效应（microRNA 155 第 12 位 G->A）
curl -X POST http://127.0.0.1:8000/v1/variant-effect \
  -H "Content-Type: application/json" \
  -d '{"reference": "UUAAUGCUAAUCGUGAUAGGGUU", "alternative": "UUAAUGCUAAUCGUAAUAGGGUU"}'

5. 命令行推理

# 使用模型卡演示序列 tRNA（76 nt）
python3 inference.py --model-path /opt/atomgit/models/ufold --device npu:0

# 指定 RNA/DNA 序列（DNA 的 T 自动转 U）
python3 inference.py --model-path /opt/atomgit/models/ufold --device npu:0 \
    --sequence "GGGCUAUUAGCUCAGUUGGUUAGAGCGCACCCCUGAUAAGGGUGAGGUCGCUGAUUCGAAUUCAGCAUAGCUCA"

# 参考/替代序列的结构变异效应
python3 inference.py --model-path /opt/atomgit/models/ufold --device npu:0 \
    --reference "UUAAUGCUAAUCGUGAUAGGGUU" --alternative "UUAAUGCUAAUCGUAAUAGGGUU"

# 其他演示序列 / 保存完整接触图
python3 inference.py --model-path /opt/atomgit/models/ufold --device npu:0 --demo hiv_tar
python3 inference.py --model-path /opt/atomgit/models/ufold --device npu:0 --save-contact-map cm.npy

6. 验证结果

6.1 演示序列预测（NPU 实测）

microRNA 21 预测碱基对 Top-5：(9,13) A-U P=0.9832、(10,12) G-C P=0.9442、 (8,14) C-G P=0.9010、(7,15) U-A P=0.6243、(6,16) A-U P=0.5834。

microRNA 155 为模型自身折叠结果，与模型卡 widget 中数据库（miRBase）参考结构 略有差异：模型预测 ...((.(((.......))).)).（2 个茎环、5 对），数据库参考 ......((.........)).....（1 个茎环）。属不同工具/来源对同一序列的合理分歧， 非部署问题。

6.2 性能（Ascend910_9362，热推理）

模型加载 ~1.7s（首次推理含算子编译 ~10s）。CPU / NPU contact_map 最大绝对差 ~1e-4（预测配对完全一致）。

6.3 变异效应示例

microRNA 155 第 12 位 G -> A（UUAAUGCUAAUCGU**G**AUAGGGUU → UUAAUGCUAAUCGU**A**AUAGGGUU）：结构从 5 对变为 1 对，丢失 4 个碱基对 （(3,21) (4,20) (7,17) (8,16)），stem 完全解旋——符合 G/C 碱基被替换后 配对自由能降低的预期。

7. 文件结构

ufold-npu/
├── inference.py        # 推理脚本（CLI + FastAPI 服务）
├── README.md           # 部署说明文档
├── requirements.txt    # 环境依赖清单
└── assets/             # 截图素材
          ├── agent_workflow.png    # 部署工作流截图（待补充）
          ├── npu_device_call.png   # NPU 设备调用截图（待补充）
          └── model_result.png      # 模型推理结果截图（待补充）

8. 参考

• 模型: multimolecule/ufold / gitcode 镜像
• 论文: UFold: fast and accurate RNA secondary structure prediction with deep learning（Nucleic Acids Research, 2021）
• 官方实现: uci-cbcl/UFold
• 框架: MultiMolecule（License: AGPL-3.0）