一天一个昇腾Agent-Skills小技巧：实现SAM 3.1模型的Ascend OM路线适配

SAM 3.1是一个典型的经典深度学习模型系统，其推理链路涉及文本、视觉、目标定位（Grounding）、视频追踪以及记忆（Memory）更新等多个模块。针对这类模型的昇腾推理适配，关键不仅在于生成单个ONNX或OM模型文件，更在于梳理真实的业务入口，识别具有实际价值的高效子图，并确保生成的产物能够稳定地接回原有的处理流程。

本文介绍的昇腾Agent-Skills主要面向经典深度学习模型的适配需求，提供了一套完整的工作流程，涵盖从源码分析、候选识别、ONNX与ATC转换，到最终接回验证的各个环节。借助这一工作流，针对SAM 3.1模型成功开展了Ascend OM路线的适配实践，顺利打通了基于文本提示的视频分割主路径，并在此基础上沉淀出一条可复用、且能够持续演进的智能化部署路径。

SAM3.1官方结构图

图 1 SAM3.1掩码预测流程（Pipeline）概述

该图展示了一种用于处理给定输入中目标嵌入的模型架构。整体流程被划分为两个主要空间：数据空间与复用空间。

数据空间：在该空间中，逐目标掩码被应用于目标嵌入，并将处理后的结果传递至下一阶段。

复用空间：该空间包含多个协同工作的组件，具体说明如下：

复用器（Mux）：将目标嵌入与逐目标掩码进行组合，以供后续处理使用。

记忆编码模块：对记忆信息进行编码，并存储由此产生的相关数据表征。

记忆库：用于存放上一阶段编码所得到的记忆表征。

记忆注意力机制：根据当前上下文，有选择地关注记忆库中的相关信息。

图像编码器：对当前帧图像进行编码，为后续处理提供特征表示。

掩码解码器：对处理过程中生成的掩码信息进行解码。

解复用器（Demux）：将系统的最终输出进行拆分，并分别传递给下游的不同任务或组件。

该系统的各组成部分按顺序协同工作，依次对目标嵌入和记忆表征进行处理与注意力建模，从而实现对视觉数据的有效编码与解码。

结构流程图清晰地展示了SAM 3.1在视频场景下的核心计算链路，也为本次适配过程中模块拆分、子图规划以及主路径的接回提供了直观的参考依据。

本次适配取得的主要成果如下：

完成了从SAM3.1源码入口分析到ONNX/OM模型产出的完整适配流程。

明确了文本编码、视觉骨干网络（Backbone）、目标定位（Grounding）、特征传播（Propagation）、掩膜记忆（Mask Memory）等关键模块的部署边界。

形成了“多个OM模型+原始编配层（Orchestration）”的接回方案。

打通了基于文本提示的视频分割主路径，为后续图融合与进一步性能优化工作奠定了良好基础。

核心主线：

基于Agent-Skills的端到端适配实践

针对上述挑战，本次适配不再采用传统的手工切图摸索，而是基于Agent-Skills 提供的一套完整工作流。我们将复杂的适配过程抽象为四个核心阶段，通过deployer、adapter和atc-pipeline三个核心Skill的协同工作，沿着SAM 3.1的真实推理路径，逐步完成端到端的昇腾OM迁移。

阶段 1：全局入口盘点与候选拆解（核心介入：ascend-om-deployer）

功能定位与核心能力

作为主编排Skill，ascend-om-deployer负责梳理SAM 3.1的目标功能范围、明确真实的推理入口，并整理候选子图集合。它能够识别模型的真实推理入口（而非仅关注单个模块的forward()方法），并将庞大的模型拆分为可供分阶段推进的候选单元，形成可持续推进的适配闭环。

迁移实践落地：确认输入场景与圈定优先模块

适配工作从predictor入口出发，我们首先梳理用户实际调用的业务主路径，明确本次需优先覆盖的核心流程。以下以官网dog.gif连续视频样例作为验证案例，展示主路径输入与多帧传播输出之间的对应关系。构建流程为：predictor → 初始化视频状态 → 添加文本提示 → 初始化目标掩码 → 多帧传播 → 输出逐帧目标掩码。

主路径确认后，进一步梳理共享主干（Backbone）、Grounding、传播解码等关键模块，从中优先选取边界清晰、复用度高、对主路径打通价值最大的部分，纳入首批适配范围。

图 2 左侧为官网dog.gif第20帧原始输入（含原视频自带字幕），右侧为同一帧的OM连续跟踪结果

图 3 Task Record中记录了权重、测试输入、目标SoC以及执行计划，有助于后续定位适配边界与生成产物

图 4 对模型功能入口进行全面盘点，

明确本次适配聚焦的主路径范围

图 5 对候选模块进行分批决策，

优先推进对主路径打通贡献最大的部分

阶段 2：源码契约识别与边界划分（核心介入：ascend-om-pipeline-adapter）

功能定位与核心能力

该阶段主要负责从源码层面梳理每个候选子图的真实输入输出契约、替换点及其下游依赖关系。ascend-om-pipeline-adapter能够精准识别用户实际调用的入口路径，判断各类输入的来源（Prompt、图像特征或状态对象），并区分哪些逻辑属于可重计算的子图，哪些属于Python控制面部分，输出具有可导图、可接回、可验证特性的候选边界。

