Framepool（multimolecule/framepool）在昇腾 NPU 上的适配

1. 简介

模型来源: multimolecule/framepool（gitcode 镜像: hf_mirrors/multimolecule/framepool）
参数量: 约 0.28M（283,525）
模型任务: 任意长度 5'UTR -> 平均核糖体负载（Mean Ribosome Load, MRL）预测
模型架构: 3 层 1D 膨胀残差卷积网络（128 卷积核，kernel 7，dilation 1,1,1）→ 帧感知池化（frame-aware pooling）→ 64 维 Dense 头 → 子库缩放回归 → 标量输出
适配状态: 成功
适配时间: 2026-08-19

Framepool（Karollus, Avsec & Gagneur, 2021，见 PLOS Computational Biology）以 5'UTR RNA 序列为输入，通过帧感知池化（frame-aware pooling） 层将特征图按三个阅读帧切片并分别池化，输出与长度无关的表示，从而支持任意长度的 5'UTR 序列。模型预测的 mean ribosome load（MRL） 是一种由多聚核糖体图谱（polysome profiling）衍生的翻译效率代理指标，数值越大代表翻译效率越高。

模型在 eGFP 多聚核糖体 MPRA 数据（约 28 万条序列，两个子库 egfp_unmod_1 和 random）上训练，并附带一个子库缩放回归层（scaling regression）校准两库间的系统性偏移。

2. 验证环境

组件	版本
torch	2.9.0
torch-npu	2.9.0.post1
transformers	5.9.0
multimolecule	0.2.1
fastapi	0.123.10
numpy	1.26.4
CANN	8.5.1
NPU	Ascend 910（Ascend910_9362，64GB HBM）

3. 模型结构

Framepool 为序列级回归 CNN：3 层 Conv1D（128 滤波器、kernel size 7、same 填充、ReLU、dilation 1,1,1）对 one-hot 编码的 RNA 序列做局部特征提取，经帧感知池化层将特征图按三个阅读帧切片后分别做全局最大值池化和掩码全局平均值池化，拼接后经 64 维 Dense 层（dropout 0.2），最后通过子库缩放回归输出标量 MRL。

配置项	值
模型类型	FramepoolForSequencePrediction
输入长度	任意（帧感知池化产生长度无关表示）
卷积层数 / 卷积核	3 / 128 × kernel 7（dilation 1,1,1，same padding）
帧感知池化	反向锚定起始密码子，三帧切片 + 全局最大池化 + 掩码全局平均池化
Dense 隐藏层	64（ReLU + dropout 0.2）
输出	单个标量 mean-ribosome-load（MRL）
子库缩放	library_size=2，one-hot 指示子库缩放回归校准
词表	A/C/G/U/N（5 tokens，RnaTokenizer，T 自动转 U）
参数量	283,525（0.28M）

输入为 RNA（RnaTokenizer 按 A/C/G/U/N 编码，DNA 中的 T 自动转为 U），输出为标量 MRL 预测值。library_indicator 可选参数选择 random（默认）或 egfp_unmod_1 子库。

4. 昇腾 NPU 适配要点

#	适配点	说明
1	非 LLM，不走 vLLM-Ascend	Framepool 是 5'UTR 翻译效率回归 CNN（序列 → 标量，非自回归生成），vLLM / vllm-ascend 无法直接服务；采用 multimolecule + torch_npu + FastAPI 方案在昇腾 NPU 上推理
2	依赖版本约束	multimolecule 0.2.1 依赖 `transformers.initialization`，需要 transformers>=5.0（本仓库固定 5.9.0，与 config.json 的 `transformers_version` 一致）；这会与 vllm 0.18（要求 transformers<5）冲突，但本模型不使用 vLLM，无影响
3	推理设备	通过 `torch_npu` 注册 npu 后端，模型 `.to("npu:0")` 在昇腾 910 上计算；权重为 float32（约 1.1MB），无需量化
4	one-hot 嵌入	模型内部用 `F.one_hot` 将 token 投影为 (batch, vocab=5, seq_len)；在 NPU 上仅告警 "Cannot create tensor with interal format"（输出正常），无需修补
5	帧感知池化	Framepool 核心创新：序列反向 + 三帧切片 + 双池化策略，在 NPU 上完整支持，无需任何修改
6	子库缩放回归	两子库（random / egfp_unmod_1）通过 `library_indicator` 选择，在 NPU 上正确产生校准后的 MRL 输出

模型验证: 在昇腾 NPU 上对 50 nt 示例 5'UTR 序列推理，预测 MRL = 5.568919，推理耗时约 0.15s，输出结构与官方实现一致，行为符合预期。

5. 快速开始

5.1 权重准备

从 HuggingFace 镜像或 ModelScope 拉取权重：

# 方式一：从 gitcode 镜像拉取（推荐）
git clone https://ai.gitcode.com/hf_mirrors/multimolecule/framepool.git /path/to/weights

# 方式二：从 HuggingFace 直接拉取
git clone https://huggingface.co/multimolecule/framepool /path/to/weights

或使用已下载的本地权重（默认路径 /opt/atomgit/models/framepool）。

5.2 CLI 推理（单序列）

# 预测 MRL（默认 random 子库）
python inference.py \
  --seq "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAC" \
  --device npu:0

# 指定 egfp_unmod_1 子库
python inference.py \
  --seq "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAC" \
  --library egfp_unmod_1 \
  --device npu:0

5.3 变异效应评分（参考/替代配对）

python inference.py \
  --seq "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAC" \
  --alt-seq "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAA" \
  --device npu:0

输出参考序列 MRL、替代序列 MRL 和 log2 倍变化。

5.4 精度 / 性能基准

python inference.py --benchmark --n-runs 10 --device npu:0

输出 CPU fp32 参考 vs NPU 输出的余弦相似度、最大绝对误差及延迟统计。

5.5 服务化推理（OpenAI 兼容）

python inference.py --serve --port 8000 --device npu:0

服务端点：

端点	方法	说明
`/v1/models`	GET	获取模型元信息
`/v1/predict`	POST	单序列 MRL 预测
`/v1/variant`	POST	变异效应（参考/替代配对）评分
`/v1/chat/completions`	POST	OpenAI 兼容包装（从消息中提取序列）
`/v1/health`	GET	健康检查

请求示例：

# 单序列预测
curl -X POST http://localhost:8000/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"sequence": "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAC", "library": "random"}'

# 变异效应
curl -X POST http://localhost:8000/v1/variant \
  -H "Content-Type: application/json" \
  -d '{"reference": "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAC", "alternative": "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAA"}'

# OpenAI 兼容
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "ACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUACGUAC"}]}'

6. 项目结构

framepool-npu/
├── inference.py        # 推理脚本（CLI / 基准 / 服务化）
├── README.md           # 部署说明文档
├── requirements.txt    # 环境依赖清单
└── assets/             # 截图素材文件夹
    ├── agent_workflow.png
    ├── npu_device_call.png
    └── model_result.png

7. 参考

Framepool 论文 — Predicting mean ribosome load for 5'UTR of any length using deep learning
MultiMolecule GitHub — 官方实现框架
Framepool 官方 Kipoi 仓库 — 上游 Kipoi 包装
Sample et al., 2019 — eGFP 多聚核糖体 MPRA 数据来源
昇腾社区 — CANN / torch_npu 官方文档