查看 Markdown

Axelera Metis

format="axelera" 把 LibreYOLO 模型编译成面向 Axelera Metis AIPU 的 INT8 .axm,导出的目录可以通过 LibreYOLO() 重新加载,predict、val 和 track 的调用方式与 PyTorch 模型完全相同。1.8.0 新增,标记为预览。

参数
export(format="axelera")
精度
仅 INT8。half=True、quantize=16 和 quantize=32 会抛错。
编译主机
Linux x86_64(Ubuntu 22.04 或 24.04,或 WSL2),Python 3.10 到 3.13。编译不需要 Metis 设备。
SDK
来自 Axelera 自有包索引的 axelera-devkit 和 axelera-rt 1.9.0,不是 LibreYOLO 的 extra
输出
weights/<stem>_axelera_model/
状态
预览。23 个家族已在一块 Metis M.2 Max 上用 SDK 1.9.0 完成编译和测量。

安装

Axelera SDK 是 Axelera 的专有软件,受 Axelera 的 EULA 约束,从 Axelera 自有的包索引分发。 它不在 PyPI 上,也不是 LibreYOLO 的 extra,LibreYOLO 从不捆绑它。axelera-devkit 负责编译; axelera-rt 运行编译好的模型,也是部署机器上唯一需要的那个。

专用环境
python -m venv ~/venvs/axelera && source ~/venvs/axelera/bin/activatepip install "libreyolo[onnx]"   # 编译需要 onnx 这个 extra # 最后安装 SDK:它的 wheel 会锁定 LibreYOLO 也在用的包# 编译(导出):pip install --extra-index-url https://software.axelera.ai/artifactory/api/pypi/axelera-pypi/simple axelera-devkit==1.9.0# 运行(.axm 推理):pip install --extra-index-url https://software.axelera.ai/artifactory/api/pypi/axelera-pypi/simple axelera-rt==1.9.0
让 LibreYOLO 来安装
# 不设置的话,缺少 SDK 时会报错并给出上面的 pip 命令export LIBREYOLO_AUTOINSTALL=1

请使用专用的虚拟环境。SDK 1.9.0 的 wheel 锁定了几个 LibreYOLO 也在用的包,pip 安装时会把它们降级:

包锁定为
torch>=2.7,<2.15
typer>=0.12,<0.13
click==8.1.8
rich<14
onnx<1.19
opencv-python<5
pillow<13

LibreYOLO 在这些版本下都能工作。在 SDK 之后再安装其他 LibreYOLO extra 可能会把它们重新升级,所以最后装 SDK。 缺少某个包时,导出或加载会失败并给出确切的 pip install 命令;设置 LIBREYOLO_AUTOINSTALL=1 可以让 LibreYOLO 替你执行它,并记录到日志。

运行需要一台 Metis 设备、Axelera 的 metis-dkms 内核驱动(SDK 1.9 需要 1.7.0 或更高版本)以及 axelera-rt。axdevice 会列出每台设备及其固件,libreyolo checks 会列出它看到的 Axelera 包和 Metis 设备。

导出

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt")path = model.export(format="axelera")   # weights/LibreYOLO9t_axelera_model # 用你自己领域的数据校准,并写出一致性报告path = model.export(    format="axelera",    data="my_dataset.yaml",    fraction=0.5,    verify=True,)
CLI
libreyolo export model=LibreYOLO9t.pt format=axeleralibreyolo export model=LibreYOLO9t.pt format=axelera verify=true
参数Axelera 下的行为
imgsz固化进编译后的模型;必须是 32 的倍数。默认:检查点(checkpoint)的尺寸
data校准数据集 YAML。detect 和 pose 默认用 coco128.yaml
fraction使用校准划分中的比例。推荐 100 到 400 张图像;少于 100 张会记录警告
batch仅用于校准加载器的批大小。编译后的模型一次只接收一张图像
device用于追踪模型的 Torch 设备,不是 Metis 设备
quantize、int8INT8 始终开启。quantize=16、quantize=32 和 half=True 会抛错
dynamic始终是静态的;dynamic=True 会抛错
opsetONNX 中间图的 opset,14 到 17(默认 17)
nms不支持:NMS 在主机上运行
output_path默认 weights/<checkpoint stem>_axelera_model
verify写出 <stem>.parity.json,把量化模型与 FP32 对比,有设备时也与设备结果对比
compiler_config仅限 Python:一个由 Axelera CompilerConfig 字段组成的 dict。未知字段和由 LibreYOLO 管理的字段会抛错

校准使用模型自己的预处理。对于微调过的模型,请用它所在领域的图像校准。编译需要几分钟到几十分钟,以及数 GB 内存。

weights/LibreYOLO9t_axelera_model/    LibreYOLO9t.axm               compiled model    compiler_config_final.toml    compiler settings used for the build    metadata.yaml                 LibreYOLO metadata    LibreYOLO9t.parity.json       only with verify=True

