查看 Markdown

EdgeCrafter

一个紧凑的视觉 transformer，面向边缘硬件上的稠密预测，上游以三个同胞模型的形式发布：ECDet、ECPose 和 ECSeg。LibreYOLO 把三者作为一个家族加载，任务由检查点（checkpoint）携带。

任务
detection, pose, instance segmentation
尺寸
s, m, l, x at 640 px
安装
pip install libreyolo
支持层级
核心，自 v1.2.0 起。核心的可训练检测器：功能在同一个发布波次里紧跟旗舰。
上游
EdgeCrafter，由 Intellindust AI Lab 发布，采用 Apache-2.0 许可。论文、源码
许可
代码采用 Apache-2.0，权重采用 Apache-2.0。商用

安装

EdgeCrafter 不需要任何可选 extra。它导入的一切都在基础安装里。

bash
pip install libreyolo

用 lora=True 做适配器微调是个例外，它需要 lora extra。

bash
pip install "libreyolo[lora]"

预测

权重在首次使用时从 Hugging Face 下载，并缓存在本地。

Python
from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreECs.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)
CLI
libreyolo predict model=LibreECs.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True
姿态
from libreyolo import LibreYOLO, SAMPLE_IMAGE # 文件名里的 -pose 后缀会选中关键点 head，所以这里不需要传# task 参数model = LibreYOLO("LibreECs-pose.pt")result = model(SAMPLE_IMAGE, save=True) print(result.keypoints.xy)print(result.boxes.conf)
实例分割
from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreECs-seg.pt")result = model(SAMPLE_IMAGE, save=True) print(result.masks.data.shape)

任务来自文件名，所以 -pose 或 -seg 检查点会选中自己的 head，不需要传 task 参数。三者返回的都是每个家族都会返回的那个 Results 对象，姿态额外多出 result.keypoints，分割额外多出 result.masks。姿态只覆盖一个类别，也就是人， 带 17 个 COCO 关键点，数量在模型构建时就固定了。它没有检测框 head，所以每个姿态 框都是自身关键点的包围范围，而第三个关键点通道是一个常数，不是逐点的分数。

conf 和 max_det 过滤 query 的选择；iou 为了 API 一致性会被接受，但没有任何 作用，因为三个 head 解码的都是一组 query，没有 NMS 步骤。数据源、流式处理和结果 处理见预测。

变体

四种尺寸。它们跑的输入分辨率都相同，所以表格按参数量和精度来区分。

检查点输入（px）mAP 50-95参数量（M）
LibreECl64060.132.97
LibreECm64058.419.43
LibreECs64054.39.88
LibreECx64061.149.94

COCO val2017, 500 images。数据由 LibreYOLO 基准测试工具测得，并发布在 Vision Analysis 上，可在此比较不同硬件和运行时的延迟，并查看完整的运行记录。

上游把 ECDet、ECPose 和 ECSeg 发布成三个独立的模型，而不是一个带三个 head 的 模型。它们共用 ECViT 骨干和混合编码器，只在 head 上有差别，所以 LibreYOLO 把它们 收进同一个家族，让检查点文件名来携带任务。因此同一个尺寸字母在三者之间意味着相同 的骨干和编码器，而且不管你加载的是哪一个，预测、验证和导出接受的参数都一样。

训练

三个任务都通过 train() 训练，它从加载的检查点里读出任务，再挑选对应的训练器。

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreECs.pt")model.train(    data="my-dataset.yaml",    epochs=50,    imgsz=640,    batch=8,    lr0=5e-4,)
CLI
libreyolo train model=LibreECs.pt data=my-dataset.yaml epochs=50 imgsz=640 batch=8 lr0=5e-4
姿态
from libreyolo import LibreYOLO # 需要一个单类别的关键点数据集，它的 data.yaml 里要声明# kpt_shape，并且 imgsz 取检查点的原生尺寸model = LibreYOLO("LibreECs-pose.pt")model.train(    data="my-pose-dataset.yaml",    epochs=50,    imgsz=640,)
实例分割
from libreyolo import LibreYOLO # 需要多边形标注，并且 imgsz 取检查点的原生尺寸model = LibreYOLO("LibreECs-seg.pt")model.train(    data="my-dataset.yaml",    epochs=50,    imgsz=640,)
LoRA
from libreyolo import LibreYOLO model = LibreYOLO("LibreECs.pt")model.train(    data="my-dataset.yaml",    epochs=50,    lora=True,)

检测和分割上已经验证过的是：与上游的推理一致性在 1e-5 以内，逐层、逐尺寸都比对过， 以及损失函数和单步训练能在合成输入上跑通。按 train() 自己的 docstring，尚未验证 的是：完整微调的收敛性、多卡训练、停止数据增强后重新加载最佳权重这一步，以及 Objects365 到 COCO 的类别重映射。姿态这条路走的是 DETRPose 已发布的配方，即在类别、 关键点 L1 和 OKS 代价上做匈牙利匹配，并配合对比式关键点去噪，它的收敛性同样没有 端到端验证过。

保持默认时，训练器以 lr0=5e-4 跑 74 轮，混合精度开启，遵循上游的配方：AdamW、 平坦的余弦调度、0.9999 的 EMA 以及 ImageNet 归一化的输入。姿态和分割都要求 imgsz 取检查点的原生尺寸，因为它们的评估锚点网格是在模型构建时建好的；换成别的值会在 运行开始之前就抛错。姿态还要求数据集是单类别的，它的 data.yaml 里要声明 kpt_shape，关键点数量要和 head 匹配。

lora=True 只适用于检测；姿态和分割碰到它会抛出 ValueError。在 Apple silicon 上，训练器把整个训练留在 GPU 上，只把一个操作发到 CPU：可变形注意力内部的 grid-sample 反向传播，PyTorch 没有在 Metal 里实现它。

