Exportação HEF para Modelos YOLO da Ultralytics#

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

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

Por que implantar Ultralytics YOLO no Hailo?#

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

• Câmeras inteligentes e análise de vídeo: Execute detecção de objetos em tempo real próxima à câmera para aplicações de segurança, varejo, tráfego e ocupação.
• Robótica e sistemas autônomos: Detecte pessoas, veículos, pacotes, 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 Raspberry Pi AI: Adicione inferência de visão acelerada a sistemas Raspberry Pi usando o AI Kit ou AI HAT+.
• Gateways de borda e PCs com IA: Processe vários fluxos de vídeo ou sensores localmente, reduzindo a largura de banda e os requisitos de computação em nuvem.

A inferência local pode melhorar a privacidade e o tempo de resposta, pois as imagens permanecem no dispositivo de implantação. O rendimento, 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 Hailo#

O Ultralytics detém o fluxo de trabalho de exportação completo por trás de format="hailo":

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

O exportador executa estas etapas automaticamente:

1. Exporta um grafo ONNX estático com configurações compatíveis com o compilador.
2. Seleciona as saídas de cabeçalho para a arquitetura do modelo.
3. Gera diretrizes de normalização, ativação e pós-processamento.
4. Constrói 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 o HailoRT YOLO NMS no pipeline compilado. Os modelos de detecção YOLO26 usam suas saídas um a um sem NMS, portanto o exportador seleciona um caminho de saída e quantização diferente automaticamente. A segmentação, pose e OBB do YOLOv8/YOLO11 compilam os tensores de cabeçeta brutos, que o Ultralytics decodifica na inferência, e a classificação do YOLOv8/YOLO11/YOLO26 executa softmax no chip para que o HEF retorne as probabilidades de classe diretamente. Para a segmentação semântica do YOLO26, o exportador segue o acelerador: o Hailo-8/8L (DFC v3.x) retorna logits do classificador para upsampling e redução no host, enquanto o Hailo-10/15 (DFC v5.x) compila cabeçetas ArgMax multiclasse no chip e retorna um mapa de classes compacto. As cabeçetas de classe única usam o caminho de logit do host em todos os alvos porque exigem um limite em vez de ArgMax. Os modelos de profundidade YOLO26 compilam a convolução de logit densa em a16 e reconstroem o mapa de profundidade métrica no host (o clamp/exp e a calibração log-affine aprendida que seguem a cabeçeta), para que o quantizador mantenha sua faixa mais ampla no logit bruto. Os usuários não precisam encontrar nós finais ONNX, escrever um script de modelo Hailo (.alls) ou criar um JSON de NMS manualmente.

Instalação#

Instale a Ultralytics e baixe o wheel do DFC para o seu hardware alvo na Hailo Developer Zone (é necessário registro gratuito):

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

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

Exportar um modelo HEF Hailo#

Usa format="hailo" e seleciona o acelerador de destino com name:

from ultralytics import YOLO

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

O comando CLI equivalente é:

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

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

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

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

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

Modelos e hardware suportados#

O ecossistema Hailo cobre uma ampla gama de cargas de trabalho de visão computacional, mas o exportador format="hailo" do Ultralytics atualmente valida cabeçetas padrão de detecção, segmentação, segmentação semântica, estimativa de profundidade, classificação, pose e OBB do YOLO. A tabela de tarefas descreve os caminhos de exportador disponíveis; a validação de hardware está listada separadamente abaixo.

Famílias de detecção especializadas, como YOLOv10, YOLO-World, YOLOE e RT-DETR, também são ❌ não suportadas. 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 do YOLO26 e estimativa de profundidade do YOLO26 (caminho Hailo-8/8L) foram validadas no Hailo-8L com HailoRT 4.23 e DFC 3.33. O exportador aceita os outros destinos listados, mas esses novos caminhos de tarefas exigem validação com o compilador e dispositivo correspondentes antes do uso em produção.

Seleciona um destes valores de name:

hailo8l é o padrão. Instala a geração do DFC que corresponde ao alvo selecionado.

