Ambarella CVflow SoC 部署 Ultralytics YOLO：SpongeTorch 压缩训练与 AmbaPB 编译全流程

本指南基于 Ultralytics YOLO 生态，讲解如何将检测模型部署到 Ambarella CVflow® SoC（如 CV72、CV75、CV5、CV3-AD、N1）上：先使用 Ambarella 官方 Ultralytics 分支内置的 SpongeTorch 压缩工具进行剪枝与量化感知训练，再经 ONNX 导出、CVflow 工具链离线编译为可在芯片上执行的 AmbaPB 格式，并通过 Ultralytics predict/val 在主机上完成位精确（bit-exact）验证后再上板。读完本文你将掌握完整的「压缩训练 → 导出 → 编译 → 验证 → 部署」流水线，以及各环节的关键参数、注意事项与常见问题。

⚠️ 预览说明：本文所述指南仍处于早期预览阶段，尚未经 Ambarella 官方完整验证，命令、兼容性细节与流程可能随厂商反馈调整。当前不存在 format="ambarella" 导出目标；实际流程是使用标准 ONNX 导出（format="onnx"）配合 amba_config / amba_chipset 参数，再离线用 CVflow 工具链将 ONNX 编译为可部署的 AmbaPB 格式。

什么是 Ambarella CVflow？

Ambarella 是一家总部位于美国 Santa Clara 的半导体公司，其低功耗 AI 视觉 SoC 广泛用于 IP 安防摄像头、行车记录仪、无人机、机器人及车载系统。芯片核心是 CVflow®——一个专用神经网络向量处理架构（片上 AI 加速器 / NPU），能在极低功耗下提供高推理吞吐，例如 CV72S 可在 3 W 以下运行 4K 安防摄像头 AI 工作负载。使用 PyTorch 等标准框架训练的模型，需要先经 Ambarella 离线工具链编译为 CVflow 原生格式才能部署。

当前 CVflow SoC 家族及其典型应用：

SoC 家族	典型应用
CV72/CV75	4K AI 安防摄像头、智能摄像头、工业视觉
CV5/CV52	无人机、运动相机、机器人、多摄像头系统
CV3-AD	车载 ADAS 与自动驾驶域控制器
N1	本地生成式 AI 与多路视频分析一体机

为什么在 Ambarella 上部署 YOLO？

• 每瓦性能（performance per watt）：CVflow SoC 面向常开（always-on）边缘 AI 设计，可在摄像头级别的功耗预算内运行实时目标检测。
• 压缩感知训练：SpongeTorch 在训练过程中施加剪枝（pruning）与量化感知（quantization-aware）优化，使模型在保持精度的同时变得对 NPU 友好。
• 位精确的主机验证：编译后的 AmbaPB 模型在主机上经由 Ultralytics predict/val 运行，其执行方式与在芯片上完全一致（bit-exact），因此可在接触硬件前就测出量化后的 mAP。
• 一体化摄像头流水线：Ambarella SoC 将 AI 引擎与 ISP、视频编码器集成于一体，是 AI 摄像头的单芯片解决方案。

工作流总览

整个流水线分为四个阶段：

1. 压缩感知训练——使用 SpongeKit 配置（amba_config）训练，SpongeTorch 在训练过程中按进度施加剪枝/量化。
2. ONNX 导出——使用与训练相同的 amba_config 导出压缩后的 checkpoint，将压缩结构保留在 ONNX 图中。
3. CVflow 编译——用 CVflow 工具链把 ONNX 模型编译为 AmbaPB 工件。
4. 推理与验证——通过 AmbaPB 后端在 Ultralytics predict/val 中运行编译产物 *.ambapb.ckpt.onnx，随后部署到开发板上。

如果你不需要 SpongeTorch 训练期优化，SpongeTorch 训练及其感知导出可替换为普通 ONNX 导出（见下文 不使用 SpongeTorch 的导出）。

前置条件

环境安装

本工作流需要两个关键前提：

1. Ambarella 的 Ultralytics 分支：Ambarella 将 SpongeTorch 压缩工具直接集成进了 train / validate / export 流水线，因此必须安装该分支（对应 amba_v8.4.46 分支），而非主线版本。本文所在的当前仓库 ultralytics/ 主线源码中并不包含 amba_config / amba_chipset 参数，这两个参数只存在于 Ambarella 分支中。
2. 专有工具链组件：spongetorch、CVflow 编译器以及 cvflowbackend 均为专有组件，不在 PyPI 上发布，需通过 Ambarella Developer Zone 注册并在 Cooper™ Developer Platform 申请 SDK 访问权限后获得。

CLI 安装示例：

# 从源码安装 Ambarella Ultralytics 分支
git clone https://github.com/Ambarella-Inc/ultralytics
cd ultralytics
git checkout amba_v8.4.46
pip install -e .

# 从 SDK 分发中安装 Ambarella 工具链 wheel
pip install /path/to/spongetorch-*.whl
pip install /path/to/cvflowbackend-*.whl

