Ascend-SACT/torchfold-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

TorchFold NPU 部署与适配指南


一、概述

本文档记录 TorchFold(AlphaFold3 的 PyTorch 实现)在华为昇腾 NPU 上的完整部署、适配与验证过程。

TorchFold 官方已提供 NPU 版本,本任务以官方 NPU 代码为基础,在当前机器(CANN 9.1.0 / Ascend910)上完成环境搭建、依赖安装、NPU 推理验证、性能测试和 Profiling。

核心成果

成果状态
TorchFold 及依赖在 NPU 环境正确导入✅
模型 (368.5M 参数) 成功构建并移动到 NPU✅
完整前向传播 (Pairformer + Diffusion + Confidence) 在 NPU 上运行✅
Fusion Attention (npu_fusion_attention) 在 NPU 上实际调用✅ (Profiling 证实)
输出张量无 NaN/Inf✅
置信度指标 (pLDDT, pTM, ipTM) 计算完成✅
NPU Profiling 采集与分析✅
端到端结构文件生成 (CIF/PDB)✅ 5个diffusion样本, 274原子, 36残基

二、环境要求

2.1 硬件

项目要求当前环境
NPUAscend910 (64GB HBM)✅ 8卡×2芯片
CPUaarch64 (Kunpeng 920)✅ 640 核
内存≥64 GB✅ 2 TB
磁盘≥50 GB 可用✅ 35 TB

2.2 软件栈

组件参考版本实际版本兼容性
CANN8.3.RC1.alpha0019.1.0✅
Python3.113.11.6✅
PyTorch2.6.02.6.0+cpu✅
torch_npu2.6.02.6.0.post5✅
numpy1.26.41.26.4✅
mx_driving1.0.x1.0.20251219✅
triton-ascend≥3.2.0.dev3.2.0✅
jax0.4.340.4.34✅
jax-triton0.2.00.2.0 (已适配)✅
rdkit2024.3.52024.3.5✅

2.3 系统依赖

# AlphaFold3 C++ 构建需要 (需要 root):
dnf install -y zlib-devel python3-devel

三、安装步骤

3.1 获取代码

cd /home/opencode/hwtest_0413/pcy/0914torchfold

# TorchFold NPU 代码
git clone https://gitcode.com/AI4Science/Mingchenchen.git
# commit: 706654ba2b403aa458f821418d0b3e84bc915551

# AlphaFold3 代码
git clone https://github.com/google-deepmind/alphafold3.git
cd alphafold3
git checkout a14376d249099b3e64ae8010290d4e20720d2698
git apply ../Mingchenchen/alphafold3.patch
cd ..

# jax-triton 代码
git clone --branch v0.2.0 --depth 1 https://github.com/jax-ml/jax-triton.git

3.2 创建虚拟环境

/usr/bin/python3.11 -m venv env_tf311 --system-site-packages
source env_tf311/bin/activate

3.3 安装依赖

# PyTorch + torch_npu
pip install torch==2.6.0
pip install torch-npu==2.6.0.post5
pip install numpy==1.26.4 pyyaml attrs decorator psutil

# mx_driving (aarch64 cp311 wheel)
pip install Mingchenchen/torchfold/package/mx_driving-1.0.20251219-cp311-cp311-linux_aarch64.whl

# triton-ascend
pip install "triton-ascend>=3.1"

# JAX + AlphaFold3 依赖
pip install "jax==0.4.34" "jaxlib==0.4.34"
pip install "numpy==1.26.4" "ml-dtypes==0.4.0"
pip install "dm-haiku==0.0.13" "dm-tree==0.1.8" \
    "jaxtyping==0.2.34" "absl-py==2.1.0" "typeguard==2.13.3" "tqdm" "chex"
pip install "rdkit==2024.3.5"
pip install einops zstandard scipy pybind11

3.4 适配 jax-triton (NPU 兼容)

jax-triton 默认要求 JAX GPU 支持,在 NPU 环境会 ImportError。需两处修改:

修改 1: jax-triton/pyproject.toml

-  "triton>=3.1",
+  "triton_ascend>=3.1",

