Exportação Hailo para modelos Ultralytics YOLO#

Os aceleradores de IA Hailo executam modelos compilados no Formato Executável Hailo (HEF) em dispositivos de borda, como o AI HAT+ do Raspberry Pi e o AI HAT+ 2. A Ultralytics exporta modelos YOLO de detecção, segmentação, segmentação semântica, estimativa de profundidade, classificação, pose e OBB diretamente para HEF com o Hailo Dataflow Compiler (DFC).

A implantação em Hailo foi projetada para visão computacional na borda: câmeras, robôs, sistemas industriais, gateways e outros dispositivos que precisam detectar objetos localmente sem enviar cada quadro para a nuvem. Um HEF compilado contém a rede quantizada, a alocação de hardware, o agendamento e o pós-processamento opcional do HailoRT necessários para o acelerador selecionado.

Por que implantar Ultralytics YOLO em Hailo?#

Combinar Ultralytics YOLO com uma unidade de processamento neural (NPU) Hailo oferece um caminho prático do treinamento do modelo à inferência de IA na borda. Os casos de uso comuns incluem:

• Câmeras inteligentes e análise de vídeo: execute detecção de objetos em tempo real perto da câmera para aplicações de segurança, varejo, trânsito e ocupação.
• Robótica e sistemas autônomos: detecte pessoas, veículos, encomendas, ferramentas ou obstáculos sem depender de uma conexão contínua com a nuvem.
• Visão computacional industrial: implante modelos YOLO personalizados para inspeção, contagem, monitoramento de segurança e controle de qualidade.
• Projetos de IA com Raspberry Pi: adicione inferência de visão acelerada a sistemas Raspberry Pi usando AI HAT+ ou AI HAT+ 2.
• Gateways de borda e PCs com IA: processe localmente vários fluxos de vídeo ou sensores, reduzindo os requisitos de largura de banda e computação na nuvem.

A inferência local pode melhorar a privacidade e o tempo de resposta porque as imagens permanecem no dispositivo de implantação. A taxa de transferência, a latência e o consumo de energia reais dependem do tamanho do modelo YOLO, da resolução de entrada, da arquitetura Hailo, do sistema host e do pipeline da aplicação.

Como funciona a exportação para Hailo#

A Ultralytics gerencia todo o fluxo de trabalho de exportação por trás de format="hailo":

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

O exportador executa automaticamente estas etapas:

1. Exporta um grafo ONNX estático com configurações compatíveis com o compilador.
2. Seleciona as saídas da cabeça de acordo com a arquitetura do modelo.
3. Gera diretivas de normalização, ativação e pós-processamento.
4. Cria um fluxo de calibração representativo e quantiza o modelo para INT8.
5. Compila o grafo otimizado para o acelerador Hailo selecionado.
6. Salva o HEF com metadados da Ultralytics e remove o arquivo ONNX intermediário.

Os modelos de detecção YOLOv8 e YOLO11 usam HailoRT YOLO NMS no pipeline compilado. YOLO26 compila tensores brutos da cabeça de detecção: a Ultralytics aplica NMS às saídas padrão one-to-many ou decodifica as saídas one-to-one sem NMS com nms=False. YOLOv8/YOLO11 de segmentação, pose e OBB compilam os tensores brutos da cabeça, que a Ultralytics decodifica durante a inferência; a classificação YOLOv8/YOLO11/YOLO26 executa softmax no chip, de modo que o HEF retorna diretamente as probabilidades das classes. Para segmentação semântica YOLO26, o exportador acompanha o acelerador: Hailo-8/8L (DFC v3.x) retornam logits do classificador para upsampling e redução no host, enquanto Hailo-10H/15 (DFC v5.x) compilam cabeças ArgMax multiclasse no chip e retornam um mapa de classes compacto. Cabeças de classe única usam o caminho de logits no host em todos os alvos porque exigem um limiar em vez de ArgMax. Os modelos de profundidade YOLO26 compilam a convolução densa de logits em a16 e reconstroem o mapa de profundidade métrica no host (o clamp/exp e a calibração log-affine aprendida que vêm depois da cabeça), para que o quantizador mantenha sua faixa mais ampla nos logits brutos. Os usuários não precisam encontrar nós de saída ONNX, escrever um script de modelo Hailo (.alls) nem criar manualmente um JSON de NMS.