注意：AmbaPB 推理后端通过 CVflow 工具链的 tv2 命令（tv2 -libpath cvflowbackend）定位 cvflowbackend，因此在运行编译模型的推理或验证前，必须安装工具链并将其加入 PATH。

SpongeKit 配置文件

SpongeTorch 由 SpongeKit 配置文件驱动（protobuf-text 格式，.prototxt），该文件定义要施加的压缩步骤：剪枝稀疏度目标、量化设置以及压缩进度调度。示例配置与对应的 schema 文档可从 Ambarella SDK 版本中获取。规则是：当验证需要准备未经过压缩准备的模型时使用训练配置；导出压缩 checkpoint 时始终使用与训练一致的配置。

Amba 相关参数

在 Ambarella 分支中，amba_config 与 amba_chipset 两个参数贯穿 train、val、export 三种模式，控制 SpongeTorch 集成：

参数	类型	默认值	说明
amba_config	str	None	传给 spongetorch.prepare() 的 SpongeKit 配置路径。启用压缩感知训练与 SpongeTorch 感知导出。
amba_chipset	str	None	传给 spongetorch.set_target_chipset() 的目标芯片名，例如 CV72。

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

参数	类型	默认值	说明
export_file	str	None	自定义导出输出路径/文件名，例如 '/tmp/model.onnx' 或 'model.onnx'。

压缩感知训练

通过 CLI 或 Python API 开启 SpongeTorch 压缩训练（或微调）：

!!! example "用法"

=== "Python"

    ```python
    from ultralytics import YOLO

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

=== "CLI"

    ```bash
    yolo train model=yolo26n.pt data=coco8.yaml epochs=100 \
      amba_config=config.prototxt amba_chipset=CV72
    ```

当设置了 amba_config 时，trainer 会在 setup 阶段用 spongetorch.prepare() 包装模型与优化器。压缩按步骤调度（step schedule）渐进施加，网络因此能在保持精度的同时逐步变得稀疏、对量化友好。训练好的 checkpoint 中保存了 SpongeTorch 的稀疏状态（_orig / _mask 张量），导出阶段会依赖这些状态。为保证可复现性，配置文件会以 amba_config.prototxt 的名称复制到 run 目录中。

!!! note "Checkpoint 门控"

`best.pt` 与 `last.pt` 在 SpongeTorch 压缩调度越过其 `end_step` 之前**有意不保存**——半个压缩态的 checkpoint 无法使用。请确保 `epochs` 足够长、能覆盖配置中的完整调度，日志会报告 checkpoint 保存何时开始。若训练在调度完成前结束，最后一个 epoch 仍会保存并附带警告，但这种 checkpoint 不应被部署。

!!! tip "建议微调而非从头训练"

为获得最佳精度，建议先用普通方式完整训练模型（或从预训练 checkpoint 出发），再在已训练权重上运行一段较短的、带 `amba_config` 的压缩微调。

验证压缩 checkpoint

在编译之前先用相同配置验证精度：

!!! example "用法"

=== "CLI"

    ```bash
    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 导出压缩 checkpoint：

!!! example "用法"

