SAM3 模型离线推理指导

概述

SAM3 是 Meta 开源的多模态视觉分割模型。相比 SAM2，SAM3 优化了图像分割精度，并新增了视频实时分割能力。
本文档以 SAM3 的图像分割功能为例，介绍在昇腾 NPU 上的离线推理步骤。

• 参考实现：
  url=https://github.com/facebookresearch/sam3/blob/main/README.md
model_name=sam3

推理环境准备

所需插件与驱动版本如下。

配套	版本	环境准备指导
固件与驱动	25.3.RC1	-
CANN	8.5.0	-
Python	3.11.6	-
PyTorch	2.9.0	-
Ascend Extension PyTorch	2.9.0	-

注意：当前推理步骤仅支持 Atlas 800I A2 推理卡，其他型号暂未验证。

建议拉取华为昇腾社区提供的镜像：3.0.0-800I-A2-py311-openeuler24.03-lts

快速上手

1. 获取源码

git clone https://gitcode.com/ascend/ModelZoo-PyTorch.git
cd ModelZoo-PyTorch/ACL_PyTorch/built-in/cv/SAM3

2. 安装依赖

pip3 install -r requirements.txt

3. 准备模型权重

mkdir sam3_model

从 ModelScope 下载原始模型权重（sam3.pt 等文件）至 sam3_model/ 目录：
https://modelscope.cn/models/facebook/sam3

权重目录结构应如下：

sam3_model/
├── config.json
├── configuration.json
├── LICENSE
├── merges.txt
├── model.safetensors
├── processor_config.json
├── README.md
├── sam3.pt
├── special_tokens_map.json
├── tokenizer_config.json
├── tokenizer.json
└── vocab.json

4. 输入输出数据描述

SAM3 ONNX 模型包含单一网络，输入输出如下：

ONNX 输入

输入名称	数据类型	形状	排布格式
pixel_values	FLOAT32	batch_size × 3 × 1008 × 1008	NCHW
input_ids	INT64	batch_size × 32	ND
attention_mask	INT64	batch_size × 32	ND

ONNX 输出

ONNX 模型输出保持原始形状，无需额外 reshape：

输出名称	数据类型	形状	含义
pred_masks	FLOAT32	(batch_size, NUM_QUERIES, MASK_SIZE, MASK_SIZE)	预测掩码 logits
pred_logits	FLOAT32	(batch_size, NUM_QUERIES)	预测目标分数 logits
pred_boxes	FLOAT32	(batch_size, NUM_QUERIES, 4)	预测边界框 (cx,cy,w,h)
presence_logits	FLOAT32	(batch_size, 1)	存在性 logits
semantic_seg	FLOAT32	(batch_size, 1, MASK_SIZE, MASK_SIZE)	语义分割掩码

NUM_QUERIES 为模型固定查询数（通常为 200），MASK_SIZE 为掩码分辨率（通常为 288）。具体值可通过模型配置文件获取。

OM 输出（ATC 转换后）

OM 模型输出可能被展平为一维数组，后处理时需根据以下形状进行 reshape：

输出索引	OM 输出形状（展平）	目标形状（reshape 后）
0	batch_size × NUM_QUERIES × MASK_SIZE × MASK_SIZE	(batch_size, NUM_QUERIES, MASK_SIZE, MASK_SIZE)
1	batch_size × NUM_QUERIES	(batch_size, NUM_QUERIES)
2	batch_size × NUM_QUERIES × 4	(batch_size, NUM_QUERIES, 4)
3	batch_size × 1	(batch_size, 1)
4	batch_size × 1 × MASK_SIZE × MASK_SIZE	(batch_size, 1, MASK_SIZE, MASK_SIZE)

上述 reshape 操作在推理脚本（sam3_image_infer.py）中完成。

5. 导出 ONNX 模型

在获得 PyTorch 格式的原始模型权重（sam3_model 目录）后，需要先将其转换为 ONNX 格式，以便后续使用 ATC 工具转换为昇腾 OM 模型。

5.1 执行导出

python sam3_export_onnx.py --model_path ./sam3_model

参数说明：

• --model_path：指定 PyTorch 模型权重目录（即上一步准备的 sam3_model 路径）。

导出成功后，ONNX 模型默认保存在 ./sam3_onnx/sam3.onnx。用户可根据需要修改输出路径（修改脚本内的 output_dir 变量）。

6. 准备数据集

mkdir dataset

精度验证使用 sa-co-gold 数据集。下载地址：

• SA-1B 图像：https://sa-co.roboflow.com/gold/sa1b-images.zip
• MetaCLIP 图像：https://sa-co.roboflow.com/gold/metaclip-images.zip
• 真实标注：https://sa-co.roboflow.com/gold/gt-annotations.zip

解压后目录结构（示例根目录为 ./dataset）：

dataset/
├── gt-annotations
├── metaclip-images
└── sa1b-images

7. 模型转换（ONNX → OM）

7.1 配置环境变量

source /usr/local/Ascend/ascend-toolkit/set_env.sh

7.2 获取芯片名称

npu-smi info
# 根据回显确定 chip_name，例如 Ascend910B4

7.3 准备融合开关配置文件

创建 fusion_switch.cfg，内容如下（关闭 AutomaticUbFusion 以避免精度严重下降）：

AutomaticUbFusion:off

