mmsplice-npu:可直接用于预测遗传变异对 pre-mRNA 剪接的影响，获得模块分数与 delta-logit-PSI 效应分数。项目基于 multimolecule 框架与 torch_npu，将 MMSplice 模型成功适配至昇腾 NPU，提供 CLI 与 FastAPI 服务化推理，支持模块分数及变异效应预测，性能高效且精度与 CPU 完全一致。【此简介由AI生成】 - AtomGit AI社区

MMSplice（multimolecule/mmsplice）在昇腾 NPU 上的服务化推理

1. 简介

模型来源: multimolecule/mmsplice（gitcode 镜像: hf_mirrors/multimolecule/mmsplice）
模型任务: 剪接变异效应（splice-variant-effect）预测 —— 将"外显子 + 两侧内含子"分解为 5 个区域分别打分（模块分数），并输出参考/替代序列对的 delta-logit-PSI 剪接效应分数（正=剪接获得，负=剪接丢失）
参数量: 0.057M（56,677）
模型架构: MmSpliceForSequencePrediction —— 模块化 1D CNN，5 个独立的区域子网络（acceptor_intron / acceptor / exon / donor / donor_intron）+ 固定线性组合头
适配状态: SUCCESS
适配时间: 2026-08-19

MMSplice（Cheng et al., 2019, Genome Biology）是一种模块化神经网络，用于预测遗传变异对 pre-mRNA 剪接的影响。它把"外显子 + 两侧各 100 nt 内含子"分解为五个区域，每个区域由独立的小型 1D 卷积子网络打分；五个分数构成模块分数向量。对变异效应，模型同时跑参考与替代序列，将逐模块分数差（delta）经固定线性组合器合并为单个 delta-logit-PSI 分数 —— 正值=剪接获得（splice gain），负值=剪接丢失（splice loss）。

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（64GB HBM）

3. 模型结构

MMSplice 输入为 100 nt 上游内含子 + 外显子 + 100 nt 下游内含子（外显子长度任意，内含子上下文不足时按 N 零填充）。one-hot 编码（ACGU，N 为全零掩码）后，五个子网络分别切片其目标区域并输出一个标量 logit：

子模块	架构	评分区域
acceptor_intron	conv（256×13）	左端受体内含子（截断 6 nt）
acceptor	dense（32×15 + 1x1 + BN）	受体位点窗口（50 nt 内含子 + 3 nt 外显子）
exon	conv（128×11 + BN，掩码池化）	外显子体
donor	dense（128→64→1）	供体位点窗口（5 nt 外显子 + 13 nt 内含子）
donor_intron	conv（256×13）	右端供体内含子（截断 6 nt）

变异效应：delta = alternative_logits - reference_logits（5 维），经固定线性组合器 MmSpliceDeltaLogitPsiHead（8 个固定系数 + 截距）合并为单个 delta-logit-PSI 标量。关键配置：

配置项	值
模型类型	mmsplice（MmSpliceForSequencePrediction）
子模块数	5
hidden_size（模块分数维度）	5
num_labels	1（delta-logit-PSI 回归）
词汇表	4（A/C/G/U + N 填充，RnaTokenizer T→U）
权重文件	model.safetensors（235,540 B）
权重 sha256	`023b65cd270f27507593531f6c91de990c8403836b32de7fedb1fb1592ab4023`
transformers_version	5.9.0

4. 服务化推理验证结果

4.1 CLI 推理（HBB exon2 演示序列，422 nt）

演示序列为人类 beta-globin（HBB，NCBI NG_000007.3）外显子 2（222 nt）与其上游内含子 100 nt、下游内含子 100 nt 拼接而成。

模型路径: /opt/atomgit/models/mmsplice
设备:     npu:0
参数量:   56.68K

[demo] 未提供序列，使用 HBB exon2 演示序列（422 nt）

[模块分数] 序列长度 422 nt，耗时 191.6 ms
主导模块: donor_intron (+0.7024)

5 个子模块分数:
  acceptor_intron   score=-3.2351
  acceptor          score=-3.6442
  exon              score=-3.0930
  donor             score=-0.9982
  donor_intron      score=+0.7024

