liuhongwei-2026/aimnet2-wb97m-d3
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

isayevlab/aimnet2-wb97m-d3 昇腾 NPU 部署

将 HuggingFace 模型 isayevlab/aimnet2-wb97m-d3 适配并部署到华为昇腾(Ascend)NPU 上,实现基于 AIMNet2 图神经网络的化学势能 单点预测(能量 / 原子力 / 原子电荷 / 偶极矩 / 四极矩)的服务化推理与离线推理。

项目内容
模型来源isayevlab/aimnet2-wb97m-d3(HF / hf-mirror,约 34MB,4 个 ensemble safetensors)
模型类型计算化学 / 神经网络势(NNP / MLIP),AIMNet2 图神经网络
元素覆盖H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I(14 种主族与卤素元素)
任务单点能量(eV)、原子力(eV/Å)、原子电荷(e)、偶极矩/四极矩
DFT 级别ωB97M-D3(BJ)
精度FP32
部署方式torch_npu 原生推理(纯 torch 路径)+ HTTP 服务化(/predict、/health)
NPU 设备Ascend 910(npu-smi 25.5.5)

官方 AIMNet2Calculator 在构邻居表时依赖 NVIDIA Warp / CUDA-only (nvalchemiops.neighbor_list 与 conv_sv_2d_sp),昇腾 NPU 上会抛 Invalid device identifier: npu:0。本项目改用纯 torch 的 nb_mode=0 (全连接距离窗 + 余弦/指数截断包络)直接驱动 aimnet.models.AIMNet2.forward, 输出与邻居表策略物理等价——详见第 6 节适配说明。

1. 模型简介

AIMNet2-wb97m-d3(isayevlab, MIT)是一个面向主族与卤素元素有机物的神经 网络势,在 ωB97M-D3(BJ) 精度下输出分子能量、力、电荷与静电矩。4 个 ensemble 成员可用于不确定性估计。能量约定为逐元素 shift 后的电子能量标度(eV), 仅在同一模型家族内比较差值才有物理意义(如反应能、能垒)。

1.1 完整计算图(对齐官方 safetensors 权重)

输入 numbers[1,N] 原子序数(14 种) + coord[1,N,3]
 ├─ 嵌入 a                # features -> [1,N, nfeature=16]
 ├─ AEV(原子环境向量)
 │      d_ij = ||r_i - r_j|| (全连接对, 由截断包络在 cutoff 内保留, rc_s=5.0A)
 │      -> Gaussian 展开 + cosine/exp 截断包络 -> SV 特征   # 避开 CUDA conv_sv
 ├─ AIMNet2 消息传递 (*npass:3 组 512/380 MLP, GELU)
 ├─ Output (energy_mlp): MLP(256->128->128) + last_linear -> energy_ai
 ├─ AtomicShift / AtomicSum: 逐元素 shift + 原子求和 -> 分子能量
 ├─ SRCoulomb: 短程库仑 (rc=4.6A, exp envelope, 内嵌) 叠加到能量
 └─ Dipole / Quadrupole: 由原子电荷计算分子偶极/四极

官方权重以 ensemble_[0..3].safetensors + config.json(model_yaml) 保存, 本项目复用 aimnet 库的 load_from_hf_repo(纯 torch 构建)逐层严格加载。 默认加载 ensemble_0,可 --member 切换。

2. 验证环境

组件版本
OS / ArchLinux / aarch64
Python3.11
PyTorch2.9.0
torch-npu2.9.0.post1(gitee7ba04)
CANN8.5.1
aimnet0.2.0
safetensors0.8.0
numpy1.26.4

3. 目录结构

aimnet2-wb97m-d3/
├── inference.py        # 昇腾 NPU 推理 + HTTP 服务化脚本(必选)
├── README.md           # 本说明文档(必选)
├── requirements.txt    # 环境依赖清单(推荐)
├── config.json         # 模型配置(model_yaml)
├── ensemble_*.safetensors  # 4 个 ensemble 权重
└── assets/             # 部署截图素材(agent_workflow/npu_device_call/model_result)

4. 推理示例

# 环境安装(在已装好 torch_npu 的昇腾环境里)
pip install -r requirements.txt

# 内置氨单点能量(npu:0)
python inference.py --weights . --device npu:0 --example

# 读取 XYZ 文件,并计算原子力
python inference.py --weights . --device npu:0 --xyz input.xyz --forces

# 换 ensemble 成员(0-3)
python inference.py --weights . --device npu:0 --member 1 --example

# 服务化推理(/predict + /health)
python inference.py --weights . --device npu:0 --serve --port 8000

# 另开终端 curl 调用
curl -s http://127.0.0.1:8000/predict \
  -H 'Content-Type: application/json' \
  -d '{"coords":[[0,0,0],[1.02,0,0],[-0.51,0.8833,0],[-0.51,-0.8833,0]],
       "numbers":[7,1,1,1],"charge":0.0}'
curl -s http://127.0.0.1:8000/health

5. 输出示例(Result)

[load] ensemble member 0 on npu:0
[result] 体系: ammonia (built-in)
  能量 energy: -1530.71 eV
  atomic charges: [-0.907, 0.302, 0.302, 0.302]

单点能量约为 -1530.71 eV —— 符合 AIMNet2 的逐元素 shift 电子能标度, 不能当作绝对 ωB97M-D3 电子能量,仅用于同模型下能量差(能垒、反应能) 比较。

6. NPU 适配说明(关键)

  1. AIMNet2Calculator 的邻居表 n5valchemiops.neighbor_list 依赖 NVIDIA Warp (仅 cuda 后端)。昇腾上会 ValueError: Invalid device identifier: npu:0。
  2. d2features=true 触发 conv_sv_2d_sp(注册时仅 device_types=["cuda"]), 对 NPU 会落到纯 torch 的 einsum 分支(见 aimnet/modules/aev.py)。
  3. 本项目用 nb_mode=0(全连接距离窗口) 直接调用 aimnet.models.AIMNet2.forward; nbops 邻居索引(index_select/scatter_add_)本身是纯 torch,可在 NPU 执行;cutoff(5.0A) 外的对由截断包络自动置零,与邻居表策略数值等价。
  4. D3(BJ) 色散与长程库仑(LRCoulomb/DSF)在官方栈为外置项,依赖 CUDA-only 的 nkvalchemiops(Warp)。本项目输出模型内嵌前向,已含 SRCoulomb 短程 库仑(coulomb_mode: sr_embedded);如需完整 wb97m-D3 色散,可另行在纯 torch 中实现 DFT-D3(本交付聚焦 NPU 可跑通的模型内嵌推理)。
  5. force 计算走 torch.autograd.grad,NPU 上同样可用。

7. 服务化 HTTP 接口

方法/路径描述
GET /health探活,{"status":"ok","device":"npu:0"}
POST /predict单点推理

/predict 请求 JSON:

{
  "coords": [[0,0,0], [1.02,0,0], ...],  // [N,3] 坐标 (Angstrom)
  "numbers": [7, 1, 1, 1],              // [N] 原子序数 (14种)
  "charge": 0.0,
  "forces": false
}

响应 {"energy_eV":…, "charges_e":[…], "dipole":[…], "quadrupole":[…], "forces":…}。

8. 文件说明

  • inference.py:模型加载 / 单点推理 / HTTP 服务化。
  • ensemble_*.safetensors:4 个 ensemble 成员权重(8.8MB each)。
  • config.json:模型配置与 metadata(model_yaml、cutoff、coulomb、species)。
  • assets/:部署截图(agent_workflow / npu_device_call / model_result)。