修改 2: jax-triton/jax_triton/__init__.py (lines 36-47) 将 GPU 检查的 ImportError 改为 UserWarning + dummy 函数:

try:
    get_compute_capability = gpu_triton.get_compute_capability
    get_serialized_metadata = gpu_triton.get_serialized_metadata
except AttributeError:
    import warnings as _warnings
    _warnings.warn(
        "jax-triton: JAX GPU support not found (CPU/NPU-only jaxlib). "
        "Triton kernel fusion via jax_triton will be unavailable. "
        "TorchFold PyTorch inference path is unaffected.",
        stacklevel=2,
    )
    get_compute_capability = lambda *a, **k: None
    get_serialized_metadata = lambda *a, **k: None
else:
    del gpu_triton
pip install -e jax-triton

3.5 安装 AlphaFold3

# 安装构建工具
pip install scikit-build setuptools_scm cmake

# 构建安装 (需要 zlib-devel, python3-devel)
cd alphafold3
pip install --no-deps --verbose .

# 生成化学组分数据
build_data
cd ..

3.6 安装 TorchFold

pip install -e Mingchenchen/torchfold

3.7 配置路径

修改 Mingchenchen/torchfold/scripts/env.sh 中的路径:

export JSON_PATH=<项目目录>/test_data
export DB_DIR=<项目目录>/databases
export MODEL_DIR=<项目目录>/alphafold3/src/alphafold3/model

3.8 准备权重

从官方 GCS 公开直链下载 AlphaFold3 权重:

cd alphafold3/src/alphafold3/model

# 1) 单流断点续传下载 (禁用 aria2c, 会损坏 zstd)
curl -C - --retry 20 --retry-delay 10 -o af3.bin.zst \
  https://storage.googleapis.com/alphafold3/af3.bin.zst

# 2) 解压 (使用 venv 的 zstandard)
source <项目目录>/env_tf311/bin/activate
python -c "
import zstandard
dctx = zstandard.ZstdDecompressor()
with open('af3.bin.zst', 'rb') as f_in, open('af3.bin', 'wb') as f_out:
    dctx.copy_stream(f_in, f_out)
print('解压完成')
"

# 3) 验证
sha256sum af3.bin.zst
# 预期: 74d0258616917cd122f5eab6d076afe4a8930e96823851e65e4f777dfb1f33ff

# 4) 清理压缩包 (可选)
rm af3.bin.zst

权重使用条款: https://github.com/google-deepmind/alphafold3/blob/main/WEIGHTS_TERMS_OF_USE.md


四、推理运行

4.1 快速启动

新建推理脚本 scripts_npu/run_npu_inference.sh 如下:

#!/bin/bash
# TorchFold NPU 推理启动脚本
# 用途: 在 Ascend NPU 上运行 TorchFold AlphaFold3 推理
# 用法: bash run_npu_inference.sh [INPUT_JSON_NAME] [DEVICE_ID]
# 示例: bash run_npu_inference.sh 37aa_test.json 0

set -e

PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
INPUT_NAME="${1:-37aa_test.json}"
DEVICE_ID="${2:-0}"

# 激活 venv
source "${PROJECT_DIR}/env_tf311/bin/activate"

# 设置 NPU 设备
export ASCEND_RT_VISIBLE_DEVICES=${DEVICE_ID}

# NPU 性能优化环境变量
export CPU_AFFINITY_CONF=1
export TASK_QUEUE_ENABLE=2
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export USE_DIST=0

# 检查权重
MODEL_DIR="${PROJECT_DIR}/alphafold3/src/alphafold3/model"
if ! ls "${MODEL_DIR}"/af3.bin* >/dev/null 2>&1; then
    echo "ERROR: 模型权重 af3.bin 不存在"
    echo "放置路径: ${MODEL_DIR}/af3.bin"
    exit 1
fi

# 检查输入文件
JSON_PATH="${PROJECT_DIR}/test_data/${INPUT_NAME}"
if [ ! -f "${JSON_PATH}" ]; then
    echo "ERROR: 输入文件不存在: ${JSON_PATH}"
    exit 1
fi

