用于 Ultralytics YOLO 模型的 Hailo 导出#

Hailo AI 加速器可以在边缘设备（如 Raspberry Pi AI Kit 和 AI HAT+）上运行编译好的 Hailo Executable Format (HEF) 模型。Ultralytics 可以借助 Hailo Dataflow Compiler (DFC) 将 YOLO 检测、分割、语义分割、深度估计、分类、姿态估计和 OBB 模型直接导出为 HEF。

Hailo 部署专为边缘计算机视觉设计：适用于摄像头、机器人、工业系统、网关以及其他需要在本地进行目标检测而无需将每一帧数据发送到云端的设备。编译后的 HEF 包含所选加速器所需的量化网络、硬件分配、调度以及可选的 HailoRT 后处理功能。

为何在 Hailo 上部署 Ultralytics YOLO？#

将 Ultralytics YOLO 与 Hailo 神经网络处理单元 (NPU) 相结合，提供了一条从模型训练到低功耗边缘 AI 推理的实用路径。常见的应用案例包括：

• 智能摄像头和视频分析：在摄像头附近运行实时目标检测，用于安防、零售、交通和占用检测应用。
• 机器人和自主系统：检测人员、车辆、包裹、工具或障碍物，而无需依赖持续的云连接。
• 工业计算机视觉：部署自定义 YOLO 模型用于检测、计数、安全监控和质量控制。
• Raspberry Pi AI 项目：使用 AI Kit 或 AI HAT+ 为 Raspberry Pi 系统增加加速视觉推理功能。
• 边缘网关和 AI PC：在本地处理多个视频或传感器流，同时减少带宽和云端计算需求。

本地推理可以提高隐私性和响应速度，因为图像保留在部署设备上。实际的吞吐量、延迟和功耗取决于 YOLO 模型大小、输入分辨率、Hailo 架构、主机系统和应用程序流水线。

Hailo 导出工作原理#

Ultralytics 拥有 format="hailo" 背后的完整导出工作流：

YOLO (.pt) -> ONNX -> Hailo parse -> INT8 optimization -> HEF compile

导出器自动执行以下阶段：

1. 导出具有编译器兼容设置的静态 ONNX 图。
2. 选择模型架构的头输出。
3. 生成归一化、激活和后处理指令。
4. 构建代表性校准流并将模型量化为 INT8。
5. 为所选的 Hailo 加速器编译优化后的图。
6. 保存带有 Ultralytics 元数据的 HEF 并删除中间的 ONNX 文件。

YOLOv8 和 YOLO11 检测模型在编译后的流水线中使用 HailoRT YOLO NMS。YOLO26 检测模型使用其无 NMS 的一对一输出，因此导出器会自动选择不同的输出和量化路径。YOLOv8/YOLO11 分割、姿态估计和 OBB 会编译原始头部张量，由 Ultralytics 在推理时进行解码，而 YOLOv8/YOLO11/YOLO26 分类会在芯片上运行 softmax，使 HEF 直接返回类别概率。对于 YOLO26 语义分割，导出器会跟随加速器：Hailo-8/8L (DFC v3.x) 返回用于主机上采样和缩减的分类器 logits，而 Hailo-10/15 (DFC v5.x) 在芯片上编译多分类 ArgMax 头部并返回紧凑的类别图。单分类头部在所有目标上都使用主机 logit 路径，因为它们需要阈值而不是 ArgMax。YOLO26 深度模型在 a16 中编译稠密 logit conv，并在主机上重建度量深度图（头部之后的 clamp/exp 和学习到的对数仿射校准），因此量化器在原始 logit 上保持其最宽的范围。用户无需查找 ONNX 终点节点、编写 Hailo 模型脚本 (.alls) 或手动创建 NMS JSON。

安装#

安装 Ultralytics 并从 Hailo Developer Zone 下载适用于目标硬件的 DFC wheel（需免费注册）：

pip install ultralytics
pip install /path/to/hailo_dataflow_compiler-*.whl

Hailo-8 和 Hailo-8L 使用 DFC v3.x。Hailo-10 和 Hailo-15 使用 DFC v5.x。安装与目标加速器匹配的编译器版本。

导出 Hailo HEF 模型#

使用 format="hailo" 并通过 name 选择目标加速器：

from ultralytics import YOLO

model = YOLO("yolo11n.pt")
output = model.export(format="hailo", name="hailo8l")
print(output)  # yolo11n_hailo_model/

等效的 CLI 命令为：

yolo export model=yolo11n.pt format=hailo name=hailo8l

Hailo 导出仅支持 INT8。当未提供 data 时，Ultralytics 会自动下载特定任务的校准数据集。对于自定义模型，请使用具有代表性的训练或验证图像：

