使用 Vitis AI 为 Ultralytics YOLO 导出 AMD Xilinx 格式#

使用 format="xilinx" 导出Ultralytics YOLO26模型时，会使用 AMD Quark 对模型进行量化，以用于 AMD Versal AI Edge Series Gen 2 自适应 SoC 中的 NPU，随后可由 AMD 的 Vitis AI 编译器构建 .rai 模型。部署前，同一导出流程还会在任意主机上验证 INT8 精度。

AMD Xilinx 设备广泛应用于全球各地的工业相机、汽车视觉系统、机器人、无人机和医学影像产品。这些设备将 Arm 处理器与可编程逻辑相结合，新款设备还配备专用 AI Engines，因此单个芯片便能采集视频、进行预处理、执行目标检测，并以低且可预测的推理延迟对结果作出响应。

本指南介绍 AMD Xilinx 导出、如何在 Versal 板上编译和运行、各 AMD Xilinx 设备系列的类型、AI 在这些设备上的运行方式，以及各加速器支持哪些 Ultralytics YOLO 算子。

什么是 AMD Xilinx？#

Xilinx 于 20 世纪 80 年代发明了现场可编程门阵列（FPGA），并成为自适应 SoC 和 FPGA领域的领先供应商。AMD 于 2022 年 2 月完成对 Xilinx 的收购，如今这些产品线以 AMD 品牌销售，名称分别为 AMD Zynq、AMD Kria、AMD Versal 和 AMD Vitis。

关键术语和概念#

AMD Xilinx 部署有一套专用术语。下表解释了本指南中使用的所有术语。

适用于边缘 AI 的 AMD Xilinx 设备系列#

适用于边缘 AI 的 AMD Xilinx 设备分为三个系列。Zynq 和 Kria 在可编程逻辑中使用 DPU，而本指南介绍的 Versal AI Edge 设备则在其 AI Engines 上使用 NPU。

Zynq UltraScale+ MPSoC#

每款 Zynq UltraScale+ 芯片都将 Arm 处理系统与 FPGA 逻辑相结合。处理系统配有双核（CG）或四核（EG 和 EV）Cortex-A53 核心以及实时 Cortex-R5F 核心。EV 设备还增加了硬化 H.264/H.265 视频编解码器。要运行神经网络，设计人员会在摄像头和视频管线旁的逻辑中构建 DPU。在小型设备上，DPU 会与设计的其他部分争夺空间。

Kria 系统级模块#

Kria K26 模块将 Zynq UltraScale+ MPSoC、内存和电源集成在量产级模块中，因此你无需自行设计处理器、内存和电源子系统。该模块可插入载板，可以是入门套件开发板，也可以是你自己的设计。它为智能摄像头提供 KV260 Vision AI 入门套件，为机器人提供 KR260 Robotics 入门套件。由于 K26 基于 Zynq UltraScale+ 构建，因此使用相同的 DPU 工作流。Kria 产品组合还包括其他模块，因此选择工作流前，请确认你的模块使用哪种处理器。

Versal 自适应 SoC#

Versal 是 AMD 的自适应 SoC 系列。其 AI Edge 和 AI Core 系列在 Arm 核心与可编程逻辑旁增加了硬化 AI Engines，而其他一些 Versal 系列则没有 AI Engines。AMD 的 NPU IP 会同时运行于 AI Engines 和可编程逻辑之上；Vitis AI 面向 AI Edge 系列中的 AIE-ML 芯片，例如 VE2302 和 VE2802。Versal AI Edge 系列（VEK280 评估套件）和 Versal AI Edge 系列 Gen 2（VEK385 评估套件）是 AMD 当前面向边缘 AI 的目标平台，也是当前 Vitis AI 版本的重点。

AMD Xilinx 设备上的 AI 运行方式：DPU 与 NPU#

大多数 AMD Xilinx AI 部署都遵循相同的模式。加速器运行其支持的层；Arm CPU 负责预处理、后处理，以及加速器无法执行的层；开发板上的运行时负责协调二者。

AMD 已推出两代加速器，每一代都有各自的工具链和编译模型文件。本指南使用 Vitis AI 3.5 介绍 DPU，使用 Vitis AI 6.3 介绍 NPU；如需了解后续版本，请查阅 AMD 的最新文档。

我需要哪种 Vitis AI 流程？#

根据开发板上的器件选择流程：

导出到 AMD Xilinx：转换 YOLO 模型#

支持的任务#

AMD Xilinx 导出支持全部七种 Ultralytics 任务。语义分割和深度估计仅适用于 YOLO26，因为只有 YOLO26 系列包含这些检测头。

安装#

