Exportação AMD Xilinx para Ultralytics YOLO com Vitis AI#

A exportação de modelos Ultralytics YOLO26 com format="xilinx" os quantiza com AMD Quark para a NPU dos SoCs adaptativos AMD Versal AI Edge Series Gen 2, deixando-os prontos para que o compilador Vitis AI da AMD gere um modelo .rai. A mesma exportação valida a precisão INT8 em qualquer host antes da implantação.

Os dispositivos AMD Xilinx estão presentes em muitas câmaras industriais, sistemas de visão automóvel, robôs, drones e produtos de imagiologia médica em todo o mundo. Combinam processadores Arm com lógica programável e, nos dispositivos mais recentes, AI Engines dedicados, para que um único chip possa capturar vídeo, pré-processá-lo, executar deteção de objetos e agir com base no resultado com latência de inferência baixa e previsível.

Este guia aborda a exportação AMD Xilinx, como compilar e executar em uma placa Versal, as famílias de dispositivos AMD Xilinx, como a IA é executada neles e quais operadores Ultralytics YOLO cada acelerador suporta.

O que é AMD Xilinx?#

A Xilinx inventou a matriz de portas programável em campo (FPGA) na década de 1980 e tornou-se um fornecedor líder de SoCs adaptativos e FPGAs. A AMD concluiu a aquisição da Xilinx em fevereiro de 2022, e as linhas de produtos são agora comercializadas sob a marca AMD como AMD Zynq, AMD Kria, AMD Versal e AMD Vitis.

Termos e conceitos principais#

A implementação AMD Xilinx utiliza vocabulário próprio. A tabela abaixo explica todos os termos usados neste guia.

Famílias de dispositivos AMD Xilinx para IA de periferia#

Os dispositivos AMD Xilinx para IA de periferia dividem-se em três famílias. Zynq e Kria usam a DPU na lógica programável, enquanto os dispositivos Versal AI Edge aqui abordados usam a NPU nos seus AI Engines.

Zynq UltraScale+ MPSoC#

Cada chip Zynq UltraScale+ combina um sistema de processamento Arm, com núcleos Cortex-A53 de núcleo duplo (CG) ou quádruplo (EG e EV) e núcleos Cortex-R5F em tempo real, com lógica FPGA. Os dispositivos EV acrescentam um codec de vídeo H.264/H.265 dedicado. Para executar redes neuronais, os designers integram uma DPU na lógica, junto dos pipelines de câmara e vídeo. Em dispositivos pequenos, a DPU compete por espaço com o resto do design.

Módulos de sistema Kria#

O módulo Kria K26 integra um Zynq UltraScale+ MPSoC, memória e alimentação num módulo pronto para produção, para não precisares de conceber por conta própria o processador, a memória e o subsistema de alimentação. O módulo liga-se a uma placa transportadora, seja a placa de um kit inicial ou um design teu. Alimenta o KV260 Vision AI Starter Kit para câmaras inteligentes e o KR260 Robotics Starter Kit para robótica. Como o K26 é baseado em Zynq UltraScale+, usa o mesmo fluxo DPU. O portefólio Kria também inclui outros módulos, por isso verifica que processador o teu módulo utiliza antes de escolheres um fluxo.

SoCs adaptativos Versal#

Versal é a família de SoCs adaptativos da AMD. As séries AI Edge e AI Core incluem AI Engines dedicados junto dos núcleos Arm e da lógica programável, enquanto algumas outras séries Versal não têm AI Engines. O IP de NPU da AMD é executado em conjunto nos AI Engines e na lógica programável, e o Vitis AI destina-se aos componentes AIE-ML da série AI Edge, como o VE2302 e o VE2802. A Série Versal AI Edge (kit de avaliação VEK280) e a Série Versal AI Edge Gen 2 (kit de avaliação VEK385) são os destinos atuais da AMD para IA de periferia e o foco das versões atuais do Vitis AI.

Como a IA é executada em dispositivos AMD Xilinx: DPU vs NPU#

A maioria das implementações de IA AMD Xilinx segue o mesmo padrão. O acelerador executa as camadas que suporta, a CPU Arm executa o pré-processamento, o pós-processamento e quaisquer camadas que o acelerador não consiga executar, e um runtime na placa coordena ambos.