Gerações de hardware e SDK Hailo#

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

O compilador é executado em Linux x86_64, enquanto o HEF resultante é executado no dispositivo Hailo através do HailoRT. Essa separação permite que você compile em uma estação de trabalho ou na plataforma Ultralytics e implante o pequeno artefato de runtime em um host de borda ARM ou x86.

Notas de Compatibilidade#

A compilação Hailo é específica para hardware e usa uma forma de entrada fixa. Lembre-se destas restrições:

• O name selecionado deve corresponder ao acelerador de implantação.
• As imagens de calibração devem representar a iluminação, os pontos de vista, os objetos e os fundos esperados na produção.
• Um HEF compilado com um imgsz não se torna redimensionável dinamicamente em tempo de execução.
• Contagens de classes personalizadas são suportadas porque a Ultralytics gera a configuração de pós-processamento a partir dos metadados do modelo.
• Modelos de detecção com cabeçetas padrão Detect do Ultralytics, modelos de segmentação, pose e OBB do YOLOv8/YOLO11, modelos de classificação do YOLOv8/YOLO11/YOLO26 e modelos de segmentação semântica e estimativa de profundidade do YOLO26 são suportados; segmentação de instâncias, pose e caixa delimitadora orientada do YOLO26, juntamente com exportações de YOLO-World, YOLOE, YOLOv10 e RT-DETR, não são suportadas no momento.
• Os artefatos Hailo-8/8L e Hailo-10/15 são compilados por diferentes gerações do DFC e não são intercambiáveis.

Calibração e quantização INT8#

A exportação de HEF Hailo usa quantização INT8 para mapear a rede YOLO eficientemente no acelerador. O conjunto de dados de calibração estima faixas de ativação; ele não retreina o modelo nem requer rótulos durante a compilação.

Quando data é omitido, o Ultralytics usa um conjunto de dados de calibração leve específico para a tarefa, como COCO128 para detecção, cityscapes8 para segmentação semântica ou depth8 para estimativa de profundidade. A cabeçeta 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, e conjuntos maiores do mesmo domínio melhoram a fidelidade. Para um modelo de visão computacional personalizado, aponta data para o seu YAML de conjunto de dados para que o compilador observe imagens representativas do domínio de implantação real:

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

fraction seleciona a porção do conjunto de dados usada para calibração. Mais imagens ajudam apenas quando representam o domínio de implantação; imagens fora do domínio podem reduzir a precisão quantizada e aumentar o tempo de otimização. Se o HEF INT8 perder precisão em relação ao modelo PyTorch original, melhora primeiro 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 modelo#

Medido em um Hailo-8L com calibração in-domain (COCO128, 128 imagens), as exportações INT8 HEF mantêm a seguinte parcela do seu mAP50 do PyTorch sob o mesmo protocolo de avaliação:

A retenção compara ambos os modelos no mesmo limite de confiança. Os HEFs do YOLOv8 e YOLO11 incorporam o conf do momento da exportação (padrão 0.25) no NMS integrado ao chip, portanto, validar contra uma linha de base do PyTorch em seu limite baixo padrão integra uma parte maior da curva de precisão-revocação e exagera a lacuna de quantização.

Além da detecção, os caminhos do exportador de segmentação, pose, OBB e classificação foram validados no mesmo Hailo-8L (DFC 3.33, HailoRT 4.23). Cada HEF INT8 foi comparado com seu checkpoint PyTorch na mesma divisão de validação, usando calibração in-domain:

A segmentação, a pose e o OBB foram calibrados com o conjunto padrão do próprio domínio para cada tarefa (COCO128-seg, COCO8-pose, DOTA128); a classificação foi calibrada com o ImageNet100. Duas ressalvas decorrem desses padrões: o COCO8-pose tem apenas 8 imagens, portanto trata a pose como indicativa e passa um data= maior para produção, e o DOTA8 satura o mAP50 próximo a 100% para ambos os modelos, razão pela qual o OBB é lido no DOTA128. A classificação também é a única tarefa em que o YOLO11 retém mais do que o YOLOv8; para as outras, a espinha dorsal de atenção do YOLO11 é mais sensível ao INT8.