AMD Xilinx 导出可在 Linux（x86-64 或 ARM64）上运行，需使用 Python 3.11 至 3.13，这是 AMD Quark 支持的版本。首次导出还会编译 Quark 的自定义算子，这需要 C++ 编译器，例如 g++。

# Install the required package for YOLO
pip install ultralytics

首次导出时会自动从 PyPI 安装 AMD Quark。若要预先安装导出依赖项：

pip install "ultralytics[export-xilinx]"

如需以可编辑模式安装仓库，请将 "ultralytics[export-xilinx]" 替换为 -e ".[export-base,export-xilinx]"。如需复现 CI 使用的 Python 3.12 环境和导出冒烟测试，请从仓库根目录运行现有的环境构建器：

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

用法#

AMD Xilinx 格式支持 Export、Predict 和 Validate 模式。如果没有 AMD 的 Vitis AI Execution Provider，predict 和 validate 会使用 ONNX Runtime 在 CPU 上运行量化模型，以便在任意主机上测量其 INT8 精度。如果 ONNX Runtime 提供了 VitisAIExecutionProvider，例如在 Versal AI Edge Series Gen 2 板上，Ultralytics 会自动选择它。

from ultralytics import YOLO

# 加载 YOLO26 模型
model = YOLO("yolo26n.pt")

# 导出为 VEK385 使用的 AMD Xilinx 格式（会自动强制设置 quantize=8）
model.export(format="xilinx")  # creates 'yolo26n_xilinx_model/'

from ultralytics import YOLO

# 加载导出的 AMD Xilinx 模型
model = YOLO("yolo26n_xilinx_model")

# 运行推理
results = model("https://ultralytics.com/images/bus.jpg")

from ultralytics import YOLO

# 加载导出的 AMD Xilinx 模型
model = YOLO("yolo26n_xilinx_model")

# 在 COCO8 数据集上验证 INT8 精度
metrics = model.val(data="coco8.yaml")

vitis、vitisai 和 versal 格式名称都是 xilinx 的别名。

导出参数#

将 nms=False 设为导出无需 NMS 的 YOLO26 检测头。不支持嵌入式 NMS（nms=True），因为 AMD 将 NonMaxSuppression 列为可能导致整个模型转由 CPU 执行的算子之一。

有关导出流程的更多详情，请访问 Ultralytics 导出文档页面。

输出结构#

成功导出后，会创建一个模型目录，其结构如下：

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

如下所述，编译模型会在同一目录中生成 yolo26n/ 编译器缓存，其中包含 yolo26n.rai NPU 模型，以及 final-vaiml-pass-summary.txt 等 AMD 编译报告。

导出工作原理#

该导出流程遵循 AMD 为 Versal AI Edge Series Gen 2 编写的 Vitis AI 文档工作流：

1. ONNX 导出：使用 opset 17，批量大小固定为 1。
2. AMD Quark 量化：使用 VINT8 配置（对称 INT8，采用 2 的幂次缩放系数），以及 AMD 要求用于 NPU 编译的选项：Int32Bias=False、enable_npu_cnn=True、DedicatedQDQPair=True 和 QuantizeAllOpTypes=True。校准使用标准 Ultralytics INT8 校准加载器，其 letterbox、RGB 和 0–1 预处理方式与推理相同。
3. 混合精度：模型检测头保留浮点格式，Vitis AI 编译器则在 NPU 上以 BF16 运行该检测头。将检测头量化为 INT8 会导致大部分精度损失；AMD 的 YOLOv8m 教程也出于同样原因，将后处理部分排除在 INT8 量化范围之外。
4. 编译器配置：vitisai_config.json 选择 VAIML 目标和 name 中的设备。

准确率#

此表在 COCO val2017（5,000 张图像，图像尺寸为 640）上，将导出的 INT8 模型与 FP32 ONNX 模型进行比较；两者均使用 ONNX Runtime 在主机 CPU 上运行。INT8 模型使用默认的 coco128.yaml 数据集进行校准；使用你自己的部署图像进行校准通常能缩小差距。

这些主机端结果使用 ONNX Runtime 在 CPU 上运行量化模型，是 AMD 精度评估方法用于对比 NPU 结果的基准。AMD 发布的 VEK385 上 YOLOv8m 结果也展示了在 NPU 上采用相同的混合精度方案：

来源：AMD 的 Versal AI Edge Gen 2 YOLOv8m 教程；该教程还报告了 dp_size=1 下 VART 运行 100 次的平均推理时间为 10.69 ms。

在 Versal AI Edge Gen 2 上编译并运行#

导出的目录已可交由 AMD Vitis AI 编译器处理，以构建可在 NPU 上运行的 .rai 模型。