A AMD lançou duas gerações de aceleradores, cada uma com a sua própria cadeia de ferramentas e ficheiro de modelo compilado. Este guia aborda o Vitis AI 3.5 para a DPU e o Vitis AI 6.3 para a NPU; consulta a documentação atual da AMD para versões posteriores.

De qual fluxo do Vitis AI preciso?#

Escolhe o fluxo de acordo com o dispositivo da tua placa:

Exportação para AMD Xilinx: convertendo seu modelo YOLO#

Tarefas suportadas#

A exportação AMD Xilinx é compatível com todas as sete tarefas Ultralytics. A segmentação semântica e a estimativa de profundidade estão disponíveis apenas com YOLO26, a única família que inclui essas cabeças.

Instalação#

A exportação AMD Xilinx é executada em Linux (x86-64 ou ARM64) com Python 3.11 a 3.13, as versões compatíveis com AMD Quark. A primeira exportação também compila os operadores personalizados do Quark, o que requer um compilador C++, como g++.

# Install the required package for YOLO
pip install ultralytics

O AMD Quark é instalado automaticamente do PyPI na primeira exportação. Para pré-instalar as dependências de exportação:

pip install "ultralytics[export-xilinx]"

Para instalar o repositório em modo editável, substitua "ultralytics[export-xilinx]" por -e ".[export-base,export-xilinx]". Para reproduzir o ambiente Python 3.12 e o teste rápido de exportação usados pela CI, execute o construtor de ambiente existente a partir da raiz do repositório:

ULTRALYTICS_ISOLATED_VENVS="$PWD/.venvs" python .github/scripts/create-export-env.py --env isolated-xilinx

Uso#

O formato AMD Xilinx é compatível com os modos Export, Predict e Validate. Sem o Vitis AI Execution Provider da AMD, predict e validate executam o modelo quantizado com ONNX Runtime na CPU, medindo sua precisão INT8 em qualquer host. Quando o ONNX Runtime disponibiliza o VitisAIExecutionProvider, como em uma placa Versal AI Edge Series Gen 2, o Ultralytics o seleciona automaticamente.

from ultralytics import YOLO

# Carrega um modelo YOLO26
model = YOLO("yolo26n.pt")

# Exportar para o formato AMD Xilinx para VEK385 (quantize=8 é aplicado automaticamente)
model.export(format="xilinx")  # creates 'yolo26n_xilinx_model/'

from ultralytics import YOLO

# Carregar o modelo AMD Xilinx exportado
model = YOLO("yolo26n_xilinx_model")

# Executar inferência
results = model("https://ultralytics.com/images/bus.jpg")

from ultralytics import YOLO

# Carregar o modelo AMD Xilinx exportado
model = YOLO("yolo26n_xilinx_model")

# Validar a precisão INT8 no conjunto de dados COCO8
metrics = model.val(data="coco8.yaml")

Os nomes de formato vitis, vitisai e versal são aliases de xilinx.

Argumentos de exportação#

Defina nms=False para exportar a cabeça YOLO26 sem NMS YOLO26. A NMS integrada (nms=True) não é compatível, pois a AMD lista NonMaxSuppression entre os operadores que podem forçar a execução do modelo inteiro na CPU.

Para mais detalhes sobre o processo de exportação, visita a página da documentação da Ultralytics sobre exportação.

Estrutura de saída#

Após uma exportação bem-sucedida, é criado um diretório do modelo com a seguinte estrutura:

yolo26n_xilinx_model/
├── yolo26n.onnx          # AMD Quark VINT8 model with the Ultralytics metadata
└── vitisai_config.json   # Vitis AI compiler configuration for the target device

A compilação do modelo, descrita abaixo, adiciona um cache do compilador yolo26n/ ao mesmo diretório, contendo o modelo NPU yolo26n.rai e relatórios de compilação da AMD, como final-vaiml-pass-summary.txt.

Como funciona a exportação#

A exportação segue o fluxo Vitis AI documentado pela AMD para Versal AI Edge Series Gen 2:

1. Exportação ONNX com opset 17 e tamanho de lote estático igual a 1.
2. Quantização AMD Quark com a configuração VINT8 (INT8 simétrico com escalas de potência de dois) e as opções exigidas pela AMD para compilação em NPU: Int32Bias=False, enable_npu_cnn=True, DedicatedQDQPair=True e QuantizeAllOpTypes=True. A calibração usa o carregador padrão de calibração INT8 do Ultralytics, com o mesmo pré-processamento letterbox, RGB e 0–1 da inferência.
3. Precisão mista: a cabeça do modelo permanece em ponto flutuante, e o compilador Vitis AI a executa em BF16 na NPU. Quantizar a cabeça para INT8 causa a maior parte da perda de precisão, e o tutorial YOLOv8m da AMD mantém sua etapa de pós-processamento fora do INT8 pelo mesmo motivo.
4. Configuração do compilador: vitisai_config.json seleciona o destino VAIML e o dispositivo de name.

Precisão#

A tabela compara o modelo INT8 exportado com o modelo ONNX FP32 no val2017 do COCO (5.000 imagens) em 640, ambos executados com ONNX Runtime na CPU do host. Os modelos INT8 foram calibrados no conjunto de dados padrão coco128.yaml; calibrar com suas próprias imagens de implantação geralmente reduz a diferença.

Estes resultados no host executam o modelo quantizado com ONNX Runtime na CPU, a referência com a qual a metodologia de precisão da AMD compara os resultados da NPU. Os resultados publicados pela AMD para YOLOv8m no VEK385 mostram a mesma abordagem de precisão mista na NPU:

Fonte: tutorial de YOLOv8m para Versal AI Edge Gen 2 da AMD, que também indica um tempo médio de inferência de 10,69 ms em 100 execuções VART com dp_size=1.

Compilar e executar no Versal AI Edge Gen 2#

O diretório exportado está pronto para o compilador Vitis AI da AMD, que gera o modelo .rai executado na NPU.

1. Prepare o host e a placa. Faça a compilação em um host Linux x86-64 com a imagem Docker Vitis AI 6.3 da AMD para Versal AI Edge Gen 2 e uma licença do compilador AMD AI Engine (consulte a página de licenciamento da AMD). Configure o VEK385 usando o guia de configuração da placa da AMD.

2. Compile. Dentro do contêiner, crie uma sessão do ONNX Runtime com o Vitis AI Execution Provider, usando a mesma chamada do guia de compilação da AMD. Isso grava o cache yolo26n/ com yolo26n.rai no diretório de exportação:

   import onnxruntime as ort
   
   d = "yolo26n_xilinx_model"
   options = {"config_file": f"{d}/vitisai_config.json", "cache_dir": d, "cache_key": "yolo26n", "target": "VAIML"}
   ort.InferenceSession(f"{d}/yolo26n.onnx", providers=["VitisAIExecutionProvider"], provider_options=[options])

   Confira yolo26n_xilinx_model/yolo26n/final-vaiml-pass-summary.txt para saber quanto do modelo é executado na NPU. Para YOLO26n em 640, o compilador AMD Vitis AI 6.3 coloca 99,9% dos operadores e do cálculo na NPU VEK385 em uma única partição.

3. Execute na placa. Copie o diretório de exportação para o VEK385. O ONNX Runtime com o Vitis AI Execution Provider carrega o yolo26n.rai compilado e o executa na NPU; YOLO("yolo26n_xilinx_model") seleciona automaticamente esse provedor quando ele está disponível.

A compilação requer apenas o ONNX Runtime da AMD. Portanto, exporte em qualquer máquina Linux e copie o diretório para o contêiner, em vez de instalar o Ultralytics nele, o que pode alterar os pacotes fixados do contêiner. Quando o Ultralytics está instalado junto com a compilação AMD onnxruntime-vitisai, como na placa, ele mantém essa compilação em vez de substituí-la pelo onnxruntime padrão.

Compatibilidade de modelos YOLO e operadores compatíveis#

Um acelerador só acelera os operadores que implementa em hardware. Quando um modelo contém um operador sem suporte, o compilador geralmente envia essa parte da rede para a CPU Arm, e cada ida e volta entre o acelerador e a CPU acrescenta latência. Alguns operadores não podem ser particionados: na NPU Versal AI Edge Gen 2, a AMD lista operadores como NonZero e NonMaxSuppression, que podem forçar a execução do modelo inteiro na CPU. O suporte a operadores é o fator mais importante para o desempenho de um modelo YOLO no hardware AMD Xilinx.

