MLX-VLM 中的 RF-DETR在 Apple Silicon 上跑通实时目标检测与实例分割【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlmRF-DETRReal-Time Detection TransformerICLR 2026是一个基于 Transformer 的实时目标检测模型本仓库将其完整移植到 Apple Silicon 的 MLX 框架中支持 COCO 80 类目标检测与实例分割。本文以 RF-DETR 模型文档 为主线结合仓库内完整源码带你从权重转换、模型加载、单图推理一路深入到分割、视频与实时摄像头推理掌握在 Mac 上以毫秒级延迟部署检测模型的全套方法。一、RF-DETR 是什么为什么值得在 MLX 上跑RF-DETR 由 Roboflow 提出核心思路是用 DINOv2 作为视觉骨干、配合可变形注意力deformable attention的两阶段编码器-解码器结构在保持 DETR 系列免锚框、免 NMS 训练优雅性的同时实现实时推理。官方报告了出色的速度与精度平衡并提供了检测detection与分割segmentation两类权重。本仓库的mlx_vlm/models/rfdetr/目录将官方 PyTorch 权重转换为 MLX 原生格式推理时完全不需要 PyTorch 或 rfdetr 依赖包纯 MLX 张量计算在 Apple GPU / ANE 上执行因此在 M4 Max 等芯片上单张 560 分辨率图像仅需约 33ms数据来自模型文档。二、快速开始加载模型并跑通第一次检测模型加载走 mlx-vlm 标准的load_model接口配合RFDETRProcessor图像预处理与RFDETRPredictor推理封装两步即可完成一次检测from pathlib import Path from PIL import Image from mlx_vlm.utils import load_model from mlx_vlm.models.rfdetr.processing_rfdetr import RFDETRProcessor from mlx_vlm.models.rfdetr.generate import RFDETRPredictor # Load model (uses the standard mlx-vlm loader) model load_model(Path(rfdetr-base-mlx)) processor RFDETRProcessor.from_pretrained(rfdetr-base-mlx) predictor RFDETRPredictor(model, processor, score_threshold0.3, nms_threshold0.5) # Run detection result predictor.predict(Image.open(image.jpg)) for name, score, box in zip(result.class_names, result.scores, result.boxes): print(f{name}: {score:.2f} [{box[0]:.0f}, {box[1]:.0f}, {box[2]:.0f}, {box[3]:.0f}])从源码看这条链路的内部工作方式如下对应 generate.py预处理RFDETRProcessor.preprocess_image将图像缩放到模型分辨率如 560×560除以 255 后用 ImageNet 均值(0.485, 0.456, 0.406)和标准差(0.229, 0.224, 0.225)归一化返回pixel_values与original_size原始宽高用于把归一化坐标还原到像素坐标。前向predictor.predict把pixel_values转为 MLX 数组后执行model(pixel_values)得到pred_logits每个 query 的类别 logits与pred_boxescxcywh 归一化框有分割头时还会得到pred_masks。后处理postprocess对 logits 做 sigmoid取每个 query 的最高分与对应类别做 Top-K 选取默认num_select300、阈值过滤、cxcywh → xyxy坐标转换、按原始图像尺寸缩放并裁剪到边界最后按类别执行 NMSIoU 阈值默认 0.5。结果容器DetectionResult以 numpy 数组承载boxes (N,4)、scores (N,)、labels (N,)、class_names与可选的masks。RFDETRProcessor.from_pretrained会自动读取模型目录下的config.json与preprocessor_config.json因此分辨率、归一化参数与num_select无需手动指定见 processing_rfdetr.py。三、权重转换从 Roboflow 官方 checkpoint 到 MLX推理前需要一次性将官方权重转为 MLX 格式转换过程只需torch与safetensors推理时不再需要它们# Detection python -m mlx_vlm.models.rfdetr.convert --variant base --output ./rfdetr-base-mlx python -m mlx_vlm.models.rfdetr.convert --variant small --output ./rfdetr-small-mlx python -m mlx_vlm.models.rfdetr.convert --variant large --output ./rfdetr-large-mlx # Segmentation (detection instance masks) python -m mlx_vlm.models.rfdetr.convert --variant seg-small --output ./rfdetr-seg-small-mlx python -m mlx_vlm.models.rfdetr.convert --variant seg-large --output ./rfdetr-seg-large-mlx结合 convert.py 的源码转换流程分四步下载从 Roboflow 的 GCS 存储桶直接下载.pthcheckpoint缓存到~/.cache/rfdetr-mlx已存在则复用不重复下载。提取torch.load加载后取ckpt[model]状态字典并为所有键添加model.前缀以适配sanitize()。保存把权重以model.safetensors写出同时生成config.json完整模型超参数与preprocessor_config.json图像归一化均值/标准差与num_select300。验证脚本内部会用随机张量对刚转换的模型做一次前向传播确认pred_logits形状正确后才结束。每个输出目录都包含config.json、preprocessor_config.json和model.safetensors三个文件运行期无需任何 PyTorch 或 rfdetr 依赖。四、可用变体检测与分割如何选模型文档给出五种官方变体转换器源码 convert.py 中实际定义了 8 个变体额外支持seg-xlarge与seg-2xlarge汇总如下VariantTaskResolutionParamsLatency (M4 Max)baseDetection560~32M~33mssmallDetection512~32M-largeDetection704~128M-seg-smallDetection Segmentation384~34M~88msseg-largeDetection Segmentation480~130M-seg-xlargeDetection Segmentation624--seg-2xlargeDetection Segmentation768--参数与延迟数据来自模型文档。从源码看各变体的关键差异点骨干网络base/small使用dinov2_windowed_smallhidden_size 38412 层6 头large使用dinov2_windowed_basehidden_size 768分割系列全部基于 small 骨干。解码器深度dec_layers从 base 的 3 层到 large 的 6 层、seg-large 的 5 层不等seg-small仅 100 个 query其余 300 个。patch 与窗口检测系列 patch_size 14、num_windows 4特征抽取层索引 [2,5,8,11]分割系列 patch_size 12、num_windows 2索引 [3,6,9,12]并带positional_encoding_size覆盖位置编码网格。分割头规模seg_num_blocks从 4seg-small/large到 6seg-xlarge/seg-2xlarge。这些超参数都在 config.py 的ModelConfig及其__post_init__中根据encoder字段自动推导无需手工维护子配置。五、实例分割同时拿到框与逐实例掩码使用seg-*系列权重时模型前向会额外产出pred_masks。分割输出格式为result predictor.predict(image) # result.boxes - (N, 4) xyxy pixel coordinates # result.scores - (N,) confidence scores # result.labels - (N,) COCO class indices # result.masks - (N, H, W) binary uint8 masks (or None for detection-only)掩码的生成链路在 segmentation.py 中空间特征先下采样到原图 1/4downsample_ratio4经若干DepthwiseConvBlockConvNeXt 风格深度可分离卷积 LayerNorm GELU处理后投影到交互维度解码器输出的 query 特征经MLPBlock与线性投影后通过 einsumbhwc,bnc-bnhw与空间特征做内积得到 mask logits加上可学习 bias。后处理时见 generate.py 的_resize_masksmask logits 用 OpenCV 双三次插值放大回原图尺寸以 0 为阈值二值化为uint8掩码——所以掩码边缘是平滑二值化的。六、结果过滤阈值调整与类别排除RFDETRPredictor支持通过构造参数过滤输出例如排除沙发与盆栽两类predictor RFDETRPredictor( model, processor, score_threshold0.3, # minimum confidence nms_threshold0.5, # IoU threshold for NMS exclude_classes[couch, potted plant], # filter by name )score_threshold置信度下限默认 0.5文档示例用 0.3低于该值的检测被丢弃。nms_threshold同类框的 IoU 抑制阈值默认 0.5设为小于 1.0 时启用按类别的 NMS见 generate.py 的_nms_per_class。exclude_classes按 COCO 类别名集合过滤在 NMS 之后按class_names剔除指定类同时同步裁剪 boxes/scores/labels/masks。predict方法还接受可选的score_threshold参数用于单次调用临时覆盖默认阈值。类别名来自 processing_rfdetr.py 中的 91 项COCO_CLASSES列表索引 0 为背景占位常见类别如 person、car、dog、cell phone、teddy bear 等均在其中。七、架构与推理数据流模型文档给出如下架构骨架Image (HxW) -- DINOv2-small (windowed attention, 12 layers) -- MultiScaleProjector (C2f block, P4) -- Two-Stage Encoder (top-K query selection) -- Decoder (3-4 layers, deformable cross-attention) -- Detection Head (class bbox) -- [Segmentation Head] (optional, depthwise conv einsum masks)对应到源码 rfdetr.py 的Model.__call__推理数据流为DINOv2 骨干vision.py图像按 patch_size 切块嵌入并叠加位置编码将 token 序列划分为num_windows²个窗口12 层中仅在out_feature_indexes指定层做全局注意力其余层在窗口内做注意力显著降低计算量在抽取特征层对输出做 LayerNorm 并去窗口化返回 4 个尺度特征图。MultiScaleProjectorC2f把 4 个尺度的特征沿通道拼接in_channels hidden_size × 4经 YOLOv8 风格 C2f 块1×1 卷积分流 3 个 Bottleneck 1×1 合并与 LayerNorm 融合为单一尺度 P4 特征。两阶段编码器transformer.pytwo_stage_select生成网格 proposal经线性投影、分类与 bbox 细化后按最高分类得分做 Top-K 选取K300得到解码器初始参考点与查询特征可学习参考点在bbox_reparamTrue时以参数化方式与两阶段 proposal 组合。解码器3–6 层DecoderLayer每层包含自注意力 多尺度可变形交叉注意力MSDeformableAttention基于 Metal 的grid_samplekernel16 头、每头 2 个采样点 FFN采用lite_refpoint_refinequery 位置编码由参考点正弦嵌入经ref_point_head一次计算。检测头class_embed输出类别 logitsbbox_embed3 层 MLP以参数化方式输出pred_cxcy delta_cxcy * ref_wh ref_cxcy、pred_wh exp(delta_wh) * ref_wh。分割头可选按第五节所述产出pred_masks。加载权重时Model.sanitizerfdetr.py负责把 HuggingFace/PyTorch 键名映射到 MLX 结构剥离model.前缀、重映射 DINOv2 嵌入与层键、拆分解码器融合的 QKV、将 4D 卷积权重从(out,in,kH,kW)转置为 MLX 的(out,kH,kW,in)。quant_predicate则控制量化策略——骨干、卷积、小嵌入与维度非 64 倍数的层保持全精度其余nn.Linear可量化以进一步压缩内存。八、文件结构速览mlx_vlm/models/rfdetr/ config.py # Dataclass configs vision.py # DINOv2 backbone C2f projector transformer.py # Encoder (two-stage) Decoder (deformable attention) segmentation.py # SegmentationHead (mask prediction) rfdetr.py # Main Model weight sanitization generate.py # RFDETRPredictor postprocessing NMS processing_rfdetr.py # Image preprocessing COCO class names convert.py # PyTorch checkpoint converter language.py # Stub (framework compatibility)其中language.py仅为满足 mlx-vlm 框架模块加载兼容而存在的桩实现init.py 导入processing_rfdetr以触发自动处理器补丁注册install_auto_processor_patch并提供了TextConfig、VisionConfig等框架别名。九、命令行图片、视频与实时摄像头一网打尽除了 Python APIgenerate.py内置了完整的 CLIpython -m mlx_vlm.models.rfdetr.generate支持四种任务# 单图检测 python -m mlx_vlm.models.rfdetr.generate --task detect --image photo.jpg --model ./rfdetr-base-mlx # 视频分割检测 掩码输出带标注的 mp4 python -m mlx_vlm.models.rfdetr.generate --task segment --video traffic.mp4 --model ./rfdetr-seg-small-mlx # 实时摄像头推理按 q 退出 python -m mlx_vlm.models.rfdetr.generate --task realtime --model ./rfdetr-base-mlx # 实时视频文件推理 python -m mlx_vlm.models.rfdetr.generate --task realtime --video traffic.mp4 --model ./rfdetr-seg-small-mlx主要参数generate.py 的main--taskauto默认按模型是否带分割头自动选择、detect、segment、track视频处理到文件、realtime实时显示。--image/--video输入图像路径或视频路径--video 0表示摄像头索引track/realtime必须提供--video。--model必填转换好的模型目录。--threshold置信度阈值默认 0.3--nms-thresholdNMS IoU 阈值默认 0.5。--exclude空格分隔的要排除的类别名列表。--show-boxes/--no-show-boxes分割输出是否叠加框与标签默认开关闭后仅保留掩码覆盖层与轮廓。--show-fps视频输出叠加 FPS--max-frames限制处理帧数。--annotator标注风格预设或链式组合如MaskAnnotatorBoxAnnotatorLabelAnnotator复用 SAM3 的标注系统--opacity、--contour-thickness控制掩码透明度与轮廓粗细。--output输出路径默认自动命名为原文件名_rfdetr.jpg/.mp4。单图任务会先做一次 warmup然后打印检测数量、每目标类别/分数/框坐标、推理耗时ms 与 FPS以及 MLX 峰值内存MB并把标注结果保存为 jpg。视频任务返回帧数、总耗时、平均 FPS、平均检测数与输出路径等统计信息。--no-show-boxes的行为有专门的测试覆盖见 test_rfdetr_show_boxes.py分割链关闭框后只剩MaskAnnotator而检测链因为只有框和标签可画始终保留BoxAnnotator LabelAnnotator。十、视频与实时推理的工程细节RFDETRPredictor针对摄像头/视频场景提供了两条专用路径predict_bgr直接接受 cv2 的 BGR uint8 帧跳过 PIL 往返仅做 BGR→RGB 通道翻转 双线性缩放 归一化是视频与实时推理的核心入口。predict_video逐帧处理视频通过tqdm展示进度可选叠加 FPS调用标注器绘制后以 mp4v 编码写出返回统计字典。predict_realtime实时显示推理结果。摄像头场景使用独立线程持续读取最新帧cap.read不阻塞推理并把摄像头强制设为 1280×720视频文件场景则单线程按帧率节拍frame pacing推进。画面左上角实时显示Infer FPS | Loop FPS | 目标数按q退出。这两条路径复用了 SAM3 的标注组件BoxAnnotator、LabelAnnotator、MaskAnnotator通过_to_annotator_result适配后即可直接绘制无需为 RF-DETR 单独实现可视化。结语RF-DETR 的 MLX 移植把DETR 家族无需锚框、无需训练期 NMS的简洁架构与 Apple Silicon 的 MLX 计算栈结合在一起从转换器到推理器再到 CLI 形成了完整闭环。无论你是要在 Mac 上快速验证一张图的检测效果还是想把实例分割、视频批处理乃至摄像头实时推理集成进自己的应用mlx_vlm/models/rfdetr/下的代码都是一份开箱即用的参考实现。下一步可以尝试用--task realtime连接摄像头或对比base/small/large在不同分辨率下的速度与精度权衡。【免费下载链接】mlx-vlmMLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-vlm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考