将 Ultralytics YOLO 模型导出为 Hailo 格式#

Hailo AI 加速器可在 Raspberry Pi AI HAT+ 和 AI HAT+ 2 等边缘设备上运行已编译的 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 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 会编译原始检测头张量：对于默认的一对多输出，Ultralytics 会应用 NMS；对于无 NMS 的一对一输出，则使用 nms=False 进行解码。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 中编译稠密 logit 卷积，并在主机端重建度量深度图（检测头之后的 clamp/exp 和学习得到的 log 仿射校准），以便量化器为原始 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 模型，请先改进校准数据，再调整模型或运行时设置。

不同模型系列的精度预期#

在 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% 饱和，因此 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 激活输入都会保持为 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 头部。默认的一对多输出会经过预测器的 NMS。后端会解码原始分割、姿态和 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 区分开来。估算端到端延迟或每秒帧数时，请单独测量完整应用。

基准测试#

Ultralytics 团队对 YOLO26 模型进行了基准测试，比较了 PyTorch 和 Hailo 在速度和准确率方面的表现。

性能

Raspberry Pi 5 + AI HAT+ (Hailo-8)更多设备即将推出！

模型	格式	状态	大小 (MB)	metrics/mAP50-95(B)	推理时间 (ms/im)
YOLO26n	PyTorch	✅	5.3	0.477	364.6
YOLO26n	Hailo	✅	7.3	0.455	21.7

模型	格式	状态	大小 (MB)	metrics/mIoU	推理时间 (ms/im)
YOLO26n-sem	PyTorch	✅	3.3	0.611	831.2
YOLO26n-sem	Hailo	✅	6.2	0.611	34.8

模型	格式	状态	大小 (MB)	metrics/delta1	metrics/abs_rel	metrics/rmse	推理时间 (ms/im)
YOLO26n-depth	PyTorch	✅	12.4	0.8535	0.0983	0.2047	2133.4
YOLO26n-depth	Hailo	✅	9.9	0.8241	0.1232	0.2554	29.6

模型	格式	状态	大小 (MB)	准确率 (top1)	准确率 (top5)	推理时间 (ms/im)
YOLO26n-cls	PyTorch	✅	5.5	0.431	0.716	33.8
YOLO26n-cls	Hailo	✅	3.5	0.441	0.716	2.0

注意

上述基准测试使用 COCO128 进行目标检测验证，使用 Cityscapes8 进行语义分割验证，使用 Depth8 进行深度估计验证，并使用 ImageNet100 进行分类验证。Cityscapes8 和 Depth8 各自仅包含 4 张验证图像，因此应将它们的语义分割和深度准确率数值视为冒烟测试结果，而非准确率保持情况的测量结果；在得出准确率结论前，请使用 Cityscapes 或 NYU Depth V2 等完整数据集进行验证。推理时间不包括预处理和后处理。

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

请根据执行模型的硬件选择导出格式。HEF 专用于特定硬件，只有当最终设备已配备 Hailo 加速器时才应选择它；不要将它视为通用格式或自动认为它是速度最快的边缘格式。

不要仅仅因为 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；nms=False 可选择其无 NMS 的一对一输出。分割、姿态和 OBB 使用原始检测头张量，分类返回芯片上的概率值，语义分割则在 Hailo-8/8L 和所有单类别检测头上返回原始 logits，在多类别 Hailo-10H/15 检测头上返回烘焙后的类别映射。深度估计返回原始深度 logit，Ultralytics 会在推理时将其解码为度量深度图。不支持动态形状、嵌入式 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。

常见问题#