Instalação#

Instale a Ultralytics e baixe o wheel do DFC para o hardware de destino no Hailo Developer Zone (é necessário fazer um cadastro gratuito):

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

Hailo-8 e Hailo-8L usam DFC v3.x. Hailo-10H e Hailo-15 usam DFC v5.x. Instale a geração do compilador que corresponde ao acelerador de destino.

Exporte um modelo HEF para Hailo#

Use format="hailo" e selecione o acelerador de destino com name:

from ultralytics import YOLO

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

O comando equivalente da CLI é:

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

A exportação para Hailo aceita somente INT8. A Ultralytics baixa automaticamente um conjunto de dados de calibração específico para a tarefa quando data não é fornecido. Para modelos personalizados, use imagens representativas de treinamento ou validação:

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

A compilação usa uma forma de entrada fixa. Defina imgsz com a resolução usada no dispositivo:

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

Modelos e hardware compatíveis#

O ecossistema Hailo abrange uma ampla variedade de cargas de trabalho de visão computacional, mas o exportador format="hailo" da Ultralytics valida atualmente cabeças YOLO padrão de detecção, segmentação, segmentação semântica, estimativa de profundidade, classificação, pose e OBB. A tabela de tarefas descreve os caminhos de exportação disponíveis; a validação de hardware é apresentada separadamente abaixo.

Famílias especializadas de detecção, como YOLOv10, YOLO-World, YOLOE e RT-DETR, ❌ não são compatíveis no momento pelo caminho format="hailo" da Ultralytics. A Ultralytics rejeita essas tarefas e famílias de modelos antes da compilação, em vez de produzir um HEF não validado.

Pose, OBB, classificação, segmentação semântica YOLO26 e estimativa de profundidade YOLO26 (caminho Hailo-8/8L) foram validados em Hailo-8L com HailoRT 4.23 e DFC 3.33. O exportador aceita os outros alvos listados, mas esses novos caminhos de tarefas precisam ser validados com o compilador e o dispositivo correspondentes antes do uso em produção.

Selecione um destes valores de name:

Se name for omitido, hailo8l será usado como padrão; defina name como o acelerador em que você fará a implantação. Instale a geração do DFC que corresponde ao alvo selecionado.

Hardware Hailo e gerações do SDK#

As famílias de aceleradores Hailo usam diferentes gerações de compiladores. O HEF gerado deve corresponder ao hardware de destino; portanto, escolha name para o dispositivo que executará a inferência, e não para a máquina que fará a exportação.

O compilador é executado em Linux x86_64, enquanto o HEF resultante é executado no dispositivo Hailo por meio do HailoRT. Essa separação permite compilar em uma estação de trabalho ou na Ultralytics Platform e implantar o artefato de runtime compacto em um host de borda ARM ou x86.

Notas de compatibilidade#

A compilação para Hailo é específica ao hardware e usa uma forma de entrada fixa. Leve estas restrições em conta:

• O name selecionado deve corresponder ao acelerador de implantação.
• As imagens de calibração devem representar a iluminação, os ângulos de visão, os objetos e os planos de fundo esperados em produção.
• Cada HEF é compilado para um imgsz fixo. Para processar várias resoluções, redimensione os quadros no host para o tamanho compilado ou compile um HEF separado para cada resolução.
• São aceitas quantidades personalizadas de classes porque a Ultralytics gera a configuração de pós-processamento a partir dos metadados do modelo.
• São compatíveis os modelos de detecção com cabeças padrão Detect da Ultralytics, os modelos YOLOv8/YOLO11 de segmentação, pose e OBB, os modelos YOLOv8/YOLO11/YOLO26 de classificação e os modelos YOLO26 de segmentação semântica e estimativa de profundidade; no momento, não são compatíveis as exportações de segmentação de instâncias, pose e caixa delimitadora orientada do YOLO26, nem as de YOLO-World, YOLOE, YOLOv10 e RT-DETR.
• Os artefatos para Hailo-8/8L e Hailo-10H/15 são compilados por gerações diferentes do DFC e não são intercambiáveis.

