【Bug已解决】[Bug] mistral3 offline multimodal inference example failing with prompt placeholder error 解决方案一、现象长什么样跑 Mistral3 的离线多模态推理示例官方 example 或自己照着写的LLM.generate 多模态输入时构造请求阶段报错ValueError: number of images (1) does not match number of image placeholders (0)或者模板相关KeyError: image (chat template 期望图像占位符但未找到)或处理器侧RuntimeError: prompt placeholder error: expected 2 image tokens but got 1几个特征只在离线多模态示例炸同一模型在线服务器vllm serve OpenAI 客户端传 image_url能正常跑。崩在「构造 prompt / 应用 chat template / 处理器对齐」阶段还没到模型前向。报错核心是「图像占位符数量」和「实际图像数量」对不上。离线示例往往手写 prompt 字符串最容易漏写或少写image占位符。本质Mistral3 的多模态处理器要求 prompt 文本里包含与图像数量相等的image或等效占位符 token处理器据此把图像特征「嵌」进对应位置。离线示例手写 prompt 时漏了占位符、或占位符数量和传入图像数不一致于是处理器对齐失败报「prompt placeholder error」。二、背景多模态模型Mistral3、Pixtral、LLaVA 等都一样的文本和图像是怎么「对齐」的文本 prompt 里有一串特殊占位符Mistral3 用image这类标记标记「图像特征应该插入的位置」。处理器processor / chat template数一下 prompt 里有几个image再数一下你传了几张图两者必须相等占位符多了文本里写了 2 个image但只传 1 张图→ 没图像可嵌报错。占位符少了传了 1 张图但文本里 0 个image→ 图像没地方放报错。在线服务器模式为什么不出错因为 OpenAI 客户端传image_url时服务器侧的 chat template自动把image占位符插进 prompt按消息结构生成用户不用手写所以占位符永远和图像数对齐。离线示例为什么出错因为离线示例常常绕过 chat template直接手写 prompt 字符串。示例作者可能写了Describe this picture: 但忘了加image或者照着旧版文档加了错误数量的占位符于是占位符数量和图像数错位 → 报 prompt placeholder error。一句话离线示例手写 prompt 漏写/错写image占位符与传入图像数不一致处理器对齐失败。三、根因根因是离线多模态示例构造 prompt 时没有保证「image占位符数量 传入图像数量」且没走能自动插入占位符的 chat template三层第一层主因手写 prompt 漏占位符 / 数量错配。示例直接拼字符串作者主观认为「传了图模型就知道」但处理器是机械对齐占位符的文本里没有image它就不知道图像放哪。占位符数 ≠ 图像数是直接原因。第二层没走 chat template 的自动占位符插入。Mistral3 的 chat templatetokenizer.apply_chat_template在收到含image内容的 message 时会自动在文本里生成正确数量的image。但离线示例为了「简单」跳过了apply_chat_template自己拼 prompt把这道自动对齐机制绕过了。第三层处理器报错信息笼统未给出修复方向。报错只说「不匹配」没告诉用户「你的 prompt 里有 0 个占位符、传了 1 张图请在文本中加入 1 个image」。用户要自己猜排查成本陡增。一句话离线示例手写 prompt 绕过 chat template 自动插入、占位符数与图像数错配且报错不友好。四、最小可运行复现下面用纯 Python 模拟「处理器校验占位符数量 图像数量错配即报错」的控制流不需要 GPUPLACEHOLDER image def count_placeholders(prompt: str) - int: return prompt.count(PLACEHOLDER) def process_buggy(prompt: str, images: list): n_ph count_placeholders(prompt) n_img len(images) if n_ph ! n_img: raise ValueError( fnumber of images ({n_img}) does not match fnumber of image placeholders ({n_ph}) ) return fok: {n_ph} placeholders, {n_img} images def main(): images [img1.jpg] # 传了 1 张图 # 离线示例常见写法漏写占位符 bad_prompt Describe this picture: try: process_buggy(bad_prompt, images) except ValueError as e: print(复现成功:, e) # 正确写法占位符数量 图像数 good_prompt image\nDescribe this picture: print(process_buggy(good_prompt, images)) if __name__ __main__: main()跑出来会打印复现成功: number of images (1) does not match number of image placeholders (0)和线上「占位符数量不匹配」完全一致加上image后通过。五、解决方案第一层最小直接修复最省事的救火手写 prompt 时保证image占位符数量等于传入图像数且优先走apply_chat_template让它自动插入from vllm import LLM, SamplingParams from vllm.multimodal import MultiModalDataDict llm LLM(modelmistralai/Mistral-3-...) # 正确做法 1用 chat template 自动插入占位符推荐 messages [ {role: user, content: [ {type: image, image: cat.jpg}, {type: text, text: Describe this picture.}, ]}, ] prompt llm.get_tokenizer().apply_chat_template( messages, tokenizeFalse, add_generation_promptTrue ) # apply_chat_template 会自动在文本里生成 1 个 image与 1 张图对齐 out llm.generate({ prompt: prompt, multi_modal_data: {image: load_image(cat.jpg)}, })如果必须手写 prompt 字符串手动对齐# 1 张图 - 文本里写 1 个 image n_images 1 prompt image\nDescribe this picture. assert prompt.count(image) n_images, 占位符数量必须等于图像数六、解决方案第二层结构性改进第一层是「手动对齐」第二层是「封装一个构造器自动按图像数插入占位符并校验」从设计上消灭错配from dataclasses import dataclass from typing import List, Dict, Any dataclass class MultiModalPrompt: text: str images: List[str] def render(self, placeholder: str image) - str: n_img len(self.images) n_ph self.text.count(placeholder) if n_ph n_img: return self.text # 已经对齐 if n_ph n_img: raise ValueError( f占位符({n_ph})多于图像({n_img})请减少 image 或补传图像 ) # 占位符少于图像在文本开头自动补够占位符 missing n_img - n_ph return (placeholder \n) * missing self.text def validate(self, placeholder: str image) - None: n_img len(self.images) n_ph self.render(placeholder).count(placeholder) assert n_ph n_img, ( f图像数 {n_img} 与占位符数 {n_ph} 仍不一致请检查 prompt ) def build_request(prompt: str, images: List[str]) - Dict[str, Any]: mmp MultiModalPrompt(textprompt, imagesimages) final_prompt mmp.render() # 自动补齐占位符 mmp.validate(final_prompt) # 再校验一次 return { prompt: final_prompt, multi_modal_data: {image: [load_image(i) for i in images]}, }这样即便示例作者漏写占位符render也会按图像数自动补到文本开头validate再做最后一道闸绝不会把错配的请求送进处理器。七、解决方案第三层断言 / CI 守护把「占位符 图像数」「自动补齐」「友好报错」固化成测试import pytest def test_render_fixes_missing_placeholder(): mmp MultiModalPrompt(textDescribe this., images[a.jpg]) out mmp.render() assert out.count(image) 1 assert out.endswith(Describe this.) def test_render_keeps_aligned(): mmp MultiModalPrompt(textimage\nDescribe., images[a.jpg]) assert mmp.render() image\nDescribe. def test_render_raises_when_too_many(): mmp MultiModalPrompt(textimageimage\nDescribe., images[a.jpg]) with pytest.raises(ValueError): mmp.render() def test_validate_passes_when_consistent(): mmp MultiModalPrompt(textimage\nX, images[a.jpg]) mmp.validate() # 不抛 def test_build_request_ok(): req build_request(Describe., [a.jpg, b.jpg]) assert req[prompt].count(image) 2 assert len(req[multi_modal_data][image]) 2再加一个端到端回归离线示例用build_request构造不报 prompt placeholder errordef test_offline_example_no_placeholder_error(): req build_request(What is in this image?, [cat.jpg]) out run_offline_inference(req) # 不应 ValueError: placeholder mismatch assert out is not None八、排查清单看报错是否number of images (N) does not match number of image placeholders (M)或prompt placeholder error→ 坐实本问题。数一下 prompt 文本里image或模型对应的占位符的数量和传入图像数比对。临时救火手写 prompt 时让占位符数 图像数或改用apply_chat_template自动插入。确认占位符 token 是不是image不同模型可能是img/|image_pad|看 tokenizer 的 chat template。长期修复封装构造器自动补齐占位符 校验不依赖手写对齐。升级示例到合了占位符对齐修复的版本并跑上面的「占位符图像数」用例。若在线能跑、离线不能基本就是离线绕过了 chat template 自动插入优先改回用apply_chat_template。九、小结Mistral3 离线多模态示例的 prompt placeholder error不是模型问题而是离线示例手写 prompt 漏写/错写image占位符与传入图像数不一致处理器对齐失败在线服务器因走 chat template 自动插入所以正常。最小修复是手写时对齐占位符数量或改用apply_chat_template结构性修复是封装构造器自动补齐占位符并校验最后用 pytest 把「占位符图像数」「自动补齐」「友好报错」锁死。抓住「多模态 prompt 中占位符数量必须与图像数严格相等、优先交给 chat template 自动处理」这条所有多模态离线示例的占位符问题都能照此排查。