APARENT2（multimolecule/aparent2）在昇腾 NPU 上的适配

1. 简介

• 模型来源：multimolecule/aparent2（gitcode 镜像: hf_mirrors/multimolecule/aparent2）
• 参数量：约 0.189M（188,965）
• 模型任务：从固定 205 nt 多聚腺苷酸化（polyadenylation, polyA）信号窗口预测 206 维切割位点（cleavage）分布（205 个逐核苷酸切割概率 + 1 个 no_cleavage 桶）
• 模型架构：深度膨胀残差卷积网络（dilated residual CNN，7 组膨胀卷积 × 4 残差块 + 位置特异 library bias）
• 适配状态：成功
• 适配时间：2026-08-19

APARENT2（Lavi et al., 2022，遗传算法 + 神经网络，扩展自 APARENT / Bogard et al., Cell 2019）是一个多聚腺苷酸化（alternative polyadenylation, APA）切割位点预测 模型。输入为一段固定 205 nt 的 polyA 信号窗口（模型约定核心 hexamer，如 AAUAAA，应位于窗口第 70 位，0-indexed），输出为 206 维的切割分布： 205 个逐核苷酸位置的切割概率 + 1 个 "no_cleavage"（窗口内不发生切割）桶。 切割通常发生在核心 hexamer 下游 10-30 nt。该模型可评估任意 polyA 位点的使用度 （usage = 1 - P(no_cleavage)），并可比较参考/替代序列量化变异对 polyadenylation 的影响（如 HBB 基因 polyA 信号突变导致的 β-地中海贫血）。

2. 部署方案

APARENT2 为膨胀残差卷积 CNN（非自回归 LLM），vLLM / vllm-ascend 无法加载服务。 正确路径是 multimolecule + torch_npu 直推 + FastAPI 提供服务化推理：

• 模型权重经 multimolecule.Aparent2ForSequencePrediction 加载（官方检查点 model.safetensors，0.189M 参数），计算在昇腾 NPU（torch_npu 注册的 npu 后端）上进行；
• 输入经 RnaTokenizer 编码（T 自动转 U、未知碱基映射为 N，N 在 one-hot 嵌入 中为全零向量等效掩码；不加特殊 token），嵌入层强校验定长 205 nt，不符即 ValueError；
• 输出为 206 个 pre-softmax 切割分数，经 softmax 映射为归一化切割分布 （与模型 postprocess 一致，勿再套其他激活）；polyA_usage = 1 - P(no_cleavage) 即该位点作为 polyA 切割位点的使用度；
• 变异效应 = 参考/替代序列分别推理后比较切割分布（逐位 delta 概率 + delta 使用度）， 模型无独立 ref/alt 输出 dataclass。

3. 环境与硬件

4. 模型权重获取

# 方式一：git clone 镜像仓库（AtomGit hf_mirrors）
git clone https://ai.atomgit.com/hf_mirrors/multimolecule/aparent2.git /opt/atomgit/models/aparent2

# 方式二：HuggingFace Hub 镜像（hf-mirror.com，需禁用 xet 后端）
HF_ENDPOINT=https://hf-mirror.com HF_HUB_DISABLE_XET=1 \
  python3 -c "from huggingface_hub import hf_hub_download; \
  hf_hub_download(repo_id='multimolecule/aparent2', filename='model.safetensors', \
  local_dir='/opt/atomgit/models/aparent2')"

注：克隆后若 model.safetensors 仅为 131 字节的 LFS 指针，需用 LFS batch API 下载实际权重（oid 298ccf5a...ba25a2cf，815,564 字节），或将 git-lfs 加入 PATH 后 git lfs pull。

5. 项目结构

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

6. 快速开始

6.1 安装依赖

pip install -r requirements.txt

6.2 命令行单次推理

cd /opt/atomgit/aparent2-npu