echo "================================================"
echo "TorchFold NPU 推理"
echo "  输入: ${INPUT_NAME}"
echo "  设备: NPU ${DEVICE_ID}"
echo "  权重: ${MODEL_DIR}"
echo "================================================"

cd "${PROJECT_DIR}/Mingchenchen/torchfold"
python run_alphafold.py \
    --run_data_pipeline=False \
    --json_path="${JSON_PATH}" \
    --model_dir="${MODEL_DIR}" \
    --output_dir="${PROJECT_DIR}/output" \
    --db_dir="${PROJECT_DIR}/databases" \
    --dot_product_attention=Fusion_Attention \
    2>&1 | tee -a "${PROJECT_DIR}/output/log/${INPUT_NAME}.log"

echo "================================================"
echo "推理完成"
echo "输出目录: ${PROJECT_DIR}/output"
echo "================================================"
cd /home/opencode/hwtest_0413/pcy/0914torchfold

# 运行推理 (需权重)
bash scripts_npu/run_npu_inference.sh 37aa_test.json 0

推理流程运行正常,核心模块全部执行完毕,日志输出如图所示。其中,设备探测阶段正确识别到 NPU(Found local device: npu);模型构建与权重加载阶段从 alphafold3/src/alphafold3/model/af3.bin 成功加载参数;推理阶段依次完整执行了 Temp Embed(4/4)、MSA stack(4/4)、Pairformer(10 轮 × 48/48)、Diffusion(5 样本 × 200/200)和 Confidence(5/5),无任何模块被跳过或替换。耗时方面,特征化(含一次性开销)耗时 3.93 秒(其中单 seed 特征化 0.11 秒),模型推理耗时 24.98 秒(Diffusion 约 20 秒,占主要开销),结构提取耗时 0.04 秒,推理与提取合计 25.02 秒,端到端(含特征化)约 29 秒。日志以 Done processing 1 fold inputs. 正常结束,Shell 返回提示符,退出码为 0。 alt text

4.2 手动运行

source env_tf311/bin/activate
export ASCEND_RT_VISIBLE_DEVICES=0

cd Mingchenchen/torchfold
bash run.sh 37aa_test.json

4.3 性能测试

bash scripts_npu/benchmark_npu.sh 0

4.4 Profiling

bash scripts_npu/profile_npu.sh 0
# Chrome trace: profiling/npu_trace.json (用 chrome://tracing 查看)

五、适配修改说明

修改原则

  1. 优先使用官方 NPU 代码,仅做必要的兼容性修改
  2. 不破坏 GPU 原始路径
  3. 修改通过设备判断或独立配置开关启用
  4. 不散落硬编码 "npu:0"
  5. 不用 try/except: pass 吞掉真实错误

修改清单

#文件类型GPU影响回滚
1jax-triton/pyproject.toml依赖名替换无git checkout
2jax-triton/jax_triton/init.pyNPU 兼容层无git checkout
3torchfold/scripts/env.sh路径配置无.orig.bak
4torchfold/run.shtcmalloc+pipeline无.orig.bak

详细 diff 见 docs/05_code_change_record.md。


六、验证结果

6.1 端到端推理验证 (真实官方权重)

验证项结果
权重加载✅ af3.bin (1.1 GB) 加载成功, 无 missing keys
模型构建✅ 368.5M 参数
NPU 移动✅ 1456.9 MB 显存
Pairformer (10轮×48块)✅
Diffusion (5样本×200步)✅
Confidence head✅
结构文件生成 (CIF)✅ 6 个 CIF 文件, 各 29 KB
原子记录数✅ 274 个 ATOM 记录
残基数✅ 36 (与输入序列一致)
3D 坐标合法✅ 真实坐标, 例如 MET A 1: N(-1.040, -26.709, -9.796)
输出 NaN❌ 无
输出 Inf❌ 无
pLDDT✅ 范围 [39.9, 80.71]
pTM✅ 0.40
PAE✅ 范围 [0.8, 30.5]
ranking_score✅ 最佳样本 0.90
退出码✅ 0
端到端耗时29s (5 个 diffusion 样本)

6.2 性能数据