Calibração e quantização INT8#

A exportação HEF para Hailo usa quantização INT8 para mapear a rede YOLO com eficiência no acelerador. O conjunto de dados de calibração estima os intervalos de ativação; ele não retreina o modelo nem exige rótulos durante a compilação.

Quando data é omitido, a Ultralytics usa um conjunto de dados de calibração leve e específico para a tarefa, como COCO128 para detecção, cityscapes8 para segmentação semântica ou depth8 para estimativa de profundidade. A cabeça de profundidade densa é especialmente sensível ao domínio de calibração: calibrar um modelo de profundidade com imagens de detecção não relacionadas achata o mapa previsto, enquanto conjuntos maiores do domínio correto melhoram a fidelidade. Para um modelo personalizado de visão computacional, aponte data para o YAML do conjunto de dados para que o compilador observe imagens representativas do domínio real de implantação:

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

fraction seleciona a proporção ou a quantidade de imagens usadas na calibração. As listas [train, val, test] definem o limite de cada divisão; listas com dois itens mantêm test completo, e 0 ignora o teste. Mais imagens só ajudam quando representam o domínio de implantação. Imagens fora do domínio podem reduzir a precisão após a quantização e aumentar o tempo de otimização. Se o HEF INT8 perder precisão em relação ao modelo PyTorch original, primeiro melhore os dados de calibração antes de alterar as configurações do modelo ou do tempo de execução.

Expectativas de precisão por família de modelos#

Medidos em um Hailo-8L com calibração no domínio correto (COCO128, 128 imagens), os exports HEF INT8 retêm a seguinte proporção do mAP50 do PyTorch sob o mesmo protocolo de avaliação:

A retenção compara os dois modelos no mesmo limiar de confiança. Os HEFs YOLOv8 e YOLO11 incorporam o conf usado na exportação (padrão 0.25) à NMS no chip, então validá-los em relação a uma referência PyTorch no limiar baixo padrão integra uma parte maior da curva precisão-revocação e superestima a diferença de quantização.

Além da detecção, os caminhos de exportação para segmentação, pose, OBB e classificação foram validados no mesmo Hailo-8L (DFC 3.33, HailoRT 4.23). Cada HEF INT8 foi comparado ao seu checkpoint PyTorch na mesma divisão de validação, com calibração no domínio correto:

A segmentação, a pose e o OBB foram calibrados com o conjunto padrão de cada tarefa no domínio correto (COCO128-seg, COCO8-pose, DOTA128); a classificação foi calibrada com ImageNet100. Há duas ressalvas decorrentes desses padrões: COCO8-pose contém apenas 8 imagens, então considere os resultados de pose indicativos e forneça um data= maior para produção; e DOTA8 satura o mAP50 perto de 100% para ambos os modelos, por isso o OBB é avaliado em DOTA128. A classificação também é a única tarefa em que YOLO11 retém mais que YOLOv8; nas demais, a rede principal com atenção do YOLO11 é mais sensível a INT8.

As medições no dispositivo levam a três regras práticas:

1. Calibre sempre no domínio correto. O ajuste fino com imagens fora do domínio equivale a desativar totalmente o ajuste fino: um YOLO26n calibrado com 1,238 imagens fora do domínio mantém a mesma precisão (85.7%) que um compilado sem ajuste fino. Um conjunto pequeno do domínio correto é melhor que um conjunto grande fora do domínio.
2. Reduza conf em cerca de 0.05 para implantações do YOLO26. A quantização reduz as pontuações do YOLO26 em aproximadamente 0.05, em média, então um limiar ajustado no PyTorch descarta detecções válidas no HEF. Usar conf=0.20 no dispositivo iguala a quantidade de detecções do PyTorch em conf=0.25, e reduzir um pouco mais (para cerca de conf=0.15) recupera praticamente toda a diferença restante de mAP50, ao custo de mais detecções com baixa confiança. A quantização também altera a ordem de aproximadamente 20% das detecções — um efeito permanente de ordenação que nenhum limiar desfaz —, mas essa reordenação não impede a recuperação do mAP50 com o limiar mais baixo.
3. A penalidade da atenção é estrutural no Hailo-8/8L (DFC 3.33). Os blocos de atenção compilam para operações matmul que mantêm as entradas de ativação INT8 em todos os modos oferecidos pelo compilador; o modo de saída de 16 bits falha na alocação para este grafo, e aumentar a precisão das camadas adjacentes não ajuda, porque a multiplicação de matrizes requantiza as entradas para INT8 de qualquer maneira (proteger as convoluções depthwise e de saída com 16 bits não alterou o mAP em nossos testes). Quando a precisão é prioritária e o modelo pode ser substituído, YOLO11 atualmente quantiza melhor que YOLO26 neste caso; gerações mais recentes do Hailo (DFC 5.x) oferecem mais opções de precisão mista e podem apresentar resultados diferentes.

Artefatos exportados#

A exportação cria um diretório com o HEF pronto para implantação e os metadados da Ultralytics:

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

• *.hef é o modelo compilado carregado pelo HailoRT.
• metadata.yaml preserva os nomes do modelo, a tarefa, o tamanho da entrada, o stride e as informações do alvo Hailo.
• nms_config.json registra a configuração NMS do HailoRT gerada para modelos de detecção YOLOv8 e YOLO11. A detecção YOLO26 e todas as tarefas que não são de detecção (segmentação, segmentação semântica, profundidade, classificação, pose, OBB) não usam este arquivo.

O grafo ONNX intermediário é removido após a compilação.

Executar inferência no hardware Hailo#

Instale o HailoRT no dispositivo de destino. Quem usa o Raspberry Pi AI HAT+ e o AI HAT+ 2 pode seguir o guia de software para Raspberry Pi AI. No Raspberry Pi OS, os dois conjuntos de pacotes não podem ser instalados ao mesmo tempo; execute apenas o bloco correspondente ao seu hardware e, em seguida, reinicie.

Para o AI HAT+ (Hailo-8 / Hailo-8L):

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

Para o AI HAT+ 2 (Hailo-10H, Raspberry Pi OS Trixie ou mais recente):

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

Após reiniciar, confirme se o acelerador foi detectado:

hailortcli fw-control identify

Copie o diretório completo de exportação para o dispositivo para que metadata.yaml permaneça ao lado do HEF. A Ultralytics usa o HailoRT para executar predict e val diretamente no diretório exportado:

from ultralytics import YOLO

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

Para modelos de detecção, o backend converte a saída NMS do HailoRT do YOLOv8/YOLO11 e decodifica automaticamente qualquer uma das cabeças YOLO26. As saídas padrão um-para-muitos passam pela NMS do preditor. O backend decodifica tensores brutos de segmentação, pose e OBB, retorna probabilidades de classificação calculadas no chip e gera mapas de classes semânticas por redução no host no Hailo-8/8L e em todas as cabeças de classe única, ou por um ArgMax no chip para cabeças de várias classes do Hailo-10H/15. TAPPAS, GStreamer e o auxiliar picamera2.devices.Hailo do Raspberry Pi continuam disponíveis para pipelines específicos de cada aplicação.

Para uma implantação com GStreamer, passe o HEF para 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

Opções de implantação Hailo#

O HEF é o mesmo artefato de modelo pronto para implantação em várias interfaces de tempo de execução Hailo. Escolha a interface adequada à aplicação:

Mantenha metadata.yaml junto ao HEF quando a aplicação precisar dos nomes de classe, do tamanho da entrada, do stride ou de outras informações do modelo da Ultralytics. O HEF, por si só, não substitui a lógica da aplicação para captura da câmera, visualização, rastreamento, alertas ou armazenamento.