============================================================
[demo] 额外展示变异效应：供体位点保守 G -> A（IVS2+1 G>A，β-地中海贫血）
[变异效应] 耗时 24.4 ms
  位点 pos 322（供体 GT 的 G） G->A：delta-logit-PSI = -1.1223  [splice_loss]
  逐模块 delta:
    donor             delta=-1.4970
    acceptor_intron   delta=+0.0000
    acceptor          delta=+0.0000
    exon              delta=+0.0000
    donor_intron      delta=+0.0000
SUCCESS

结果解读：供体位点保守 G 突变为 A（HBB 经典地中海贫血突变，破坏供体位点 GT 二核苷酸）后，模型正确预测 donor 模块分数下降 -1.4970、整体 delta-logit-PSI = -1.1223（splice loss），且效应完全集中在 donor 模块，与生物学机制一致。

4.2 HTTP 服务化推理

$ curl -s -X POST http://127.0.0.1:8003/v1/predict \
    -H "Content-Type: application/json" -d '{}'
{
  "length": 422,
  "module_scores": [
    {"module": "acceptor_intron", "score": -3.5887},
    {"module": "acceptor", "score": -5.4719},
    {"module": "exon", "score": -3.4821},
    {"module": "donor", "score": -0.9982},
    {"module": "donor_intron", "score": 0.7024}
  ],
  "dominant_module": "donor_intron", "dominant_score": 0.7024,
  "inference_ms": 194.67
}

4.3 剪接变异效应（delta-logit-PSI）推理

以 HBB exon2 演示序列（422 nt）为参考，在供体位点 pos 322 做 G->A 点突变（破坏规范 GT），模型正确预测 剪接丢失：

POST /v1/variant-effect
  {"reference": "<HBB exon2 422nt>", "alternative": "<同上，pos 322 G->A>"}
{
  "variant_positions": [322],
  "reference_nucleotide": "G",
  "alternative_nucleotide": "A",
  "delta_logit_psi": -1.1223,
  "direction": "splice_loss",
  "module_deltas": [
    {"module": "donor", "delta": -1.497, "reference_score": -0.9982, "alternative_score": -2.4953},
    ...
  ],
  "inference_ms": 25.14
}

5. 快速开始（复现步骤）

5.1 获取权重

# 方式一：git clone 镜像（无 git-lfs 时走 LFS batch API，见下）
git clone --filter=tree:0 --no-checkout \
    https://gitcode.com/hf_mirrors/multimolecule/mmsplice.git /tmp/mmsplice
cd /tmp/mmsplice && git checkout HEAD -- config.json tokenizer_config.json vocab.txt

# 方式二：LFS batch API 直取 model.safetensors（235,540 B）
#   oid=023b65cd270f27507593531f6c91de990c8403836b32de7fedb1fb1592ab4023
#   curl -X POST https://gitcode.com/hf_mirrors/multimolecule/mmsplice.git/info/lfs/objects/batch \
#     -H "Content-Type: application/vnd.git-lfs+json" \
#     -H "Accept: application/vnd.git-lfs+json" \
#     -H "User-Agent: git-lfs" \
#     -d '{"operation":"download","transfers":["basic"],
#          "objects":[{"oid":"023b65cd...ab4023","size":235540}]}'   # 取签名 URL 后下载
# 校验：
sha256sum /opt/atomgit/models/mmsplice/model.safetensors
# 023b65cd270f27507593531f6c91de990c8403836b32de7fedb1fb1592ab4023

5.2 安装依赖

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 若需 vllm/vllm-ascend 请用独立 venv（本模型为模块化 CNN，无需 vLLM，与 transformers>=5 不冲突）

5.3 命令行推理

python3 inference.py \
    --model-path /opt/atomgit/models/mmsplice \
    --device npu:0

# 指定序列（模块分数；输入格式：100nt 上游内含子 + 外显子 + 100nt 下游内含子）
python3 inference.py \
    --model-path /opt/atomgit/models/mmsplice \
    --sequence "AAAAAAAAAAGCTGCTGGTGGT...GGTGAGT..." --device npu:0

# 变异效应（delta-logit-PSI）：参考与替代序列必须同长（SNP/点突变）
python3 inference.py \
    --model-path /opt/atomgit/models/mmsplice \
    --reference-file ./ref.fa \
    --alternative-file ./alt.fa --device npu:0