1. 准备主机和开发板。在 x86-64 Linux 主机上，使用 AMD 的 Versal AI Edge Gen 2 Vitis AI 6.3 Docker 镜像进行编译，并准备 AMD AI Engine 编译器许可证（参阅 AMD 许可页面）。按照 AMD 的开发板设置指南配置 VEK385。

2. 编译。在容器内，使用 Vitis AI Execution Provider 创建 ONNX Runtime 会话，调用方式与 AMD 的编译指南相同。此操作会在导出目录中生成包含 yolo26n.rai 的 yolo26n/ 缓存：

   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])

   查看 yolo26n_xilinx_model/yolo26n/final-vaiml-pass-summary.txt，了解模型有多少部分在 NPU 上运行。对于输入尺寸为 640 的 YOLO26n，AMD Vitis AI 6.3 编译器会将 99.9% 的算子和计算量放在 VEK385 NPU 上的单个分区中。

3. 在开发板上运行。将导出目录复制到 VEK385。使用 Vitis AI Execution Provider 的 ONNX Runtime 会加载已编译的 yolo26n.rai 并在 NPU 上运行；如果 YOLO("yolo26n_xilinx_model") 可用，Ultralytics 会自动选择该 Provider。

编译只需要 AMD 的 ONNX Runtime，因此你可以在任意 Linux 机器上导出，再将目录复制到容器中，而不必在那里安装 Ultralytics，以免更改容器中锁定的依赖包。如果在 AMD 的 onnxruntime-vitisai 构建版本旁安装了 Ultralytics（例如在开发板上），Ultralytics 会保留该构建版本，而不会将其替换为标准的 onnxruntime。

YOLO 模型兼容性与支持的算子#

加速器只能加速由硬件实现的算子。如果模型包含不受支持的算子，编译器通常会将网络的这部分交给 Arm CPU 运行，而加速器与 CPU 之间的每次往返都会增加延迟。有些算子无法进行分区：在 Versal AI Edge Gen 2 NPU 上，AMD 列出的 NonZero 和 NonMaxSuppression 等算子可能会导致整个模型都在 CPU 上运行。算子支持是影响 YOLO 模型在 AMD Xilinx 硬件上运行效果的最重要因素。

此表展示了 YOLO26 模型中的各个算子在哪里运行。未经修改的 YOLO26n ONNX 导出模型包含 87 个 SiLU 激活，每个都导出为一个 Sigmoid 和一个 Mul；此外还有 4 个 MatMul 算子和 2 个 Softmax 算子，它们来自两个注意力模块：C2PSA 模块位于主干网络末端（第 10 层），启用注意力的 C3k2 模块则负责生成 P5 输出（第 22 层）。

来源：AMD 的 UG1414 支持的算子、PyTorch 算子支持，以及 Versal AI Edge Gen 2 的支持、CPU 分区和不支持的算子列表。支持情况还取决于 DPU 配置和计算图模式，因此务必检查编译器的分区报告。

通过 Hard-Swish 让 YOLO26 适配 DPU#

DPU 只会将 ReLU、ReLU6、LeakyReLU、Hard-Swish 和 Hard-Sigmoid 融合到卷积中。Hard-Swish 是 SiLU 的硬件友好近似，因此是自然的替代方案。Ultralytics 模型 YAML 文件支持 activation 键，用于更改 Conv 模块的默认激活函数（模型 YAML 配置指南）。

将 yolo26.yaml 复制到 yolo26-hswish.yaml，然后在参数下添加一行：

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

然后构建模型，迁移预训练的 YOLO26 权重，并在你的数据集上微调：

from ultralytics import YOLO

# 使用 Hard-Swish 激活构建 YOLO26n；名称中的 'n' 表示 nano 尺度
model = YOLO("yolo26n-hswish.yaml").load("yolo26n.pt")  # 迁移预训练权重

# 进行微调，使网络适配 Hard-Swish
model.train(data="coco8.yaml", epochs=100, imgsz=640)

激活函数没有权重，因此所有预训练权重都会迁移。导出的 ONNX 计算图随后会包含 87 个 HardSwish 算子，且不包含 SiLU。将 coco8.yaml 替换为你自己的数据集，并在部署前使用验证模式将准确率与 SiLU 模型进行比较。

在 DPU 上处理注意力模块#

YOLO26 在最低分辨率处（输入尺寸为 640 时是 20×20 网格）应用注意力，共两处：C2PSA 模块位于第 10 层，启用注意力的 C3k2 模块位于第 22 层。YOLO11 有一个 C2PSA 模块。在 DPU 上，它们的 MatMul 和 Softmax 算子会在 CPU 上运行，从而将模型拆分为交替运行的 DPU 和 CPU 子图。你有三种选择：

