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 运行时将 Cavalry 二进制文件加载到 Ambarella 设备上。预处理和后处理必须与检测模型编译时采用的设置一致：输入为 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 相关指南。完整的导出格式列表请参阅导出模式文档和集成页面。

常见问题#