MaxEntScan-score5（maxentscan-score5）在昇腾 NPU 上的适配

1. 简介

模型来源：multimolecule/maxentscan-score5（MaxEntScan 5' 剪接供体最大熵打分模型）
参数量：0（最大熵概率表，无训练权重；me2x5 固定概率表共 16,384 个浮点数）
模型任务：RNA 剪接位点打分（splice-site scoring / 5' donor, score5 模式）
模型架构：最大熵模型（Yeo & Burge, 2004），固定概率表查表，非神经网络
适配状态：成功
适配时间：2026-08-19

MaxEntScan（Maximum Entropy Modeling of Short Sequence Motifs）是经典剪接位点打分工具。本实现为 score5（5' 剪接供体）打分器：对 9 nt 固定窗口计算最大熵 log-odds 得分，正值表示该窗口更像真实剪接供体位点。模型由 MultiMolecule 团队以 PyTorch 原样复现，与官方 Perl 实现（score5.pl）产生完全一致的中间表示。

2. 验证环境

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

3. 模型结构

score5 模型打分窗口布局为 XXX(exon) | X*6(intron)，共 9 nt，其中 GU 共有序列位于第 3、4 位（0 起始索引），即外显子最后 1 位 + 内含子第 1 位。扣除共有序列后得到 7-mer 非保守区，由 me2x5 最大熵概率表（4⁷ = 16,384 个浮点数）直接哈希索引打分。

配置项	值
模型类型	MaxEntScanModel
打分模式	score5（5' 剪接供体）
窗口大小	9 nt（固定：3 外显子 + 6 内含子）
词表	A/C/G/U/N（4 碱基 + N 填充，N 自动钳位为 A）
序列处理	RnaTokenizer，T 自动转 U，`add_special_tokens=False`
输出	每窗口单个 log-odds 标量（log2）
参数量	0（固定最大熵概率表 buffer）

输入任意长度序列：长度 == 9 → 单窗口打分；长度 > 9 → 以 stride 步长滑窗扫描，逐位置输出 9-mer 得分并筛选候选剪接供体位点。

4. 昇腾 NPU 适配要点

#	适配点	说明
1	非 LLM，不走 vLLM-Ascend	MaxEntScan 为最大熵查表模型（无训练权重、非神经网络），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 概率表 buffer，无需量化
4	序列预处理	`RnaTokenizer` 内置 DNA→RNA 转换（T→U），直接接受基因组 DNA / 成熟 RNA 序列；未知碱基 N 自动钳位为 A 参与查表
5	滑窗扫描	整体 tokenize 一次后对 input_ids 做滑窗切分并批量前向，避免重复 tokenize；按阈值（默认 0.0，正分即强于背景）筛选候选剪接供体位点
6	前向常量重建	模型非持久 buffer 在 `from_pretrained` 后需重建，`MaxEntScanScorer._ensure_constants` 在前向时自动处理，设备迁移无需额外操作

模型验证（昇腾 NPU 实测）：

强 5' 剪接供体 CAGGUAAGU（3 外显子 + GU + 6 内含子，GU 位于第 3/4 位） → 得分 10.8583（强正分，判定为真实剪接供体位点）；
合成前体 mRNA 示例（69 nt，含多个 GU 供体基序）滑窗扫描 → 在 pos 41 检出 score 10.8766 的强候选剪接供体位点，与真实生物学标注一致；
随机对照位置得分普遍为负（-3 ~ -39），正负区分度清晰。

5. 快速开始

5.1 安装依赖

pip install -r requirements.txt

若 vLLM-Ascend 环境已存在（transformers<5），建议使用独立 venv 安装本仓库依赖，避免与 multimolecule 所需的 transformers 5.9.0 冲突。

5.2 下载模型权重

# 方式一：GitCode 镜像
git clone https://gitcode.com/hf_mirrors/multimolecule/maxentscan-score5.git

# 方式二：HuggingFace 镜像（hf-mirror.com）
git clone https://hf-mirror.com/multimolecule/maxentscan-score5

