MLX-VLM 中的 LocateAnything：在 Mac 上运行 NVIDIA 3B 视觉定位模型的完整指南

MLX-VLM 中的 LocateAnything在 Mac 上运行 NVIDIA 3B 视觉定位模型的完整指南【免费下载链接】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-vlmLocateAnything 是 NVIDIA 发布的 3B 视觉语言定位模型vision-language grounding model专门用于在图像中定位目标对象与指代区域referred regions。本仓库mlx-vlm已将其完整移植到 Apple Silicon 上运行包括 MoonViT 视觉编码塔、Qwen2.5 文本骨干、自定义图像处理器以及模型专属的 Parallel Box Decoding并行框解码路径。读完本文你将掌握如何通过 CLI 与 Python API 在 Mac 上运行 LocateAnything 的两种生成方式自回归与并行框解码并理解其从视觉塔到坐标 token 的完整架构原理。模型概览LocateAnything 是一个约 30 亿参数的视觉语言模型核心任务覆盖视觉定位visual grounding、开放词汇目标定位open-vocabulary object localization与指代表达定位referring expression localization即根据自然语言描述在图像中输出目标的位置坐标框。其关键信息如下表项目内容Model IDnvidia/LocateAnything-3B架构MoonViT 视觉编码器 MLP 连接器 Qwen2.5 语言模型参数量3B模态图像 文本核心任务视觉定位、开放词汇目标定位、指代表达定位在 mlx-vlm 中该模型位于 mlx_vlm/models/locateanything/ 目录模型类型标识为locateanything见 config.py并通过 mlx_vlm/models/init.py 注册到模型工厂因此可以直接使用nvidia/LocateAnything-3B作为模型 ID 加载。通过 CLI 运行与多数视觉语言模型一致LocateAnything 支持标准的自回归生成autoregressive generation使用仓库提供的mlx_vlm.generate命令行入口即可mlx_vlm.generate \ --model nvidia/LocateAnything-3B \ --image examples/images/cats.jpg \ --prompt Locate the cats. \ --max-tokens 128 \ --temperature 0.0参数说明--model指定 Hugging Face 上的模型标识符nvidia/LocateAnything-3B首次运行会自动下载权重--image输入图像路径这里使用仓库自带的示例图 examples/images/cats.jpg--prompt定位指令例如Locate the cats.--max-tokens最大生成 token 数。README 特别提示场景中目标对象较多时应适当增大该值例如 256 或 512以保证每个对象都能被完整输出--temperature采样温度定位任务推荐设为0.0贪心解码保证输出坐标的确定性。通过 Python API 运行自回归生成在 Python 中使用load加载模型与处理器配合apply_chat_template组装提示词再调用generate完成推理from mlx_vlm import generate, load from mlx_vlm.prompt_utils import apply_chat_template model, processor load(nvidia/LocateAnything-3B) prompt apply_chat_template( processor, model.config, Locate the cats., num_images1, ) result generate( modelmodel, processorprocessor, promptprompt, imageexamples/images/cats.jpg, max_tokens128, temperature0.0, ) print(result.text)要点apply_chat_template需要传入num_images1因为模板中需要放置image-N占位符见下文「处理器与图像占位符展开」生成结果result.text中包含模型输出的坐标 token 序列需要按模型约定解析为边界框max_tokens128对于单目标场景足够多目标场景请按 README 建议增大。Parallel Box Decoding并行框解码LocateAnything 相比普通 VLM 的特殊之处在于它暴露了model.pbd_generate这一直接模型 API用于fast、hybrid、slow三种生成模式。该路径不走高层generate而是自行准备输入后直接调用模型方法from mlx_vlm import load from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import prepare_inputs model, processor load(nvidia/LocateAnything-3B) prompt apply_chat_template( processor, model.config, Locate the cats., num_images1, ) inputs prepare_inputs( processor, images[examples/images/cats.jpg], promptsprompt, ) input_ids inputs.pop(input_ids) inputs.pop(attention_mask, None) tokens model.pbd_generate( input_ids, generation_modehybrid, max_tokens128, **inputs, ) print(processor.decode(tokens, skip_special_tokensFalse))几个值得注意的细节prepare_inputs返回的input_ids需要从字典中取出单独传入attention_mask会被显式丢弃inputs.pop(attention_mask, None)因为 PBD 解码器内部使用自建的块状掩码而非标准因果掩码model.pbd_generate的实现位于 locateanything.py它先通过get_input_embeddings计算输入嵌入若未提供缓存视觉特征则前向视觉塔与连接器再构造PBDDecoder并驱动生成循环解码结果直接是 token id 列表需要调用processor.decode(..., skip_special_tokensFalse)还原为包含特殊标记的文本才能看到完整的box.../box结构。generation_mode 的三种模式generation_mode参数接受以下取值对应 pbd.py 中PBDDecoder的三种运行策略模式行为hybrid先用 Parallel Box Decoding 生成遇到无法并行处理的模式如error_box时自动回退到自回归解码是默认推荐模式fast仅使用 Parallel Box Decoding任何非标准框模式都会被强制按coord_box处理速度最快但可能牺牲精度slow完全走自回归解码但经由 LocateAnything 的 PBD 包装器即复用同一套 PBD 调用框架只是内部逐 token 生成架构解析README 用五点概括了模型架构下面结合源码逐一展开主模型定义见 locateanything.py。视觉塔MoonViT 图像编码器MoonViT 视觉塔的配置在 config.py 的VisionConfig中定义hidden size 1152、27 层、16 个注意力头、intermediate size 4304patch size 为 14并带 2×2 的 patch 合并核merge_kernel_size[2, 2]。实现位于 vision.py 的VisionModel其关键组件包括PatchEmbedvision.py14×14 卷积切 patch并使用Learnable2DInterpPosEmb学习式二维插值位置编码——位置编码以 64×64 的初始网格预置遇到不同分辨率输入时通过双三次插值bicubic适配任意 grid 尺寸二维 RoPERope2DPosEmbvision.py在 512×512 的网格上预计算二维频率x/y 两个方向各自编码按输入图像的实际 grid 形状切片使用从而为任意长宽比图像提供位置信息patch mergingpatch_mergervision.py将 2×2 邻域 patch 的特征在空间维度上拼接到 channel 维输出序列长度缩减为原来的 1/4与处理器中的merge_kernel_size对应块状注意力掩码make_block_attention_maskvision.py多图输入时按cu_seqlens将各图的 token 分组禁止跨图注意力。连接器LayerNorm 两层线性LocateAnythingMultiModalProjectorlocateanything.py将合并后的视觉特征投影到语言模型的 hidden size输入维度为vit_hidden * merge_kernel[0] * merge_kernel[1]即 1152×2×2 4608经过 LayerNorm → Linear → GELU → Linear 后输出 2048 维即 Qwen2.5 的 hidden size。语言模型Qwen2 风格解码器文本骨干是 Qwen2 风格解码器配置见 config.py 的TextConfighidden size 2048、36 层、16 个注意力头、2 个 KV 头GQA、rope_theta1e6、最大位置 32768并开启权重绑定tie_word_embeddingsTrue同时vocab_size152681。实现位于 language.py 的LanguageModel绑定权重时直接通过embed_tokens.as_linear(out)输出 logits省去独立的 lm_head 层因此 locateanything.py 的sanitize会跳过language_model.lm_head.weight。特殊 token 体系模型使用一组专用 token id 表达坐标框结构config.pytokenid含义image_token_index151665图像占位符 tokenbox_start_token_id151668框开始box_end_token_id151669框结束ref_start_token_id151672指代对象开始ref_end_token_id151673指代对象结束coord_start_token_id151677坐标范围开始coord_end_token_id152677坐标范围结束none_token_id4064空框标记text_mask_token_id151676MTP 掩码 tokenblock_size6null_token_id152678空位填充 tokenswitch_token_id152679模式切换 token其中block_size6是 PBD 并行块的大小——pbd.py 在初始化时强制断言其为 6因为handle_pattern/decode_ref的逻辑均假设单个框块恰好包含 6 个 token。处理器图像占位符展开LocateAnythingProcessorprocessing_locateanything.py的核心职责是把文本中的image-N占位符展开为img...IMG_CONTEXT.../img的 token 序列先由LocateAnythingImageProcessor把图像切成 patch 并返回image_grid_hws每张图的 grid 高宽再根据merge_kernel_size计算每个占位符应展开的IMG_CONTEXT数量grid_h * grid_w // merge_length并校验占位符数量与图像数量一致否则抛出异常。图像预处理image_processing_locateanything.py遵循「先缩放、后补齐」的策略若 patch 总数超过in_token_limit默认 25600则按比例缩小随后把宽高向上取整到merge_kernel * patch_size的整数倍例如 2×1428 的倍数保证图像能被 2×2 合并核完整切分最后校验 grid 不超过 512×512否则超过 RoPE 预置范围报错。此外README 特别注明该自定义处理器支持save_pretrained()调用后会写出processor_config.json、preprocessor_config.json与chat_template.json三个文件processing_locateanything.py其中preprocessor_config.json记录了image_mean、image_std、in_token_limit、merge_kernel_size、patch_size等完整预处理参数便于本地保存与复加载。PBD并行框解码器PBDDecoderpbd.py是整个 LocateAnything 移植最具特色的部分。其核心思想是利用模型的多 token 预测MTP能力一次性前向产出 6 个位置的 logits 块然后通过模式识别从概率分布中直接「解析」出一整个坐标框 token 块而不是逐 token 解码。关键子流程块前向MTP_forward_mtp与_mtp_prefill将「上一步生成的最后一个 token 5 个掩码 token」作为窗口送入语言模型配合build_magi_block_masklanguage.py构造的块状注意力掩码与错位 position ids一次性获得 6 个位置各自的 logits随后cache.trim(B)回退 KV 缓存框合法性判定is_valid_box_framepbd.py检查box_start概率是否超过阈值默认 0.6、是否被im_end/null抢占从而区分legal_box、empty_box与illegal_box坐标平均解码decode_bbox_avgpbd.py对中间 4 个坐标位置各自取 top-k默认 5候选筛选出落在coord_start..coord_end范围内的 token idhybrid模式下若首候选概率低于 0.9 且候选跨度超过 60判定为异常并输出 0坐标原点否则输出首候选模式回退handle_patternpbd.py将解码结果分类为im_end终止、empty_box、coord_box4 坐标框、point_box2 坐标点、error_box或ref_object指代对象其中只有error_box会触发need_switch_to_ar即hybrid模式在此回退到自回归逐 token 解码而fast模式则强制按coord_box处理以保持全并行。目录结构本模型在仓库中的完整文件布局如下mlx_vlm/models/locateanything/ __init__.py # 导出 Model / Processor / 各 Config config.py # VisionConfig / TextConfig / ModelConfig image_processing_locateanything.py # 图像缩放、归一化、patchify language.py # Qwen2 风格语言模型 MTP 块掩码 locateanything.py # 主模型、投影器、pbd_generate、权重清洗 pbd.py # PBD 解码器与坐标解析逻辑 processing_locateanything.py # 处理器占位符展开、save_pretrained vision.py # MoonViT 视觉塔PatchEmbed/RoPE/合并入口文件init.py 将Model、LanguageModel、VisionModel、Processor、ImageProcessor及各配置类统一导出供模型工厂自动发现与加载。使用注意事项多图输入当 prompt 中包含多张图像时apply_chat_template的num_images必须传len(images)同时generate/prepare_inputs中传入相同数量的图像保证占位符与图像一一对应max-tokens 与场景复杂度README 明确建议在对象较多的场景增大--max-tokens否则可能截断后续对象的坐标输出解码模式选择追求速度且场景简单可用fast追求鲁棒性用默认hybridslow相当于经 PBD 包装器的纯自回归基线保存处理器processor.save_pretrained(目录)会同时写出processor_config.json、preprocessor_config.json与chat_template.json后续可通过LocateAnythingProcessor.from_pretrainedprocessing_locateanything.py从本地目录恢复包含完整的图像预处理参数与聊天模板。【免费下载链接】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），仅供参考