Exportação Hailo para modelos YOLO da Ultralytics#

Os aceleradores Hailo AI executam modelos compilados no Hailo Executable Format (HEF) em dispositivos edge, como o Raspberry Pi AI HAT+ e o AI HAT+ 2. A Ultralytics exporta modelos YOLO de deteçã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 implementação com Hailo foi concebida para visão computacional na edge: câmaras, robôs, sistemas industriais, gateways e outros dispositivos que precisam de deteção de objetos local sem enviar cada fotograma para a cloud. Um HEF compilado contém a rede quantizada, a alocação de hardware, o agendamento e o pós-processamento HailoRT opcional necessários para o acelerador selecionado.

Porquê implementar Ultralytics YOLO na Hailo?#

Combinar Ultralytics YOLO com uma unidade de processamento neural (NPU) Hailo proporciona um caminho prático desde o treino do modelo até à inferência de IA na edge. Os casos de uso comuns incluem:

• Câmaras inteligentes e análise de vídeo: Executa deteção de objetos em tempo real junto à câmara para aplicações de segurança, retalho, tráfego e ocupação.
• Robótica e sistemas autónomos: Deteta pessoas, veículos, encomendas, ferramentas ou obstáculos sem depender de uma ligação contínua à cloud.
• Visão computacional industrial: Implementa modelos YOLO personalizados para inspeção, contagem, monitorização de segurança e controlo de qualidade.
• Projetos de IA com Raspberry Pi: Adiciona inferência de visão acelerada a sistemas Raspberry Pi utilizando o AI HAT+ ou o AI HAT+ 2.
• Gateways edge e AI PCs: Processa localmente vários fluxos de vídeo ou sensores, reduzindo simultaneamente os requisitos de largura de banda e computação na cloud.

A inferência local pode melhorar a privacidade e o tempo de resposta, porque as imagens permanecem no dispositivo de implementação. O débito, 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 anfitrião e do pipeline da aplicação.

Como funciona a exportação Hailo#

A Ultralytics gere todo o fluxo 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 definições compatíveis com o compilador.
2. Seleciona as saídas da cabeça para 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. Guarda o HEF com metadados da Ultralytics e remove o ficheiro ONNX intermédio.

Os modelos de deteção YOLOv8 e YOLO11 utilizam HailoRT YOLO NMS no pipeline compilado. Os modelos de deteção YOLO26 utilizam as suas saídas one-to-one sem NMS, pelo que o exportador seleciona automaticamente uma saída e um caminho de quantização diferentes. A segmentação, a pose e o OBB de YOLOv8/YOLO11 compilam os tensores brutos da cabeça, que a Ultralytics descodifica durante a inferência, e a classificação YOLOv8/YOLO11/YOLO26 executa softmax no chip, para que o HEF devolva diretamente as probabilidades das classes. Para a segmentação semântica YOLO26, o exportador segue o acelerador: Hailo-8/8L (DFC v3.x) devolvem logits do classificador para sobreamostragem e redução no anfitrião, enquanto Hailo-10H/15 (DFC v5.x) compilam cabeças ArgMax multiclasse no chip e devolvem um mapa de classes compacto. As cabeças de classe única utilizam o caminho de logits no anfitrião em todos os destinos, porque requerem um limiar em vez de ArgMax. Os modelos de profundidade YOLO26 compilam a convolução de logits densa em a16 e reconstroem o mapa de profundidade métrica no anfitrião (o clamp/exp e a calibração log-afim aprendida que se seguem à cabeça), pelo que o quantizador mantém o seu intervalo mais amplo nos logits brutos. Os utilizadores não precisam de localizar nós finais ONNX, escrever um script de modelo Hailo (.alls) ou criar manualmente um JSON de NMS.

Instalação#

Instala a Ultralytics e descarrega o wheel DFC para o teu hardware de destino a partir da Hailo Developer Zone (é necessário um registo gratuito):

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

Hailo-8 e Hailo-8L utilizam DFC v3.x. Hailo-10H e Hailo-15 utilizam DFC v5.x. Instala a geração do compilador correspondente ao acelerador de destino.

Exportar um modelo HEF Hailo#

Utiliza format="hailo" e seleciona 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 CLI equivalente é:

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

A exportação Hailo é apenas INT8. A Ultralytics descarrega automaticamente um conjunto de dados de calibração específico da tarefa quando data não é fornecido. Para modelos personalizados, utiliza imagens representativas de treino ou validação:

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

