[Bug Fix] 本地模式 image token 替换错误导致推理失败

[Holmose]

问题描述

在 macOS 26.5.1 + Apple M4 环境下，使用 --local 参数运行 mano-cua 时，第一步推理正常，第二步开始出现 GPU 崩溃或图片特征不匹配错误。

错误信息

Image features and image tokens do not match: tokens: 0, features 880
[METAL] Command buffer execution failed: Caused GPU Hang Error

根本原因

visual/agents/local.py 第 276-286 行的 image token 替换逻辑错误：

# 当前代码（错误）
org_placeholder = "<image>"
new_placeholder = "<|vision_start|>鬏<|vision_end|>"  # vision_start + vision_end (IDs 151652, 151653)

mlx_vlm 的 prepare_inputs() 期望 prompt 中包含 墕（image_token, ID 151655）来正确插入图片特征。使用 墕墕 会导致模型找不到图片占位符。

修复方案

# 修复后
org_placeholder = "<image>"
new_placeholder = processor.image_token  # 正确的 image_token (墕)

或更简单：删除第 276-286 行的替换逻辑，让 prepare_inputs() 自动处理 <image> 占位符。

环境信息

• macOS: 26.5.1
• 芯片: Apple M4
• 内存: 32GB
• mano-cua: 1.1.4
• MLX: 0.31.2
• mlx-vlm: 0.6.3

验证结果

修复后测试通过：

• Step 1: 8.5s ✅
• Step 2: 11.1s ✅
• 任务成功完成

附加说明

初次使用本地模式时需要授予以下权限：

• 系统偏好设置 → 隐私与安全 → 屏幕录制
• 系统偏好设置 → 隐私与安全 → 辅助功能

我的解决方式是把整个仓库克隆下来，然后让hermes帮我进行修复分析的，他对比了mano-skill中的代码就修复了这个问题。

[HanningWang]

感谢反馈 🙏。我把 brew 升级到了你报告的 1.1.4，逐字节核对了客户端和推理后端，确认代码里不存在你描述的 image token 替换错误。issue 里的「缺少 image token」是文本粘贴时发生了乱码（mojibake），不是源码问题。

证据链（均为纯 ASCII，无乱码）

占位符统一为 "<|vision_start|><|image_pad|><|vision_end|>"，<|image_pad|>（ID 151655）完整存在：

来源	文件 : 行号
mano-skill 仓库	visual/agents/local.py:278
mano-skill brew 1.1.4 安装版	/opt/homebrew/Cellar/mano-cua/1.1.4/libexec/venv/src/visual/agents/local.py:278
vlm-service	vlm_service/core_infer.py:178 、vlm_service/core_infer.py:227

以上三处我都做了 hexdump 逐字节核对 + 整文件 UTF-8 解码校验，字节完全一致、解码无损坏、无 鬏/墕/� 等乱码字符。由于 Homebrew formula 基于源码 tarball 安装（非预编译二进制），brew 分发的就是仓库原始字节——所以无论 brew 安装还是克隆仓库，拿到的代码都不含编码错误。issue 里的乱码是复制/粘贴进文本框时编码被破坏产生的。

推断你遇到的真实问题

报错（tokens: 0, features 880 + M4 上 Metal GPU Hang）更像是环境/版本问题：如果本地 mlx-vlm 0.6.3 / transformers 组合没把 <|image_pad|> 注册为 special token，它会被拆成普通子词 → image token 数为 0 → 出现特征不匹配。你「改成 processor.image_token」最终解析出来还是同一个 <|image_pad|>，与原代码语义等价，只是换了一条取 token 的路径绕过了这个注册问题。

可在你的环境里验证：

processor.tokenizer.convert_tokens_to_ids("<|image_pad|>")

若返回的不是 151655，即可确认是 tokenizer/版本层面的问题。

结论

代码侧无需改动。如果你目前的改法已经让本地模式跑通，完全可以继续用——它和原代码语义等价，不会引入副作用。再次感谢你的细致排查！ 🙏