zyzoe/sam3
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

facebook/sam3 on Ascend NPU (torch_npu 2.9.0.post1)

1. 简介

本文档记录 Meta SAM3 视频分割模型(facebook/sam3,Promptable Concept Segmentation,文本提示词驱动的开放词汇目标检测+跟踪+分割)在华为昇腾 NPU 上的适配与真机验证结果。

  • 架构:Sam3VideoModel(detector + tracker,model_type=sam3_video),参数量 0.86B,fp32 推理
  • 任务:video-segmentation(文本 prompt → 逐帧 mask/box/score 检测与跟踪)
  • 引擎:torch_npu,直接 .to("npu:0")
  • 适配要点:
    • transformers ≥ 5.15.1 才包含 Sam3VideoModel(4.57.x 无 sam3),本验证使用 5.16.0.dev0
    • 必须 attn_implementation="eager":NPU 上 SDPA(flash-attention) 路径对该 ViT 的 fp32 计算结果错误(详见第 9 节)
    • 需绕过 aclnnClamp 不支持 bool 张量的限制(processor 后处理补丁,inference.py 内置)
    • 权重从 HuggingFace/ModelScope 镜像获取(HF 官方仓库 gated,本次实际使用 ModelScope 镜像)

相关获取地址:

  • 权重下载地址(HuggingFace):https://huggingface.co/facebook/sam3
  • 权重下载地址(ModelScope 镜像,本次实际使用):https://www.modelscope.cn/models/facebook/sam3
  • 测试视频(sam2-fixtures bedroom.mp4):https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures

2. 验证环境

组件版本
CANN8.5.1
torch2.9.0+cpu(aarch64)
torch-npu2.9.0.post1
transformers5.16.0.dev0(≥5.15.1,需含 Sam3VideoModel)
Python3.11.14
  • NPU:Ascend910_9362(Atlas 800I A2,npu-smi 25.5.5,HBM 65536 MB)
  • 推理引擎:torch_npu
  • 权重路径:/tmp/bigw/facebook/sam3(约 3.44 GB,model.safetensors 1797 tensors 完整校验)
  • 任务类型:video-segmentation

3. 环境准备与权重获取

pip install -r requirements.txt   # transformers 需含 Sam3VideoModel(>=5.15.1)
npu-smi info
python -c "import torch, torch_npu; print(torch.npu.is_available())"

权重获取(HF 官方 gated,可用 ModelScope 镜像,实测约 3.44 GB):

python -c "from modelscope import snapshot_download; print(snapshot_download('facebook/sam3', cache_dir='/tmp/bigw'))"
export SAM3_MODEL_DIR=/tmp/bigw/facebook/sam3

4. 推理运行

已验证通过的命令(仅 NPU,不支持 CPU 参数):

export SAM3_MODEL_DIR=/tmp/bigw/facebook/sam3
# 精度 smoke(51 帧整段检测+跟踪)
python inference.py --device npu
# 性能测试(预热 5 次整段 pass + 正式 20 次)
python inference.py --device npu --warmup 5 --iters 20

5. Smoke 验证

python inference.py --device npu(prompt=person,bedroom.mp4 前 51 帧)在昇腾 NPU 上的真实输出:

[env] torch=2.9.0+cpu torch_npu ok, device=Ascend910_9362
[weights] /tmp/bigw/facebook/sam3
[model] Sam3VideoModel params=0.86B dtype=float32 device=npu (eager attention)
[input] video frames=200 prompt='person'
=== NPU (npu:0) 推理结果 ===
processed_frames=51 frames_with_masks=51
objects_detected_on_first_frame=2
total_mask_pixels=2317400 mean_max_score=0.9741
first_pass_wall=23.08s
frame0 object_ids: [0, 1]
frame0 scores: [0.9682, 0.9741]
frame0 boxes(xyxy): [[146.0, 135.0, 291.0, 404.0], [312.0, 0.0, 514.0, 394.0]]
[done] results -> /tmp/sam3_npu_results.json