Verificar o dispositivo Hailo e o HEF#

Antes de integrar uma câmera ou um pipeline de vídeo, verifique o tempo de execução e o acelerador de forma independente:

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

As medições de desempenho apenas no dispositivo isolam a inferência Hailo da decodificação de vídeo, do redimensionamento de imagens, da renderização e da E/S da aplicação. Meça a aplicação completa separadamente ao estimar a latência de ponta a ponta ou os quadros por segundo.

Benchmarks#

A equipe da Ultralytics avaliou modelos YOLO26, comparando a velocidade e a precisão entre PyTorch e Hailo.

Desempenho

Raspberry Pi 5 + AI HAT+ (Hailo-8)Mais dispositivos em breve!

Modelo	Formato	Status	Tamanho (MB)	metrics/mAP50-95(B)	Tempo de inferência (ms/im)
YOLO26n	PyTorch	✅	5.3	0.477	364.6
YOLO26n	Hailo	✅	7.3	0.455	21.7

Modelo	Formato	Status	Tamanho (MB)	metrics/mIoU	Tempo de inferência (ms/im)
YOLO26n-sem	PyTorch	✅	3.3	0.611	831.2
YOLO26n-sem	Hailo	✅	6.2	0.611	34.8

Modelo	Formato	Status	Tamanho (MB)	metrics/delta1	metrics/abs_rel	metrics/rmse	Tempo de inferência (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

Modelo	Formato	Status	Tamanho (MB)	acc (top1)	acc (top5)	Tempo de inferência (ms/im)
YOLO26n-cls	PyTorch	✅	5.5	0.431	0.716	33.8
YOLO26n-cls	Hailo	✅	3.5	0.441	0.716	2.0

Nota

A validação dos benchmarks acima foi realizada usando COCO128 para detecção, Cityscapes8 para segmentação semântica, Depth8 para estimativa de profundidade e ImageNet100 para classificação. Cityscapes8 e Depth8 contêm apenas 4 imagens de validação cada, portanto, considere os valores de precisão da segmentação semântica e da profundidade como resultados de testes de verificação, não como medições de retenção da precisão; valide em um conjunto de dados completo, como Cityscapes ou NYU Depth V2, antes de tirar conclusões sobre a precisão. O tempo de inferência não inclui o pré-processamento nem o pós-processamento.

Hailo em comparação com outros formatos de exportação YOLO#

Escolha um formato de exportação com base no hardware que executará o modelo. O HEF é específico do hardware e deve ser escolhido quando o dispositivo final já contém um acelerador Hailo, não como um formato genérico ou automaticamente mais rápido para edge.

Não presuma que Hailo é mais rápido ou mais eficiente em termos de energia apenas por ser uma NPU. Para novas implantações M.2, DeepX é a opção mais forte para obter maior desempenho YOLO e melhor desempenho por watt, enquanto Axelera visa uma vazão de vários fluxos substancialmente maior. Rockchip é uma opção popular e de menor custo em SBCs e sistemas embarcados. Os valores de TOPS e de consumo de energia dos fornecedores não são benchmarks de aplicações diretamente comparáveis; portanto, valide o mesmo checkpoint YOLO, tamanho de entrada, precisão, host e pipeline de vídeo completo nos dispositivos candidatos antes de comprar hardware.

Otimize o desempenho de visão computacional Hailo#

As escolhas do modelo e do pipeline costumam importar mais que as flags do compilador:

• Comece com um modelo YOLO pequeno e aumente o tamanho do modelo apenas quando a precisão exigir.
• Escolha o menor valor fixo de imgsz que ainda preserve os objetos importantes para a aplicação.
• Sempre que possível, use imagens de calibração da câmera e do ambiente reais.
• Mantenha a rede Hailo ativa entre os quadros, em vez de reabrir o HEF para cada inferência.
• Separe o tempo de inferência no dispositivo do pré-processamento, da decodificação de vídeo, do pós-processamento, da visualização e da E/S de rede.
• Usa um pipeline de streaming, como o GStreamer, para cargas de trabalho de vídeo contínuas.
• Valida o HEF exportado no acelerador exato e na versão do HailoRT usados em produção.

Argumentos de exportação#

As exportações de detecção YOLOv8/YOLO11 recebem NMS do HailoRT. Por padrão, YOLO26 gera saídas brutas one-to-many para NMS no host; nms=False seleciona suas saídas one-to-one sem NMS. Segmentação, pose e OBB usam tensores brutos da cabeça; classificação retorna probabilidades no chip; e a segmentação semântica retorna logits brutos no Hailo-8/8L e em todas as cabeças de classe única, ou mapas de classes incorporados nas cabeças Hailo-10H/15 de várias classes. A estimativa de profundidade retorna o logit bruto de profundidade, que o Ultralytics decodifica em um mapa de profundidade métrica durante a inferência. Formas dinâmicas, NMS incorporado do Ultralytics, FP16 e FP32 não são compatíveis.

Solução de problemas da exportação para Hailo#

Erro de importação do Hailo Dataflow Compiler#

Se a exportação informar que hailo_sdk_client está ausente, instala o wheel do DFC para a geração de hardware de destino no mesmo ambiente Python que o Ultralytics. Hailo-8/8L e Hailo-10H/15 exigem gerações diferentes do compilador.

Sistema operacional ou arquitetura não compatível#

A compilação de HEF é compatível com Linux x86_64. Exporta através da Ultralytics Platform ou usa uma estação de trabalho compatível se o computador local tiver macOS, Windows, Raspberry Pi ou outro sistema ARM.

A exportação demora muito#

A otimização do DFC é a etapa que exige mais recursos. O tempo de compilação aumenta com o tamanho do modelo, a resolução da entrada e os dados de calibração. Uma GPU compatível pode acelerar a otimização, enquanto a compilação apenas com CPU pode ser consideravelmente mais lenta.

A precisão do modelo quantizado diminui#

Usa imagens de calibração semelhantes às entradas de produção e que incluam os objetos, as escalas, as condições de iluminação e os fundos importantes. Compara o modelo PyTorch original e o HEF exportado no mesmo conjunto de validação antes da implantação. Mesmo com uma boa calibração, permanece uma diferença moderada que depende da família do modelo; consulta Expectativas de precisão por família de modelo para ver as referências medidas.

O HEF não carrega no dispositivo#

Confirma que name corresponde à arquitetura física do Hailo e que o driver do dispositivo, o firmware e os pacotes do HailoRT são compatíveis entre si. Inspeciona o artefato com hailortcli parse-hef e verifica o acelerador com hailortcli fw-control identify.

A análise da saída parece incorreta#

Mantém metadata.yaml junto ao HEF para que o Ultralytics possa selecionar o caminho de pós-processamento correspondente a YOLOv8, YOLO11 ou YOLO26. Aplicações personalizadas do HailoRT também precisam usar um pós-processamento correspondente à família do modelo exportado.

Resumo#

A exportação para Hailo do Ultralytics oferece um caminho direto de um modelo YOLO treinado a um HEF pronto para implantação:

1. Carrega um modelo de detecção ou classificação YOLOv8, YOLO11 ou YOLO26; um modelo de segmentação, pose ou OBB YOLOv8/YOLO11; ou um modelo de segmentação semântica ou estimativa de profundidade YOLO26.
2. Exporta com format="hailo" e seleciona a arquitetura de destino.
3. Faz a calibração e a compilação localmente com o DFC correspondente ou usa a exportação gerenciada na Ultralytics Platform.
4. Copia o HEF e metadata.yaml para o dispositivo de borda equipado com Hailo.
5. Executa a inferência com HailoRT, Raspberry Pi Picamera2 ou um pipeline de vídeo GStreamer.

Para outros destinos de implantação de visão computacional, consulta o modo Export, o modo Benchmark e o guia de integrações. Os guias relacionados a hardware incluem DeepX, Axelera, ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 e Qualcomm QNN.

Perguntas frequentes#