Ultralytics YOLO 模型的 Ambarella CVflow 导出#

在 Ambarella SoC 上部署 Ultralytics YOLO 模型，需要使用 Ambarella 的编译工具编译模型；针对 CVflow 架构优化的模型在推理时性能更佳。这个 Ultralytics 分支将 Ambarella 的 SpongeTorch 压缩工具包直接集成到训练、验证和导出流程中，使开发者能够生成经过优化的模型，从而在 Ambarella 硬件上高效部署。

本指南介绍当前的目标检测部署流程，从压缩感知训练到设备端推理（完整流程请参阅工作流概览）。

AmbaPB 检查点格式是 Ambarella 对 ONNX IR 规范的专用扩展，支持 CVflow 计算原语，并打包 SDK 工具生成的产物。它是在部署前用于验证编译模型精度的主机端产物；而为目标设备生成的独立 Cavalry 二进制文件才是在板上运行的文件。

Ambarella 是什么？#

Ambarella 总部位于加利福尼亚州圣克拉拉，是一家设计边缘 AI SoC 的半导体公司。其处理器集成了图像信号处理、视频编码和芯片端 AI 计算功能，应用于安防、汽车、机器人、工业和消费类设备。

CVflow 是什么？#

CVflow 是 Ambarella 的视觉处理架构。它采用独立于 CPU 和 GPU 的专用视觉引擎来运行计算机视觉和神经网络工作负载。使用 PyTorch 等框架训练的模型，会先通过 Ambarella SDK 编译为 CVflow 原生格式，再由该引擎运行。

当前的 CVflow SoC 系列及其典型应用：

为什么在 Ambarella 上部署 YOLO？#

• 每瓦性能：CVflow SoC 专为常开型边缘 AI 设计，可在摄像头级别的功耗预算内实时执行目标检测。
• 压缩感知训练：SpongeTorch 在训练期间执行剪枝，帮助模型在保持精度的同时变得更稀疏、更适合在 CVflow 上部署。
• 集成式摄像头流水线：Ambarella SoC 集成了图像信号处理器（ISP）、超高清视频编码和 CVflow，能够以低功耗支持多种摄像头系统，因此单个 Ambarella SoC 就能处理完整的 AI 摄像头流水线。

工作流概览#

该流水线分为六个阶段：

1. 压缩感知训练 — 使用 SpongeKit 配置（amba_config）进行训练，让 SpongeTorch 在训练期间逐步执行非结构化剪枝。如果训练后量化（PTQ）的精度无法满足要求，SpongeTorch 也支持量化感知训练（QAT），但该流程尚未接入此 Ultralytics 集成，计划在未来版本中推出。
2. ONNX 导出 — 使用相同的 amba_config 导出压缩后的检查点，在 ONNX 图中保留压缩结构。
3. 编译 — 使用 SDK 编译工具将 ONNX 模型编译为 AmbaPB 检查点，编译工具会针对 CVflow 引擎执行 PTQ。
4. 主机端验证 — 通过 AmbaPB 后端，使用 Ultralytics predict/val 运行已编译的 *.ambapb.ckpt.onnx 模型，以便在部署前验证精度。
5. Cavalry 转换 — 使用 SDK 工具将经过验证的 AmbaPB 检查点转换为 Cavalry 二进制文件。
6. 在设备上运行 — 使用 Ambarella 的 SDK 运行时库在设备上运行 Cavalry 二进制文件。

SpongeTorch 训练和导出流程是可选的，可以替换为普通的 ONNX 导出（参阅不使用 SpongeTorch 导出）。

前置条件#

安装#

安装此 Ultralytics 分支，然后设置 Ambarella CVflow SDK（其中包含编译工具和 cvflowbackend 库），并安装随 SDK 一同分发的 spongetorch wheel：

# Install this Ultralytics fork from source
git clone https://github.com/Ambarella-Inc/ultralytics
cd ultralytics
git checkout amba_v8.4.46
pip install -e .

# Access and set up the Ambarella SDK compilation tools
# After the environment is ready, install the spongetorch library
pip install /path/to/spongetorch-*.whl

AutoBackend 通过 SDK 编译工具的 tv2 命令（tv2 -libpath cvflowbackend）定位 cvflowbackend，因此，在使用编译后的模型执行推理或验证之前，必须先安装 SDK 编译工具并将其添加到 PATH。

SpongeKit 配置文件#

SpongeTorch 使用 SpongeKit 配置文件（protobuf 文本格式，.prototxt）驱动，该文件定义剪枝流程，包括稀疏度目标和压缩计划。从 Ambarella SDK 版本中获取示例配置及对应的架构文档。为确保训练、验证和部署的一致性，如果验证时需要重新准备模型，请使用训练配置；导出压缩检查点时也始终使用相同的配置。

Amba 参数#

以下两个参数用于控制 SpongeTorch 在 train、val 和 export 模式下的集成：

此分支还新增了一个通用导出参数：

压缩感知训练#

启用 SpongeTorch 压缩来训练（或微调）模型：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.train(
    data="coco8.yaml",
    epochs=100,
    amba_config="config.prototxt",
    amba_chipset="CV72",
)

设置 amba_config 后，训练器会在初始化时使用 spongetorch.prepare() 包装模型和优化器。压缩会按照步骤计划逐步进行，使网络在变得稀疏的同时学会保持精度。训练后的检查点会保存 SpongeTorch 的稀疏状态（_orig/_mask 张量），后续导出步骤需要这些状态。配置文件会复制到运行目录并命名为 amba_config.prototxt，以便复现。

验证压缩后的检查点#

编译前请使用相同的配置验证精度：