A compilação utiliza uma forma de entrada fixa. Define imgsz para a resolução utilizada no dispositivo:

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

Modelos e hardware suportados#

O ecossistema Hailo abrange uma vasta gama de cargas de trabalho de visão computacional, mas o exportador format="hailo" da Ultralytics valida atualmente cabeças YOLO padrão de deteçã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 do hardware é apresentada separadamente abaixo.

Famílias especializadas de deteção, como YOLOv10, YOLO-World, YOLOE e RT-DETR, não são atualmente ❌ suportadas através do caminho format="hailo" da Ultralytics. A Ultralytics rejeita estas tarefas e famílias de modelos antes da compilação, em vez de produzir um HEF não validado.

A pose, o OBB, a classificação, a segmentação semântica YOLO26 e a 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 destinos listados, mas esses novos caminhos de tarefas requerem validação com o compilador e o dispositivo correspondentes antes da utilização em produção.

Seleciona um destes valores name:

Se name for omitido, hailo8l será utilizado como predefinição; define name para o acelerador no qual vais implementar. Instala a geração do DFC correspondente ao destino selecionado.

Hardware Hailo e gerações do SDK#

As famílias de aceleradores Hailo utilizam diferentes gerações de compiladores. O HEF gerado tem de corresponder ao hardware de destino, por isso escolhe name para o dispositivo que executará a inferência, e não para a 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. Esta separação permite compilar numa estação de trabalho ou na Ultralytics Platform e implementar o pequeno artefacto de runtime num host edge ARM ou x86.

Notas de compatibilidade#

A compilação Hailo é específica do hardware e utiliza uma forma de entrada fixa. Tem em conta estas restrições:

• O name selecionado tem de corresponder ao acelerador de implementação.
• As imagens de calibração devem representar a iluminação, os pontos de vista, os objetos e os fundos esperados em produção.
• Cada HEF é compilado para um imgsz fixo. Para disponibilizar várias resoluções, redimensiona os fotogramas no anfitrião para o tamanho compilado ou compila um HEF separado para cada resolução.
• São suportadas contagens de classes personalizadas, porque a Ultralytics gera a configuração de pós-processamento a partir dos metadados do modelo.
• São compatíveis os modelos de deteção com cabeças Ultralytics Detect padrão, os modelos de segmentação, pose e OBB YOLOv8/YOLO11, os modelos de classificação YOLOv8/YOLO11/YOLO26 e os modelos de segmentação semântica e estimativa de profundidade YOLO26; a segmentação de instâncias, pose e caixas delimitadoras orientadas do YOLO26, bem como as exportações YOLO-World, YOLOE, YOLOv10 e RT-DETR, não são atualmente compatíveis.
• Os artefactos 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 Hailo HEF utiliza quantização INT8 para mapear eficientemente a rede YOLO no acelerador. O conjunto de dados de calibração estima os intervalos de ativação; não volta a treinar o modelo nem exige etiquetas durante a compilação.

Quando data é omitido, a Ultralytics utiliza um conjunto de dados de calibração leve e específico da tarefa, como COCO128 para deteçã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 deteção não relacionadas achata o mapa previsto, e conjuntos maiores do mesmo domínio melhoram a fidelidade. Para um modelo personalizado de visão computacional, aponta data para o YAML do conjunto de dados para que o compilador observe imagens representativas do domínio real de implementação:

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

fraction seleciona a proporção ou o número de imagens utilizado na calibração. As listas [train, val, test] definem o limite de cada divisão, as listas com dois itens deixam test completo e 0 ignora o teste. Mais imagens só ajudam quando representam o domínio de implementaçã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 definições do modelo ou do runtime.

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

Medidos num Hailo-8L com calibração do mesmo domínio (COCO128, 128 imagens), os HEF INT8 exportados mantêm a seguinte proporção do mAP50 PyTorch segundo o mesmo protocolo de avaliação:

A retenção compara ambos os modelos com o mesmo limiar de confiança. Os HEF YOLOv8 e YOLO11 incorporam o conf do momento da exportação (predefinido como 0.25) no NMS no chip, pelo que validar em relação a uma referência PyTorch no seu limiar baixo predefinido integra uma parte maior da curva de precisão-recall e sobrestima a diferença de quantização.

Além da deteção, os caminhos de exportação 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 o respetivo checkpoint PyTorch na mesma divisão de validação, utilizando calibração do mesmo domínio:

