DeepMEL（multimolecule/deepmel）在昇腾 NPU 上的服务化推理

1. 简介

模型来源: multimolecule/deepmel（gitcode 镜像: hf_mirrors/multimolecule/deepmel）
模型任务: 染色质主题活性预测（regulatory-activity）—— 直接由 500 bp DNA 序列预测 24 个黑色素瘤染色质主题（chromatin topic）的活性（multi-label 二分类），覆盖 4-MEL 黑色素细胞样、7-MES 间充质样及其他可及性程序
参数量: 3.445M（3,444,760）
模型架构: DeepMelForSequencePrediction —— 混合卷积/循环网络（1D CNN + BiLSTM），正向链与反向互补链经共享编码器分别编码，分支平均 sigmoid 概率
适配状态: SUCCESS
适配时间: 2026-08-19

DeepMEL（Minnoye et al., 2020，Genome Research, Cross-species analysis of enhancer logic using deep learning）以黑色素瘤细胞系单细胞 ATAC-seq 数据训练，将可及的基因组区间建模为 24 个染色质主题，输入固定 500 bp 基因组窗口，输出每个主题的激活概率，用于解析增强子/调控元件逻辑及跨物种比较。

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

3. 模型结构

DeepMEL 将 500 bp DNA 序列 one-hot 编码（ACGT + N，反向互补在内部计算）后，经共享编码器逐分支编码：Conv1d(128, kernel=20, valid) → ReLU → MaxPool1d(10) → TimeDistributed(Dense 128) → BiLSTM(128, hard_sigmoid) → FC(256)；前向链与反向互补链各经 sigmoid 得到 24 个主题概率后分支平均（与上游 Keras 拓扑一致）。关键配置：

配置项	值
模型类型	DeepMelForSequencePrediction
卷积核	128 filters / kernel 20 / pool 10
BiLSTM 隐藏层	128（双向，hard_sigmoid）
FC 隐藏层	256
输入窗口（input_length）	固定 500 bp
主题数（num_labels）	24（multi-label）
输出形式	分支平均 sigmoid 概率（无 softmax 面）
词汇表	5（A/C/G/T/N，DnaTokenizer）
权重文件	model.safetensors（13,780,496 B）
权重 sha256	`dcf09b7210e1d777d924580a5c93050edc949607ba4ca10b76a769ee9ccf2889`

模型权重为官方 multimolecule 转换权重（与上游 aertslab/DeepMEL Keras 实现产生一致的中间表示），config architectures: DeepMelForSequencePrediction，无 id2label，输出通道为通用 topic_0..topic_23。

4. 服务化推理验证结果

4.1 CLI 推理（GRCh38 chr1:10000000..10000500 真实 500 bp 演示序列）

[demo] 未提供序列，使用 GRCh38 chr1:10000000..10000500 真实 500 bp 演示序列
模型路径: /opt/atomgit/models/deepmel
设备:     npu:0
序列长度: 500 bp（居中裁剪/补齐后 500 bp）
正在加载模型（首次加载会编译算子，可能较慢）...
模型加载完成，耗时 7.3s，参数量 3.445M

推理耗时: 685.5 ms
输出概率向量: (24,)  (24 个染色质主题, multi-label sigmoid)
NaN 检查: False
主题概率和: 0.924993  激活主题（p>0.5）: 0  （p>0.8）: 0

Top 染色质主题:
  topic_19      prob=0.1452
  topic_2       prob=0.1278
  topic_10      prob=0.1132
  topic_16      prob=0.0894
  topic_17      prob=0.0777
  topic_4       prob=0.0601
  topic_5       prob=0.0421
  topic_12      prob=0.0420
  topic_8       prob=0.0378
  topic_14      prob=0.0355
SUCCESS

演示序列来自 GRCh38 参考基因组 chr1:10000000..10000500（Ensembl REST API），位于高 GC 调控区附近。模型预测该窗口最活跃主题为 topic_19 / topic_2 / topic_10，24 个主题概率和为 0.925（multi-label 无需归一化到 1）。

4.2 HTTP 服务化推理

$ curl -s -X POST http://127.0.0.1:8000/v1/predict -H "Content-Type: application/json" -d '{"top_k": 5}'
{
  "sequence_length": 500, "window_length": 500, "num_labels": 24,
  "sum_probs": 0.924993, "n_active_gt_0_5": 0,
  "top_topics": [
    {"topic": "topic_19", "index": 19, "prob": 0.145205},
    {"topic": "topic_2",  "index": 2,  "prob": 0.12782},
    {"topic": "topic_10", "index": 10, "prob": 0.113167},
    ...
  ],
  "inference_ms": 111.79
}

4.3 调控变异效应推理

以演示序列（500 bp）为参考，在 pos 250 处做 C->G 点突变（SNP），模型预测 24 个染色质主题活性变化（alternative - reference），其中受影响最大的主题：

POST /v1/variant-effect
  {"reference": "<500 bp 演示序列>", "alternative": "<500 bp 序列, pos250 C->G>"}
  topic_19   ref=0.1452 -> alt=0.1344  delta=-0.0108  loss   （主导主题活性下降）
  topic_16   ref=0.0894 -> alt=0.0849  delta=-0.0045  loss
  topic_15   ref=0.0301 -> alt=0.0338  delta=+0.0038  gain
  topic_2    ref=0.1278 -> alt=0.1311  delta=+0.0033  gain
  topic_12   ref=0.0420 -> alt=0.0451  delta=+0.0031  gain
  n_variant_topics: 23   inference_ms: 294.99