Três regras práticas decorrem das medições do dispositivo:

1. Calibre in-domain, sempre. O ajuste fino com imagens fora do domínio é equivalente a desativar o ajuste fino completamente: um YOLO26n calibrado com 1.238 imagens fora do domínio retém a mesma precisão (85,7%) que um compilado sem ajuste fino. Um pequeno conjunto in-domain supera um grande conjunto fora do domínio.
2. Reduz conf em cerca de 0.05 para implantações do YOLO26. A quantização diminui as pontuações do YOLO26 em aproximadamente 0.05 em média, de modo que um limite ajustado no PyTorch descarta detecções válidas no HEF. Usar conf=0.20 no dispositivo corresponde à contagem de detecções do PyTorch em conf=0.25, e reduzir um pouco mais (em torno de conf=0.15) recupera essencialmente toda a lacuna restante do mAP50 ao custo de mais detecções de baixa confiança. A quantização também reclassifica aproximadamente 20% das detecções — um efeito de ordenação permanente que nenhum limite desfaz —, mas essa reorganização não bloqueia a recuperação do mAP50 no limite inferior.
3. A penalidade de atenção é estrutural no Hailo-8/8L (DFC 3.33). Os blocos de atenção compilam para operações matmul que mantêm entradas de ativação INT8 em todos os modos que o compilador oferece para elas; o modo de saída de 16 bits falha na alocação para este grafo, e aumentar a precisão das camadas ao redor não ajuda porque o matmul requantiza suas entradas para INT8 de qualquer maneira (proteger as convoluções de profundidade e de saída em 16 bits deixou o mAP inalterado em nossos testes). Quando a precisão é a prioridade e o modelo é intercambiável, o YOLO11 atualmente quantiza melhor do que o YOLO26 aqui; gerações mais recentes da Hailo (DFC 5.x) expõem mais opções de precisão mista e podem diferir.

Artefatos exportados#

A exportação cria um diretório contendo o HEF implantável 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 dos modelos, a tarefa, o tamanho da entrada, o stride e as informações do alvo Hailo.
• nms_config.json registra a configuração de NMS do HailoRT gerada para os modelos de detecção YOLOv8 e YOLO11. A detecção do YOLO26 e todas as tarefas que não são de detecçã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#

Instala o HailoRT no dispositivo de destino. Os usuários do Raspberry Pi AI Kit e do AI HAT+ podem seguir o guia de software de IA do Raspberry Pi:

sudo apt install hailo-all
hailortcli fw-control identify

Copia o diretório de exportação completo para o dispositivo para que metadata.yaml permaneça ao lado do HEF. O 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 do NMS HailoRT do YOLOv8 e YOLO11 e decodifica as saídas um a um do YOLO26 automaticamente. Ele decodifica tensores brutos de segmentação, pose e OBB, retorna probabilidades de classificação no chip e produz mapas de classes semânticas por meio de redução no host no Hailo-8/8L e em todas as cabeçetas de classe única ou um ArgMax no chip para cabeçetas multiclasse do Hailo-10/15. TAPPAS, GStreamer e o auxiliar picamera2.devices.Hailo do Raspberry Pi permanecem disponíveis para pipelines específicos de aplicativos.

Para uma implantação no GStreamer, passa 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 implantável em várias interfaces de runtime Hailo. Escolha a interface que melhor se adapta à aplicação:

Mantém metadata.yaml junto com o HEF quando o aplicativo precisar de nomes de classes, tamanho de entrada, stride ou outras informações de modelo do Ultralytics. O próprio HEF não substitui a lógica de nível de aplicativo para captura de câmera, visualização, rastreamento, alertas ou armazenamento.

Verifique o dispositivo Hailo e o HEF#

Antes de integrar uma câmera ou pipeline de vídeo, verifique o runtime e o acelerador de forma independente:

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

Medições de desempenho apenas no dispositivo isolam a inferência Hailo da decodificação de vídeo, redimensionamento de imagem, desenho e I/O da aplicação. Meça a aplicação completa separadamente ao estimar a latência de ponta a ponta ou quadros por segundo.

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