A segmentação, a pose e o OBB foram calibrados com o conjunto predefinido de cada tarefa no mesmo domínio (COCO128-seg, COCO8-pose, DOTA128); a classificação foi calibrada com ImageNet100. Há duas ressalvas decorrentes dessas predefinições: COCO8-pose tem apenas 8 imagens, por isso considera a pose indicativa e passa um data= maior para produção; além disso, DOTA8 satura o mAP50 perto de 100% para ambos os modelos, razão pela qual o OBB é avaliado em DOTA128. A classificação é também a única tarefa em que o YOLO11 retém mais do que o YOLOv8; nas restantes, a espinha dorsal de atenção do YOLO11 é mais sensível ao INT8.

Das medições no dispositivo resultam três regras práticas:

1. Calibra sempre no mesmo domínio. O ajuste fino com imagens fora do domínio equivale a desativar completamente o ajuste fino: um YOLO26n calibrado com 1 238 imagens fora do domínio retém a mesma precisão (85,7%) que um modelo compilado sem ajuste fino. Um conjunto pequeno do mesmo domínio é melhor do que um conjunto grande fora do domínio.
2. Reduz conf em cerca de 0,05 para implementações YOLO26. A quantização reduz as pontuações do YOLO26 em aproximadamente 0,05, em média, pelo que um limiar ajustado em PyTorch elimina deteções válidas no HEF. Utilizar conf=0.20 no dispositivo corresponde à contagem de deteções do PyTorch em conf=0.25, e reduzir um pouco mais (para cerca de conf=0.15) recupera essencialmente toda a diferença restante de mAP50, ao custo de mais deteções de baixa confiança. A quantização também reordena cerca de 20% das deteções — um efeito permanente na ordenação que nenhum limiar desfaz —, mas essa alteração da ordem não impede a recuperação do mAP50 com o limiar mais baixo.
3. A penalização da atenção é estrutural no Hailo-8/8L (DFC 3.33). Os blocos de atenção são compilados para operações matmul que mantêm entradas de ativação INT8 em todos os modos que o compilador disponibiliza; 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 recalibra as suas entradas para INT8 de qualquer forma (proteger as convoluções depthwise e de saída em 16 bits não alterou o mAP nos nossos testes). Quando a precisão é prioritária e o modelo é intercambiável, o YOLO11 quantiza atualmente melhor do que o YOLO26 neste caso; as gerações Hailo mais recentes (DFC 5.x) disponibilizam mais opções de precisão mista e podem comportar-se de forma diferente.

Artefactos exportados#

A exportação cria um diretório que contém o HEF implementá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 do modelo, a tarefa, o tamanho de entrada, o stride e as informações sobre o destino Hailo.
• nms_config.json regista a configuração NMS HailoRT gerada para os modelos de deteção YOLOv8 e YOLO11. A deteção YOLO26 e todas as tarefas que não são de deteção (segmentação, semântica, profundidade, classificação, pose, OBB) não utilizam este ficheiro.

O grafo ONNX intermédio é removido após a compilação.

Executar inferência no hardware Hailo#

Instala o HailoRT no dispositivo de destino. Os utilizadores do Raspberry Pi AI HAT+ e AI HAT+ 2 podem seguir o guia de software Raspberry Pi AI. No Raspberry Pi OS, os dois conjuntos de pacotes não podem ser instalados em conjunto; executa apenas o bloco correspondente ao teu hardware e reinicia depois.

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 posterior):

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

Depois de reiniciar, confirma que o acelerador foi detetado:

hailortcli fw-control identify

Copia o diretório completo da exportação para o dispositivo para que metadata.yaml permaneça junto ao HEF. A Ultralytics utiliza 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 deteção, o backend converte automaticamente a saída NMS HailoRT do YOLOv8 e YOLO11 e descodifica as saídas one-to-one do YOLO26. Descodifica tensores brutos de segmentação, pose e OBB, devolve probabilidades de classificação no chip e produz mapas de classes semânticas através de redução no anfitrião no Hailo-8/8L e em todas as cabeças de classe única, ou através de um ArgMax no chip para cabeças Hailo-10H/15 multiclasses. TAPPAS, GStreamer e o auxiliar picamera2.devices.Hailo do Raspberry Pi continuam disponíveis para pipelines específicos de aplicações.

Para uma implementação 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 implementação Hailo#

O HEF é o mesmo artefacto de modelo implementável em várias interfaces de runtime Hailo. Escolhe a interface adequada à aplicação:

Mantém metadata.yaml junto ao HEF quando a aplicação necessita dos nomes de classes da Ultralytics, do tamanho de entrada, do stride ou de outras informações do modelo. O próprio HEF não substitui a lógica ao nível da aplicação para captura da câmara, visualização, tracking, alertas ou armazenamento.

Verificar o dispositivo Hailo e o HEF#

Antes de integrares uma pipeline de câmara ou vídeo, verifica o runtime e o acelerador de forma independente:

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

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

Hailo comparado com outros formatos de exportação YOLO#

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

Não assumas que o Hailo é mais rápido ou mais eficiente energeticamente apenas por ser um NPU. Para novas implementações M.2, o DeepX é o candidato mais forte para maior desempenho YOLO e melhor desempenho por watt, enquanto o Axelera visa um débito substancialmente maior em múltiplos streams. O Rockchip é uma opção popular e económica para SBCs e sistemas incorporados. Os valores de TOPS e de potência dos fornecedores não são benchmarks de aplicações diretamente comparáveis; por isso, valida o mesmo checkpoint YOLO, tamanho de entrada, precisão, anfitrião e pipeline de vídeo completo nos dispositivos candidatos antes de comprar hardware.

Otimizar o desempenho de visão computacional Hailo#

As escolhas do modelo e da pipeline são frequentemente mais importantes do que as flags do compilador:

• Começa com um modelo YOLO pequeno e aumenta o tamanho do modelo apenas quando a precisão o exigir.
• Escolhe o imgsz fixo mais baixo que ainda preserve os objetos importantes para a aplicação.
• Utiliza, sempre que possível, imagens de calibração da câmara e do ambiente reais.
• Mantém a rede Hailo ativa entre frames, em vez de reabrir o HEF para cada inferência.
• Separa o tempo de inferência no dispositivo do pré-processamento, descodificação de vídeo, pós-processamento, visualização e E/S de rede.
• Utiliza uma pipeline de streaming, como GStreamer, para cargas de trabalho de vídeo contínuas.
• Valida o HEF exportado no acelerador exato e na versão HailoRT utilizada em produção.

Argumentos de Exportação#

Na exportação de detecção, YOLOv8 e YOLO11 recebem NMS do HailoRT, enquanto YOLO26 mantém as suas saídas um-para-um sem NMS. Segmentação, pose e OBB utilizam tensores brutos da cabeça, a classificação devolve probabilidades no chip, e a segmentação semântica devolve logits brutos no Hailo-8/8L e em todas as cabeças de classe única, ou mapas de classes incorporados para cabeças Hailo-10H/15 de várias classes. A estimativa de profundidade devolve o logit bruto de profundidade, que a Ultralytics descodifica num mapa de profundidade métrica durante a inferência. Não passes end2end; as substituições explícitas são rejeitadas. Formas dinâmicas, NMS incorporado da Ultralytics, FP16 e FP32 não são suportados.

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

Erro de importação do Hailo Dataflow Compiler#

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

Sistema operativo ou arquitetura não suportados#

A compilação de HEF é suportada em Linux x86_64. Exporta através da Ultralytics Platform ou utiliza 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 tempo#

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

A precisão do modelo quantizado diminui#

Utiliza imagens de calibração semelhantes às entradas de produção e que incluam os objetos importantes, as escalas, as condições de iluminação e os fundos. Compara o modelo PyTorch original e o HEF exportado no mesmo conjunto de validação antes da implementação. Mesmo com uma boa calibração, mantém-se uma diferença moderada dependente da família; consulta Expectativas de precisão por família de modelos para conhecer as linhas de base medidas.

O HEF não carrega no dispositivo#

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

A análise das saídas parece incorreta#

Mantém metadata.yaml junto do HEF para que a Ultralytics possa selecionar o caminho de pós-processamento correspondente de YOLOv8, YOLO11 ou YOLO26. As aplicações HailoRT personalizadas também devem associar 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 pronto para implementaçã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. Calibra e compila localmente com o DFC correspondente ou utiliza a exportação gerida na Ultralytics Platform.
4. Copia o HEF e metadata.yaml para o dispositivo de edge com Hailo.
5. Executa a inferência com HailoRT, Raspberry Pi Picamera2 ou um pipeline de vídeo GStreamer.

Para outros destinos de implementação de visão computacional, consulta Modo de exportação, Modo de benchmark e o guia de integrações. Os guias de hardware relacionados incluem DeepX, Axelera, ONNX, OpenVINO, TensorRT, NCNN, RKNN, Sony IMX500 e Qualcomm QNN.

Perguntas frequentes#