model.export(format="hailo", name="hailo8l", data="path/to/dataset.yaml")

编译使用固定的输入形状。将 imgsz 设置为设备上使用的分辨率：

model.export(format="hailo", name="hailo8l", imgsz=640)

支持的模型和硬件#

Hailo 生态系统涵盖广泛的计算机视觉工作负载，但 Ultralytics format="hailo" 导出器目前验证标准的 YOLO 检测、分割、语义分割、深度估计、分类、姿态估计和 OBB 头部。任务表描述了可用的导出器路径；硬件验证单独列在下方。

诸如 YOLOv10、YOLO-World、YOLOE 和 RT-DETR 等专用检测系列也 ❌ 不支持。Ultralytics 会在编译前拒绝这些任务和模型系列，而不是产生未经验证的 HEF。

姿态估计、OBB、分类、YOLO26 语义分割和 YOLO26 深度估计（Hailo-8/8L 路径）已在搭载 HailoRT 4.23 和 DFC 3.33 的 Hailo-8L 上通过验证。导出器接受其他列出的目标，但在投入生产使用之前，这些新的任务路径需要使用匹配的编译器和设备进行验证。

选择以下 name 值之一：

hailo8l 是默认值。安装与所选目标匹配的 DFC 版本。

Hailo 硬件和 SDK 版本#

Hailo 加速器系列使用不同的编译器版本。生成的 HEF 必须与目标硬件匹配，因此请为运行推理的设备选择 name，而不是执行导出的机器。

编译器在 Linux x86_64 上运行，而生成的 HEF 则通过 HailoRT 在 Hailo 设备上运行。这种分离使你可以在工作站或 Ultralytics Platform 上进行编译，并将小型的运行时工件部署到 ARM 或 x86 边缘主机上。

兼容性说明#

Hailo 编译与硬件相关，并使用固定的输入形状。请记住这些约束：

• 所选的 name 必须与部署加速器匹配。
• 校准图像应代表生产环境中预期的光照、视点、对象和背景。
• 使用一个 imgsz 编译的 HEF 在运行时无法动态调整大小。
• 支持自定义类别计数，因为 Ultralytics 从模型元数据生成后处理配置。
• 支持带有标准 Ultralytics Detect 头部的检测模型、YOLOv8/YOLO11 分割、姿态估计和 OBB 模型、YOLOv8/YOLO11/YOLO26 分类模型以及 YOLO26 语义分割和深度估计模型；目前不支持 YOLO26 实例分割、姿态估计和定向边界框，以及 YOLO-World、YOLOE、YOLOv10 和 RT-DETR 导出。
• Hailo-8/8L 和 Hailo-10/15 工件由不同的 DFC 版本编译，不可互换。

校准和 INT8 量化#

Hailo HEF 导出使用 INT8 量化，以便将 YOLO 网络高效映射到加速器上。校准数据集用于估计激活范围；它不会重新训练模型，也不需要在编译期间提供标签。

当省略 data 时，Ultralytics 使用特定任务的轻量级校准数据集，例如用于检测的 COCO128、用于语义分割的 cityscapes8 或用于深度估计的 depth8. 稠密深度头部对校准领域特别敏感：使用不相关的检测图像校准深度模型会使预测的地图变平，而更大的域内数据集可以提高保真度。对于自定义计算机视觉模型，将 data 指向其数据集 YAML，以便编译器观察来自实际部署领域的代表性图像：

model.export(format="hailo", name="hailo8l", data="my_dataset.yaml")

fraction 选择用于校准的数据集部分。只有当它们代表部署领域时，更多的图像才会有所帮助；域外图像会降低量化准确率并增加优化时间。如果 INT8 HEF 相对于原始 PyTorch 模型失去准确率，请在更改模型或运行时设置之前，首先改进校准数据。

各模型系列的精度预期#

在 Hailo-8L 上使用域内校准（COCO128，128 张图像）进行测量，在相同的评估协议下，INT8 HEF 导出的模型保留了其 PyTorch mAP50 的以下比例：

保留率在相同的置信度阈值下比较两个模型。YOLOv8 和 YOLO11 HEF 将导出时的 conf（默认 0.25）烘焙到片上 NMS 中，因此在与其默认低阈值的 PyTorch 基线进行验证时，会整合精确率-召回率曲线的更大一部分，并夸大量化差距。

除了检测外，分割、姿态、OBB 和分类导出路径已在相同的 Hailo-8L (DFC 3.33, HailoRT 4.23) 上通过验证。每个 INT8 HEF 都与同个验证集上的 PyTorch 检查点进行了对比，并使用域内数据进行了校准：

