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

背景概述SAM 3.1 是一个典型的经典深度学习模型系统其推理链路涉及文本、视觉、目标定位Grounding、视频追踪以及记忆Memory更新等多个模块。针对这类模型的昇腾推理适配关键不仅在于生成单个 ONNX 或 OM 模型文件更在于梳理真实的业务入口识别具有实际价值的高效子图并确保生成的产物能够稳定地接回原有的处理流程。本文介绍的昇腾 Agent Skills 主要面向经典深度学习模型的适配需求提供了一套完整的工作流程涵盖从源码分析、候选识别、ONNX 与 ATC 转换到最终接回验证的各个环节。借助这一工作流针对 SAM 3.1 模型成功开展了 Ascend OM 路线的适配实践顺利打通了基于文本提示的视频分割主路径并在此基础上沉淀出一条可复用、且能够持续演进的智能化部署路径。SAM 3.1 官方结构图图 1SAM 3.1 掩码预测流程Pipeline概述该图展示了一种用于处理给定输入中目标嵌入的模型架构。整体流程被划分为两个主要空间数据空间与复用空间。数据空间在该空间中逐目标掩码被应用于目标嵌入并将处理后的结果传递至下一阶段。复用空间该空间包含多个协同工作的组件具体说明如下复用器Mux将目标嵌入与逐目标掩码进行组合以供后续处理使用。记忆编码模块对记忆信息进行编码并存储由此产生的相关数据表征。记忆库用于存放上一阶段编码所得到的记忆表征。记忆注意力机制根据当前上下文有选择地关注记忆库中的相关信息。图像编码器对当前帧图像进行编码为后续处理提供特征表示。掩码解码器对处理过程中生成的掩码信息进行解码。解复用器Demux将系统的最终输出进行拆分并分别传递给下游的不同任务或组件。该系统的各组成部分按顺序协同工作依次对目标嵌入和记忆表征进行处理与注意力建模从而实现对视觉数据的有效编码与解码。结构流程图清晰地展示了 SAM 3.1 在视频场景下的核心计算链路也为本次适配过程中模块拆分、子图规划以及主路径的接回提供了直观的参考依据。本次适配取得的主要成果如下完成了从 SAM 3.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功能定位与核心能力作为主编排 Skillascend-om-deployer负责梳理 SAM 3.1 的目标功能范围、明确真实的推理入口并整理候选子图集合。它能够识别模型的真实推理入口而非仅关注单个模块的 forward() 方法并将庞大的模型拆分为可供分阶段推进的候选单元形成可持续推进的适配闭环。迁移实践落地确认输入场景与圈定优先模块适配工作从 predictor 入口出发我们首先梳理用户实际调用的业务主路径明确本次需优先覆盖的核心流程。以下以官网 dog.gif 连续视频样例作为验证案例展示主路径输入与多帧传播输出之间的对应关系。构建流程为predictor → 初始化视频状态 → 添加文本提示 → 初始化目标掩码 → 多帧传播 → 输出逐帧目标掩码。主路径确认后进一步梳理共享主干Backbone、Grounding、传播解码等关键模块从中优先选取边界清晰、复用度高、对主路径打通价值最大的部分纳入首批适配范围。图 2左侧为官网 dog.gif 第 20 帧原始输入含原视频自带字幕右侧为同一帧的 OM 连续跟踪结果。图 3Task 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 转换到主路径接回的完整适配路径为传统模型在昇腾AscendOM 环境下的部署提供了一条可复用的参考方案使适配效率从周级提升至天级。本次实践的另一个重要意义在于通过 Agent Skills 将复杂的适配工作拆解为可执行、可复用、可持续演进的工作流程帮助开发者更快地完成模型适配。在此基础上后续还可以围绕子图合并、边界优化以及整体运行效率进行更深入的优化为进一步提升部署效果提供参考。社区共建欢迎开发者贡献 skills共同完善昇腾生态。开源地址https://gitcode.com/Ascend/agent-skills