RuntimeError: Model does not support EAGLE3 interface but aux_hidden_state_outputs was requested

快速结论：该报错发生在使用 vLLM 加载 MiniMax-M3 模型并启用 EAGLE3 推测解码时，但当前 vLLM ROCm 镜像中的 MiniMax-M3 模型尚未支持 EAGLE3 接口。优先检查 vLLM 版本和 Docker 镜像是否包含 EAGLE3 支持补丁。

问题场景

用户在 ROCm MI355X 平台上使用官方推荐的 vllm/vllm-openai-rocm:minimax-m3 Docker 镜像（sha256: e8071a526942ec2798f17363501c7ef62eeb7f7c21ba0fb5144bd36c74569ead）加载 MiniMax-M3 模型，并通过 vLLM 的推测解码功能启用 EAGLE3 时触发。具体操作为按照 vLLM ROCm 配方（recipe）部署模型并启用 tool_calling、reasoning、spec_decoding 和 variant=mxfp8。

报错原文

RuntimeError: Model does not support EAGLE3 interface but aux_hidden_state_outputs was requested

原因分析

可能原因：该 vLLM ROCm 镜像中的 MiniMax-M3 模型实现尚未添加 EAGLE3 接口支持。虽然模型本身具备 EAGLE3 权重，但 vLLM 的 _setup_eagle3_aux_hidden_state_outputs 方法检查到模型未实现必要的 EAGLE3 接口，因此拒绝加载。Issue 中提及的相关 PR（如 SemiAnalysisAI/InferenceX #1742）表明该功能正在开发或测试中，但尚未合入主分支。

环境排查

确认使用的 vLLM Docker 镜像是否为 vllm/vllm-openai-rocm:minimax-m3 及具体的 sha256 值。
确认 ROCm 版本和 GPU 架构（如 MI355X / gfx942），可通过 rocminfo | grep gfx 获取。
确认 Python 版本（示例中为 3.12）和 CUDA（ROCm 环境中不适用 CUDA，但需确认 PyTorch 的 ROCm 版本）。
确认模型路径和权重文件是否完整，特别是 EAGLE3 相关的权重部分。
检查 vLLM 启动命令中是否包含 --speculative-model 或相关 EAGLE3 参数。

解决步骤

优先尝试：回退到不启用 EAGLE3 推测解码的配置，仅加载基础 MiniMax-M3 模型进行推理。可以在启动命令中移除 spec_decoding 特性或相关参数。
检查镜像更新：查看 Docker Hub 上是否有更新的 vllm/vllm-openai-rocm:minimax-m3 镜像，该镜像可能已包含 EAGLE3 支持补丁。或切换到开发分支镜像（如 vllm/vllm-openai-rocm:minimax-m3-dev 或类似标签）。
手动集成补丁：从 Issue 中引用的 PR（SemiAnalysisAI/InferenceX #1742）获取 EAGLE3 支持代码，手动合并到当前 vLLM 安装目录中。注意备份原文件。
编译最新源码：从 vLLM 主仓库（master 或包含 EAGLE3 支持的分支）从头编译 ROCm 版本，以确保包含所有最新修改。
联系社区：在 Issue 中回复您的环境信息（特别是 rocminfo 输出和启动命令），等待官方或社区开发者提供针对 ROCm MI355X 的修复。

验证方法

在应用上述任一解决方案后，重新运行之前触发报错的命令。如果不再出现 “RuntimeError: Model does not support EAGLE3 interface but aux_hidden_state_outputs was requested”，并且模型加载成功、推理正常输出，则问题解决。