分割、姿态估计和 OBB 使用每个任务的默认域内集（COCO128-seg、COCO8-pose、DOTA128）进行校准；分类使用 ImageNet100 进行校准。这些默认值带来两个注意事项：COCO8-pose 只有 8 张图像，因此将姿态估计视为指示性的，并在生产环境中传递更大的 data=；而 DOTA8 对于这两个模型的 mAP50 都接近 100% 饱和，这就是为什么在 DOTA128 上读取 OBB 的原因。分类也是 YOLO11 保留率超过 YOLOv8 的唯一任务；对于其他任务，YOLO11 注意力主干网络对 INT8 更敏感。

根据设备测量结果，得出以下三条实用规则：

1. 始终进行域内校准。 使用域外图像进行微调等同于完全禁用微调：使用 1,238 张域外图像校准的 YOLO26n 保留的精度（85.7%）与不进行微调直接编译的模型相同。一小部分域内数据集优于大量域外数据集。
2. **对于 YOLO26 部署，将 conf 降低约 0.05。**量化会使 YOLO26 分数平均降低约 0.05，因此在 PyTorch 中调优的阈值会丢弃 HEF 上的有效检测。在设备上使用 conf=0.20 可以匹配 PyTorch 在 conf=0.25 处的检测计数，并且再稍微降低一点（大约 conf=0.15）可以以更多低置信度检测为代价，恢复几乎所有的剩余 mAP50 差距。量化还会重新对约 20% 的检测进行排名——这是一种没有任何阈值可以撤销的永久顺序效应——但这种重新排序不会阻碍在较低阈值下恢复 mAP50。
3. **在 Hailo-8/8L (DFC 3.33) 上，注意力惩罚是结构性的。**注意力块编译为 matmul 操作，在编译器为其提供的每种模式下都保持 INT8 激活输入；16 位输出模式对该图分配失败，并且提高周围层的精度也没有帮助，因为矩阵乘法无论如何都会将其输入重新量化为 INT8（在我们的测试中，将深度和输出卷积保护在 16 位使 mAP 保持不变）。当准确率是首要任务且模型可互换时，YOLO11 目前在这里的量化表现比 YOLO26 更好；更新的 Hailo 版本 (DFC 5.x) 公开更多的混合精度选项，可能会有所不同。

导出工件#

导出操作会创建一个包含可部署 HEF 和 Ultralytics 元数据的目录：

yolo11n_hailo_model/
├── yolo11n.hef
├── metadata.yaml
└── nms_config.json

• *.hef 是 HailoRT 加载的编译模型。
• metadata.yaml 保留了模型名称、任务、输入大小、步长和 Hailo 目标信息。
• nms_config.json 记录了为 YOLOv8 和 YOLO11 检测模型生成的 HailoRT NMS 配置。YOLO26 检测和所有非检测任务（分割、语义、深度、分类、姿态估计、OBB）不使用此文件。

中间的 ONNX 图在编译后会被删除。

在 Hailo 硬件上运行推理#

在目标设备上安装 HailoRT。Raspberry Pi AI Kit 和 AI HAT+ 用户可以按照 Raspberry Pi AI 软件指南 进行操作：

sudo apt install hailo-all
hailortcli fw-control identify

将完整的导出目录复制到设备，以便 metadata.yaml 保持在 HEF 旁。Ultralytics 使用 HailoRT 直接在导出的目录上运行 predict 和 val：

from ultralytics import YOLO

model = YOLO("yolo11n_hailo_model")
results = model.predict("path/to/image.jpg")

对于检测模型，后端会自动转换 YOLOv8 和 YOLO11 HailoRT NMS 输出并解码 YOLO26 一对一输出。它解码原始分割、姿态估计和 OBB 张量，返回片上分类概率，并通过 Hailo-8/8L 上的主机缩减和所有单分类头部或多分类 Hailo-10/15 头部的片上 ArgMax 生成语义类别图。TAPPAS、GStreamer 和 Raspberry Pi picamera2.devices.Hailo 助手仍然可用于特定于应用程序的流水线。

对于 GStreamer 部署，将 HEF 传递给 hailonet：

gst-launch-1.0 filesrc location=video.mp4 ! decodebin ! videoconvert ! \
  hailonet hef-path=yolo11n_hailo_model/yolo11n.hef ! \
  hailofilter function-name=yolov8 ! hailooverlay ! autovideosink

Hailo 部署选项#

HEF 是在多个 Hailo 运行时接口中通用的可部署模型工件。选择适合应用程序的接口：

当应用程序需要 Ultralytics 类别名称、输入大小、步长或其他模型信息时，请将 metadata.yaml 与 HEF 放在一起。HEF 本身不能替代用于相机捕获、可视化、跟踪、警报或存储的应用级逻辑。

验证 Hailo 设备和 HEF#

在集成摄像头或视频流水线之前，请独立验证运行时和加速器：