单个 SNP 在 500 bp 窗口内对整体主题活性的影响较小（|delta| < 0.02），但模型可分辨出主导主题 topic_19 的活性下降与其他主题的补偿性上升，体现调控变异效应分析能力。

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

5.1 获取权重

# 方式一：git clone 镜像（无 git-lfs 时 model.safetensors 为 LFS 指针，见下）
git clone https://gitcode.com/hf_mirrors/multimolecule/deepmel.git /opt/atomgit/models/deepmel

# 方式二：LFS batch API 直取 model.safetensors（无 git-lfs 环境）
#   oid=dcf09b7210e1d777d924580a5c93050edc949607ba4ca10b76a769ee9ccf2889
#   curl -X POST https://gitcode.com/hf_mirrors/multimolecule/deepmel.git/info/lfs/objects/batch \
#     -H "Content-Type: application/vnd.git-lfs+json" \
#     -d '{"operation":"download","objects":[{"oid":"dcf09...2889","size":13780496}]}' \
#     取签名 URL 后下载
# 校验：
sha256sum /opt/atomgit/models/deepmel/model.safetensors
# dcf09b7210e1d777d924580a5c93050edc949607ba4ca10b76a769ee9ccf2889

5.2 安装依赖

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

5.3 命令行推理

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

# 指定序列（自动居中裁剪/补齐到 500 bp）
python3 inference.py \
    --model-path /opt/atomgit/models/deepmel \
    --sequence "ACGTACGT..." --device npu:0

# 调控变异效应：参考与替代序列必须同长。
# 示例：以演示序列（500 bp）为参考，将 pos250 的 C 改为 G 作为替代序列，
# 验证输出见 4.3 节。
python3 inference.py \
    --model-path /opt/atomgit/models/deepmel \
    --reference-file ./ref.fa \
    --alternative-file ./alt.fa --device npu:0

5.4 服务化推理（FastAPI）

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

5.5 调用示例

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

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

# 染色质主题活性预测（sequence 缺省用 GRCh38 chr1 演示序列）
curl -s -X POST http://127.0.0.1:8000/v1/predict \
  -H "Content-Type: application/json" \
  -d '{"sequence":"ACGTACGT...","top_k":10,"include_scores":true}'

# 调控变异效应预测（参考/替代必须同长；示例：500 bp 演示序列 pos250 C->G）
curl -s -X POST http://127.0.0.1:8000/v1/variant-effect \
  -H "Content-Type: application/json" \
  -d '{"reference":"<500 bp 序列>","alternative":"<500 bp 序列, pos250 位 C 改为 G>"}'

6. 服务化推理 API

端点	方法	说明
`/health`	GET	健康检查（返回 NPU 设备信息与模型状态）
`/v1/models`	GET	模型信息（模型 ID、任务、参数量、窗口长度、主题数）
`/v1/predict`	POST	染色质主题活性预测；请求体 `{"sequence": "...", "top_k": 24, "include_scores": true}`
`/v1/variant-effect`	POST	调控变异效应预测；请求体 `{"reference": "...", "alternative": "..."}`（同长）

/v1/predict 返回：24 个主题的分支平均 sigmoid 概率、Top 主题、激活统计（p>0.5 / p>0.8 的主题数）；include_scores=true 时附带完整 24 主题分数。 /v1/variant-effect 返回：参考/替代序列 24 主题概率及差值（gain/loss）。

7. NPU 适配说明

DeepMEL 为 1D CNN + BiLSTM 模型（非自回归 LLM），vLLM / vllm-ascend 无法服务；采用 multimolecule + torch_npu + FastAPI 方案在昇腾 NPU 上推理。
模型通过 multimolecule.DeepMelForSequencePrediction.from_pretrained 加载（config architectures: DeepMelForSequencePrediction），计算在昇腾 NPU （torch_npu 注册的 npu 后端）上进行。
输入固定 500 bp（config.input_length）：长度超出时居中裁剪、过短时由 DnaTokenizer 用 N（pad_token，id=4）补齐；attention_mask 将补齐位置置 0，嵌入层将对应 one-hot 置零（等效掩码）。模型内部 _check_input_length 校验输入必须恰为窗口长度。
输入支持 DNA 大小写与 N 占位；DnaTokenizer 直接编码 ACGTN，不做 T→U 转换（DNA 模型）。
模型输出为 logits（内部为 logit(mean(sigmoid(branch)))）， model.postprocess(outputs) 直接返回前向/反向互补两分支 sigmoid 概率的平均（multi-label 二分类，无需再套 softmax）。
one-hot 编码 F.one_hot 在 NPU 上仅触发 "internal format" 告警（输出正常，无需修补），与 Enformer 等部署一致。
首次推理会编译 NPU 算子（约 0.7s），warm 后单次推理约 50ms；服务化推理用 FastAPI（非 OpenAI 格式），inference.py 支持 CLI + --serve 双模式。

8. 目录结构

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

9. 精度与性能

场景	输入长度	耗时
CLI 推理（首次，含算子编译）	500 bp	685.5 ms
CLI 推理（warm，模型内 torch 计时）	500 bp	53.7 ms
HTTP `/v1/predict`（warm）	500 bp	111.8 ms
HTTP `/v1/variant-effect`（warm）	500 bp × 2	295.0 ms

模型权重 model.safetensors（13,780,496 B，sha256 dcf09b...2889）来自 gitcode 镜像 hf_mirrors/multimolecule/deepmel，与 HF 官方权重一致。
CPU 与 NPU 推理结果一致（24 主题概率最大偏差 1.98e-05）。