说明：--reference/--alternative 也可直接传序列字符串；二者长度必须相等（delta-logit-PSI 仅支持同长变异，如 SNP/点突变）。

5.4 服务化推理（FastAPI）

python3 inference.py --serve \
    --model-path /opt/atomgit/models/mmsplice \
    --host 0.0.0.0 --port 8003 --device npu:0

5.5 调用示例

# 健康检查
curl -s http://127.0.0.1:8003/health
# {"status":"ok","model":"multimolecule/mmsplice","device":"npu:0",
#  "npu":{"available":true,"device_count":2,"name":"Ascend910_9362"}}

# 模型信息
curl -s http://127.0.0.1:8003/v1/models

# 模块分数预测（sequence 缺省用 HBB exon2 演示序列）
curl -s -X POST http://127.0.0.1:8003/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"sequence":"<100nt 内含子+外显子+100nt 内含子>"}'

# 变异效应预测（参考/替代必须同长；示例：HBB exon2 演示序列 pos322 donor G->A）
curl -s -X POST http://127.0.0.1:8003/v1/variant-effect \
  -H "Content-Type: application/json" \
  -d '{"reference":"<参考序列>","alternative":"<替代序列，pos 322 G 改为 A>"}'

6. 服务化推理 API

端点	方法	说明
`/health`	GET	健康检查（返回 NPU 设备信息与模型状态）
`/v1/models`	GET	模型信息（模型 ID、任务、参数量、模块）
`/v1/predict`	POST	模块分数预测；请求体 `{"sequence": "..."}`，返回 5 个模块分数
`/v1/variant-effect`	POST	变异效应预测；请求体 `{"reference": "...", "alternative": "..."}`（同长）

/v1/predict 返回：module_scores（5 个子模块 logit）、dominant_module、 dominant_score、length。 /v1/variant-effect 返回：delta_logit_psi（剪接效应分数）、direction （splice_gain / splice_loss / neutral）、variant_positions、module_deltas （逐模块 delta，|delta| 排序）。

7. NPU 适配说明

MMSplice 为模块化 1D 卷积模型（非自回归 LLM），vLLM / vllm-ascend 无法服务；采用 multimolecule + torch_npu + FastAPI 方案在昇腾 NPU 上推理。
模型通过 multimolecule.MmSpliceForSequencePrediction.from_pretrained 加载（config architectures: MmSpliceForSequencePrediction，权重键名 model.* + prediction.*），计算在昇腾 NPU（torch_npu 注册的 npu 后端）上进行。
模块分数：model.model(input_ids=...) 返回 (1, 5) 的 logits（参考序列）；变异效应：model(input_ids=ref, alternative_input_ids=alt) 返回 (1, 1) 的 delta-logit-PSI。
one-hot 编码 F.one_hot 在 NPU 上仅触发 "internal format" 告警（输出正常，已与 CPU 结果核对：模块分数余弦相似度 1.0、delta-logit-PSI 逐位一致）。
输入支持 DNA/RNA 大小写，RnaTokenizer 自动将 T 转换为 U、未知碱基映射为 N （N 在 one-hot 中为全零向量，等效掩码）；tokenize 时 add_special_tokens=False。
服务化用 FastAPI（非 OpenAI 格式），inference.py 支持 CLI + --serve 双模式。

8. 目录结构

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

9. 精度与性能

场景	输入长度	耗时
CLI 模块分数推理（首次加载约 8s）	422 nt	~192 ms
HTTP `/v1/predict`	422 nt	~195 ms
HTTP `/v1/variant-effect`	422 nt（同长）	~25 ms

模型权重 model.safetensors（235,540 B，sha256 023b65cd...ab4023）来自 gitcode 镜像 hf_mirrors/multimolecule/mmsplice，与 HF 官方权重一致。
CPU/NPU 一致性：模块分数余弦相似度 1.000000，delta-logit-PSI 绝对误差 0.00e+00。
供体 G->A 点突变（β-地中海贫血 IVS2+1 G>A）正确预测 splice loss（delta-logit-PSI = -1.1223，donor 模块 delta = -1.4970）。