安装¶
各后端(MACE、DPA、GRACE、UMA,以及需要显式选择的 NEP)各自依赖不同的运行时栈,放在同一个环境里经常
冲突。所以安装脚本给每个后端单独建一个环境,每个环境里各装一份 mliport。.venv-mace
里的 mliport 只能跑 MACE,.venv 里的只能跑 UMA,其余类推。需要哪个后端就装哪个,用的
时候从对应环境里调用 mliport。
安装脚本¶
先装好 uv,再克隆仓库:
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/hydrogen1222/mliport
cd mliport
有 NVIDIA GPU 且驱动正常的机器(在 V100-SXM2-16GB、驱动 580.173.02 上测试过):
没有 GPU 的机器:
NEP 需要显式选择:它不在默认引擎列表里,因为它的原生路径还需要你自己编译的 gpumd
(见 NEP):
./scripts/install_mliport.sh --engines nep --device cpu # CPU 的 ASE 路径(Calorine CPUNEP)
./scripts/install_mliport.sh --engines nep --device auto # 有 GPU 的机器;结尾的 doctor 需要你编译的 gpumd
与其他后端一样,.venv-nep 在同一次依赖解析里装入固定版本的 calorine 和可编辑安装的
mliport,所以 .venv-nep/bin/mliport 一定存在,doctor 才能运行。安装脚本不会编译
gpumd。用 --device cpu 安装时不需要 gpumd,CPU 的 ASE 路径装好即可使用。用 --device cuda,或者在
有 NVIDIA GPU 的机器上用 --device auto,结尾的 doctor 会检查 CUDA 路径,在 PATH 或
MLIPORT_GPUMD_COMMAND 里找不到 gpumd 时会报错并点名 gpumd。此时环境已经装好,但
bin/mliport-nep 启动器要等所有步骤都成功才会写出;可以编译好 gpumd 后重新运行安装脚本,也可以改用
--device cpu 或 --skip-doctor 安装(期间直接用 .venv-nep/bin/mliport)。
环境已经存在时重新运行安装脚本,会在执行任何步骤之前先做一次明确的判定。兼容的环境(真正的虚拟环境、
Python 版本符合要求、且不含其他后端的软件包)会被复用,其中的固定版本依赖就地重新解析安装;其他情况一律拒绝:
路径上是普通目录、解释器无法报告版本、用别的 Python 版本建的 venv,或者环境里已经装了其他后端的框架(例如
.venv-nep 里有 torch)。拒绝时会说明原因、不改动任何东西,并提示你加 --clean;--clean 只会删除并重建
你所指定后端的环境(只动这些)。只要部分后端时,--engines 后面少写几个就行。--dry-run 只打印要执行的步骤,不真正安装。
安装结束时脚本会在每个环境里运行一次 mliport doctor(加 --skip-doctor 可以跳过)。分析、
输运和电解质相关的依赖会一起装好,不用另外安装。
安装脚本还会在 ./bin/ 里生成几个启动脚本:
./bin/mliport-mace sp structure.cif --model model.model --model-type mace
./bin/mliport-uma sp structure.cif --model uma.pt --model-type uma
启动脚本只负责选对 Python 环境,模型、精度等计算参数仍要你自己指定。
哪个环境跑什么¶
| 后端 | 环境 | Python | 运行时 |
|---|---|---|---|
| UMA (FAIRChem) | .venv |
3.11, 3.12, 3.13 | fairchem-core==2.25.0 (torch 2.13.0) |
| MACE | .venv-mace |
3.10, 3.11, 3.12, 3.13 | mace-torch==0.3.16 (torch 2.8.0) |
| DPA (DeepMD-kit) | .venv-dpa |
3.10, 3.11, 3.12, 3.13 | deepmd-kit @ git+https://github.com/deepmodeling/deepmd-kit.git@0edeaef5617e9878edeb2346bf37bb6a035a4f51 (torch 2.11.0) |
| NEP (Calorine / GPUMD) | .venv-nep |
3.10, 3.11, 3.12, 3.13 | calorine==4.1(NumPy/ASE 由安装器解析;gpumd 需用 CUDA Toolkit 12.9 编译) |
| GRACE | .venv-grace |
3.10, 3.11, 3.12, 3.13 | tensorpotential==0.6.0 (tensorflow 2.20.0) |
NEP 一行括号里的两个东西不是同一个版本:Calorine 运行在 NumPy 和 ASE 之上,二者由安装器与
mliport 一起解析(不单独锁定);CUDA Toolkit 12.9 则是单独编译的 gpumd 二进制所验证过的
工具包版本。
Python 一列是该后端可用的 Python 版本,取 mliport、后端本身和所需框架三者支持范围的交集。
这张表由兼容性注册表(mliport/mliport/install/compatibility.py)自动生成,具体的版本锁定
也写在那里。
可以用 --python 指定解释器版本,但它必须同时满足所选的每一个后端。像
--python 3.10 --engines uma 这种装不上的组合,会在开始安装前就报错,脚本不会自作主张换
版本。
检查安装¶
.venv-mace/bin/mliport doctor --engine mace --device auto
.venv-dpa/bin/mliport doctor --engine dpa --device auto
.venv-grace/bin/mliport doctor --engine grace --device auto
.venv/bin/mliport doctor --engine uma --device auto
.venv-nep/bin/mliport doctor --engine nep --device cpu # 若安装了 NEP
必需的检查都通过时,命令以 0 退出,最后一行类似 Environment checks passed for MACE on CUDA.。
报告里还会列出可选功能(TUI、分析、输运、电解质、绘图)是否可用。想顺便用真实模型试算一次,
加上 --model PATH --task TASK --structure FILE。doctor --json 输出同样内容的 JSON,方便在
集群上做自动化部署。
运行 mliport¶
从对应后端的环境里调用命令:
.venv-mace/bin/mliport sp structure.cif --model model.model --model-type mace
.venv-dpa/bin/mliport sp structure.cif --model model.pt --model-type dpa --head Omat24
.venv-grace/bin/mliport sp structure.cif --model saved_model --model-type grace
.venv/bin/mliport sp structure.cif --model uma.pt --model-type uma
.venv-nep/bin/mliport sp structure.cif --model nep.txt --model-type nep --nep-runtime ase --device cpu
./bin/ 里的启动脚本执行的就是这些命令。Windows 上每个环境里有一个 Scripts\mliport.exe,
安装脚本也会在 bin\ 里生成 mliport-*.cmd:
DPA、GRACE 与 GPU¶
DPA 和 GRACE 的框架一旦加载,就不能再换 GPU。如果没有设置 CUDA_VISIBLE_DEVICES,命令行
会新开一个进程,只让你指定的那块 GPU 可见,再重新执行同一条命令,并打印一行说明。Python
API 没法重启调用它的程序,所以在 Python 里用 DPA 或 GRACE 时,请在导入框架之前自己设置
CUDA_VISIBLE_DEVICES(设为 "" 表示用 CPU)。
模型¶
mliport 不负责下载模型。请用上游工具下载模型文件,再用 --model 传入路径;本地文件离线也
能用。下载地址、验证时用到的文件名和 SHA-256 见模型。
如果要通过 SOCKS 代理从 Hugging Face 下载,请在用来下载的环境里装 httpx[socks],并且
NO_PROXY 里不要有 [::1] 这种带方括号的写法,httpx 不认。设置
HF_ENDPOINT=https://hf-mirror.com 可以改用镜像站。安装脚本通过 uv 联网,读取的是同样的
代理变量。
GPU 架构¶
PyTorch 和 TensorFlow 针对不同代的 GPU 提供不同的 CUDA 版本,安装脚本会自动选择:
Maxwell、Pascal、Volta 用 cu126,Turing 及更新的用 cu128 或更高。CUDA 13 频道(cu130,
UMA 运行时从 torch 2.13 起使用)需要 580 或更新的 NVIDIA 驱动,而且该构建不包含 Turing
以下的内核,所以 Volta 继续留在 cu126,老驱动也能用。mliport setup 会打印检测到的 GPU
和准备采用的安装方案。
| 引擎 | Maxwell | Pascal | Volta / V100 | Ada / RTX 4090 | Other Turing+ | Hopper / Blackwell |
|---|---|---|---|---|---|---|
| UMA | 实验性 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 |
| MACE | 实验性 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 |
| DPA | 实验性 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 |
| NEP | 实验性 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 实验性 |
| GRACE | 实验性 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 需运行时冒烟测试 | 实验性 |
表中的标记含义:实验性 表示上游框架不测试这一代 GPU;需运行时冒烟测试 表示有可用的安装
方案,但 mliport 还没在这类硬件上实际跑过。这两种都还没验证。目前只有 V100 有实测记录,其
他型号的分类是检查 wheel 和原生扩展得出的(编译进去的架构列表、+cu126/+cu128 wheel 的
哈希、cuobjdump 输出),详见
架构报告。
mliport doctor 会对检测到的 GPU 打印这个分类。
Turing 之前的 GPU 依赖 CUDA 12.6 版本,而 PyTorch 从 2.15 起不再提供。这类机器上请保持安装 脚本装的版本,不要升级框架;CUDA 13 的构建在这里也帮不上忙,因为它不包含 Turing 以下的内核。
离线机器¶
用 --source offline 指向事先准备好的 wheel 缓存,或者在联网机器上装好再把环境拷过去。需要
拷贝的只有 uv 的缓存(UV_CACHE_DIR)和模型目录。设置 UV_PYTHON_DOWNLOADS=never 可以禁止
安装脚本下载 Python 解释器。
磁盘占用与卸载¶
四个后端都装 GPU 版大约占 25–35 GB,大部分是 PyTorch 和 TensorFlow;CPU 版小一些。要删掉
某个后端,直接删除它的环境目录(.venv-mace、.venv-dpa、.venv-grace、.venv-nep 或 .venv)即可,
仓库和模型文件不受影响。./bin/mliport-* 启动脚本可以连同 bin/ 目录一起删。需要时重新
运行安装脚本即可恢复。
手动安装¶
每个后端环境里都要装 mliport 和该后端的依赖。准确的版本锁定在
mliport/mliport/install/compatibility.py,安装脚本会按你的 GPU 型号选对版本,所以推荐用脚本
安装。如果一定要手动装:每个后端建一个环境,在每个环境里都装一次 ./mliport,然后运行
mliport doctor,全部检查通过后再开始计算。只在一个环境里装 mliport,其他环境是用不了的。