yolo val model=runs/detect/train/weights/best.pt data=coco8.yaml \
  amba_config=config.prototxt amba_chipset=CV72

验证器会在需要时重新应用 spongetorch.prepare()，并禁用 Conv+BN 融合，以保留压缩结构。将 mAP 与未压缩基线进行比较；如果精度下降过多，请调整 SpongeKit 配置并重新训练。

导出为 ONNX#

使用训练时相同的 amba_config 导出压缩后的检查点：

from ultralytics import YOLO

model = YOLO("runs/detect/train/weights/best.pt")
model.export(
    format="onnx",
    amba_config="config.prototxt",
    amba_chipset="CV72",
)

导出器会重建模型，根据你的配置重新应用 spongetorch.prepare()，将稀疏检查点权重重新加载到准备好的结构中，并在禁用 Conv+BN 融合的情况下跟踪并导出为 ONNX，从而生成完全符合 SDK 编译工具预期格式的图。

保留模型元数据#

ONNX 导出会将模型任务、类别名称、步幅和输入尺寸嵌入 ONNX 文件，而 AmbaPB 后端会从编译模型旁的 metadata.yaml 伴随文件中读取这些信息。除非你的 SDK 编译工具会创建此伴随文件，否则请在编译前从 ONNX 模型中提取这些信息：

import onnx

from ultralytics.utils import YAML

model = onnx.load("model.onnx")
YAML.save("metadata.yaml", {item.key: item.value for item in model.metadata_props})

将 metadata.yaml 与编译后的 *.ambapb.ckpt.onnx 或 *.ambapb.fastckpt.onnx 文件放在同一目录中。

使用 SDK 工具进行编译#

按照 SDK 编译指南，使用 SDK 编译工具为目标芯片编译导出的 ONNX 模型。这些工具会将计算图映射到 CVflow AI 引擎上——执行 PTQ、调度和内存规划——并生成用于主机验证的 AmbaPB 检查点。

PTQ 使用校准图像进行 INT8 量化（图像需按照 SDK 编译指南中的说明准备），编译工具会在精度和运行时延迟之间进行权衡：将更多操作映射到 INT8 可降低延迟，但可能降低精度；保留更多操作为 FP16 则能保持精度，但延迟较高。如果 PTQ 在延迟预算要求的 INT8 级别下无法达到目标精度，预期的解决方法是使用 SpongeTorch 进行 QAT——通过训练模型适应更激进的 INT8 量化，在更低延迟的工作点恢复精度。目前此集成尚未提供 QAT，计划在未来版本中推出。

使用已编译模型运行推理#

已编译的 AmbaPB 模型可直接通过 Ultralytics API 加载——AutoBackend 会检测 .ambapb 后缀，并通过 cvflowbackend 执行推理，以模型在 AI 引擎上的实际运行方式执行模型：

from ultralytics import YOLO

model = YOLO("model.ambapb.ckpt.onnx")

# Inference
results = model("https://ultralytics.com/images/bus.jpg")

# Validation
metrics = model.val(data="coco8.yaml")

这是部署到硬件前的最终精度检查，包含编译器量化带来的所有影响。如果已编译模型旁边有 metadata.yaml 文件，后端会从中读取类别名称、步长和任务信息。后端默认使用 CVflow 推理模式 acinf；设置环境变量 ULTRALYTICS_AMBAPB_DEBUG=1 可记录输入/输出详情以便调试。

转换为 Cavalry 二进制文件#

AmbaPB 检查点通过主机验证后，按照 SDK 编译指南，使用 SDK 编译工具将其转换为适用于目标设备的 Cavalry 二进制文件。Cavalry 二进制文件是 SDK 运行时库在开发板上执行的形式。

在开发板上部署#

使用 Ambarella SDK 运行时在 Ambarella 设备上加载 Cavalry 二进制文件。预处理和后处理必须与检测模型编译时的设置一致：输入为 0–255 范围内的 letterbox RGB 图像，输出则采用标准 YOLO 检测解码。有关运行时 API，请参阅 SDK 部署文档。

不使用 SpongeTorch 进行导出#

如果不需要 SpongeTorch 在训练期间进行剪枝，标准 Ultralytics 流程也能生成可由 SDK 工具编译的模型：

yolo export model=yolo26n.pt format=onnx

使用 SDK 编译工具编译生成的 ONNX，这些工具会自行执行训练后量化。此流程简化了工作步骤，训练时无需依赖 spongetorch，但会牺牲一些运行时性能和量化后精度。

实际应用#

Ambarella CVflow SoC 上的 Ultralytics YOLO 模型可在边缘设备上实现常开视觉：

• AI 安防摄像头：在 4K IP 摄像头上实时检测人员和车辆，功耗预算低于 3 W。
• 无人机和机器人：在 CV5 级芯片上运行机载目标检测和跟踪，用于导航、巡检和配送。
• 工业和零售分析：在边缘设备上进行多路视频流人数统计、PPE 检测和货架监控。

总结#

本指南概述了当前在 Ambarella CVflow SoC 上部署 Ultralytics YOLO 模型的流程：使用 SpongeTorch 进行压缩感知训练（amba_config/amba_chipset）、导出压缩后的检查点为 ONNX、使用 SDK 工具离线编译为 AmbaPB 检查点、通过 Ultralytics 在主机上验证，以及转换为 Cavalry 二进制文件，使用 Ambarella SDK 在设备上部署。

如需了解其他边缘 AI 目标平台，请参阅相关指南：Hailo、Rockchip RKNN、Sony IMX500、Qualcomm QNN、DEEPX 和 Axelera。如需查看完整的导出格式列表，请访问 导出模式文档和集成页面。

常见问题#