A tabela mostra onde cada operador de um modelo YOLO26 é executado. Uma exportação ONNX padrão de YOLO26n contém 87 ativações SiLU, cada uma exportada como Sigmoid e Mul, além de 4 operadores MatMul e 2 Softmax provenientes dos dois blocos de atenção: o bloco C2PSA no fim do backbone (camada 10) e o bloco C3k2 com atenção ativada, que produz a saída P5 (camada 22).

Fontes: operadores compatíveis UG1414 da AMD, suporte a operadores do PyTorch e listas de operadores compatíveis, de partição na CPU e não compatíveis da Versal AI Edge Gen 2. O suporte também depende da configuração da DPU e dos padrões do grafo, então verifica sempre o relatório de particionamento do compilador.

Prepara o YOLO26 para DPU com Hard-Swish#

A DPU funde nas convoluções apenas ReLU, ReLU6, LeakyReLU, Hard-Swish e Hard-Sigmoid. Hard-Swish é uma aproximação de SiLU compatível com hardware, o que a torna a substituição natural. Os ficheiros YAML dos modelos Ultralytics aceitam uma chave activation que altera a ativação padrão dos blocos Conv (Guia de configuração YAML do modelo).

Copia yolo26.yaml para yolo26-hswish.yaml e adiciona uma linha sob os parâmetros:

# Parameters
nc: 80 # number of classes
activation: nn.Hardswish() # default Conv activation, DPU-native
end2end: True # whether to use end-to-end mode

Em seguida, cria o modelo, transfere os pesos YOLO26 pré-treinados e faz ajuste fino com o teu conjunto de dados:

from ultralytics import YOLO

# # Cria YOLO26n com ativações Hard-Swish; o 'n' no nome seleciona a escala nano
model = YOLO("yolo26n-hswish.yaml").load("yolo26n.pt")  # # transfere os pesos pré-treinados

# # Faz ajuste fino para adaptar a rede a Hard-Swish
model.train(data="coco8.yaml", epochs=100, imgsz=640)

As ativações não têm pesos, então todos os pesos pré-treinados são transferidos. O grafo ONNX exportado contém então 87 operadores HardSwish e nenhum SiLU. Substitui coco8.yaml pelo teu próprio conjunto de dados e compara a precisão com o modelo SiLU usando o modo Val antes da implementação.

Como lidar com blocos de atenção na DPU#

O YOLO26 aplica atenção na resolução mais baixa (uma grelha de 20×20 com entrada 640) em dois pontos: no bloco C2PSA da camada 10 e no bloco C3k2 com atenção ativada da camada 22. O YOLO11 tem um bloco C2PSA. Numa DPU, os operadores MatMul e Softmax são executados na CPU, dividindo o modelo em subgrafos alternados de DPU e CPU. Tens três opções:

1. Aceitar os blocos de CPU. O .xmodel compilado contém então subgrafos de CPU, por isso executa-o com o Graph Runner da AMD, que executa em conjunto os subgrafos de DPU e CPU quando existe uma implementação de CPU para cada operador; caso contrário, tens de implementar e registrar os operadores em falta. Com 20×20, o cálculo da atenção é pequeno, mas cada transferência adicional entre a DPU e a CPU acrescenta latência, então mede o desempenho na tua placa.

2. Usar um YAML sem atenção. No teu YAML de Hard-Swish, substitui a camada C2PSA por nn.Identity para manter válidos os índices de camada usados por Concat e Detect, e desativa a atenção na camada 22:

   backbone:
       # ... layers 0-9 unchanged
       - [-1, 1, nn.Identity, []] # 10 C2PSA removed; keeps later layer indices valid
   
   head:
       # ... layers 11-21 unchanged
       - [-1, 1, C3k2, [1024, True, 0.5, False]] # 22 (P5/32-large), attention disabled
       - [[16, 19, 22], 1, Detect, [nc]] # Detect(P3, P4, P5)

   O grafo ONNX exportado não contém então operadores MatMul nem Softmax. Os pesos de atenção deixam de ser aplicáveis (624 dos 666 pesos do YOLO26n são transferidos), então faz um ajuste fino mais longo e compara a precisão com o modo Val.

