Link to this sectionAmbarella CVflow 导出适用于 Ultralytics YOLO 模型#

Deploying Ultralytics YOLO models on Ambarella SoCs requires a model format optimized for the CVflow® AI engine. This fork of Ultralytics integrates Ambarella's SpongeTorch compression toolkit directly into the train, validate, and export pipeline, so you can produce pruned and quantization-optimized models that run efficiently on Ambarella hardware. This guide outlines the current object detection workflow: compression-aware training, ONNX export, compilation with the CVflow toolchain, and inference with the compiled AmbaPB model.

Link to this section什么是 Ambarella CVflow？#

Ambarella 是一家总部位于圣克拉拉的半导体公司，以其低功耗 AI 视觉 SoC 而闻名，广泛用于 IP 安防摄像头、行车记录仪、无人机、机器人和汽车系统。其芯片围绕 CVflow® 构建，这是一种专用的神经矢量处理架构（片上 AI 加速器或 NPU），可在极低功耗下提供高推理吞吐量——例如 CV72S 在 3W 以下即可运行 4K 安防摄像头 AI 工作负载。在 PyTorch 等标准框架中训练的模型在部署前，会使用 Ambarella 的离线工具链编译为 CVflow 的原生格式。

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

Link to this section为什么要将 YOLO 部署到 Ambarella？#

• 单位功耗性能：CVflow SoC 专为始终在线的边缘 AI 设计，在相机级的功耗预算内运行实时 目标检测。
• 压缩感知训练：SpongeTorch 在训练期间应用 剪枝 和 量化 感知优化，使模型在保持准确性的同时变得更适应 NPU。
• 位精确的主机验证：编译后的 AmbaPB 模型在你的工作站上通过 Ultralytics predict/val 运行，与它在芯片上的执行效果完全一致，因此你可以在接触硬件之前测量量化后的 mAP。
• 集成相机流水线：Ambarella SoC 将 AI 引擎与 ISP 和视频编码器结合在一起，使其成为 AI 摄像头的单芯片解决方案。

Link to this section工作流程概述#

流水线分为四个阶段：

1. 压缩感知训练 — 使用 SpongeKit 配置 (amba_config) 进行训练，以便 SpongeTorch 在训练过程中逐步应用剪枝/量化。
2. ONNX 导出 — 使用相同的 amba_config 导出压缩后的检查点，在 ONNX 图中保留压缩结构。
3. CVflow 编译 — 使用 CVflow 工具链将 ONNX 模型编译为 AmbaPB 工件。
4. Inference and validation — run the compiled *.ambapb.ckpt.onnx model through Ultralytics predict/val via the AmbaPB backend, then deploy on the board.

如果你不需要 SpongeTorch 的训练时优化，可以用普通的 ONNX 导出替换 SpongeTorch 训练和 SpongeTorch 感知导出（参见 在没有 SpongeTorch 的情况下导出）。

Link to this section前提条件#

Link to this section安装#

安装 此 Ultralytics 分支，然后从 SDK 发行版中安装 Ambarella 工具链 wheel 文件：

!!! Tip "安装"

# 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 .

# Install Ambarella toolchain wheels from the SDK
pip install /path/to/spongetorch-*.whl
pip install /path/to/cvflowbackend-*.whl

The AmbaPB inference backend locates cvflowbackend through the CVflow toolchain's tv2 command (tv2 -libpath cvflowbackend), so the toolchain must be installed and on your PATH before running inference or validation with compiled models.

Link to this sectionSpongeKit 配置文件#

SpongeTorch 由定义压缩过程的 SpongeKit 配置文件（protobuf 文本格式，.prototxt）驱动：剪枝稀疏度目标、量化设置和压缩计划。从你的 Ambarella SDK 版本中获取示例配置和匹配的模式文档。当验证需要准备一个未准备的模型时，请使用训练配置，并且在导出压缩检查点时始终使用相同的配置。

Link to this sectionAmba 参数#

有两个参数控制 train、val 和 export 模式下的 SpongeTorch 集成：

该分支还添加了一个通用导出参数：

Link to this section压缩感知训练#

在启用 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。

Link to this section验证压缩检查点#

在编译之前，使用相同的配置验证准确性：

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 配置并重新训练。

Link to this section导出到 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——生成 CVflow 编译器期望的确切格式的图。

Link to this section保留模型元数据#

ONNX 导出将模型任务、类名、步长和输入大小嵌入到 ONNX 文件中，而 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 文件相同的目录中。

Link to this section使用 CVflow 工具链编译#