数据集、数据增强、多卡训练和日志记录器见训练。

验证

val() 返回一个以指标名为键的字典，并在 verbose 保持开启时打印每个类别的结果。

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreECs.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])
CLI
libreyolo val model=LibreECs.pt data=my-dataset.yaml
姿态
from libreyolo import LibreYOLO model = LibreYOLO("LibreECs-pose.pt")metrics = model.val(data="my-pose-dataset.yaml") print(metrics["metrics/keypoints_mAP50-95"])print(metrics["metrics/keypoints_mAP50"])
实例分割
from libreyolo import LibreYOLO model = LibreYOLO("LibreECs-seg.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95(M)"])   # 掩码print(metrics["metrics/mAP50-95(B)"])   # 检测框

姿态在 metrics/keypoints_* 下报告关键点的 OKS 指标。分割把掩码放在普通的 metrics/mAP50-95 键里，并在同一次运行中给出两种视角，检测框在 (B) 下，掩码在 (M) 下。

导出

任务ONNXTorchScriptExecuTorchTensorRTOpenVINOPaddleMNNRKNNncnnTFLiteCoreMLCore AI
DetectionDetection to ONNX：支持Detection to TorchScript：支持Detection to ExecuTorch：支持Detection to TensorRT：支持Detection to OpenVINO：支持Detection to Paddle：支持Detection to MNN：支持Detection to RKNN：不支持Detection to ncnn：不支持Detection to TFLite：不支持Detection to CoreML：不支持Detection to Core AI：支持
PosePose to ONNX：支持Pose to TorchScript：支持Pose to ExecuTorch：支持Pose to TensorRT：支持Pose to OpenVINO：支持Pose to Paddle：支持Pose to MNN：不支持Pose to RKNN：不支持Pose to ncnn：不支持Pose to TFLite：不支持Pose to CoreML：不支持Pose to Core AI：不支持
Instance segmentationInstance segmentation to ONNX：支持Instance segmentation to TorchScript：支持Instance segmentation to ExecuTorch：支持Instance segmentation to TensorRT：支持Instance segmentation to OpenVINO：支持Instance segmentation to Paddle：支持Instance segmentation to MNN：不支持Instance segmentation to RKNN：不支持Instance segmentation to ncnn：不支持Instance segmentation to TFLite：不支持Instance segmentation to CoreML：不支持Instance segmentation to Core AI：不支持

导出的产物按文件后缀经由 LibreYOLO() 重新加载，所以一个 .onnx 或 .engine 文件的表现和检查点一样，返回同样的 Results。姿态和分割导出时用的是固定的 640×640 输入，而不是动态形状，几个检测目标同样是固定画布，包括 OpenVINO、Paddle、 MNN、ExecuTorch 和 Core AI。导出列出了每种格式接受的参数，以及 其中少数几种额外增加的参数。

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreECs.pt")model.export(format="onnx", imgsz=640)model.export(format="tensorrt", imgsz=640, half=True)
CLI
libreyolo export model=LibreECs.pt format=onnx imgsz=640libreyolo export model=LibreECs-pose.pt format=onnx imgsz=640libreyolo export model=LibreECs-seg.pt format=onnx imgsz=640
使用导出的文件
from libreyolo import LibreYOLO, SAMPLE_IMAGE # 工厂按文件后缀分发，所以导出的产物加载方式和任何检查点一样，# 返回的也是同一个 Results 对象model = LibreYOLO("LibreECs.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

检查点

这个家族已发布的全部权重文件。

文件输入（px）权重许可
Detection
LibreECs.pt640apache-2.0
LibreECm.pt640apache-2.0
LibreECl.pt640apache-2.0
LibreECx.pt640apache-2.0
Pose
LibreECs-pose.pt640apache-2.0
LibreECm-pose.pt640apache-2.0
LibreECl-pose.pt640apache-2.0
LibreECx-pose.pt640apache-2.0
Instance segmentation
LibreECs-seg.pt640apache-2.0
LibreECm-seg.pt640apache-2.0
LibreECl-seg.pt640apache-2.0
LibreECx-seg.pt640apache-2.0

上面的每个文件目前都在 LibreYOLO 组织中，并会在首次使用时下载。

许可证

请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可，同一家族内也不一定相同。该仓库是权威来源；以下摘要说明本页上次验证时适用的情况。

这里只说明涉及的许可证，不构成法律意见。如果答案对商用很重要，请自行阅读许可证并咨询法律顾问。

原始工作
EdgeCrafter, Intellindust AI Lab
上游许可
Apache-2.0
上游来源
github.com/Intellindust-AI-Lab/EdgeCrafter
LibreYOLO 代码
MIT
权重
采用 Apache-2.0 许可，重新发布在 huggingface.co/LibreYOLO
解读
Apache-2.0 is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep its license text and attribution notices with any copy of the weights you redistribute, and it grants a patent license. One license covers all three upstream models, so the detection, pose and segmentation weights carry identical terms, and weights you train yourself on your own data are yours.

引用

@article{liu2026edgecrafter,
  title={EdgeCrafter: Compact ViTs for Edge Dense Prediction via Task-Specialized Distillation},
  author={Liu, Longfei and Hou, Yongjie and Li, Yang and Wang, Qirui and Sha, Youyang and Yu, Yongjun and Wang, Yinzhi and Ru, Peizhe and Yu, Xuanlong and Shen, Xi},
  journal={arXiv},
  year={2026}
}

复制自作者在 github.com/Intellindust-AI-Lab/EdgeCrafter#-citation 上提供的引用块。

已针对 LibreYOLO v1.5.0 验证。本页的支持表、检查点和基准测试数据由已发布的库和权重生成，并非手工编写。