=== "Python"

    ```python
    from ultralytics import YOLO

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

=== "CLI"

    ```bash
    yolo export model=runs/detect/train/weights/best.pt format=onnx \
      amba_config=config.prototxt amba_chipset=CV72
    ```

导出器会重建模型，用你的配置重新执行 spongetorch.prepare()，把稀疏 checkpoint 权重重新加载进已准备的结构中，并在禁用 Conv+BN 融合的情况下 trace 到 ONNX——从而产生 CVflow 编译器所期望的精确图形态。

在主线 Ultralytics 中，ONNX 导出本身还支持 opset、dynamic、simplify、batch、nms、quantize 等通用参数（可参考 导出器实现 中 export_onnx 的完整逻辑），这些参数在该分支的 Amba 导出路径下同样可用作辅助控制。

保留模型元数据

ONNX 导出会将模型任务、类别名、stride 与输入尺寸等元数据嵌入 ONNX 文件（主线 导出器源码 通过 model_onnx.metadata_props.add() 逐项写入；AutoBackend 会从元数据读取 names/stride），而 AmbaPB 后端是从编译模型旁侧的 metadata.yaml 侧车文件读取这些信息的。除非你的 CVflow 编译器会自动生成该侧车文件，否则应在编译前先从 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 的同级目录。

!!! warning

- checkpoint 必须包含 SpongeTorch 压缩状态。对普通 checkpoint 设置 `amba_config` 导出会报错：*"Checkpoint has no SpongeTorch pruning state... Use a compressed checkpoint from amba training before export."*
- 配置必须与训练时一致，否则权重重载会失败。

使用 CVflow 工具链编译

使用 SDK 中的 CVflow 编译器，依据 SDK 的编译指南，将导出的 ONNX 模型编译到目标芯片。编译器会把图映射到 CVflow AI 引擎上（量化、调度、内存规划），产出可部署的 AmbaPB 工件。

!!! note

为了让 Ultralytics 识别编译后的模型，其文件名必须以 `.ambapb.ckpt.onnx` 或 `.ambapb.fastckpt.onnx` 结尾。

用编译模型运行推理

编译后的 AmbaPB 模型可直接通过 Ultralytics API 加载——AutoBackend 会检测 .ambapb 后缀并把推理路由到 cvflowbackend，以与芯片 AI 引擎位精确一致的方式执行模型：

!!! example "用法"

=== "Python"

    ```python
    from ultralytics import YOLO

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

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

    # 验证
    metrics = model.val(data="coco8.yaml")
    ```

=== "CLI"

    ```bash
    yolo predict model=model.ambapb.ckpt.onnx source='https://ultralytics.com/images/bus.jpg'
    yolo val model=model.ambapb.ckpt.onnx data=coco8.yaml
    ```

这是硬件部署前的最终精度检查，已包含编译器全部量化影响。若编译模型旁存在 metadata.yaml，后端会从中读取类别名、stride 与任务信息。后端默认使用 CVflow 推理模式 acinf；设置环境变量 ULTRALYTICS_AMBAPB_DEBUG=1 可打印输入/输出细节用于调试。

在开发板上部署

在 Ambarella 设备上使用 Ambarella SDK 运行时加载编译模型。预处理与后处理必须与检测模型编译时约定的方式一致：letterbox 缩放到 RGB、取值 0–255（Ultralytics AmbaPB 后端向编译模型输入的就是 0–255 的 RGB），输出端做标准 YOLO 检测解码。运行时 API 请查阅 SDK 部署文档。

不使用 SpongeTorch 的导出

若不需要 SpongeTorch 训练期的剪枝与量化感知优化，标准 Ultralytics 流水线同样能产出可被 CVflow 编译的模型：

!!! example "用法"

=== "CLI"

    ```bash
    yolo export model=yolo26n.pt format=onnx
    ```

用 CVflow 工具链编译生成的 ONNX 即可，工具链会自行执行训练后量化（post-training quantization）。这条路径以部分 NPU 性能与量化精度为代价，换取更简单的流程，且训练阶段不依赖 spongetorch。

真实应用场景

搭载 Ultralytics YOLO 模型的 Ambarella CVflow SoC，支撑着边缘端的常开视觉任务：

• AI 安防摄像头：在 4K IP 摄像头上、低于 3 W 功耗预算内实时检测行人与车辆。
• 无人机与机器人：在 CV5 级芯片上做机载目标检测与跟踪，用于导航、巡检与配送。
• 车载：在 CV3-AD 域控制器上承载 ADAS 感知负载，如行人、车辆检测。
• 工业与零售分析：边缘一体机上的多路人数统计、PPE（防护装备）检测与货架监控。

总结

本预览指南梳理了在 Ambarella CVflow SoC 上部署 Ultralytics YOLO 模型的完整现行流程：用 SpongeTorch 做压缩感知训练（amba_config / amba_chipset）、导出压缩 checkpoint 为 ONNX、用 CVflow 工具链离线编译为 AmbaPB，并在上板前通过 Ultralytics 对编译模型做位精确验证。

其他边缘 AI 目标可参考同目录下的 Hailo、Rockchip RKNN、Sony IMX500、Qualcomm QNN、DEEPX 与 Axelera 指南。完整的导出格式清单见 Export 模式文档 与 集成总览页。

FAQ

能否用 model.export() 直接把 YOLO 模型导出为 Ambarella 格式？

不能。当前不存在 format="ambarella" 目标。请先导出 ONNX（可选地通过 amba_config 启用 SpongeTorch 压缩），再用 SDK 中的 CVflow 工具链把 ONNX 离线编译为 AmbaPB。

哪些 Ambarella 芯片可以运行 Ultralytics YOLO 模型？

只要 CVflow 工具链支持，任何基于 CVflow 的 SoC 均可作为目标，包括面向 AI 摄像头的 CV72/CV75 家族、面向无人机与机器人的 CV5/CV52，以及面向车载的 CV3-AD。amba_chipset 参数配置的是 SpongeTorch 的优化目标；编译时需另行选择匹配的目标。可接受的 chipset 字符串及其可用性取决于所安装的 SDK 版本。

什么是 SpongeTorch？我是否必须使用它？

SpongeTorch 是 Ambarella 的模型压缩工具包，被集成进 Ambarella 的 Ultralytics 分支，用于剪枝与量化感知训练。它是可选的：普通 Ultralytics ONNX 导出同样可用 CVflow 工具链做训练后量化并编译，只是会在 NPU 性能与量化精度上付出一定代价。

从哪里获取 Ambarella SDK、SpongeTorch 与 CVflow 工具链？

它们均为专有软件，不在 PyPI 上发布。请在 Ambarella Developer Zone 注册并申请 SDK 访问权限；spongetorch 与 cvflowbackend wheel、CVflow 编译器随 SDK 发行包一起提供。

部署前如何检查编译模型的精度？

安装 Ambarella 分支后执行 yolo val model=model.ambapb.ckpt.onnx data=your_data.yaml。AmbaPB 后端以与 CVflow AI 引擎位精确一致的方式执行编译模型，因此报告的 mAP 已包含编译器全部量化影响。