SPOT-RNA（multimolecule/spotrna）在昇腾 NPU 上的服务化推理

1. 简介

• 模型来源: multimolecule/spotrna（gitcode 镜像: hf_mirrors/multimolecule/spotrna）
• 模型任务: RNA 二级结构预测 —— 由单条 RNA 序列预测碱基配对接触图（base-pair contact map），输出序列中每个 (i, j) 位置的配对概率（含 Watson-Crick/wobble 与非经典配对、伪结 pseudoknot）
• 参数量: 17.463M（17,463,221）
• 模型架构: SpotRnaModel —— 逐碱基 one-hot 特征（A/C/G/U，N 为无效掩码）做外积拼接得到 L×L×8 配对表示，经 5 个集成成员（2D 膨胀残差卷积块，其中 1 个成员含 2D-BiLSTM 路径）逐对打分，对每个 (i,j) 输出配对 logit
• 适配状态: SUCCESS
• 适配时间: 2026-08-19

SPOT-RNA（Singh et al., Nature Communications 2019）由 MultiMolecule 团队复现并发布 单 checkpooint。相比 1D 逐位置打分模型（如 OpenSpliceAI / DeltaSplice），SPOT-RNA 直接对 配对空间 建模：5 个成员各自的 sigmoid 输出取平均得到配对概率矩阵 contact_map (1, L, L)；施加阈值（config.threshold = 0.335）+ 多重配对（multiplet）去除 后得到 0/1 配对图，可还原为 dot-bracket 结构串（支持 () [] {} <> 四级括号标注伪结）。

2. 验证环境

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

3. 昇腾 NPU 适配要点

1. 非 vLLM 路径：SPOT-RNA 为 2D 卷积判别模型，vLLM-Ascend 无法加载；正确路径为 multimolecule.SpotRnaModel + torch_npu + FastAPI（同 OpenSpliceAI / DeltaSplice 等生物模型部署模式）。
2. 2D-BiLSTM 成员 NPU 兼容补丁（本适配的关键）： inference.py 在导入后自动对 SpotRna2DBiLSTM._forward_packed 打补丁——torch_npu 的 pad_packed_sequence(..., total_length=L) 不生效（返回批内实际最长长度而非指定长度）， 导致第 4 个集成成员（含 2D-BiLSTM）形状不匹配报错 （RuntimeError: shape mismatch ... [21,21,400] vs [21,22,400]）。补丁在赋值前显式补齐 时间维度，CPU 与 NPU 输出一致性 ~1e-4。
3. 输入/输出约定：RnaTokenizer（词表 A/C/G/U/N，DNA 的 T 自动转 U，N 在 one-hot 置零）， add_special_tokens=False；输出 contact_map 为配对概率矩阵，model.postprocess() 施加阈值 + multiplet 去除得到 0/1 配对图。
4. 长度限制：模型全卷积无固定窗口，但计算量随 L 二次增长（L×L×8 配对表示 + L×L×64 隐藏层），默认最大长度 1000 nt（--max-length 可调至 2000），超长拒绝。
5. 演示序列：使用模型卡 widget 内置真实 RNA（microRNA 21 / microRNA 155 / HIV-1 TAR）， 其中 microRNA 21 与 HIV-1 TAR 预测结构与参考结构完全一致。

4. 服务化推理

4.1 启动服务

python3 inference.py --serve \
    --model-path /opt/atomgit/models/spotrna \
    --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. 命令行推理

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

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

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

# 其他演示序列 / 保存完整接触图
python3 inference.py --model-path /opt/atomgit/models/spotrna --device npu:0 --demo hiv_tar
python3 inference.py --model-path /opt/atomgit/models/spotrna --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.6s（首次推理含算子编译 ~9.3s）。CPU / NPU contact_map 最大绝对差 1.19e-04（预测配对完全一致）。

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. 文件结构

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

8. 参考

• 模型: multimolecule/spotrna / gitcode 镜像
• 论文: RNA secondary structure prediction using an ensemble of two-dimensional deep neural networks and transfer learning（Nature Communications, 2019）
• 官方实现: jaswindersingh2/SPOT-RNA
• 框架: MultiMolecule（License: AGPL-3.0）