验证结果:

  • 51/51 帧均有 mask 输出,第 0 帧检出 2 个 person 实例并全程跟踪
  • 最高检测分数 0.9741,均值 0.9741,检测框坐标合理
  • 加载门禁:from_pretrained(output_loading_info=True) 为 0 missing / 0 unexpected / 0 mismatched
  • config 审计:仓库 config.json 全部 28 个顶层键与 model.config.to_dict() 逐键比对,无功能性键丢失(仅遗留生成类默认参数被丢弃)
  • 随机初始化对照:同架构随机初始化模型在同一视频/prompt 上 0 检出 / 0 帧 mask,正确加载模型决定性胜出

6. 性能参考

测试条件:fp32 + eager attention,51 帧整段 pass(检测+跟踪全流程),预热 5 次 pass,正式 20 次 pass,前后 torch.npu.synchronize(),flock /tmp/npu_card0_perf.lock 独占测得。

指标数值
avg_ms22540.96 ms
p50_ms / p90_ms / p95_ms22407.08 / 23618.30 / 24031.28 ms
min_ms / max_ms22287.58 / 24031.28 ms
throughput2.26 frame/s(单卡单流)
  • p95/p50 = 1.07,无多 agent 共卡污染,p50/p90 为稳态口径
  • 单帧折算约 439 ms/frame(检测+跟踪+mask 解码全流程,fp32)

7. 精度评测

无权威公开基准需对齐;采用 CPU fp32 同输入参照 + 随机初始化对照双验证:

指标数值
数据集sam2-fixtures bedroom.mp4(51 帧)
样本数51 帧
评测方式CPU fp32 参照(图像检测 car 用例 score 0.686,NPU eager 0.8995 同样 >0.5 检出门限)+ 随机初始化对照
随机初始化对照0 检出 / 0 帧 mask(加载模型 2 实例 / 51 帧 / score 0.974)
平均最高检测分0.9741

8. 适配截图

  • agent workflow
  • npu device call
  • model result

9. 注意事项

NPU 上 SDPA(flash-attention)路径对本模型 fp32 计算结果错误,必须用 eager attention。

实际失败特征如下:

  • 现象:默认 SDPA 下检测分数全面塌缩(car 用例 pred_probs max=0.037,阈值 0.5,0 检出),CPU fp32 同输入为 0.686
  • 关键报错:无报错(静默数值错误);定位依据是逐段比对:vision encoder last_hidden_state CPU/NPU maxdiff=14.25(a_max=213),fpn_hidden_states maxdiff=0.446,最终 pred_logits maxdiff=4.68
  • 位置:Sam3ViTRoPEAttention / SDPA 路径(transformers/models/sam3/modeling_sam3.py)

原因不是权重加载或预处理,而是 NPU SDPA 算子在该 ViT(RoPE 相对位置偏置 + fp32)上的数值实现问题。

当前环境的可用处理方式:

Sam3VideoModel.from_pretrained(model_dir, dtype=torch.float32, attn_implementation="eager").to("npu:0")

其余注意事项:

  1. aclnnClamp 不支持 bool 张量:processor 后处理 torch.clamp(pred_masks, max=...) 对 bool mask 报 aclnnClamp failed, error code 161002 / DT_BOOL not implemented。inference.py 的 patch_processor 先转 float32 clamp 再转回,等价处理。
  2. transformers 4.57.x 无 sam3 模块;需 ≥5.15.1(Sam3VideoModel),且 5.15.x 还要求 tokenizers<=0.23.0(该 final 版未发布,可用 0.23.1 + transformers 主干 5.16.0.dev0)。
  3. transformers 提示 kernels library is not installed 时 NMS/填洞仅告警降级,不影响检出(本验证未装 kernels)。
  4. bf16(CPU 与 NPU 一致)检测分数同样塌缩(car max≈0.12),本模型在 transformers 移植下建议 fp32。

10. 标签

#NPU #Ascend