关闭该融合规则可能导致约 3% 的性能损失，但精度恢复至正常水平。

7.4 执行 ATC 转换

以 batch size = 4 为例：

batch_size=4
atc --framework=5 \
    --model=./sam3_onnx/sam3.onnx \
    --output=./sam3_om/sam3_bs${batch_size}_fusion_off \
    --input_format=NCHW \
    --input_shape="pixel_values:${batch_size},3,1008,1008;input_ids:${batch_size},32;attention_mask:${batch_size},32" \
    --soc_version=Ascend910B4 \
    --log=info \
    --fusion_switch_file=./fusion_switch.cfg

导出的 OM 文件会附加 OS 与架构后缀（如 _linux_aarch64.om），例如 sam3_bs4_fusion_off_linux_aarch64.om，请以实际文件名为准。 ATC 参数说明：

参数	说明
--framework=5	原始框架为 ONNX
--model	输入的 ONNX 模型路径
--output	生成的 OM 模型路径（不含后缀）
--input_format	输入数据排布格式，NCHW
--input_shape	指定各输入节点的 shape，需与 ONNX 导出时的形状一致
--soc_version	目标芯片型号，根据 npu-smi info 获取
--fusion_switch_file	融合开关配置文件

8. 推理验证

8.1 安装 ais_bench 推理工具

参考 ais_bench 推理工具 安装。

8.2 性能验证

运行以下命令测试 OM 模型性能（以 batch size = 4 为例）：

python3 -m ais_bench \
    --model ./sam3_om/sam3_bs4_fusion_off.om \
    --device 0 \
    --loop 100

ais_bench 参数说明：

• --model：OM 模型路径。
• --device：NPU 设备 ID（如 0）。
• --loop：推理循环次数，用于计算平均性能。

8.3 精度验证

执行：

python sam3_image_infer.py \
    --model_path ./sam3_om/sam3_bs4_fusion_off.om \
    --processor_path ./sam3_model \
    --dataset_root ./dataset \
    --device "0,1,2,3" \
    --batch_size 8

脚本参数说明：

参数	说明
--model_path	OM 模型路径
--processor_path	包含 tokenizer 和配置的 SAM3 处理器目录（即原始权重目录）
--dataset_root	sa-co-gold 数据集根目录，须包含 sa1b-images、metaclip-images、gt-annotations 子目录
--device	使用的 NPU 设备 ID 列表，逗号分隔（如 "0,1,2,3"）
--batch_size	推理 batch size，需与 OM 转换时的 batch size 一致

建议使用多卡并行推理，sa-co-gold 数据量较大，单卡耗时较长。

8.4 精度计算

评估脚本 sam3_image_infer.py 运行完成后，会在 --pred_dir（默认 ./gold_predictions）目录下为每个子集生成对应的预测结果 JSON 文件，例如 predictions_metaclip.json。

随后使用 batch_eval.py 脚本汇总各子集的预测结果，并与 Ground Truth 标注对比，计算最终的 cgF1 指标：

python batch_eval.py \
    --gt_base ./dataset/gt-annotations \
    --pred_dir ./gold_predictions

脚本行为说明
batch_eval.py 会自动扫描 --pred_dir 下所有 predictions_{subset}.json 文件，对每个子集调用 standalone_cgf1.py 计算 cgF1 分数。例如，对于 wiki_common 子集，实际执行的命令相当于：

python standalone_cgf1.py \
    --pred_file ./gold_predictions/predictions_wiki_common.json \
    --gt_files \
        ./dataset/gt-annotations/gold_wiki_common_merged_a_release_test.json \
        ./dataset/gt-annotations/gold_wiki_common_merged_b_release_test.json \
        ./dataset/gt-annotations/gold_wiki_common_merged_c_release_test.json

每个子集的 Ground Truth 可能由多个分片文件（_a_、_b_、_c_）组成，standalone_cgf1.py 支持通过多个 --gt_files 参数同时传入。

脚本参数说明

参数	说明
--gt_base	Ground Truth 标注文件所在根目录，默认为 ./dataset/gt-annotations。该目录下需包含 gold_{subset}_merged_{v}_release_test.json 格式的标注文件。
--pred_dir	预测结果 JSON 文件所在目录，默认为 ./gold_predictions。该目录下应存在 predictions_{subset}.json 格式的预测文件。

脚本输出

• 依次输出每个子集（metaclip、sa1b、crowded、fg_food、fg_sports_equipment、attributes、wiki_common）的 cgF1 值。
• 最后输出所有子集的 平均 cgF1 值，即为模型在 sa-co-gold 数据集上的最终精度指标。

模型推理性能

芯片型号	模型	Batch Size	性能 (fps)
Ascend910B4	sam3	1	4.3706
Ascend910B4	sam3	4	4.9664
Ascend910B4	sam3	8	4.6780

模型推理精度

芯片型号	模型	Batch Size	数据集	精度（cfg1）
Ascend910B4	sam3	1	sa-co-gold	0.5505
Ascend910B4	sam3	4	sa-co-gold	0.5505
Ascend910B4	sam3	8	sa-co-gold	0.5505

精度指标基于 sa-co-gold 数据集计算，采用 cgF1（Concept‑Guided F1）评价标准，具体定义可参考 SAM3 官方说明（https://github.com/facebookresearch/sam3/blob/main/README.md）。