端到端推理(真实权重,seed=1,5 个 diffusion 样本)

阶段耗时说明
特征化(Featurisation)3.93s其中单 seed 0.11s,其余为一次性开销
模型推理(Model inference)24.98s含 Pairformer + Diffusion + Confidence
├─ Pairformer(10 轮 × 48 块)<1sit/s 在 450–567,非瓶颈
├─ Diffusion(5 样本 × 200 步)~20sit/s 在 42–44,占推理约 80%
└─ Confidence(5/5)~0.07s73.79 it/s
结构提取(Extract structures)0.04s
推理 + 提取25.02s
端到端(含特征化)~29s3.93s + 25.02s
峰值 NPU 显存2169 MB权重加载后 1456.9 MB,推理峰值 2169 MB

6.3 Profiling 关键发现

算子调用次数NPU 时间占比
aclnnMatmul55,5130.525s16.9%
aclnnLayerNorm33,5700.372s12.0%
aclnnFlashAttentionScore22,8640.401s12.9%
aclnnAddmm31,7020.271s8.7%
总计418,1383.104s100%

由此可见,Fusion Attention 确认在 NPU 上运行。


七、目录结构

0914torchfold/

├── Mingchenchen/                   # TorchFold NPU 代码
│   ├── torchfold/
│   │   ├── run.sh                  # 推理脚本 (已适配)
│   │   ├── run_alphafold.py        # 推理入口
│   │   ├── scripts/env.sh          # 环境配置 (已适配)
│   │   └── torchfold/              # Python 包
│   └── alphafold3.patch
├── alphafold3/                     # AlphaFold3 代码 (补丁已应用)
├── jax-triton/                     # jax-triton (已适配)
├── env_tf311/                      # Python 3.11 虚拟环境
├── scripts_npu/                    # 辅助脚本
│   ├── check_environment.sh
│   ├── prepare_environment.sh
│   ├── prepare_test_input.sh
│   ├── run_npu_inference.sh
│   ├── validate_output.py
│   ├── benchmark_npu.sh
│   ├── benchmark_npu.py
│   ├── profile_npu.sh
│   └── profile_npu.py
├── test_data/                      # 测试输入
│   └── 37aa_test.json
├── logs/                           # 执行日志
├── profiling/                      # Profiling 产物
└── output/                         # 推理输出 (权重到位后)

八、常见问题

Q1: torch_npu 导入失败 (No module named 'yaml')

pip install pyyaml attrs decorator psutil

Q2: mx_driving 导入失败 (libc10.so not found)

确保 import torch 在 import mx_driving 之前执行。TorchFold 代码已满足此顺序。

Q3: AlphaFold3 构建失败 (ZLIB/Python3 not found)

dnf install -y zlib-devel python3-devel

Q4: jax-triton 导入失败 (requires GPU support)

见本文档 §3.4,修改 __init__.py 的 GPU 检查逻辑。

Q5: Featurisation 失败 (missing unpaired MSA)

在输入 JSON 中添加 unpairedMsa 字段 (自比对 MSA):

"unpairedMsa": ">seq_name\nYOUR_SEQUENCE"

Q6: tcmalloc 不存在

run.sh 中已注释掉 tcmalloc LD_PRELOAD。系统默认使用 jemalloc,功能不受影响。如需安装 tcmalloc 作为性能优化:

wget https://github.com/gperftools/gperftools/releases/download/gperftools-2.16/gperftools-2.16.tar.gz
tar -zvxf gperftools-2.16.tar.gz && cd gperftools-2.16
./configure --prefix=/usr/local/lib --with-tcmalloc-pagesize=64
make && make install
export LD_PRELOAD=/usr/local/lib/libtcmalloc.so.4

九、可复现命令

# 1. 检查环境
bash scripts_npu/check_environment.sh

# 2. 运行推理 (需权重 af3.bin)
bash scripts_npu/run_npu_inference.sh 37aa_test.json 0

# 3. 性能测试
bash scripts_npu/benchmark_npu.sh 0

# 4. Profiling
bash scripts_npu/profile_npu.sh 0

# 5. 验证输出
python scripts_npu/validate_output.py output/