3. Usar um modelo sem atenção, como o YOLOv8, que a AMD já usou nos próprios exemplos de DPU.

Na Versal AI Edge Gen 2, os operadores de atenção aparecem como compatíveis com a NPU, então essas alterações geralmente são desnecessárias. Confirma a atribuição no relatório do compilador, pois a AMD observa que operadores compatíveis ainda podem ser executados na CPU devido a restrições de configuração ou memória.

Compatibilidade de modelos em resumo#

Implantação em outros destinos AMD Xilinx#

As DPUs Zynq UltraScale+ e Kria e a NPU Versal AI Edge de primeira geração usam fluxos Vitis AI que format="xilinx" não gera. Treine com o Ultralytics e, em seguida, gere o artefato do destino com as ferramentas da AMD em suas imagens Docker Linux x86-64. Selecione a aba correspondente ao seu dispositivo:

Prepare a placa com um projeto de hardware e uma imagem Linux que contenham a configuração do acelerador para a qual você compilou, além do ambiente de execução Vitis AI correspondente. Consulte os guias de configuração da AMD para os destinos DPU Zynq UltraScale+ e Kria e Versal AI Edge (VEK280) e, em seguida, copie os artefatos necessários para o ambiente de execução:

Na DPU, os buffers VART armazenam valores INT8 de ponto fixo: consulte o formato de cada tensor e a escala fix_point, quantize as entradas e desquantize as saídas antes do pós-processamento. O Graph Runner retorna as saídas do grafo completo, enquanto um executor somente para DPU retorna as saídas intermediárias do subgrafo DPU, cujo cálculo restante deve ser concluído pelo seu código. O VART-ML no VEK280 usa por padrão visualizações de tensor de hardware, cujo formato, tipo de dados e disposição de memória podem diferir dos formatos ONNX. Portanto, configure os tipos de tensor de entrada e saída do executor como visualizações de CPU ou converta o formato de hardware por conta própria (consulte a visão geral da arquitetura VART-ML da AMD).

Aplicações no mundo real#

Os dispositivos AMD Xilinx são comuns sempre que a IA de visão tem de funcionar em tempo real, com baixo consumo de energia e perto do sensor:

• Segurança industrial e na construção: deteta pessoas e máquinas junto a equipamento pesado e monitoriza zonas de trabalho com deteção de objetos e contagem de objetos.
• Visão automóvel e fora de estrada: executa perceção baseada em câmaras em componentes certificados para o setor automóvel, dando suporte a veículos autónomos e à assistência ao condutor.
• Câmaras inteligentes e análise de vídeo: combina captura de vídeo, codificação e inferência YOLO num único chip para sistemas de segurança e análise de vídeo.
• Visão artificial e inspeção de qualidade: combina captura de imagens de alta velocidade baseada em FPGA com segmentação de instâncias ou classificação YOLO para detetar defeitos na linha de produção.
• Robótica e drones: usa módulos Kria KR260 ou Versal para estimativa de pose, deteção de objetos orientados e navegação com latência determinística.

Resumo#

A exportação com format="xilinx" quantiza modelos Ultralytics YOLO com AMD Quark para NPUs Versal AI Edge Series Gen 2, mantém a cabeça em BF16 e grava a configuração do compilador Vitis AI junto ao modelo. Valide a precisão INT8 em qualquer host, compile o modelo .rai na imagem Docker Vitis AI da AMD e execute-o na placa com ONNX Runtime e Vitis AI Execution Provider.

Dispositivos AMD Xilinx mais antigos usam outros fluxos. A DPU do Zynq UltraScale+ e do Kria usa a toolchain Vitis AI 3.5 congelada e arquivos .xmodel, requer ativações nativas da DPU, como Hard-Swish, e executa a atenção na CPU. A NPU Versal AI Edge de primeira geração usa o fluxo snapshot, com cobertura de operadores que depende da versão e da precisão do Vitis AI.

Para outros destinos de implantação, consulte o guia de opções de implantação de modelos, as práticas recomendadas de implantação e integrações com aceleradores, como Hailo, Rockchip RKNN e Axelera.

Perguntas frequentes#