1. 接受 CPU 模块。 编译后的 .xmodel 会包含 CPU 子图，因此请使用 AMD 的 Graph Runner 运行；当每个算子都有 CPU 实现时，它会一起执行 DPU 和 CPU 子图，否则你必须实现并注册缺少的算子。20×20 时注意力计算量很小，但 DPU 与 CPU 之间的每次额外传输都会增加延迟，因此请在开发板上进行测量。

2. 使用不含注意力的 YAML。 在 Hard-Swish YAML 中，将 C2PSA 层替换为 nn.Identity，以确保 Concat 和 Detect 使用的层索引仍然有效，并禁用第 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)

   导出的 ONNX 计算图随后将不包含 MatMul 或 Softmax 算子。注意力权重将不再适用（YOLO26n 的 666 个权重中有 624 个可以迁移），因此请延长微调时间，并使用验证模式比较准确率。

3. 使用不含注意力的模型，例如 YOLOv8；AMD 在自己的 DPU 示例中使用过该模型。

在 Versal AI Edge Gen 2 上，注意力算子被列为 NPU 支持的算子，因此通常不需要进行这些更改。请在编译器报告中确认算子的位置，因为 AMD 指出，即使算子受支持，也可能因配置或内存限制而回退到 CPU。

模型兼容性一览#

在其他 AMD Xilinx 目标上部署#

Zynq UltraScale+ 和 Kria DPU，以及第一代 Versal AI Edge NPU，使用 format="xilinx" 不会生成的 Vitis AI 工作流。使用 Ultralytics 训练，然后在 AMD 的 x86-64 Linux Docker 镜像中使用 AMD 工具构建目标设备所需的产物。选择与你的设备对应的标签页：

准备开发板时，需要使用包含已编译加速器配置的硬件设计和 Linux 镜像，并安装匹配的 Vitis AI 运行时。请参阅 AMD 的 Zynq UltraScale+ 和 Kria DPU 目标设置指南以及 Versal AI Edge (VEK280) 设置指南，然后复制运行时所需的产物：

在 DPU 上，VART 缓冲区保存定点 INT8 值：查询每个张量的形状和 fix_point 缩放系数，在后处理前对输入进行量化，并对输出进行反量化。Graph Runner 返回整个图的输出，而仅运行 DPU 的 Runner 返回 DPU 子图的中间输出，需要由你的代码完成后续计算。VEK280 上的 VART-ML 默认使用硬件张量视图，其形状、数据类型和内存布局可能与 ONNX 布局不同，因此请将 Runner 的输入和输出张量类型配置为 CPU 视图，或自行转换硬件格式（参阅 AMD 的 VART-ML 架构概述）。

实际应用#

在需要以低功耗、实时地在传感器附近运行视觉 AI 的场景中，AMD Xilinx 设备十分常见：

• 工业和建筑安全：检测重型设备周围的人员和机器，并使用目标检测和目标计数监控作业区域。
• 汽车和非公路车辆视觉：在符合汽车级标准的部件上运行基于摄像头的感知，支持自动驾驶汽车和驾驶辅助。
• 智能摄像头和视频分析：在一颗芯片上结合视频采集、编码和 YOLO 推理，用于安防系统和视频分析。
• 机器视觉和质量检测：将基于 FPGA 的高速图像采集与 YOLO 的实例分割或分类结合，用于生产线上的缺陷检测。
• 机器人和无人机：使用 Kria KR260 或 Versal 模块进行姿态估计、有向目标检测和导航，实现确定性延迟。

总结#

使用 format="xilinx" 导出时，Ultralytics YOLO 模型会通过 AMD Quark 量化，以用于 Versal AI Edge Series Gen 2 NPU；检测头保留为 BF16，并在模型旁生成 Vitis AI 编译器配置。你可以在任意主机上验证 INT8 精度，在 AMD Vitis AI Docker 镜像中编译 .rai 模型，然后使用 ONNX Runtime 和 Vitis AI Execution Provider 在开发板上运行。

较早的 AMD Xilinx 设备使用其他工作流。Zynq UltraScale+ 和 Kria 上的 DPU 使用已冻结的 Vitis AI 3.5 工具链和 .xmodel 文件，需要 Hard-Swish 等 DPU 原生激活函数，并在 CPU 上运行注意力计算。第一代 Versal AI Edge NPU 使用 snapshot 工作流，其算子覆盖范围取决于 Vitis AI 版本和精度。

如需了解其他部署目标，请参阅模型部署选项指南、部署最佳实践，以及 Hailo、Rockchip RKNN 和 Axelera 等加速器集成。

常见问题#