# 演示序列（真实 HBB 3' UTR polyA 窗口，205 nt，AAUAAA@70 + 变异效应示例）
python3 inference.py --model-path /opt/atomgit/models/aparent2 --device npu:0

# 指定序列（定长 205 nt 效果最佳；短序列自动补 N、长序列中心裁剪）
python3 inference.py --sequence "UAGCUUAUCAGACUGAUGUUGA" --device npu:0

# 变异效应（参考 vs 替代，必须等长，逐位比较切割分布 + polyA 使用度）
python3 inference.py \
    --reference  "...AAUAAA..."  --alternative "...AAUAAG..."  --device npu:0

6.3 服务化推理（FastAPI + Uvicorn）

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

服务化推理暴露的 HTTP 端点：

请求/响应示例：

# 切割分布预测（sequence 缺省时用 HBB 3' UTR 演示窗口）
curl -X POST http://127.0.0.1:8000/v1/predict \
    -H "Content-Type: application/json" \
    -d '{"sequence": "...", "top_k": 5}'

# 变异效应（参考/替代等长）
curl -X POST http://127.0.0.1:8000/v1/variant-effect \
    -H "Content-Type: application/json" \
    -d '{"reference": "...AAUAAA...", "alternative": "...AAUAAG...", "top_k": 5}'

/v1/predict 返回：polyA_usage（使用度）、no_cleavage_prob、 dominant_cleavage_site（主导切割位点及其相对 hexamer 偏移）、 top_cleavage_sites、完整 cleavage_profile（206 维 softmax 切割分布）。

7. 实测结果

7.1 演示序列（人类 HBB 3' UTR）

演示输入为真实 beta-globin（HBB）基因 3' UTR polyA 窗口（hg38 chr11:5,225,300-5,225,700；经典 polyA 信号 AATAAA 位于 chr11:5,225,474-5,225,479， 已对齐为窗口内 AAUAAA@70）：

预测切割峰位于核心 hexamer 下游 21-23 nt，符合多聚腺苷酸化经典几何（切割通常 发生在 AAUAAA 下游 10-30 nt），结果有明确生物学意义。

7.2 变异效应（HBB polyA 信号突变 AATAAA→AATAAG）

该突变（hexamer 第 6 位 A→G，位于窗口 pos 75）是已知 β-地中海贫血（β-thalassemia） 致病变异，预期降低 polyadenylation：

模型正确识别出 polyA 信号突变显著削弱主切割位点的切割概率，与临床已知致病机制一致。

7.3 性能基准（昇腾 910B NPU）

8. 注意事项

• 定长 205 nt 强校验：one-hot 嵌入层要求恰好 205 个 token，脚本对短序列双侧补 N、 长序列中心裁剪；但请尽量提供已按模型约定对齐的 205 nt 窗口（核心 hexamer 位于 窗口第 70 位）以获得有生物学意义的预测。
• 核心 hexamer 位置：模型在训练中约定 AAUAAA 等核心 hexamer 起点位于窗口第 70 位 （0-indexed），切割通常在其下游 10-30 nt。
• 输出后处理：206 维输出为 pre-softmax 分数，需 softmax 归一化（模型 postprocess 即 softmax）；polyA_usage = 1 - P(no_cleavage)。
• 非 vLLM：APARENT2 为 CNN 模型，vLLM-Ascend 无法加载，必须走 multimolecule + torch_npu 方案。
• 变异效应同长约束：仅支持同长变异（SNP/点突变），参考/替代等长校验。
• 依赖冲突：multimolecule 0.2.1 需 transformers>=5.0，与 vllm（要求 transformers<5）冲突，二者不可同环境混装。

9. 截图

截图素材由人工补充，占位说明如下：

• assets/agent_workflow.png：模型部署工作流截图（Agent 工作流）
• assets/npu_device_call.png：NPU 设备调用/推理日志截图（torch.npu.get_device_name 等）
• assets/model_result.png：模型推理结果截图（/v1/predict 与 /v1/variant-effect 响应）