在昇腾 Atlas A3（910C）上部署 SLARM 动态场景重建模型：基于 CANN 8.2.RC1 的 NPU 推理实战
在昇腾 Atlas A3（910C）上部署 SLARM 动态场景重建模型：基于 CANN 8.2.RC1 的 NPU 推理实战
SLARM（Streaming and Language-Aligned Reconstruction Model for Dynamic Scenes，发表于 CVPR 2026）是一个前馈式动态场景重建模型，能够从稀疏多视角序列中统一完成动态场景重建、语义理解与实时流式推理，联合学习 3D 高斯（3D Gaussians） 与场景流（Scene Flow）。本文基于开源仓库中 SLARM 的 NPU 适配版本（位于 3d_vision/SLARM），完整讲解其在昇腾 Atlas A3（910C）环境上的环境搭建、模型与渲染算子安装、Waymo 数据准备、推理与评测全流程，并结合仓库源码深入解析 NPU 性能优化开关、模型命令行参数与评测指标实现，帮助读者在昇腾生态上直接复现 SLARM 的渲染可视化结果与量化评测指标。
SLARM 模型与 NPU 适配概览
SLARM 的核心能力是将动态场景重建、语义理解与实时流式推理统一到同一个前馈式网络框架中：
- 从稀疏多视角序列输入出发，前向推理直接输出 3D 高斯参数与场景流，无需逐场景优化；
- 支持实时渲染（RGB、深度）与语义分割，可将语义信息直接对齐到重建出的三维高斯上；
- 在运动估计、渲染质量、场景解析等多项任务上达到官方 README 所述 SOTA 水平：相比已有方法运动精度提升 21%、重建 PSNR 提升 1.6 dB、分割 mIoU 提升 20%（数据来自 README_en.md 与 README.md）。
从源码结构看，模型主体定义在 src/models/slarm.py 的 class SLARM(nn.Module, ...)（该文件第 174 行附近），内部通过 forward_gs_predictor、forward_motion_predictor、forward_feat_predictor、forward_decoder 等模块分工完成高斯参数预测、运动（场景流）预测、语义特征预测与可微渲染解码；模型构建与权重加载统一由 engine_tools.py 中的 build_model / load_model 完成，其中 --model slarm 会实例化 models.SLARM，--model storm 等会实例化 models.STORM_models 中的对应模型。本项目提供的 NPU 适配版本正是围绕这一模型，将渲染算子、环境变量与推理脚本全面对齐到昇腾 910C（Atlas A3）。
环境准备
本样例支持在昇腾 Atlas A3 环境（910C）上运行推理，官方适配版本依赖 CANN 8.2.RC1 与 torch / torch_npu 2.1.0。建议在独立的 conda 环境中完成安装，避免与已有深度学习环境冲突。
安装 CANN 8.2.RC1
- 从 CANN 官方下载页面获取
Ascend-cann-toolkit_${version}_linux-${arch}.run与Ascend-cann-kernels-${chip_type}_${version}_linux-${arch}.run两个软件包（版本对应 8.2.RC1），并按官方安装文档完成安装。 - 安装完成后，可通过如下命令确认 CANN 版本：
cat /usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/ascend_toolkit_install.info
# 例如输出：version=8.2.RC1
创建 Python 环境
conda create -n SLARM python=3.10 -y
conda activate SLARM
安装 PyTorch / torch_npu / torch-scatter
本样例的 torch 与 torch_npu 版本为 2.1.0，需要从 Ascend Extension for PyTorch 插件渠道下载与 CANN 版本匹配的安装包。请根据实际 torch 与 CANN 版本选择正确的 torch_npu 版本：
# 安装 PyTorch
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0
# 安装 torch-npu
pip install torch-npu==2.1.0.post13
# 安装 torch-scatter（需要先固定 setuptools 版本）
pip install setuptools==69.5.1
pip install torch-scatter==2.0.9 --no-build-isolation
注意：
torch-scatter是 SLARM 在高斯属性聚合等场景使用的扩展库，安装时必须使用--no-build-isolation，并提前将setuptools固定为 69.5.1，否则可能因构建环境问题安装失败。
模型代码与依赖安装
克隆仓库并进入项目目录
git clone https://gitcode.com/cann/cann-recipes-embodied-ai.git
cd cann-recipes-embodied-ai/3d_vision/SLARM
安装 Python 依赖
pip install -r requirements_npu.txt
requirements_npu.txt 中的核心依赖包括：timm、einops、jaxtyping、opencv-python-headless、matplotlib==3.7.3、imageio / imageio-ffmpeg（视频输出）、torch_kmeans / torch_pca、open3d（点云可视化）、plyfile（高斯 PLY 导出）、scipy==1.15.3 / scikit-learn==1.2.2 / scikit-image==0.20.0 / numpy==1.26.4（特征蒸馏与指标计算）、torchmetrics、wandb / tensorboard（日志）以及 nerfview / viser 等查看器依赖。
安装渲染算子 meta_gauss_render
SLARM 的可微渲染链路在 NPU 上依赖自定义算子包 meta_gauss_render（适配 torch 2.1.0 与昇腾 910C（A3）的特定版本）。渲染时主要调用链如下：
- src/utils/npu_rendering.py 从
meta_gauss_render导入AscendGaussRender，并从meta_gauss_render.npu导入CalcRender、get_render_schedule、get_num_vector_core等算子接口； - src/utils/rasterizer.py 导入
spherical_harmonics、flash_gaussian_build_mask、gaussian_sort、calc_render等经昇腾适配的 3DGS 算子（对应算子 C++ 实现位于 ops/ascendc/kernels）。
请参考仓库中专门为昇腾硬件适配的 3DGS 代码并从源码编译安装：gaussian_splatting README。安装完成后，如需替换为与当前运行环境匹配的算子版本，可使用仓库提供的 replace_meta_gauss_render.sh，其用法为：
bash replace_meta_gauss_render.sh <conda环境名> <渲染算子版本>
该脚本会将 src/utils 下对应版本的 projection_three_dims_gaussian_fused_${版本}.py 覆盖安装到 meta_gauss_render 包内（例如 /home/ma-user/anaconda3/envs/${环境名}/lib/python3.10/site-packages/meta_gauss_render/ops/projection_three_dims_gaussian_fused.py），从而保证自定义投影算子与当前 NPU 环境严格匹配。
安装用于语义对齐的 CLIP
pip install git+https://github.com/openai/CLIP.git
CLIP 用于提取文本标签特征并与 SLARM 预测的高斯语义特征做对齐（对应 engine_tools.py 中基于 FEAT_DIST 环境变量启用的 tools.feats_tools.get_text_label_feats / feat2class 流程）。
数据集与模型权重
Waymo Open Dataset
SLARM 在 Waymo Open Dataset 上训练与评测。完整的注册、下载与预处理说明见 Waymo 数据说明，这里概述关键步骤：
- 注册账号并安装 gcloud SDK：访问 Waymo Open Dataset 官网注册账号，安装 gcloud SDK 并完成认证。
- 建立数据目录：因为场景流标注与语义标注不在同一份原始数据中，需要下载两个版本：
mkdir -p ./data/waymo/raw_scene_flow
mkdir -p ./data/waymo/raw_1_4_3
- 下载原始数据：使用 preproc/waymo_download.py 按场景列表下载（可指定
--version区分waymo_open_dataset_scene_flow与waymo_open_dataset_v_1_4_3两个版本，也可指定--scene_ids只下载个别场景）：
python preproc/waymo_download.py \
--target_dir ./data/waymo/raw_scene_flow/training \
--split_file data/dataset_scene_list/waymo_train_list.txt \
--scene_ids 700 754 23
- 预处理：使用 preprocess.py 分别处理两个版本的原始数据，提取 images、lidar、calib、pose、dynamic_masks、ground、panoptic_segs 等键，并把标注 JSON 保存到
data/SLARM_data/annotations/waymo。 - 天空掩码提取：推荐使用 DepthAnything-v2 预测的相对深度图（低值表示远处、零值表示无限远即天空）配合 tools/extract_sky.py 生成
sky_masks。 - 最终整理：将处理后的数据软链接到
data/SLARM_data/datasets/waymo，并生成data/SLARM_data/scene_list/waymo_train.txt/waymo_val.txt场景列表（格式为annotations/waymo/training/segment-xxx.json每行一个）。
SLARM 权重与 Demo 数据
仓库提供 SLARM 权重与 demo 数据集，可从 README 中给出的华为云 OBS 链接（cann-recipes-embodied-ai/SLARM/SLARM.zip）获取。使用 demo 数据可以跳过全量 Waymo 下载与预处理，直接验证推理流程与评测指标。
运行推理
仓库已将 NPU 环境变量、性能优化配置与模型参数封装在 inference.sh（推理出可视化结果）与 evaluation.sh（出评测指标）两个脚本中。使用样例数据集与脚本默认配置，直接执行：
bash inference.sh # 输出可视化结果（视频）
bash evaluation.sh # 输出评测指标
使用脚本前必须配置的路径参数（脚本中目前为占位符）：
DATA_ROOT：数据集根目录路径（对应--data_root）CKPT_PTH：SLARM checkpoint 权重路径（对应--load_from）--lseg_model_scratch_path：LSeg 模型 scratch 权重路径（位于 inference.sh 中）--lseg_model_pretrained_path：LSeg 模型预训练权重路径（位于 inference.sh 中）
NPU 环境变量与性能优化开关
两个脚本头部均包含一组面向 NPU 的性能优化环境变量，含义如下（均来自脚本内注释及 src 源码逻辑）：
| 环境变量 | 取值 | 作用 |
|---|---|---|
DEVICE_TYPE |
NPU |
声明运行平台为 NPU |
ASCEND_RT_VISIBLE_DEVICES |
0 |
指定使用的 NPU 设备 ID |
AVOID_AI_CPU |
1 |
避免因 double 数据类型生成 AI_CPU 的 Sin/Cos 算子 |
USE_EQUAL_CROSS |
1 |
对 torch.cross 做等价替换，规避 NPU 上的算子缺失问题 |
TASK_QUEUE_ENABLE |
2 |
加速 host 侧任务分发，降低调度开销 |
PYTORCH_NPU_ALLOC_CONF |
expandable_segments:True |
开启虚拟内存段以节省设备显存 |
CONTEXT_FEAT |
1 |
不渲染特征，特征仅在输入视角做监督（配合 online_feat 使用） |
FEAT_DIST |
1 |
开启语义特征蒸馏相关逻辑（见 engine_tools.py） |
inference.sh 关键模型参数
inference.sh 通过 torchrun 拉起 inference.py，核心模型参数如下（默认值与可选范围参考 src/utils/parser.py 的 get_args_parser）：
| 参数 | 脚本取值 | 说明 |
|---|---|---|
--model slarm |
slarm | 模型类型（默认 slarm，另有 storm 等） |
--dataset waymo |
waymo | 数据集，可选范围见 DATASET_DICT |
--load_depth --load_flow --load_ground |
开 | 加载深度、场景流、地面标签 |
--num_max_cameras 3 |
3 | 上下文相机数量（默认 3） |
--use_affine_token |
开 | 使用仿射 token |
--sigmoid_rgb |
开 | 对 RGB 输出使用 sigmoid 激活 |
--num_motion_tokens 0 |
0 | 运动 token 数量（默认 16，推理置 0） |
--use_sky_token |
开 | 使用天空 token 表示天空区域 |
--embed_dim 768 |
768 | token 嵌入维度（默认 1024） |
--depth 12 |
12 | Transformer 层数（默认 24） |
--patch_embed conv --patch_size 8 |
conv / 8 | patch 化方式与 patch 尺寸（默认 dinov2_vitl14_reg / 14） |
--use_ms3_motion |
开 | 使用 MS3 运动表示（场景流/角速度相关） |
--use_last_token |
开 | 使用序列末尾 token |
--shortcut_rgb |
开 | RGB 预测使用 shortcut 结构 |
--add_patch_plucker_embed |
开 | 在 patch 嵌入中加入 Plücker 坐标嵌入 |
--similarity_probs_threshold 0.2 |
0.2 | 语义相似度概率阈值（默认 0.2，见 slarm.py） |
--online_feat --img_norm_for_online_feat |
开 | 在线特征提取（调用 LSegFeatureExtractor，见 inference.py build_feature_extractor） |
--scene_id / --scene_start_index / --scene_end_index |
0 / 0 / 15 | 推理场景 ID 与帧区间 |
--save_rendered_pc |
开 | 保存渲染点云，路径 output_rendered_pc_${SCENE_ID}_... |
--save_gaussian |
开 | 保存高斯参数，路径 output_gs_${SCENE_ID}_... |
--load_from |
$CKPT_PTH |
SLARM 权重路径 |
推理主流程（inference.py 的 main）依次为：setup_experiment 初始化日志目录 → build_model / load_model 构建并加载模型 → build_dataset 构建 SingleSequenceDataset → build_feature_extractor 加载 LSeg 特征提取器 → load_scene_data 读取指定场景帧区间 → generate_video_frames 通过 make_video 逐帧渲染 → 最终以 mp4 视频形式保存可视化结果。
evaluation.sh 关键参数
evaluation.sh 以 torchrun 拉起 eval_slarm.py，与推理脚本的区别在于：
- 增加
--evaluate进入评测模式，并使用--eval_batch_size 1； - 增加
--load_semantic_label加载语义标签以评测分割指标； - 增加
--enable_tensorboard将评测指标写入 TensorBoard； - 参数整体与训练时保持一致，保证
--load_from的权重可以无缝复现指标。
eval_slarm.py 会构建重建/语义评测与场景流评测两套 dataloader，分别调用 engine_tools.evaluate、evaluate_flow、evaluate_semantic 得到三组指标。
评测结果与指标解读
使用仓库提供的样例数据集与默认脚本配置，评测输出如下（原文完整保留）：
Average PSNR: 27.3069
Average SSIM: 0.8419
Average Depth RMSE (0.01-100m): 1.9343
Average Depth RMSE (100-200m): -1.0000
Average Depth RMSE (0.01-200m): 1.9343
Average Occupied PSNR: 27.4185
Average Occupied SSIM: 0.8366
Average Dynamic PSNR: 24.8740
Average Dynamic SSIM: 0.7683
Average Dynamic Depth RMSE (0.01-100m): 2.9485
Average Dynamic Depth RMSE (100-200m): -1.0000
Average Dynamic Depth RMSE (0.01-200m): 2.9485
Evaluated on 468 samples.
Valid depth samples (0.01-100m): 468
Valid depth samples (100-200m): 0
Valid dynamic depth samples (0.01-100m): 450
Valid dynamic depth samples (100-200m): 0
flow:
Average Flow EPE: 0.1406
Average Flow Acc Strict: 80.5886
Average Flow Acc Relax: 85.1571
Average Flow Angle: 0.3104
Average Flow RMSE: 0.2307
Evaluated on 182.0 samples.
segment:
Average Semantic mIOU: 0.6058
Average Semantic Accuracy: 0.9025
Evaluated on 21.0 samples.
指标背后的实现细节
评测指标在 engine_tools.py 中实现，可从源码确认以下口径：
- 深度 RMSE 分区间：源码顶部定义了
DEPTH_MIN_THRESHOLD = 0.01、DEPTH_MAX_THRESHOLD = 200.0、DEPTH_MID_THRESHOLD = 100.0三个阈值，分别对应评测输出中的0.01-100m/100-200m/0.01-200m三个深度区间；当某区间无有效样本时，_safe_divide返回-1.0000（对应输出中的100-200m区间）。 - PSNR / SSIM：PSNR 基于 MSE 计算（
-10 * log10(mse)），SSIM 使用skimage.metrics.structural_similarity，并分别对全图、占用区域（occupied_mask，即非天空区域）和动态区域（dynamic_mask）单独统计，对应输出中的 Occupied / Dynamic 系列指标。 - 场景流指标：通过
compute_scene_flow_metrics计算 EPE3D、严格/宽松 3D 精度、角度误差，并输出 Flow RMSE。 - 语义指标：通过
compute_semantic_metrics计算 Semantic mIoU 与 Accuracy（需要--load_semantic_label且数据集提供语义标签）。
与其他方法的性能对比
以下两表来自仓库 README（README_en.md），为官方在 Waymo Open Dataset（WOD）上复现或公开的结果。其中 SLARM-F 表示使用全注意力的离线模式，SLARM-W 表示使用窗口注意力的在线模式（对应 parser.py 中 --mode 参数的可选值 full / causal / window_N，其中 window_N 即滑动窗口注意力）。
表 1：WOD 数据集上光写实性与几何指标对比
| Method | Dynamic-only | Full image† | ||||
|---|---|---|---|---|---|---|
| PSNR↑ | SSIM↑ | D-RMSE↓ | PSNR↑ | SSIM↑ | D-RMSE↓ | |
| LGM | 17.36 | 0.216 | 11.09 | 18.53 | 0.447 | 9.07 |
| LGM* | 19.58 | 0.443 | 9.43 | 23.59 | 0.691 | 8.02 |
| GS-LRM* | 20.02 | 0.520 | 9.95 | 25.18 | 0.753 | 7.94 |
| MapAnything | - | - | - | - | - | 13.53 |
| STORM* | 22.03 | 0.623 | 7.50 | 25.86 | 0.804 | 5.47 |
| Ours | ||||||
| SLARM-W | 23.20 | 0.676 | 6.38 | 27.30 | 0.825 | 4.75 |
| SLARM-F | 23.51 | 0.691 | 6.16 | 27.49 | 0.828 | 4.57 |
注：* 表示由官方复现；† 表示非天空区域（Full image 列）。
表 2：语义分割性能定量对比
| Method | mIoU↑ | Acc↑ |
|---|---|---|
| EfficientViT-Seg | 0.4352 | 0.7637 |
| Mask2Former-R50 | 0.4429 | 0.7082 |
| SegMAN | 0.4567 | 0.7186 |
| SegFormer | 0.4660 | 0.7572 |
| OffSeg-B | 0.4612 | 0.7417 |
| OffSeg-L | 0.4868 | 0.7635 |
| LSeg | 0.4876 | 0.7976 |
| Mask2Former-Swin | 0.5505 | 0.8192 |
| SLARM | 0.6663 | 0.8923 |
按官方 README 的表述，SLARM 在语义分割的 mIoU 与准确率上均优于表中对比方法。
注意事项与常见问题
- 权重路径占位符：直接运行脚本前务必把
DATA_ROOT、CKPT_PTH、两个--lseg_model_*_path占位符替换为真实路径，否则会在数据集加载或load_model阶段报错。 - 渲染算子版本匹配：
meta_gauss_render必须与 torch 2.1.0、昇腾 910C（A3）严格匹配，必要时用 replace_meta_gauss_render.sh 替换对应版本的projection_three_dims_gaussian_fused实现。 - 双版本 Waymo 数据：场景流标注与语义标注分属
waymo_open_dataset_scene_flow与waymo_open_dataset_v_1_4_3两个版本，预处理与评测时需要两套数据配合（详见 Waymo 数据说明）。 - 环境变量不可省略：
AVOID_AI_CPU、USE_EQUAL_CROSS、TASK_QUEUE_ENABLE、PYTORCH_NPU_ALLOC_CONF等环境变量直接影响 NPU 上的算子生成、显存分配与调度性能，建议保持脚本默认值。
引用
如使用 SLARM 模型，请引用论文：
@InProceedings{Qiu_2026_CVPR,
author = {Qiu, Zhicheng and Meng, Jiarui and Luo, Tong-an and Huang, Yican and Feng, Xuan and Li, Xuanfu and Xu, Zhan},
title = {SLARM: Streaming and Language-Aligned Reconstruction Model for Dynamic Scenes},
booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
month = {June},
year = {2026},
pages = {29023-29034}
}