multimolecule/hal 在昇腾 NPU 上的适配

1. 简介

• 模型来源：multimolecule/hal（Hexamer Additive Linear model，HAL）
• 参数量：0.004M（4096 个 hexamer 系数）
• 模型任务：替代性 5' 剪接位点使用度打分 —— 依据 160 nt 供体区（donor-region）窗口的归一化 hexamer（6-mer）频率，输出单个剪接分数；可对参考/突变窗口成对比较评估剪接变体效应（splice-variant-effect）
• 适配状态：成功
• 适配时间：2026-08-19

2. 验证环境

3. 模型说明

HAL 是一个线性（加性）查表评分模型，由 Rosenberg 等（Learning the Sequence Determinants of Alternative Splicing from Millions of Random Sequences, Cell 2015）从大规模平行报告实验（MPRA）中学得：

1. 输入为 160 nt 固定供体区窗口，字母表 ACGU（T 自动转 U）；
2. 统计窗口中每个 hexamer（6-mer，共 4096 种）的出现频率并做归一化（跨越 N 的 hexamer 被忽略）；
3. 公开系数表为 (4096, 8) 的 hexamer 效应矩阵，8 列平均后得到每个 hexamer 的单个效应；
4. 剪接分数 = 归一化 hexamer 频率与 hexamer 系数的线性组合（nn.Linear(4096, 1, bias=False)），输出单个标量分数；
5. 变体效应：对参考窗口与变体窗口分别打分，delta = score_variant - score_reference，再对 delta 施加 sigmoid 得到"突变提高供体使用度"的概率。

注：HAL 是判别式评分模型而非自回归生成模型，vLLM-Ascend（自回归文本生成引擎）无法加载。本仓库通过 multimolecule + torch_npu 直接在 Ascend NPU 上运行，并用 FastAPI 提供 OpenAI 兼容的服务化推理。

4. 适配说明

• 算子全部为标准 PyTorch（embedding 查表 / scatter_add 频数统计 / Linear / Sigmoid），无 CUDA-only 依赖，torch_npu 直接映射到 NPU AICore，代码零改动；
• 权重以 fp32 加载（config 原生精度），避免 bf16/fp16 精度损失；
• 固定 160 nt 输入窗口：短序列自动在 3' 端补 N（含 N 的 hexamer 被忽略，不贡献特征）；长序列以步长 1 做 160 nt 滑窗扫描并返回最高分窗口，用于扫描序列中的潜在强供体位点；
• 变体效应接口按模型卡协议实现：窗口分数相减后外部施加 sigmoid。

5. 目录结构

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

6. 环境准备

# 建议配置华为镜像源加速
export PIP_INDEX_URL=https://repo.huaweicloud.com/repository/pypi/simple/

pip install -r requirements.txt

权重目录（config.json / model.safetensors / tokenizer_config.json / vocab.txt）放置于 /opt/atomgit/models/hal，也可通过 --model-path 指定其它位置。来源：https://huggingface.co/multimolecule/hal（镜像 https://gitcode.com/hf_mirrors/multimolecule/hal）。

7. 使用方式

7.1 单序列剪接打分

python3 inference.py --model-path /opt/atomgit/models/hal \
    --device npu:0 --seq "UUAAUGCUAAUCGUGAUAGGGGUU"

7.2 变体效应评估

python3 inference.py --model-path /opt/atomgit/models/hal \
    --device npu:0 --ref "ACGUACGU..." --variant "ACGAACGU..."

输出参考分数、突变分数、delta 与 P(变体提高供体使用度)=sigmoid(delta)。

7.3 精度 / 性能基准（CPU 参考 vs NPU 余弦相似度）

python3 inference.py --benchmark --model-path /opt/atomgit/models/hal \
    --device npu:0 --n-runs 20

7.4 服务化推理（FastAPI，OpenAI 兼容）

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

# 模型列表
curl http://127.0.0.1:8000/v1/models

# 剪接打分
curl http://127.0.0.1:8000/v1/predict -H 'Content-Type: application/json' \
    -d '{"sequence": "UUAAUGCUAAUCGUGAUAGGGGUU"}'

# 变体效应
curl http://127.0.0.1:8000/v1/variant-effect -H 'Content-Type: application/json' \
    -d '{"reference": "ACGUACGU...", "variant": "ACGAACGU..."}'

# OpenAI 兼容 chat 接口
curl http://127.0.0.1:8000/v1/chat/completions -H 'Content-Type: application/json' \
    -d '{"model": "hal", "messages": [{"role": "user", "content": "UUAAUGCUAAUCGUGAUAGGGGUU"}]}'

7.5 服务端点一览

8. 实测结果（Ascend 910B NPU）

9. 参考

• 模型卡片：https://huggingface.co/multimolecule/hal
• 论文：Rosenberg, A. B., Patwardhan, R. P., Shendure, J., & Seelig, G. (2015). Learning the Sequence Determinants of Alternative Splicing from Millions of Random Sequences. Cell.
• MultiMolecule 文档：https://multimolecule.danling.org