Escolha um formato de exportação baseado no hardware que executará o modelo:

O HEF é a escolha correta quando o dispositivo final contém um acelerador Hailo. O ONNX continua sendo útil como um formato de intercâmbio portátil, mas o HailoRT executa o HEF específico de hardware produzido pelo DFC em vez do modelo ONNX original.

Otimize o desempenho de visão computacional Hailo#

Escolhas de modelo e pipeline muitas vezes importam mais do que flags de compilador:

• Comece com um modelo YOLO pequeno e aumente o tamanho do modelo apenas quando a precisão exigir.
• Escolhe o menor imgsz fixo que ainda preserve os objetos importantes para o aplicativo.
• Use imagens de calibração da câmera e do ambiente reais sempre que possível.
• 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, decodificação de vídeo, pós-processamento, visualização e I/O de rede.
• Use um pipeline de streaming como o GStreamer para cargas de trabalho de vídeo sustentadas.
• Valide o HEF exportado no acelerador exato e na versão do HailoRT usada em produção.

Argumentos de Exportação#

Para exportação de detecção, YOLOv8 e YOLO11 recebem NMS do HailoRT, enquanto o YOLO26 mantém suas saídas um a um sem NMS. A segmentação, pose e OBB usam tensores de cabeçeta brutos, 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çetas de classe única ou mapas de classes incorporados para cabeçetas multiclasse do Hailo-10/15. A estimativa de profundidade retorna o logit de profundidade bruto, que o Ultralytics decodifica em um mapa de profundidade métrica na inferência. Não passes end2end; substituições explícitas são rejeitadas. Formas dinâmicas, lotes maiores que um, NMS do Ultralytics embutido, FP16 e FP32 também não são suportados.

Solução de problemas na exportação Hailo#

Erro de importação do Hailo Dataflow Compiler#

Se a exportação relatar 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. O Hailo-8/8L e o Hailo-10/15 exigem gerações de compiladores diferentes.

Sistema operacional ou arquitetura não suportados#

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

A exportação leva muito tempo#

A otimização do DFC é o estágio mais dispendioso. O tempo de compilação aumenta com o tamanho do modelo, resolução de entrada e dados de calibração. Uma GPU suportada pode acelerar a otimização, enquanto a compilação apenas por CPU pode ser substancialmente mais lenta.

A precisão do modelo quantizado cai#

Usa imagens de calibração que se pareçam com as entradas de produção e incluam os objetos importantes, escalas, condições de iluminação e fundos. Compara o modelo PyTorch original e o HEF exportado no mesmo conjunto de validação antes da implantação. Uma lacuna moderada dependente da família permanece mesmo com uma boa calibração; consulta Accuracy Expectations by Model Family para ver as linhas de base medidas.

O HEF não carrega no dispositivo#

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

O processamento de saída parece incorreto#

Mantém metadata.yaml ao lado do HEF para que o Ultralytics possa selecionar o caminho de pós-processamento correspondente do YOLOv8, YOLO11 ou YOLO26. Aplicativos HailoRT personalizados devem da mesma forma corresponder o pós-processamento à família de modelos exportada.

Resumo#

A exportação Hailo da Ultralytics fornece um caminho direto de um modelo YOLO treinado para um HEF implantável:

1. Carregue um modelo de detecção ou classificação do YOLOv8, YOLO11 ou YOLO26, um modelo de segmentação, pose ou OBB do YOLOv8/YOLO11, ou um modelo de segmentação semântica ou estimativa de profundidade do YOLO26.
2. Exporta com format="hailo" e seleciona a arquitetura de destino.
3. Calibre e compile localmente com o DFC correspondente, ou use a exportação gerenciada na Plataforma Ultralytics.
4. Copia o HEF e metadata.yaml para o dispositivo de borda alimentado por Hailo.
5. Execute 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 Export mode, Benchmark mode e o guia de integrações. Guias de hardware relacionados incluem ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 e Qualcomm QNN.

FAQ#