apply_chat_template returns all-zero assistant_masks for multimodal inputs

问题场景

用户在调用 AutoProcessor.apply_chat_template 处理多模态对话（包含 image + text 的 messages）时，传入 tokenize=True、return_dict=True、return_tensors="pt"、return_assistant_tokens_mask=True，期望返回的 assistant_masks 在 assistant 回复对应位置为 1，但实际得到的是全 0 的 mask。典型触发模型为 Qwen/Qwen3.5-0.8B 等多模态处理器。

报错原文

apply_chat_template returns all-zero assistant_masks for multimodal inputs

assistant_masks is all zeros.

Expected behavior:
The tokens corresponding to the assistant response should be marked with 1 in assistant_masks.

原因分析

根据 Issue 中维护者确认的根因：generation_indices 是基于 render_jinja_template 返回的原始（未展开）文本提示计算的，而 offset_mapping 来自多模态处理路径展开占位符之后（例如 <|image_pad|> 展开为 N 个副本）的文本。两者字符跨度不一致，导致 bisect_left 在查找 assistant 文本片段时完全匹配不到，最终 assistant_masks 全为 0。

环境排查

• 确认 transformers 版本，Issue 中为 5.3.0，但反馈 5.17 仍存在，建议先确认当前版本。
• 确认使用的 processor 与模型是否属于多模态（图文/音视频）模型，例如 Qwen/Qwen3.5-0.8B。
• 确认 apply_chat_template 调用中是否开启了 return_assistant_tokens_mask=True。
• 确认是否传入了 images/videos/audio 等多模态输入，因为该 bug 仅在占位符被展开时触发。
• 确认对话模板的 assistant 头部与结束 token 样式（如 Qwen3 指令风格或 Gemma4 风格），以便对照 workaround 方案。

解决步骤

1. 先确认问题是否由该 bug 引起：打印 inputs["assistant_masks"]，若全为 0 且输入包含图像等多模态内容，则基本可判定为该索引错位问题。
2. 关注 transformers 主分支上针对该问题的修复 PR（Issue 中维护者表示会将其纳入一个更大的 refactor PR 中），在修复合并后升级版本并重新验证。
3. 可优先尝试官方讨论中提出的思路：使用 processor(**inputs, return_text_replacement_offsets=True).text_replacement_offsets 获取占位符替换偏移，重新对齐字符索引；该方案尚未在 Issue 中验证合并，属于推测性修复方向。
4. 如项目急需可用，可参考社区 workaround LUOXIAO92/MultimodalAssistantMask，其通过正则匹配方式从 assistant 头部与结束 token 之间提取 assistant input ids 和 mask；需根据自己模型的模板自定义头部 token 和结束 token。

验证方法

重新运行 Issue 中的复现脚本，检查 inputs["assistant_masks"]：assistant 回复对应的 token 位置应被标记为 1，非 assistant 部分（用户、系统、图像占位符等）应为 0；若仍全为 0，说明未应用有效修复。

参考来源

huggingface/transformers #44521

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。