目录按检查点文件命名。预训练的 YOLO-NAS 权重在首次使用时会被转换,所以它们的导出产物落在 weights/LibreYOLONASs-converted_axelera_model。重新导出到同一路径时,只有在新构建成功之后才会替换目录, 并且不会留下 ONNX 文件或编译器构建文件。

运行导出的产物

Python
from libreyolo import LibreYOLO, SAMPLE_IMAGE npu = LibreYOLO("weights/LibreYOLO9t_axelera_model")   # 或者其中的 .axmresults = npu(SAMPLE_IMAGE, conf=0.25)metrics = npu.val(data="coco128.yaml")for r in npu.track("video.mp4"):    print(r.track_id)
CLI
libreyolo predict model=weights/LibreYOLO9t_axelera_model source=image.jpglibreyolo val model=weights/LibreYOLO9t_axelera_model data=coco128.yamllibreyolo track model=weights/LibreYOLO9t_axelera_model source=video.mp4

网络在 Metis AIPU 上运行;预处理、检测框解码和 NMS 在主机上运行,所以检测框坐标和分数从不经过 8 位张量。 结果与 PyTorch 模型给出的 Results 对象相同。输入尺寸由导出固定。device="auto"、"axelera"、 "metis"、"aipu" 和 "cpu" 都在 AIPU 上运行;CUDA 设备会被忽略并给出警告。把这个目录复制到任何一台装有 Metis 设备和 axelera-rt 的 Linux 机器上即可。

支持的家族

下面每个尺寸都能编译、能在 Metis 设备上运行,也能导出。「1.0 以内」表示在配对集上 INT8 结果与 FP32 相差不超过 1.0 个点;测得下降更大的尺寸照样能导出,导出时会把这个下降以警告形式记录一次。精度从不阻止导出。每个家族和任务在导出矩阵里 都有自己的 validated 或 available 单元格(libreyolo formats --family yolonas 会打印出来), 未列出的组合会在编译前抛错。

家族任务尺寸测得的下降
YOLO-NASdetects、m、l1.0 以内
YOLO-NASposen、s、m、ln 和 s 更大
YOLO-NAS-Robbs、m、l1.0 以内;需要校准数据
YOLO9detectt、s、m、c1.0 以内
YOLOXdetectn、t、s、m、l、xn 更大
YOLOv2detectt、b1.0 以内
YOLOv3detectt、b、spp1.0 以内
YOLOv4detectt、bb 更大
YOLOv7detectb1.0 以内
PP-YOLOEdetects、m、l、xs、m 和 x 更大
PicoDetdetects、m、l更大
RTMDetdetectt、s、m、l更大
RTMDet-Inssegmentt、s、m、l更大
RetinaNetdetectr50更大
SSDdetect3001.0 以内
EfficientDetdetectd0、d1、d2更大
ResNetclassify18、34、50、1011.0 以内
MobileNetV4classifys、m、ls 和 l 更大
EfficientNetV2classifyb0更大
VGGclassify16、19、16bn、19bn19bn 更大
AlexNetclassifyb1.0 以内
FCNsemanticr50、r1011.0 以内
DeepLabV3semanticmv3更大
MiDaSdepths更大
QuickSRNetrestorem2更大
Real-ESRGANrestorex4t更大

部分实测差值,在 1000 张 COCO val2017 图像上的 mAP50-95,设备上的 INT8 对比同一批图像上的 FP32:YOLO9-s 从 0.4502 到 0.4450(-0.52),YOLO9-t -0.45,YOLO-NAS-s -0.30,YOLOX-s -0.48,YOLOX-n -1.81(300 张图像),PicoDet-m -2.86,RTMDet-s -6.75。ResNet-50 在 ImageNetV2 top-1 上损失 0.7 个点。包含每个数字的逐尺寸表格在库的 docs/axelera.md 里。

因结构原因被阻止的:EfficientNetV2 b1 到 b3、EfficientDet-d3、RTMDet-x、RTMDet-Ins-x、DeepLabV3 r50 和 r101、 MiDaS-l、RetinaNet-r50v2、FCOS、HRNet、CenterNet、Faster R-CNN、ConvNeXt 和 ConvNeXt V2、YOLOv1、EC、 TinyFormer、NAFNet、TEED 和 ZipDepth。RF-DETR 和其他 transformer 家族不在范围内。YOLO9-E2E、YOLO9-P2、 EfficientDet-d4、Real-ESRGAN x4 和 x2、PIDNet、DEKR 和 UNet 尚未测量。

许可证

LibreYOLO 的代码采用 MIT 许可。axelera-devkit 和 axelera-rt 是 Axelera 的专有软件,需要你自己安装。 编译后的模型沿用其来源权重的许可证:YOLO-NAS 预训练权重仅限非商用且不可再分发,所以 LibreYOLO 不托管任何 YOLO-NAS .axm 文件,每个用户自己编译。axelera 单元格是如何判定的,见导出矩阵。

读自 dev 分支 1.8.0 候选版本上的 docs/axelera.md、libreyolo/export/axelera.py、libreyolo/export/support.py 和 libreyolo/cli/commands/export.py。精度数字来自库自己做的 INT8 与 FP32 配对测量,本站没有重跑。