关键适配范围与边界界定

在本次适配中，我们做出了以下关键的软硬件边界判断：tokenizer、session、frame cache、object id以及prompt管理等功能继续保留在原始Python环境中实现。而以下模块优先作为稳定重计算的候选模块进入图计算：

Text Encoder（文本编码）：负责将tokenizer处理后的token_ids转换为后续Grounding所需的文本特征。将字符串处理留在Python侧，张量计算走ONNX/OM。这样输入输出边界清晰，避免了图内复杂字符串操作的潜在问题，也为将来评估“文本特征前置缓存”留有余地。

Tri Backbone（视觉主干）：采用TriHead ViTDet视觉骨干网络，为后续多条路径提供共享的视觉特征。作为计算最密集的视觉重计算部分，优先纳入OM模型候选。

Detector / Grounding（目标定位）：根据文本提示在图像特征上完成目标检测与分割。本次优先聚焦于纯文本引导的主场景，打通最核心业务路径，暂不一次性覆盖所有交互模式。

Propagation Decoder（传播解码器）：依据当前帧特征与前一阶段目标信息预测掩码。作为视频主路径的关键候选推进适配，优先保证其能顺利接回predictor并支持多帧传播。

Mask Memory Encoder（掩码记忆编码器）：负责将当前帧的预测结果写回记忆库。本次保留了外层的会话与状态管理，仅将其中重计算部分作为候选导出，降低对原始控制逻辑的侵入。

核心能力

识别用户实际调用的入口路径，理清执行流程。

判断各类输入的来源：哪些来自文本提示（Prompt），哪些来自图像特征，哪些来自状态对象。

区分哪些逻辑属于可重计算的子图，哪些属于Python控制面部分。

输出具有可导图、可接回、可验证特性的候选边界。

本次适配中的关键判断

tokenizer、session、frame cache、object id以及prompt管理等功能继续保留在原始Python环境中实现。

文本编码、视觉骨干网络、传播解码器（Propagation Decoder）以及掩码记忆编码器（Mask Memory Encoder）优先作为稳定重计算的候选模块。

Grounding模块以纯文本主场景为切入点，先完成一版基础适配，暂不一次性覆盖所有交互模式。

其他交互方式及扩展分支，将作为后续演进方向继续记录和规划。

阶段 3：从ONNX到OM的工具链闭环（核心介入：ascend-onnx-atc-pipeline）

功能定位与核心能力

本阶段负责对阶段二圈定的每个候选子图完成ONNX导出、优化、ATC转换以及基本正确性验证，形成完整的工具链闭环。它能够执行ONNX完整性检查与最小化探针测试，使用onnxslim、auto_optimizer等工具进行图结构修补，并完成ATC转换。

迁移实践落地：生成ONNX / OM产物

针对首批候选模块，我们按照统一流程依次完成ONNX导出、图优化、ATC转换与基础验证。通过这套标准流水线，不仅将工具链相关问题、模型边界条件分层记录，还生成了稳定可复用的ONNX / OM产物，为后续集成奠定稳定基础。

图 6 以首批模块为例，展示从ONNX导出到OM生成的完整流程及

基础验证结果

阶段 4：接回原始推理流程与主路径闭环验证（核心协同）

迁移实践落地：制定接回策略与最终验证

获得OM产物后，将其逐步接回原始predictor推理流程。接回过程严格遵循在阶段二中确认的契约原则：

Python负责控制面与状态管理：保持灵活的流程编排与数据流转能力。

OM负责计算密集型模块：将稳定的重计算部分卸载至昇腾硬件执行，充分利用NPU算力。

适配边界保持清晰可追踪：便于后续按需扩大覆盖范围。

在主路径接回后，我们进一步对官网dog.gif连续视频样例进行验证，确认文本提示能够稳定传导到多帧传播阶段，并持续输出对应的目标掩码。至此，输入、关键运行过程和目标输出效果形成完整闭环。

图 7 官网dog.gif连续视频样例的多帧传播跟踪结果示例：左图、中图、右图分别为第 20、40、60帧的OM输出，可见场景中的多只dog在后续帧中均被持续保留，目标掩码与检测框的对应关系清晰

总结与展望

目前，这套基于Agent-Skills的工作流已经可以为SAM 3.1这类经典深度学习模型提供从入口梳理、候选识别、ONNX/ATC转换到主路径接回的完整适配路径，为传统模型在昇腾（Ascend）OM环境下的部署提供了一条可复用的参考方案，使适配效率从周级提升至天级。

本次实践的另一个重要意义在于，通过Agent-Skills将复杂的适配工作拆解为可执行、可复用、可持续演进的工作流程，帮助开发者更快地完成模型适配。在此基础上，后续还可以围绕子图合并、边界优化以及整体运行效率进行更深入的优化，为进一步提升部署效果提供参考。

社区共建：欢迎开发者贡献Skills，共同完善昇腾AI生态。

开源地址：

https://gitcode.com/Ascend/agent-skills