ValueError: Unrecognized image processor in

问题场景

用户通过 Transformers 的 AutoProcessor 或 AutoImageProcessor 加载 qwen3_5 / qwen3_vl 家族的视觉语言检查点（例如 Qwen/Qwen3.8-27B 及 mlx-community/Qwen3.8-27B-4bit 本地快照），在 from_pretrained 阶段直接抛出异常。报告者在 transformers 5.15.1 和 5.16.1 上都能复现，并且指出 mlx-vlm 0.6.8 的 load_processor()（内部就是包一层 AutoProcessor.from_pretrained）在其允许的整个 transformers>=5.14 范围内同样失败，vLLM 0.28 的 get_processor 包装也会触发，因此不是某个推理框架独有的问题。

报错原文

ValueError: Unrecognized image processor in <path>. Should have a `image_processor_type` key in its preprocessor_config.json of config.json, or one of the following `model_type` keys in its config.json: aria, beit, bit, ...

触发调用示例：

from transformers import AutoProcessor
AutoProcessor.from_pretrained("<local snapshot of Qwen3.8-27B>")
# ValueError: Unrecognized image processor in <path>. Should have a `image_processor_type` key ...

原因分析

报告者追踪后的结论是：在 5.15.1 / 5.16.1 上，针对 Qwen3_5Config 的类型键映射解析成了从未随任何已测版本发布的类名字符串：

{'torchvision': 'Qwen3VLImageProcessor', 'pil': 'Qwen3VLImageProcessorPil'}

而 transformers/models/qwen3_vl/image_processing_qwen3_vl.py 在 5.12.1、5.14.0、5.15.1、5.16.1 中都不存在，该目录只提供 configuration / modeling / processing / video_processing。于是 _load_class_with_fallback / _load_backend_class 返回 None，AutoImageProcessor.from_pretrained 落到通用的 “Unrecognized image processor” 错误上。同时，旧字符串注册表里 qwen3_5 指向的是正确的 Qwen2VLImageProcessor(Pil)，两个注册表不一致，报告者认为像是一次未完成的迁移。

另一条触发路径与检查点自带的 image_processor_type: "Qwen2VLImageProcessorFast" 有关——该 legacy-Fast 类名已不再注册。报告者还补充，在 5.12.1 上类型键映射里放的是真实的 Qwen2VL 类对象，但 AutoProcessor.from_pretrained 对该检查点仍报同样的 “Unrecognized” 错误，说明 5.12 时期的派发逻辑里至少还有一个未定位的失败模式。维护者随后表示当前 main 上该映射已正确指向 Qwen2-VL 图像处理器，并能从 https://huggingface.co/Qwen/Qwen3.8-27B 正常加载，且用 use_fast=True 或删除 image_processor_type 键都无法复现。

环境排查

• 确认 transformers 具体版本：报告者在 5.15.1 与 5.16.1 的发布 wheel 上稳定复现；main 分支已不可复现。
• 确认是否是发布版与 main 的差异：报告者强调 main 不可复现属于预期，残留悬挂类名只出现在已发布的 5.15.x / 5.16.x 运行时。
• 检查检查点 preprocessor_config.json：是否存在 image_processor_type 键，以及其值是否为 legacy 的 Qwen2VLImageProcessorFast。
• 确认调用方：裸库调用与 mlx-vlm、vLLM 等包装调用行为不同，vLLM 0.28 即使配置正确也可能走到坏路径。
• 检查 Python 版本与平台：已确认测试环境为 Python 3.12、macOS arm64。
• Issue 中未提供 CUDA、PyTorch、显卡信息，这些项目无法据此结论判断。

解决步骤

1. 先用最小脚本确认所处版本的实际映射，判断是否命中悬挂类名：pip install transformers==5.15.1（或 5.16.1），然后读取 transformers.models.auto.image_processing_auto.IMAGE_PROCESSOR_MAPPING.get(type(AutoConfig.from_pretrained(p)))，观察是否输出 {'torchvision': 'Qwen3VLImageProcessor', 'pil': 'Qwen3VLImageProcessorPil'}。
2. 如果走的是裸 AutoProcessor.from_pretrained(path) / 不带额外 kwargs 的路径，可优先尝试把检查点 preprocessor_config.json 中的 image_processor_type 改为 "Qwen2VLImageProcessor"。报告者用 mlx-vlm 0.7.0rc0 的加载器和上传的 gist 配置验证过该写法；复现 gist 为 https://gist.github.com/suntp/d0045bbbc382230c47c74f95ce8d08c9，其中只含三个 config 文件，无需 torch。
3. 如果调用来自 vLLM 这类会额外传参的包装器，仅改配置无效。报告者验证有效的做法是 monkeypatch transformers.models.auto.image_processing_auto._load_backend_class / _load_class_with_fallback，让请求 Qwen3VL 类失败时回退到 Qwen2VLImageProcessor。
4. 若不打算打补丁，可切换到维护者确认已修复的 main；报告者认为如果 main 已把 Qwen3_5Config 映射到 Qwen2VL 类，本 Issue 即可视为已解决，但已发布的 5.15.x / 5.16.x 仍受影响。
5. 不要指望通过设置任意已注册的 image_processor_type 类名绕过：Issue 正文明确说过“将其设为任何已注册类名都无济于事”。

验证方法

报告者给出的验证标准是：monkeypatch 之后 AutoProcessor.from_pretrained 能够完整走通，并返回一个可用的 Qwen3VLProcessor，其预处理参数与 Qwen2VL 处理器一致——patch 16 / merge 2 / mean=std=0.5。报告者表示已用该方案跑通端到端视觉推理。若你采用改 image_processor_type 的方案，则以 AutoProcessor.from_pretrained(path) 不再抛出 “Unrecognized image processor” 且能正常完成一次前向预处理作为通过标准。

参考来源

huggingface/transformers #48511

AI 工具推荐

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

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

了解 GamsGo AI

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