hailortcli fw-control identify
hailortcli parse-hef yolo11n_hailo_model/yolo11n.hef

仅设备的性能测量可将 Hailo 推理与视频解码、图像缩放、绘制和应用程序 I/O 隔离开来。在评估端到端延迟或每秒帧数时，请单独测量整个应用程序。

Hailo 与其他 YOLO 导出格式的比较#

根据将要执行该模型的硬件选择导出格式：

当最终设备包含 Hailo 加速器时，HEF 是正确的选择。ONNX 作为一种可移植的交换格式仍然很有用，但 HailoRT 执行的是由 DFC 生成的硬件特定 HEF，而不是原始的 ONNX 模型。

优化 Hailo 计算机视觉性能#

模型和流水线的选择通常比编译器标志更重要：

• 从小型 YOLO 模型开始，只有在精度有要求时才增加模型大小。
• 选择仍然能保留应用程序重要对象的最低固定 imgsz。
• 尽可能使用来自真实摄像头和环境的校准图像。
• 保持 Hailo 网络在各帧之间保持活跃，而不是为每次推理重新打开 HEF。
• 将设备推理时间与预处理、视频解码、后处理、可视化和网络 I/O 分离开来。
• 对于持续的视频工作负载，请使用 GStreamer 等流式传输流水线。
• 在生产环境中使用的确切加速器和 HailoRT 版本上验证导出的 HEF。

导出参数#

对于检测导出，YOLOv8 和 YOLO11 接收 HailoRT NMS，而 YOLO26 保持其无 NMS 的一对一输出。分割、姿态估计和 OBB 使用原始头部张量，分类返回片上概率，语义分割在 Hailo-8/8L 和所有单分类头上返回原始 logits，或者为多分类 Hailo-10/15 头返回烘焙的类别图。深度估计返回原始深度 logit，Ultralytics 在推理时将其解码为度量深度图。请勿传递 end2end；显式覆盖将被拒绝。动态形状、大于 1 的批次、嵌入式 Ultralytics NMS、FP16 和 FP32 也不受支持。

排查 Hailo 导出问题#

Hailo Dataflow Compiler 导入错误#

如果导出报告缺少 hailo_sdk_client，请在与 Ultralytics 相同的 Python 环境中为目标硬件生成安装 DFC wheel。Hailo-8/8L 和 Hailo-10/15 需要不同的编译器版本。

不支持的操作系统或架构#

HEF 编译在 Linux x86_64 上受支持。如果本地计算机是 macOS、Windows、Raspberry Pi 或其他 ARM 系统，请通过 Ultralytics Platform 导出或使用兼容的工作站。

导出耗时较长#

DFC 优化是最昂贵的阶段。编译时间会随着模型大小、输入分辨率和校准数据而增加。受支持的 GPU 可以加速优化，而仅使用 CPU 编译可能会慢得多。

量化模型精度下降#

使用类似于生产输入并包含重要对象、比例、光照条件和背景的校准图像。在部署之前，在相同的验证集上比较原始 PyTorch 模型和导出的 HEF。即使有良好的校准，仍然存在一个适度的与系列相关的差距；请参阅各模型系列的准确率期望了解测量的基线。

HEF 无法在设备上加载#

确认 name 与物理 Hailo 架构匹配，并且设备驱动程序、固件和 HailoRT 软件包相互兼容。使用 hailortcli parse-hef 检查工件并通过 hailortcli fw-control identify 验证加速器。

输出解析看起来不正确#

将 metadata.yaml 放在 HEF 旁边，以便 Ultralytics 可以选择匹配的 YOLOv8、YOLO11 或 YOLO26 后处理路径。自定义 HailoRT 应用程序也必须将后处理与导出的模型系列相匹配。

总结#

Ultralytics Hailo 导出提供了一条从训练好的 YOLO 模型到可部署 HEF 的直接路径：

1. 加载 YOLOv8、YOLO11 或 YOLO26 检测或分类模型，YOLOv8/YOLO11 分割、姿态估计或 OBB 模型，或 YOLO26 语义分割或深度估计模型。
2. 使用 format="hailo" 导出并选择目标架构。
3. 使用匹配的 DFC 在本地进行校准和编译，或在 Ultralytics Platform 中使用托管导出。
4. 将 HEF 和 metadata.yaml 复制到由 Hailo 驱动的边缘设备。
5. 使用 HailoRT、Raspberry Pi Picamera2 或 GStreamer 视频管线运行推理。

有关其他计算机视觉部署目标，请参阅导出模式、基准测试模式和集成指南。相关的硬件指南包括 ONNX、OpenVINO、TensorRT、NCNN、RKNN、Sony IMX500 和 Qualcomm QNN。

常见问题解答#