按照 SDK 的编译指南，使用 SDK 中的 CVflow 编译器为你的目标芯片组编译导出的 ONNX 模型。编译器将图映射到 CVflow AI 引擎上（量化、调度、内存规划），并生成可部署的 AmbaPB 工件。

Link to this section使用编译后的模型运行推理#

编译后的 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 以记录输入/输出详细信息以便调试。

Link to this section在开发板上部署#

使用 Ambarella SDK 运行时将编译后的模型加载到你的 Ambarella 设备上。预处理和后处理必须与检测模型的编译目标匹配：0–255 范围内的信箱格式 (letterboxed) RGB 输入（Ultralytics AmbaPB 后端向编译后的模型提供 0–255 RGB），以及输出上的标准 YOLO 检测解码。有关运行时 API，请参考 SDK 部署文档。

Link to this section在没有 SpongeTorch 的情况下导出#

如果你不需要 SpongeTorch 的训练时剪枝和量化感知优化，标准的 Ultralytics 流水线也可以生成可编译为 CVflow 的模型：

yolo export model=yolo26n.pt format=onnx

使用 CVflow 工具链编译生成的 ONNX，该工具链本身执行训练后量化。此路径以牺牲一些 NPU 性能和量化准确性为代价，换取了一个训练时没有 spongetorch 依赖的更简单工作流程。

Link to this section实际应用场景#

Ambarella CVflow SoC 上的 Ultralytics YOLO 模型为边缘侧的始终在线视觉提供支持：

• AI 安防摄像头：在 3W 以下的功耗预算内，在 4K IP 摄像头上实现实时人员和车辆检测。
• 无人机和机器人：在 CV5 级芯片上进行用于导航、检测和交付的板载目标检测和跟踪。
• 汽车：在 CV3-AD 域控制器上进行诸如行人和车辆检测之类的 ADAS 感知工作负载。
• 工业和零售分析：在边缘设备上进行多流人员计数、PPE 检测和货架监控。

Link to this section总结#

本预览指南概述了在 Ambarella CVflow SoC 上部署 Ultralytics YOLO 模型的当前工作流程：使用 SpongeTorch 进行压缩感知训练 (amba_config/amba_chipset)，压缩检查点的 ONNX 导出，使用 CVflow 工具链进行离线编译为 AmbaPB，以及在板级部署前通过 Ultralytics 对编译后的模型进行位精确验证。

对于其他边缘 AI 目标，请参阅相关的 Hailo、Rockchip RKNN、Sony IMX500、Qualcomm QNN、DEEPX 和 Axelera 指南。有关导出格式的完整列表，请访问 导出模式 文档和 集成页面。

Link to this section常见问题解答#

Link to this section我可以将 YOLO 模型直接使用 model.export() 导出为 Ambarella 格式吗？#

不行。没有 format="ambarella" 的目标。请导出到 ONNX（可选择通过 amba_config 使用 SpongeTorch 压缩），然后使用 SDK 中的 Ambarella CVflow 工具链将 ONNX 模型离线编译为 AmbaPB。

Link to this section哪些 Ambarella 芯片可以运行 Ultralytics YOLO 模型？#

任何由你的 CVflow 工具链支持的基于 CVflow 的 SoC 都可以作为目标，包括用于 AI 摄像头的 CV72/CV75 系列、用于无人机和机器人的 CV5/CV52，以及用于汽车的 CV3-AD。amba_chipset 参数配置 SpongeTorch 的优化目标；在编译时选择匹配的目标。接受的芯片组字符串和可用性取决于已安装的 SDK 版本。

Link to this section什么是 SpongeTorch，我需要它吗？#

SpongeTorch 是 Ambarella 的模型压缩工具包，集成在 Ultralytics 的 Ambarella 分支中，用于剪枝和量化感知训练。它是可选的：普通的 Ultralytics ONNX 导出也可以使用训练后量化并通过 CVflow 工具链进行编译，但这会以一定的 NPU 性能和量化准确性为代价。

Link to this section我在哪里可以获得 Ambarella SDK、SpongeTorch 和 CVflow 工具链？#

它们是专有的，不在 PyPI 上。请在 Ambarella Developer Zone 注册以申请 SDK 访问权限；spongetorch 和 cvflowbackend wheel 文件以及 CVflow 编译器随 SDK 发行版一起提供。

Link to this section部署前我该如何检查编译后模型的准确性？#

在安装了 Ambarella 分支的情况下运行 yolo val model=model.ambapb.ckpt.onnx data=your_data.yaml。AmbaPB 后端以位精确的方式执行编译后的模型，正如其在 CVflow AI 引擎上运行一样，因此报告的 mAP 包含了所有编译器量化效果。