Ultralytics YOLO 模型的 Hailo 导出#

Hailo AI 加速器可在 Raspberry Pi AI HAT+ 和 AI HAT+ 2 等边缘设备上运行已编译的 Hailo 可执行格式 (HEF) 模型。Ultralytics 可使用 Hailo 数据流编译器 (DFC) 将 YOLO 检测、分割、语义分割、深度估计、分类、姿态和 OBB 模型直接导出为 HEF。

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

为什么要在 Hailo 上部署 Ultralytics YOLO？#

将 Ultralytics YOLO 与 Hailo 神经处理单元 (NPU) 结合，可为从模型训练到边缘 AI 推理提供实用路径。常见用例包括：

• 智能摄像头和视频分析：在摄像头附近运行实时目标检测，用于安防、零售、交通和占用情况分析。
• 机器人和自主系统：检测人员、车辆、包裹、工具或障碍物，无需依赖持续的云连接。
• 工业计算机视觉：部署自定义 YOLO 模型，用于检测、计数、安全监控和质量控制。
• Raspberry Pi AI 项目：使用 AI HAT+ 或 AI HAT+ 2 为 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-10H/15（DFC v5.x）会在芯片上编译多类别 ArgMax 检测头并返回紧凑的类别图。单类别检测头在所有目标上都使用主机 logits 路径，因为它们需要阈值而不是 ArgMax。YOLO26 深度模型会在 a16 中编译密集 logits 卷积，并在主机端重建度量深度图（即检测头之后的 clamp/exp 和学习得到的 log-affine 校准），因此量化器会在原始 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-10H 和 Hailo-15 使用 DFC v5.x。安装与目标加速器匹配的编译器版本。

导出 Hailo HEF 模型#

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

from ultralytics import YOLO

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

对应的 CLI 命令为：

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

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

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

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

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

支持的模型和硬件#

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

YOLOv10、YOLO-World、YOLOE 和 RT-DETR 等专用检测系列目前无法通过 Ultralytics format="hailo" 路径支持。Ultralytics 会在编译前拒绝这些任务和模型系列，而不是生成未经验证的 HEF。

姿态、OBB、分类、YOLO26 语义分割以及 YOLO26 深度估计（Hailo-8/8L 路径）已在 Hailo-8L、HailoRT 4.23 和 DFC 3.33 上完成验证。导出器接受下方列出的其他目标，但这些新的任务路径需要使用匹配的编译器和设备进行验证后，才能用于生产环境。

选择以下某个 name 值：

如果省略 name，则使用 hailo8l 作为默认值；将 name 设置为你要部署使用的加速器。安装与所选目标匹配的 DFC 版本。

Hailo 硬件和 SDK 版本#

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

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

兼容性说明#

Hailo 编译与硬件相关，并使用固定输入形状。请注意以下限制：

• 所选的 name 必须与部署加速器匹配。
• 校准图像应代表生产环境中预期的光照、视角、物体和背景。
• 每个 HEF 都针对固定的 imgsz 进行编译。若要支持多个分辨率，请在主机上将帧调整为已编译的尺寸，或针对每个分辨率分别编译一个 HEF。
• 由于 Ultralytics 会根据模型元数据生成后处理配置，因此支持自定义类别数量。
• 支持使用标准 Ultralytics Detect 头的检测模型、YOLOv8/YOLO11 分割、姿态和 OBB 模型，以及 YOLOv8/YOLO11/YOLO26 分类模型和 YOLO26 语义分割与深度估计模型；目前不支持 YOLO26 实例分割、姿态和定向边界框，以及 YOLO-World、YOLOE、YOLOv10 和 RT-DETR 导出。
• Hailo-8/8L 和 Hailo-10H/15 工件由不同代的 DFC 编译，并且不能互换。

校准和 INT8 量化#

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

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

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

fraction 选择用于校准的比例或图像数量。[train, val, test] 列表会限制每个拆分，两个元素的列表会保留完整的 test，而 0 会跳过测试集。只有当图像代表部署域时，增加图像数量才有帮助。域外图像可能降低量化精度并增加优化时间。如果 INT8 HEF 相比原始 PyTorch 模型丢失精度，应先改进校准数据，再更改模型或运行时设置。

各模型系列的精度预期#

在具有域内校准（COCO128，128 张图像）的 Hailo-8L 上测得，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% 饱和，这也是 OBB 使用 DOTA128 进行评估的原因。分类也是唯一一个 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 HAT+ 和 AI HAT+ 2 用户可以参阅 Raspberry Pi AI 软件指南。在 Raspberry Pi OS 上，两组软件包不能同时安装，因此只运行与硬件匹配的代码块，然后重启。

对于 AI HAT+（Hailo-8 / Hailo-8L）：

sudo apt install dkms
sudo apt install hailo-all
sudo reboot

对于 AI HAT+ 2（Hailo-10H，Raspberry Pi OS Trixie 或更高版本）：

sudo apt install dkms
sudo apt install hailo-h10-all
sudo reboot

重启后，确认已检测到加速器：

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-10H/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 导出格式的比较#

根据执行模型的硬件选择导出格式。HEF 特定于硬件；当最终设备已包含 Hailo 加速器时应选择 HEF，而不应将其视为通用或自动最快的边缘格式。

不要仅因为 Hailo 是 NPU，就认为它一定更快或更节能。对于新的 M.2 部署，DeepX 是追求更高 YOLO 性能和更好每瓦性能的更强候选，而 Axelera 面向显著更高的多流吞吐量。Rockchip 是 SBC 和嵌入式系统中广受欢迎的低成本选项。厂商提供的 TOPS 和功耗数据并不是可直接比较的应用基准，因此在购买硬件之前，应在候选设备上验证相同的 YOLO 检查点、输入尺寸、精度、主机和完整视频流水线。

优化 Hailo 计算机视觉性能#

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

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

导出参数#

对于检测导出，YOLOv8 和 YOLO11 会使用 HailoRT NMS，而 YOLO26 保留其无 NMS 的一对一输出。分割、姿态和 OBB 使用原始检测头张量，分类返回芯片上的概率，语义分割在 Hailo-8/8L 上以及所有单类别检测头上返回原始 logits，在多类别 Hailo-10H/15 检测头上返回烘焙后的类别映射。深度估计返回原始深度 logit，Ultralytics 会在推理时将其解码为度量深度图。不要传入 end2end；显式覆盖会被拒绝。不支持动态形状、嵌入式 Ultralytics NMS、FP16 和 FP32。

Hailo 导出故障排除#

Hailo Dataflow Compiler 导入错误#

如果导出报告缺少 hailo_sdk_client，请在与 Ultralytics 相同的 Python 环境中安装适用于目标硬件代际的 DFC wheel。Hailo-8/8L 和 Hailo-10H/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 视频管道运行推理。

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

常见问题#