# 方式三：multimolecule / transformers 直接加载（会自动下载）
python -c "from multimolecule import MaxEntScanModel, RnaTokenizer; \
tok = RnaTokenizer.from_pretrained('multimolecule/maxentscan-score5'); \
m = MaxEntScanModel.from_pretrained('multimolecule/maxentscan-score5')"

注意：权重文件由 Git LFS 托管（model.safetensors，约 65 KB），克隆后需 git lfs pull 或使用 hf_hub_download 直接下载真实权重。

5.3 命令行推理

# 单窗口打分（9 nt，GU 共识位于第 3/4 位）
python3 inference.py \
    --model-path ./maxentscan-score5 \
    --device npu:0 \
    --sequence "CAGGUAAGU"

# 长序列滑窗扫描（示例序列见 example_sequence.fa，含多个 5' 剪接供体位点）
python3 inference.py \
    --model-path ./maxentscan-score5 \
    --device npu:0 \
    --sequence-file ./example_sequence.fa \
    --threshold 3.0

5.4 服务化推理（FastAPI）

# 启动服务（默认 0.0.0.0:8000，此处演示用 127.0.0.1:8005）
export ASCEND_RT_VISIBLE_DEVICES=0
python3 inference.py --serve \
    --model-path ./maxentscan-score5 \
    --device npu:0 \
    --host 127.0.0.1 --port 8005

调用示例：

# 健康检查
curl http://127.0.0.1:8005/health

# 模型信息
curl http://127.0.0.1:8005/v1/models

# 单窗打分（9 nt 强 5' 剪接供体）
curl -X POST http://127.0.0.1:8005/v1/predict \
    -H "Content-Type: application/json" \
    -d '{"sequence": "CAGGUAAGU"}'

# 滑窗扫描（长序列，筛选 score ≥ 3.0 的候选剪接供体位点）
curl -X POST http://127.0.0.1:8005/v1/predict \
    -H "Content-Type: application/json" \
    -d '{"sequence": "ACGAUCGACGGUACCUAGCCUAGCAGGUACGUAGCCUGAUGCAGGUACGGUACCUAGCCUAGCCUAGCU", "threshold": 3.0}'

6. 推理结果

模型推理结果

命令行推理输出（示例序列，昇腾 NPU）：

序列长度: 69 nt
滑窗扫描: 窗口=9 nt, stride=1, 共 61 个位置, 推理耗时 149.3 ms
最高得分: 10.8766 @ pos 41
候选剪接位点（score ≥ 3.0）: 4 个
  pos     7  score=6.7939
  pos    23  score=10.6547
  pos    41  score=10.8766
  pos    46  score=6.7939

服务化推理返回（POST /v1/predict，单窗 9 nt 强供体）：

{
  "sequence": "CAGGUAAGU",
  "length": 9,
  "mode": "single",
  "window": 9,
  "scores": [10.8583],
  "candidates": [{"pos": 0, "score": 10.8583}],
  "best_score": 10.8583,
  "inference_ms": 111.82
}

7. 环境检查

NPU 设备调用

服务健康检查返回：

{
  "status": "ok",
  "model": "multimolecule/maxentscan-score5",
  "device": "npu:0",
  "npu": {"available": true, "device_count": 1, "name": "Ascend910_9362"}
}

Agent 工作流

8. 复现步骤

# 1. 环境准备（依赖 + 权重）
pip install -r requirements.txt
git clone https://gitcode.com/hf_mirrors/multimolecule/maxentscan-score5.git
# （下载 LFS 权重 model.safetensors，约 65 KB）

# 2. 命令行推理（单窗 + 滑窗扫描）
python3 inference.py --model-path ./maxentscan-score5 \
    --device npu:0 --sequence "CAGGUAAGU"
python3 inference.py --model-path ./maxentscan-score5 \
    --device npu:0 --sequence-file ./example_sequence.fa --threshold 3.0

# 3. 服务化推理
export ASCEND_RT_VISIBLE_DEVICES=0
python3 inference.py --serve --model-path ./maxentscan-score5 \
    --device npu:0 --host 127.0.0.1 --port 8005
curl http://127.0.0.1:8005/health

贡献者: liuhongwei-2026 | 赛道: 模型适配赛道